V2 to V3

General

For the Orderful platform V1 was a short-term POC which makes V2 effectively the first version. V3 is an incremental update that consists solely of API surface updates designed to make integration easier. It's launched alongside improved documentation and new features as part of a holistic effort to improve the integration experience. Estimated time to migrate from V2 equivalents is 30 minutes.

Changes By Endpoint

Create Transaction - POST /v3/transactions

Summary

Changed: Identity properties renamed from from and to to sender and receiver.
Changed: Identity objects drops idType & id combo pair and moves to single named property e.g. isaId.
Changed: id on response is now a string.
Removed: attachments properties.
Changed: Nested previous message body under a new content property on message.
Changed: Inline idempotencyId previously in headers

Before

// REQUEST
{
	"from": {
		"idType":"isaId",
    "id":"SENDERINC"
	},
	"to": {
		"idType":"isaId",
    "id":"RECEIVERCORP"
	},
	"type": {
		"name": "810_INVOICE"
	},
	"stream": "live",
	"message": { ...},
}
  
// RESPONSE
{
  "id": 213213
}

After

// REQUEST
{
	"sender": {
		"isaId": "SENDERINC",
	},
	"receiver": {
		"isaId": "RECEIVERCORP",
	},
	"type": {
		"name": "810_INVOICE"
	},
	"stream": "live",
	"message": {
		content: {...}
	},
	"idempotencyId": "70dc2150-0169-4de7-bd90-032547886488"
}

// RESPONSE
{
  "id": "213213"
}

Get Transaction - Get /v3/transactions/:id

Summary

Changed: Identity properties from from and to to sender and receiver.
Added: isaId, organizationId, organizationName, ediAccountId and ediAccountName property to identity objects.
Changed: Identity objects drops idType & id combo pair and moves to single named property e.g. isaId.
Changed: id on response is now a string.
Removed attachments and structureChangeLog properties.
Changed: Nested previous message body under a new content property on message.
Changed: Statuses grouped under new state property.
Moved: businessNumber under metadata property
Added: workflow property showing related transactions

Before

{
	"id": 326,
	"from": {
		"idType":"isaId",
    "id":"SENDERINC"
	},
	"to": {
		"idType":"isaId",
    "id":"RECEIVERCORP"
	},
	"type": {
		"name": "810_INVOICE"
	},
	"stream": "LIVE",
	"status": "PENDING"
	"businessNumber": "ABC231333",
	"message": { ...},
	"createdAt": "2020-08-24T18:29:45.457Z",
	"lastUpdatedAt": "2020-08-24T18:29:45.457Z",
}

After

{
	"id": "326",
	"sender": {
		"isaId": "SENDERINC",
		"organizationId": 305,
		"organizationName": "Sender Inc"
		"ediAccountId": 4242,
		"ediAccountName": "Primary"
	},
	"receiver": {
		"isaId": "RECEIVERCORP",
		"organizationId": 385,
		"organizationName": "Receiver Corp"
		"ediAccountId": 3392
		"ediAccountName": "North America Division"
	},
	"type": {
		"name": "810_INVOICE"
	},
  "workflow": {
      "relatedTransactions": [{
        "type": "850_PURCHASE_ORDER",
        "url": "https://api.orderful.com/v3/transactions/3333"
      }]
  },
	"stream": "LIVE",
	"state": {
		delivery: "PENDING",
		deliveryStatusReason: "n/a",
		acknowledgement: "UNACKNOWLEDGED"
	}
	"metadata": {
	    "businessNumber": "ABC231333",
	}
	"message": {
		"content": {...},
		"validationStatus: "VALID",
		"sizeInBytes": 3251,
	},
	"createdAt": "2020-08-24T18:29:45.457Z",
	"lastUpdatedAt": "2020-08-24T18:29:45.457Z",
}