This is the right section for you if you are acting as a fulfillment provider and looking to send dispatch instruction responses to a supplier.

Throughout this guide you will learn how to send new dispatch instruction responses to the Procuros API.

PHP examples are included but you will likely also want to look at the relevant API calls in the API reference.

​
Process

These are usually the steps taken when sending a dispatch instruction response to Procuros:

  1. Check, if this document should be sent via Procuros (see: Enabled Trade Partners)
  2. Verify this document has not already been sent (see: Tracking Document Status)
  3. Build the transaction payload to be sent via Procuros
  4. Send the transaction payload via the Procuros API

​
Authentication

You will need an API token to authenticate. We use a bearer token which has to be included in each request you send to the API.

Please read the Authentication section of our API reference for a detailed description.

​
Error Handling

The API will return a 2xx status code for successful requests. Anything else indicates an error.

Please read the Errors section of our API reference for a detailed description plus examples of how to handle them.

​
Send Dispatch Instruction Responses

The API call Send transaction is used to create transactions, including dispatch instruction responses.

The following fields are required:

  • type (Transaction type. In this case DISPATCH_INSTRUCTION_RESPONSE)
  • content (The details of the dispatch instruction response.)

Inside the content you will need to build all dispatch instruction response items. All details can be found in the DISPATCH_INSTRUCTION_RESPONSE schema as described in the API reference.

An example request would look like:

// install dependency
// $ composer require guzzlehttp/guzzle

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$transaction = [
    "type" => "DISPATCH_INSTRUCTION_RESPONSE",
    "content" => [
        "header" => [
            "orderId" => null,
            "orderDate" => null,
            "shipmentId" => "48148",
            "shippingNoticeIdentifier" => "SHIPMENT-123",
            "shippingNoticeDate" => "2022-10-12T12:53:51.000000Z",
            "dispatchInstructionResponseDate" => "2022-10-12T12:53:51.000000Z",
            "responseDate" => "2022-10-12T12:53:51.000000Z",
            "shipmentDate" => "2022-10-12T12:53:51.000000Z",
            "requestedDeliveryDate" => "2022-10-11T22:00:00.000000Z",
            "expectedDeliveryDate" => "2022-10-11T22:00:00.000000Z",
            "shipFrom" => [
                "name" => "Foo GmbH",
                "identifiers" => [
                    [
                        "domain" => "GS1",
                        "identifier" => "GS1",
                    ],
                ],
                "postalAddress" => [
                    "name" => "Foo",
                    "street" => "Musterstraße 123",
                    "addressExtra" => "1st Floor",
                    "city" => "Hamburg",
                    "postalCode" => "12345",
                    "state" => "HH",
                    "countryCode" => "DE",
                ],
                "contacts" => [
                    [
                        "title" => "Dr.",
                        "salutation" => "Herr",
                        "firstName" => "Max",
                        "lastName" => "Muster",
                        "phone" => "+49 12345",
                        "mobile" => "+49 12345",
                        "email" => "[email protected]",
                        "fax" => "+49 12345",
                    ],
                ],
            ],
            "shipTo" => [
                "name" => "Foo GmbH",
                "identifiers" => [
                    [
                        "domain" => "GS1",
                        "identifier" => "GS1",
                    ],
                ],
                "postalAddress" => [
                    "name" => "Foo",
                    "street" => "Musterstraße 123",
                    "addressExtra" => "1st Floor",
                    "city" => "Hamburg",
                    "postalCode" => "12345",
                    "state" => "HH",
                    "countryCode" => "DE",
                ],
                "contacts" => [
                    [
                        "title" => "Dr.",
                        "salutation" => "Herr",
                        "firstName" => "Max",
                        "lastName" => "Muster",
                        "phone" => "+49 12345",
                        "mobile" => "+49 12345",
                        "email" => "[email protected]",
                        "fax" => "+49 12345",
                    ],
                ],
            ],
            "billTo" => [
                "name" => "Foo GmbH",
                "identifiers" => [
                    [
                        "domain" => "GS1",
                        "identifier" => "GS1",
                    ],
                ],
                "postalAddress" => [
                    "name" => "Foo",
                    "street" => "Musterstraße 123",
                    "addressExtra" => "1st Floor",
                    "city" => "Hamburg",
                    "postalCode" => "12345",
                    "state" => "HH",
                    "countryCode" => "DE",
                ],
                "contacts" => [
                    [
                        "title" => "Dr.",
                        "salutation" => "Herr",
                        "firstName" => "Max",
                        "lastName" => "Muster",
                        "phone" => "+49 12345",
                        "mobile" => "+49 12345",
                        "email" => "[email protected]",
                        "fax" => "+49 12345",
                    ],
                ],
            ],
            "buyer" => [
                "name" => "Foo GmbH",
                "identifiers" => [
                    [
                        "domain" => "GS1",
                        "identifier" => "GS1",
                    ],
                ],
                "postalAddress" => [
                    "name" => "Foo",
                    "street" => "Musterstraße 123",
                    "addressExtra" => "1st Floor",
                    "city" => "Hamburg",
                    "postalCode" => "12345",
                    "state" => "HH",
                    "countryCode" => "DE",
                ],
                "contacts" => [
                    [
                        "title" => "Dr.",
                        "salutation" => "Herr",
                        "firstName" => "Max",
                        "lastName" => "Muster",
                        "phone" => "+49 12345",
                        "mobile" => "+49 12345",
                        "email" => "[email protected]",
                        "fax" => "+49 12345",
                    ],
                ],
            ],
            "supplier" => [
                "name" => "Foo GmbH",
                "identifiers" => [
                    [
                        "domain" => "GS1",
                        "identifier" => "GS1",
                    ],
                ],
                "postalAddress" => [
                    "name" => "Foo",
                    "street" => "Musterstraße 123",
                    "addressExtra" => "1st Floor",
                    "city" => "Hamburg",
                    "postalCode" => "12345",
                    "state" => "HH",
                    "countryCode" => "DE",
                ],
                "contacts" => [
                    [
                        "title" => "Dr.",
                        "salutation" => "Herr",
                        "firstName" => "Max",
                        "lastName" => "Muster",
                        "phone" => "+49 12345",
                        "mobile" => "+49 12345",
                        "email" => "[email protected]",
                        "fax" => "+49 12345",
                    ],
                ],
            ],
            "comments" => null,
        ],
        "transportUnits" => [
            [
                "unitIdentifier" => "342601560208144493",
                "unitType" => null,
                "containedTradeUnitCount" => null,
                "items" => [
                    [
                        "lineNumber" => 4,
                        "shippingNoticeLineNumber" => 1,
                        "shippedQuantity" => 1,
                        "orderedQuantity" => 1,
                        "isDepositItem" => false,
                        "identifiers" => [
                            [
                                "domain" => "GS1",
                                "identifier" => "abc",
                            ],
                        ],
                        "unitOfMeasure" => "EA",
                        "unitPrice" => null,
                        "currency" => null,
                        "description" => "",
                        "batches" => [
                            [
                                "batchIdentifier" => "abc",
                                "expirationDate" => "2022-12-31",
                                "quantity" => 30,
                            ],
                        ],
                        "parentLineNumber" => null,
                        "openQuantityAction" => null,
                    ],
                ],
            ],
        ],
    ],
];

$response = $client->request('POST', 'https://api.procuros.io/v2/transactions', [
  'headers' => [
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <your-api-token>',
  ],
  'json' => $transaction,
]);

​
Mark Document Status

Finally, as per the instructions mentioned under Tracking Document Status you must now track the status of the document locally, based on the returned HTTP response.

The document should be marked with either status TRANSMITTED or NO_ACTION. If there is an error with the document and it is not accepted, do not mark it with a status so it may be retried. For more information on retrying failed documents, please see: Retrying Documents.

For example:

$statusCode = $response->getStatusCode();

if ($statusCode == 201) {
  $document->updateProcurosStatus("TRANSMITTED");
} else if ($statusCode == 202) {
  $document->updateProcurosStatus("NO_ACTION");
} else {
  // No need to do anything if it's not accepted, in an error case the document should be retried.
}

Was this page helpful?