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",
}

Accept Transaction - POST /v3/transactions/:id/accept

Summary

No changes except for new v3 version parameter

Reject Transaction - POST /v3/transactions/:id/reject

Summary

No changes except for new v3 version parameter

Fail Transaction - POST /v3/transactions/:id/fail

Summary

No changes except for new v3 version parameter.