Find below some information on the steps to create your orders using the API
We will present all the elements needed to create a job, update the options, check the returns...

Authentication & logout

Authentication
  • POST /authentication/authenticate
  • withProfileDetail:true
- WithProfile:true is needed to create a job, not to track a job. You will need to parse and store informations about the services.
- authenticate with the user who will perform the order.
- The service array must be parsed to get the serviceId (use it in next steps, and identify the MAIN boxes identifiers).
- In the next requests, use the header X-Auth-Token with the token return by the authentication.
Logout
  • /authentication/logout
  • X-Auth-Token header with the token you get from the authenticate
- After you process your requests, do not forget to clean and logout.

Channel options types and values

Options types
  • GET options/type
  • X-Auth-Token header with the token you get from the authenticate
- parse the result array to store name, id
Each entry refers to an option for the channels : printMode, envelopeType...
Note : production ant test environment do not use the same ids.
Note : each provider has its own set of options. For example in PostGreen instance, the Belgian provider does not use C4P envelopes
Options
  • GET options
  • X-Auth-Token header with the token you get from the authenticate
- parse the result array to store values, id and related option type
This is mandatory if you want to change the default 1SIDE printMode of the service with the 2SIDE printMode for example

Create a job

Classic job with autocreate deliveries
  • POST /jobs
  • X-Auth-Token header with the token you get from the authenticate
parameters : {"jobName":"MyJobName","serviceId":"MyServiceID","autocreateDeliveryCommand":true}
file_main<BoxID_1>_0 : first file in BoxID_1
file_main<BoxID_1>_1 : second file in BoxID_1
file_main<BoxID_2>_0 : first file in BoxID_2

- We use autocreateDeliveryCommand=true, you won't be able to update the service options.
- If you get a return, it's OK, you can continue. Otherwise, the files you sent are probably not compatible with the service you used.
- If the statuts received is PACK_GROUP_CREATED, store the jobId returned. You have to check the DELIVERIES are created, and the PACKGROUP statuses.
--- For a job with 1 PACKGROUP to send, look and the packGroupCountPerStates. NOT_ELIGIBLE:1 means you have an issue.
--- For a job with N DOCUMENT to send call the GET /jobs/{jobId}/packGroups and check the status.
- If the statuts received is PROCESSING_ERROR, the files are not correct (impossible to split, to extract content...).
- If it's another status, the job is still processing, you can ask each 2 or 3 minutes.
Classic job
  • POST /jobs
  • X-Auth-Token header with the token you get from the authenticate
parameters : {"jobName":"MyJobName","serviceId":"MyServiceID","autocreateDeliveryCommand":false}
file_main<BoxID_1>_0 : first file in BoxID_1
file_main<BoxID_1>_1 : second file in BoxID_1
file_main<BoxID_2>_0 : first file in BoxID_2

- We use autocreateDeliveryCommand=false to be able to update the service options.
- If you get a return, it's OK, you can continue. Otherwise, the files you sent are probably not compatible with the service you used.
- If the statuts received is PACK_GROUP_CREATED, store the jobId returned. You have to check the DELIVERIES are created, and the PACKGROUP statuses.
--- For a job with 1 PACKGROUP to send, look and the packGroupCountPerStates. NOT_ELIGIBLE:1 means you have an issue.
--- For a job with N DOCUMENT to send call the GET /jobs/{jobId}/packGroups and check the status.
- If the statuts received is PROCESSING_ERROR, the files are not correct (impossible to split, to extract content...).
- If it's another status, the job is still processing, you can ask each 2 or 3 minutes.
Mail merged job
  • POST /jobs
  • X-Auth-Token header with the token you get from the authenticate
parameters : {"jobName": "MyJobName","serviceId": "MyServiceID", "autocreateDeliveryCommand":false, "packRequirements": { "POSTAL_ADDRESS_RECIPIENT": {"@type":"exv.Value","value":"NIRVA SOFTWARE\n65 RUE HENON\n69004 LYON"}}
file_main<BoxID_1>_0 : first file in BoxID_1
file_main<BoxID_1>_1 : second file in BoxID_1
file_main<BoxID_2>_0 : first file in BoxID_2

- We use autocreateDeliveryCommand=false to be able to update the service options.
- If you get a return, it's OK, you can continue. Otherwise, the files you sent are probably not compatible with the service you used.
- If the statuts received is PACK_GROUP_CREATED, store the jobId returned. You have to check the DELIVERIES are created, and the PACKGROUP statuses.
--- For a job with 1 PACKGROUP to send, look and the packGroupCountPerStates. NOT_ELIGIBLE:1 means you have an issue.
--- For a job with N DOCUMENT to send call the GET /jobs/{jobId}/packGroups and check the status.
- If the statuts received is PROCESSING_ERROR, the files are not correct (impossible to split, to extract content...).
- If it's another status, the job is still processing, you can ask each 2 or 3 minutes.

Editing a packgroup (to fix errors)

Get Job packgroups
  • /jobs/{jobId}/packGroups
- Send the parameter jobId
- A packgroup is a non-composed element that will go either to email, or to mail, or... This is not yet the shipment. - You will find the problem in the eligibility
Update packGroup
  • /packGroups/{packGroupId}/edit
- Remember to edit the RAW value of the pack

Check delivery (autocreateDeliveryCommand=true)

Check deliveries if autocreateDeliveryCommand=true
  • GET /deliveries?jobId<myJobId>
  • X-Auth-Token header with the token you get from the authenticate
- If ALL the deliveries of the job are READY or OUTPUTTED then we can consider that it is OK
- If no return, you have an error somewhere, probably an incorrect address. You will need to access the packgroups to check

Create delivery (autocreateDeliveryCommand=false)

Check accessible options for the delivery
  • POST /deliveries/CheckOptions?jobId<myJobId>
  • X-Auth-Token header with the token you get from the authenticate
- As a result you will get the accessible options for your deliveries.
- This will be something like "result": {"selectableOptions": {"packId": {"channelName": {"boxName": {"OptionType1": [OptionValue1, OptionValue2, OptionValue3], "OptionType1": [OptionValeur4]}
- You will need to match with the optionsTypes and options
Create the delivery with selected options
  • POST /deliveries/commands
  • X-Auth-Token header with the token you get from the authenticate
- {"jobId": "JobID","packGroupIds": [packId1, packID2,....],"serviceChannelOptions": {"channelName": {"boxName": [OptionValue1, OptionValue2]}}}
- You delivery should then be created

The address page is not an option you can configure on the delivery creation process.
The address page exists or not and it's configured in the service

Track shipments (and get proofs)

A good approach is to track the delivery
Get delivery information
  • GET /deliveries?jobId<myJobId>
  • X-Auth-Token header with the token you get from the authenticate
- Check that the status is OUTPUTTED. If not, just wait for the output triggers.
- Otherwise you will get a list of shipments and you can parse each of them looking for some information (metadata)

Shipment metadata
- metadataKind=TRACKING & metadataType=SHORT_VALUE & name=TRACKING to get the registered tracking number
- metadataKind=TRACKING & metadataType=FILE & name=TRACKING_DETAIL to get a json complete tracking from (LaPoste_Fr or LaPoste_Be national posts)
- metadataKind=TRACKING & metadataType=FILE & name=ACKN to get the acknowledgement PDF proof
- metadataKind=TRACKING & metadataType=FILE & name=CERTIF to get he deposit PDF proof
You can get a proof using GET /shipments/<shipmentId>/trackingFile/trackingName