Transacting against a system of record

Configure the integration tool that will act as a JSON transactions endpoint.

Synchronous Transactions Against Customer Endpoints

In order for LDS to be able to send transactions to customer endpoints, customer needs to implement an endpoint that conforms to the following specification.

HTTP POST

The endpoint must accept an HTTP POST protected with BASIC HTTP Authentication.

POST Body

There are two options for the format of the post body, TableData and Items. The TableData option includes just the data portion of the item being transacted. The Items option includes all the header and data information of the item being transacted.

TableData POST Body

HTTP body is of mime type “application/json” and is a JSON list of objects that conform to the data portion of the LD item schema. Examples of items may be obtained from Mission Control by using just the data portion of the item. The list may contain only one object as of January, 2015. This may change in the future to support multiple transactions per post.

For example, an HTTP POST submitting a Cart may look like this:

[
    {
    "accountId": "ACCOUNTID1",
    "cartId": "93576A49-2EA0-4FA4-8E20-KIKIKK",
    "cartType": "/Workflow/cartType[Cart]",
    "createdByUser": "[email protected]",
    "currency": "",
    "customerMessage": "This is a Test customer message",
    "description": "",
    "freightTerms": "",
    "lineItemType": "CartLineItem",
    "logisticsCode": "",
    "logo": "",
    "mediaId": "",
    "name": "93576A",
    "orderNumber": "",
    "orgPath": "/Org/company[A]/businessUnit[B]",
    "processStatus": "/Workflow/processStatus[Submit]",
    "lineItems": [
      {
        "uom": "/Data/uom[Case]",
        "itemId": "011e52927903f0af1c6a36b83861938ae0596dc9",
        "cartId": "93576A49-2EA0-4FA4-8E20-ERERGH",
        "productDescription": 
            "Some Product Sold in Cases",
        "requestedTotalPrice": "12.0",
        "productId": "014216DCDEND1P",
        "itemType": "Product",
        "requestedQuantity": "7",
        "lineItemId": "000010"
      },
      {
        "uom": "/Data/uom[Bottle]",
        "itemId": "011e52927903f0af1c6a36b83861938ae0596dc9",
        "cartId": "93576A49-2EA0-4FA4-8E20-ERERGH",
        "productDescription": 
            "Some Product Sold in Bottles",
        "requestedTotalPrice": "12.0",
        "productId": "014216DCDEND1P",
        "itemType": "Product",
        "requestedQuantity": "7",
        "lineItemId": "000020"
      }
    ]
    }
]
Items POST Body

HTTP body is of mime type “application/json” and is a JSON list of objects that conform to the header and data portion of the LD item schema. Examples of items may be obtained from Mission Control. The list may contain only one object as of January, 2015. This may change in the future to support multiple transactions per post.

For example, an HTTP POST submitting a Cart may look like this:

[
        {   
          "headers": {
            "community": "Test Community",
            "state": "SendingToApplication",
            "type": "Cart",
            "clientId": "12DC39E3-AA55-4265-BD04-96207F488F79",
            "updatedAt": "1418377838193",
            "id": "dcb93e54401bcd8ed367cd8510c3256b5ca01a24",
            "updatedByUserId": "[email protected]",
            "category": "work",
            "createdAt": "1418377146577",
            "action": "Create",
            "deviceId": "3AFC225A-A5DE-4416-AFEF-5C88331C20FE",
            "processedAt": "1418377839094"
          },  
          "data": {
            "accountId": "1234567",
            "cartId": "A7989442-E961-4894-890D-60DD25B0957D",
            "cartType": "/Workflow/cartType[Order]",
            "createdByUser": "[email protected]",
            "currency": "/Global/currency[USD]",
            "customerPONumber": "890",
            "externalId": "0200297196",
            "lineItemType": "CartLineItem",
            "name": "A79895",
            "processStatus": "/Workflow/processStatus[Submit]",
            "processType": "/Workflow/cartType[Order]/processType[1]",
            "updatedByUser": "[email protected]",
            "userId": "[email protected]",
            "documentAmount": 0.0,
            "totalAmount": 56.25,
            "combineForInvoice": false,
            "locked": true,
            "verified": true,
            "createdAt": "2014-12-12T05:00:00+0000",
            "customerPODate": "2014-12-12T05:00:00+0000",
            "deliveryDate": "2014-12-13T05:00:00+0000",
            "verifiedAt": "2014-12-12T09:50:03+0000",
            "lineItems": [
              {   
                "lineItemId": "000010",
                "productId": "9023391",
                "requestedQuantity": "5",
                "uom": "/Data/uom[EA]",
                "productDescription": "TEST PRODUCT",
                "overridePrice": "0.000000000",
                "confirmedQuantity": "5",
                "confirmedUnitPrice": "11.250000000",
                "confirmedTotalPrice": "56.250000000",
                "comment": "", 
                "parentExternalId": "", 
                "parentLineItemId": "000000",
                "requestedTotalPrice": "0.000000000",
                "parentExternalType": "", 
                "priceName": "", 
                "cartId": "A7989442-E961-4894-890D-60DD25B0957D",
                "itemType": "Product",
                "itemId": "7211484f3a120798c47d75ce486ef1e9345aa7a1"
              }   
            ]   
          }   
        }   
]

POST Response

Response format conforms to LDS Query API specification (available upon request) and is an array list of objects, each object carrying information about transaction results. The response differs slightly depending on if TableData or Items is being used

POST Response TableData

For example, a response to the above TableData Cart transaction may look like this:

[
    {
        "status": "Completed",
        "reason": "Success",
        "message": "Cart succesfully received",
        "tableData":    [
            {
            "accountId": "ACCOUNTID1",
            "cartId": "93576A49-2EA0-4FA4-8E20-KIKIKK",
            "cartType": "/Workflow/cartType[Payment]",
            "createdByUser": "[email protected]",
            "currency": "",
            "customerMessage": "This is a Test customer message",
            "description": "",
            "freightTerms": "",
            "lineItemType": "CartLineItem",
            "logisticsCode": "",
            "logo": "",
            "mediaId": "",
            "name": "93576A",
            "orderNumber": "",
            "orgPath": "/Org/company[A]/businessUnit[B]",
            "processStatus": "/Workflow/processStatus[Submitted]",
            "lineItems": [
                      {
                        "uom": "/Data/uom[Case]",
                        "itemId": "011e52927903f0af1c6a36b83861938ae0596dc9",
                        "cartId": "93576A49-2EA0-4FA4-8E20-ERERGH",
                        "productDescription": 
                            "Some Product Sold in Cases",
                        "requestedTotalPrice": "12.0",
                        "productId": "014216DCDEND1P",
                        "itemType": "Product",
                        "requestedQuantity": "7",
                        "lineItemId": "000010"
                      },
                    {
                        "uom": "/Data/uom[Bottle]",
                        "itemId": "011e52927903f0af1c6a36b83861938ae0596dc9",
                        "cartId": "93576A49-2EA0-4FA4-8E20-ERERGH",
                        "productDescription": 
                            "Some Product Sold in Bottles",
                        "requestedTotalPrice": "12.0",
                        "productId": "014216DCDEND1P",
                        "itemType": "Product",
                        "requestedQuantity": "7",
                        "lineItemId": "000020"
                    }
                ]
            }
           ]
    }    
]
POST Response Items

For example, a response to the above Item Cart transaction may look like this:

[
    {
        "status": "Completed",
        "reason": "Success",
        "message": "Cart succesfully received",
        "items":        
        [
            {   
            "headers": {
            "community": "Test Community",
            "type": "Cart",
            "clientId": "12DC39E3-AA55-4265-BD04-96207F488F79",
            "updatedAt": "1418377838193",
            "id": "dcb93e54401bcd8ed367cd8510c3256b5ca01a24",
            "updatedByUserId": "[email protected]",
            "category": "work",
            "createdAt": "1418377146577",
            "action": "Update",
            "state": "TransactionCompleted",
            "receiptOccuredAt": "1418377838193",
            "deviceId": "3AFC225A-A5DE-4416-AFEF-5C88331C20FE",
            "processedAt": "1418377839094"
          },  
          "data": {
            "accountId": "1234567",
            "cartId": "A7989442-E961-4894-890D-60DD25B0957D",
            "cartType": "/Workflow/cartType[Order]",
            "createdByUser": "[email protected]",
            "currency": "/Global/currency[USD]",
            "customerPONumber": "890",
            "externalId": "0200297196",
            "lineItemType": "CartLineItem",
            "name": "A79895",
            "processStatus": "/Workflow/processStatus[Submitted]",
            "processType": "/Workflow/cartType[Order]/processType[1]",
            "updatedByUser": "[email protected]",
            "userId": "[email protected]",
            "documentAmount": 0.0,
            "totalAmount": 56.25,
            "combineForInvoice": false,
            "locked": true,
            "verified": true,
            "createdAt": "2014-12-12T05:00:00+0000",
            "customerPODate": "2014-12-12T05:00:00+0000",
            "deliveryDate": "2014-12-13T05:00:00+0000",
            "verifiedAt": "2014-12-12T09:50:03+0000",
            "lineItems": [
              {
                "lineItemId": "000010",
                "productId": "9023391",
                "requestedQuantity": "5",
                "uom": "/Data/uom[EA]",
                "productDescription": "TEST PRODUCT",
                "overridePrice": "0.000000000",
                "confirmedQuantity": "5",
                "confirmedUnitPrice": "11.250000000",
                "confirmedTotalPrice": "56.250000000",
                "comment": "", 
                "parentExternalId": "", 
                "parentLineItemId": "000000",
                "requestedTotalPrice": "0.000000000",
                "parentExternalType": "", 
                "priceName": "", 
                "cartId": "A7989442-E961-4894-890D-60DD25B0957D",
                "itemType": "Product",
                "itemId": "7211484f3a120798c47d75ce486ef1e9345aa7a1"
              }   
            ]   
          }   
        }   
        ]
    }    
]

Transacting Deletes

Transacting delete messages for items is done in one of two ways depending on if the TableData or Items option is being used.

TableData deletes

If delete transactions will be necessary and TableData is being used, a second url must be provided, any posts done to that URL will indicate a delete of the posted item. The post will look identical to the above TableData POST Body example.

Items deletes

In the header of the data being transacted there will be a field called "action". If action is set to "Delete" it indicates that a delete transaction is occurring. If it is set otherwise, it should be considerd as a Create or Update of the item. The post body will othewise look identical to the above Items POST Body example and will be sent to the same URL.

Error Handling

The endpoint should always return HTTP 200 OK. A non-200 response is considered a system error.

The endpoint should indicate error conditions in the "status" and "reason" fields of the POST response.

  • status indicates the status of the response,
  • reason indicates the reason for status,
  • message is an optional message with human readable explanation for both status and reason

Status codes can be as follows:

Status Description
Completed Transaction has been accepted by the endpoint
NoResult Transaction has resulted in an error and no result has been returned

Reason codes can be as follows:

Reason Description
Success Transaction has been accepted by the endpoint and processed successfully. If status==Completed and reason is not provided, reason is assumed to be Success
Error Transaction has resulted in a business logic error
SystemError A system error has prevented this transaction from being processed successfully

The endpoint should return the item that was sent in the HTTP POST with all modifications applied. For example, in case of Carts, the customer may want to populate "orderNumber" and update processStatus to the next workflow state. LDS will consider transaction a failure if status=Completed and tableData is null or empty.

results matching ""

    No results matching ""