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.

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

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.

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 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

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": {"channelLabel": {"ouputFileName": {"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": {"channelLabel": {"outputFileName": [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

Sending document sometimes in 1SIDE, then in 2SIDE

Authenticate

• POST /authentication/authenticate
• withProfileDetail:true

- You need to parse the services array. From this you have to store the service/name and then go deeper in the properties.
- You need to keep the properties/boxes/@type properties/boxes/name (to drop your files in the appropriate box).
- You need to keep the properties/boxes/channels/label properties/boxes/channels/label/outputFilesConfig (to configure the output files options).
- Note: if a box has a coniguredFiles configuration, you need to store the serviceFileId and you will need to send it on the job creation. A configuredFile is often a background page

Options and types

• This is something to be done one time at loading. Options are not meant to change every week.
• POST /options/type, /options

- You need to look at the options/type print_mode (get the id) to manage 1SIDE/2SIDE.
- Then in the /options go to the result array and get the object named with the print_mode id, this will give you the 1SIDE and 2SIDE options ids
- Note: you can do it for each options, for example for print_color, which is also a simple option to manage

Create a job autocreateDeliveryCommand=false

• POST /jobs

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

- remember the BoxID was spomething you get from the service parsing when you auhenticate.
Note : if your service has preconfiguredFiles, you need to pass in the box the values
serviceFile__file_<BoxID_2>_0 : SERVICE_FILE_ID

Create the delivery with selected options

• POST /deliveries/commands

- {"jobId": "JobID","serviceChannelOptions": {"channelLabel": {"outputFileName": [OptionValue1, OptionValue2]}}}
- Note: use the channelLabel of the service (properties/channels/label). A common error is to send the channel name.
- Note: use the outputFileName from (properties/channels/outputFilesConfig). By default it should be MAIN. We strongly advise to not try to change options in other output files because they are not meant to be updated.
- Note: it's not mandatory to send all the OptionsValues of the outputFile, you only can send the value you override..

- Note: packgroupdsIds list is not mandatory if you want to send all the packgroups in one time.
- Note: expectedPostDate is not mandatory. By default it uses the earliest date possible. Otherwise send a future date in epochDateMillis before the channel cutOff (1733889600000 for December,11 5am)

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 national posts)
- metadataKind=TRACKING & metadataType=FILE & name=ACKN to get the acknowledgement PDF proof
- metadataKind=TRACKING & metadataType=FILE & name=FAIL_PROOF to get a failure 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