Skip to content

Instantly share code, notes, and snippets.

@nobordist

nobordist/api-v1-sellers.md

Last active December 17, 2024 21:02
Show Gist options
  • Save nobordist/0bd0c3d72a0ceff87b553b7ca58ee643 to your computer and use it in GitHub Desktop.
Save nobordist/0bd0c3d72a0ceff87b553b7ca58ee643 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
api-v1-sellers.md

Tutorial: Nobordist Integration Tutorial

What is this?

This tutorial aims at helping you integrate to the NB APIs (Seller API and Carrier API). It consists in a precise and complete to-do list that will walk you through the whole shipment process and will deliberately engage you in some mistakes and errors so that you can catch the techniques to solve them in case they appear for you in the future. The tutorial is pretty complete, so when you finish it succesfully, you can consider that you are fully integrated to Nobordist APIs. This tutorial is NOT an API DOC. If this is what you are looking for, please refer to the below section.

This tutorial is divided into 2 parts:

  • Seller API, used for creating packages
  • Carrier API, used for gathering packages into masterboxes and embarking flights.

Please refer to your CX contact to know to which of these API you have to integrate (to both, maybe). The Carrier API needs some test orders to work properly. You can use the Seller API tutorial to create them, if you plan to integrate to Seller API. On the contrary, you can ask your CX contact to create the necessary orders so that you can start integrating.

Resources

  1. API DOC The API DOC gathers the most comprehensive information of the 2 APIS. Click here to see the online API DOC for production. Click here to see the online API DOC for homologation. In both documents, you can select Carrier Docs or Seller Docs in the top right menu. Click here to download the API DOCs as an mht documents (readable off-line by any navigator).

  2. Postman collections We created 2 Postman collections to help you during the integration process. Please click here to download them.

  3. Tutorial You can download a PDF version of this tutorial clicking here.

  4. Ultimate zip file You can download a zip file containing

  • the PDF of this SOP
  • the API DOC in html format
  • the 2 postman collections by clicking here.

How to use

We recommend that you follow this tutorial in the natural order, without missing any section. We also highly recommend that you take a look at the API DOC during the tutorial process, as it contains more comprehensive information about some fields and requests that may not appear in this document. Last, you can use the Postman collections as a help to perform the exercises described in this tutorial.

Seller API

Overview

The Nobordist Seller API allows you to create and manage orders as well as their related labels, invoice and tracking histories. Access Here Tecnical doc) https://drive.google.com/file/d/1frIxmAyczfeWl0ynMOzloGX_3ry9m4up/view?usp=sharing

Base URL

  • Production: https://api.nobordist.com
  • Homologation : https://hmlapi.nobordist.com

1. Authentication

First of all, let's authenticate to the Nobordist API. This step will give you a Bearer Token, that will be necessary to authenticate at each of your Seller API requests.

You will need to use following request: POST/authenticate/{{platform}}/seller (Generate the API Token)

1.1 Understand Authentication error

At first, please copy and paste the following request body and call the request. Remember to replace `{{platform}}` by your actual platform (your CX contact will provide you with this information). 
{
  "email": "MY EMAIL",
  "password": "MY PASS"
}

You'll receive an error with the following message:

"user_authentication": "invalid email" This is absolutely normal as you have to first fill your actual email and password.

1.2 Authenticate with your credentials

To do that, please refer to your CX contact to get your email and password.

IMPORTANT: Your homolog credentials and production credentials are not necessary the same, please make sure to know if you want to login to homolog or production environment

Now, susbistute "MY EMAIL" and "MY PASS" in the previous json body and call the request again. This, time, you will get a 200 response, containing a field "auth_token". You should get a response similar to this:

{
  ...
  "auth_token": "eyJhbefakoo99998ZGciOiJIUjoihad8778728bibiu7Y78.HIOUQNiJ9.eyJ1c2VyX2lkIjoyNCjoxNzAwOTUzNTkyfQ.U7U-GeGwnV1Lw9dauMdfaiijazdjioazexuhZ_8Putn4lZLC0",
  ...
}

Now, just copy the value of the auth_token field and store it for future use.

Important: this token will expire exactly 24 hours after generation. Passing this time, you will have to generate it again.

2. Create an Order

Let's now create an order! You will need to use following request: POST/v1/orders (Create an Order)

2.1 Understand Authentication error

Let's perform a first try to create an order. Please copy and paste this json and call the request. To understand the fields, please refer to the documentation.

{
  "contract_id": 1,
  "order_number": "20231110",
  "customer_full_name": "cliente novo",
  "customer_document_type": "CPF",
  "customer_document_number": 14305162750,
  "customer_address": "Rua Salomão",
  "customer_address_number": 68,
  "customer_postal_code": "05442050",
  "customer_address_quarter": "Santa Ana",
  "customer_city": "Sao Paulo",
  "customer_state": "AAA",
  "customer_country": "AAA",
  "customer_phone": 11947399648,
  "customer_email": "[email protected]",
  "incoterm": "DDU",
  "currency": "USD",
  "return_insurance": false,
  "collected_taxes_currency": "USD",
  "prc": false,
  "seller_legal_name": "Seller LTDA",
  "seller_rfb_code": "999999",
  "volumes_attributes": [
    {
      "height": 12,
      "width": 12,
      "length": 17,
      "weight": 12,
      "freight_value": 9.99,
      "order_items_attributes": [
        {
          "name": "PS4",
          "description": "bb",
          "weight": 5,
          "value": 10,
          "hs_code": "660110",
          "sku": 1,
          "quantity": 1,
          "origin_country": "US"
        }
      ]
    },
    {
      "height": 12,
      "width": 12,
      "length": 17,
      "weight": 12,
      "freight_value": 9.99,
      "order_items_attributes": [
        {
          "name": "PS4",
          "description": "PS4 Console",
          "weight": 12,
          "value": 10,
          "hs_code": "851830",
          "sku": 1,
          "quantity": 1,
          "origin_country": "US"
        }
      ]
    }
  ]
}

You'll receive a response with the following message:

"messages": "Invalid token"

This appears because we have to pass the Authentification token in the request in order to prove our identity.

2.2 Resolving Authentication error and understand Validation errors

To resolve that, you just need to add a header called Authorization and fill it with the value Bearer 12345678, where 12345678 is the token you got from the Authentication request. If you are using Postman, you can also use the Authorization tab.

Texto Alternativo

Now call the request again It seems there are some (voluntary) mistakes in the body because we get a 422 response. You'll receive the following error:

{
  "data": {},
  "status": "ERROR",
  "messages": [
    {
      "customer_country": [
        "Wrong country code. Please use 2 letters (example: BR, US, CN ...)"
      ],
      "contract_id": [
    "Contract expired."
    ],
      "customer_state": [
        "No state AAA for , must be one of the official  letters state codes(for example ...)"
      ]
    }
  ]
}

All validations errors will always come in that format. As you can see, the list of erratic fields (customer_country, contract_idand customer_state) are listed and for each of them, the error is described in form of a simple sentence

2.3 Resolving Validation erros

Let's fix these errors. Correct the customer_country in your body, passing for example "BR" (Brazil). For thecustomer_state, pass "SP" (Sao Paulo state). Finally, ask your CX team which contract_id you have to use and replace the 1 by this id. Let's call the request again using the corrected body.

Congrats! Your order is now created and you have received a response that contains all informations about your order. The beginning of the response looks like this:

{
"data": {
"id": 96712,
...
}

This 96712is the Order ID, you internal reference number to the order. Store it for future use.

3. Get Order Information

Now, we will see how to retrieve the information of an order we created, using its order_id.

To do that, please call a request to GET/v1/orders/{order_id} (Get Order) , where {order_id} is the number you got in the last step. You'll receive a response that contains the details of the specific order, including the last mile tracking number (number which is on the label), found inside the volumesobject, field last_mile_tracking_number.

Important: Note that if you create various volumes, you will also see various last mile tracking numbers. Please remember also that this number creation could take up to a few seconds, so if you call the request very quickly, a temporary "nil" could appear in this field until the final number is generated.

4. Get All Orders

What if you want to retrieve various orders of if you forgot your order_id? You can use the GET/v1/orders (Get All Orders) request.

4.1 Create two more orders

At first time, we'll create 2 more orders to use as exemple using the following body request: 
{
"contract_id": 1,
"order_number": "20231111",
"customer_full_name": "cliente novo",
"customer_document_type": "CPF",
"customer_document_number": 14305162750,
"customer_address": "Rua Salomão",
"customer_address_number": 68,
"customer_postal_code": "05442050",
"customer_address_quarter": "Vila Carmela",
"customer_city": "Sao Paulo",
"customer_state": "SP",
"customer_country": "BR",
"customer_phone": 11947222348,
"customer_email": "[email protected]",
"incoterm": "DDU",
"currency": "USD",
"return_insurance": false,
"volumes_attributes": [
{
"height": 12,
"width": 12,
"length": 17,
"weight": 12,
"freight_value": 9.99,
"order_items_attributes": [
{
"name": "PS4",
"description": "bb",
"weight": 5,
"value": 10,
"hs_code": "660110",
"sku": 1,
"quantity": 1,
"origin_country": "US"
}
]
}
]
}

AND

{
"contract_id": 1,
"order_number": "20231112",
"customer_full_name": "cliente novo",
"customer_document_type": "CPF",
"customer_document_number": 14305162750,
"customer_address": "Avendia Atlantica",
"customer_address_number": 1702,
"customer_postal_code": "22021001",
"customer_city": "Rio de Janeiro",
"customer_state": "RJ",
"customer_country": "BR",
"customer_phone": 11947399148,
"customer_email": "[email protected]",
"incoterm": "DDU",
"currency": "USD",
"return_insurance": false,
"volumes_attributes": [
{
"height": 12,
"width": 12,
"length": 17,
"weight": 12,
"freight_value": 9.99,
"order_items_attributes": [
{
"name": "PS4",
"description": "bb",
"weight": 5,
"value": 10,
"hs_code": "660110",
"sku": 1,
"quantity": 1,
"origin_country": "US"
}
]
}
]
}

Call the Order Create request for these 2 bodies, successively, remembering to susbistute the contract_idwith the right number.

4.2 Get all the Orders

Now call the GET /v1/orders request and observe the response. There are 3 fields:

  • Inside the elementsfield, you will get the info of the 3 orders you have just created.

Important: By default, this request will only show the 15 first orders found (most recent first). If you want to see more orders, please use thelimit and offsetfilters. For example, if you want to see all orders between the 31th and the 40th most recent, include this body:

{
  "offset": 30,
  "limit": 10
}
  • Inside the ids field, you will see the list of all order_ids found, even the ones who are not displayed in the offset and limit filtering.
  • Inside the countfield, you will see the total amount of orders found (in other words, the number of ids in the idsfield.

4.3 Apply a filter

Let us suppose we want to see the informations of an order whose order_id we don't know. We can find it using, for example, the order_numberfield. Let's call the request passing this body:

{
  "order_number": "20231112"
}

Here it is! You found your order!

4.4 Apply multiple filter

You can also apply multiple filters at the same time. Here, let us filter by customer_stateand customer_city. Let's call the request passing this body:

{
 "customer_city": "Sao Paulo",
"customer_state": "SP"
}

Now, you will only see 2 of the 3 created orders, as only the first 2 correspond to these criteria.

4.5 Apply date filter

Last, let's see how to filter by date using these 2 filters:

  • start_registration_date : indicates that you want to see only the orders created on this date or after
  • end_registration_date : indicates that you want to see only the orders created on this date or before

Let's call the request passing this body:

{
  "start_registration_date": "2023-11-01",
  "end_registration_date": "2023-11-10"
}

You will get no order now, this is because you have not create any order between november 1st and november 10th, 2023. Change these dates to the current date, you will see all your orders in the response.

Important: The format is: YYYY-MM-DD

5. Get the invoice

Let's generate our first order's commercial Invoice.

To do that, please call that request PUT/v1/orders/{order_id}/commercial-invoice (Generate Commercial Invoice) , where {order_id} is the number you got in the 2. Create an Order step.

After that, you'll receive a similar response body:

{
  "data": {
    "download_url": "https://nb-logistics-local.s3.amazonaws.com/ex5qbagkdgeh08uqwk4vgame5b9p29362b72233d"
  },
  "status": "SUCCESS",
  "messages": [
    "Commercial invoice created"
  ]
}

Just copy and paste the value of the download_url field in your navigator and you will get your invoice, ready for display and download. The generated invoice looks like that:

Texto Alternativo

6. Get the label

Let's generate our first order's shipping label.

To do that, please call that request PUT/v1/orders/{order_id}/cn23-merged (Generate Last Mile Label) , where {order_id} is the number you got in the 2. Create an Order step.

After that, you'll receive a similar response body:

{
  "data": {
    "download_url": "https://nb-logistics-local.s3.amazonaws.com/ex5qbagkdgeh08uqwk4vgame5b9p29362b72233d"
  },
  "status": "SUCCESS",
  "messages": [
    "Label created"
  ]
}

Just copy and paste the value of the download_url field in your navigator and you will get your invoice, ready for display and download. The label looks like that: Texto Alternativo

7. Update Order

We will now suppose you want to update your order because you passed some informations wrong. Let's test this.

7.1 Simple update

Let's suppose you'll need to update the order_number and customer_name fields.

To do that make a request to PUT/v1/orders/{order_id} (Update Order)where {order_id} is the number you got in the2. Create an Order step

Important: You always have to pass the whole volumes_attributes field, even if you don't want to update it.

Copy and paste this body in the request.

{
  "order_number": "WZX-9999",
  "customer_name": "Jack Jim",
  "volumes_attributes": [
    {
"height": 12,
"width": 12,
"length": 17,
"weight": 12,
"freight_value": 9.99,
"order_items_attributes": [
{
"name": "PS4",
"description": "bb",
"weight": 5,
"value": 10,
"hs_code": "660110",
"sku": 1,
"quantity": 1,
"origin_country": "US"
}
]
}
]
}

After that, you'll receive a response containing the complete order data and a success message.

7.2 Check Updated Infos

Right now, we will prove the order has been updated the way we wanted

To do that, please make a request to GET/v1/orders/{order_id} passing order_id. Go look for the order_numberand customer_full_namefields and check that they have the updated values.

7.3 Understanding and resolve Update Errors

Let's now change the first item value from 10 to 33.

To do that, make a request to PUT/v1/orders/{order_id} passing the following body:

{  "volumes_attributes": [
    {
      "height": 12,
      "width": 12,
      "weight": 12,
      "freight_value": 9.99,
      "order_items_attributes": [
        {
          "name": "PS4",
          "description": "bb",
          "weight": 5,
          "value": 35,
          "hs_code": "660110",
          "sku": 1,
          "quantity": 1,
          "origin_country": "XX"
        }
      ]
    },
    {
      "height": 12,
      "width": 12,
      "length": 17,
      "weight": 12,
      "freight_value": 9.99,
      "order_items_attributes": [
        {
          "name": "PS4",
          "description": "PS4 Console",
          "weight": 12,
          "value": 10,
          "hs_code": "851830",
          "sku": 1,
          "quantity": 1,
          "origin_country": "US"
        }
      ]
    }
  ]
}

You will receive a error message like that:

{
"data": {},
"status": "ERROR",
"messages": [
{
"volumes[0].order_items[0].origin_country": ["Wrong country code. Please use 2 letters (example: BR, US, CN ...)"],
"volumes[0].length": ["can't be blank"]
}
]
}

This happened because you forgot a required field and did an error passing the origin_countryfield. To resolve that, correct "XX" to "US" for example, and add the "length" field, with value 12, for example. Now, you will receive a success if you call the request again.

7.4 Checking Update

Just like in the 7.2, call the GET /v1/orders/{order_id}request and look at the update data (the item value).

8. Delete Order

Let's now try to remove your order.

8.1 Delete an order

To delete an order, make a request to DELETE/v1/orders/{order_id} (Delete Order) replacing {order_id}by your order_id. After that you'll receive the following response:

{
  "data": {},
  "status": "SUCCESS",
  "messages": [
    "Order removed"
  ]
}

8.2 Checking Deletion

Right now, we will prove the order has been deleted

To do that, please make a request to GET/v1/orders/{order_id} passing order_id. You will receive a 404 response showing the order has been successfully removed.

9. Dispatch Order

9.1 What is dispatch

After you have created the order, it is very important you dispatch the order. This will inform us that you do not consider the order as a draft anymore and that we can start running all the necessary integrations and processes on it. Once the order is dispatched, you can not remove it or update it anymore. If you do not dispatch an order, we will not consider it as active and will not run tracking for it.

9.2 Creating a new order

At first, let's create a new order.

To do this, make a request to POST/v1/orders using the following body request, and changing the contract_id:

{
  "contract_id": 1,
  "order_number": "20231114",
  "customer_full_name": "cliente novo",
  "customer_document_type": "CPF",
  "customer_document_number": 14305162750,
  "customer_address": "Rua Salomão",
  "customer_address_number": 68,
  "customer_postal_code": "05442050",
  "customer_address_quarter": "Vila Carmela",
  "customer_city": "Sao Paulo",
  "customer_state": "SP",
  "customer_country": "BR",
  "customer_phone_country_code": "+55",
  "customer_phone": 11887313348,
  "customer_email": "[email protected]",
  "incoterm": "DDU",
  "currency": "USD",
  "return_insurance": false,
  "volumes_attributes": [
    {
      "height": 12,
      "width": 12,
      "length": 17,
      "weight": 12,
      "freight_value": 9.99,
      "order_items_attributes": [
        {
          "name": "PS4",
          "description": "bb",
          "weight": 5,
          "value": 10,
          "hs_code": "660110",
          "sku": 1,
          "quantity": 1,
          "origin_country": "US"
        }
      ]
    }
  ]
}

Store the order_id for the next steps.

9.3 Dispatch order

To do that make a request to PUTv1/orders/{order_id}/dispatch (Dispatch Order) where {order_id} is the number you got in the last step.

Very good! You have just dispatched your order!

9.4 Try to update the dispatched order

Let's try to update a dispatched order.

To do that make a request to PUT/v1/orders/{order_id} passing order_id.

You'll use the following body.

{
  "order_number": "WZX-9999",
  "customer_name": "Jack Jim"
}

After that, you'll receive a response containing an error and the following message:

{
  "data": {},
  "status": "ERROR",
  "messages": [
    "The order can not be removed because it is already dispatched"
  ]
}

Conclusion: it is impossible to update a dispatched order.

9.5 Try to delete a dispatched order

Let's try to delete a dispatched order.

To do that, make a request to DELETE/v1/orders/{order_id} passing order_id. After that you'll receive the following response:

{
  "data": {},
  "status": "ERROR",
  "messages": [
    "The order can not be removed because it is already dispatched"
  ]
}

Conclusion: it is impossible to delete a dispatched order.

10. Get the last tracking status

Let's get the last tracking status for a specific order by its order_id.

To get the last tracking status for an order, make a request to GET/v1/orders/{order_id}/status (Get Last Order Status) passing order_id. After that you'll receive a similar response:

{
  "data": {
    "status": {
      "id": 17,
      "date_iso": "2023-11-07T14:25:38.000Z",
      "attachment": null,
      "message": null,
      "order_id": 6,
      "created_at": "2023-11-07T14:25:38.726Z",
      "updated_at": "2023-11-07T14:25:38.726Z",
      "macro_status_id": 3,
      "micro_status_id": null,
      "platform_id": 1,
      "macro_status": {
        "id": 3,
        "type": "MACRO",
        "slug": "READY_TO_SHIP",
        "name": "READY TO SHIP",
        "description": "The order is ready to be dispatched",
        "name_pt": "PRONTO PARA DESPACHAR",
        "description_pt": "A remessa está pronta para ser despachado",
        "title_pt": "Pedido pronto para envio",
        "created_at": "2023-10-02T14:22:52.896Z",
        "updated_at": "2023-10-02T14:22:52.896Z",
        "tracking_code": 300,
        "title": "Order ready to be dispatched",
        "hierarchy_status": 300,
        "is_internal": false,
        "final_status": false,
        "zone_code": 1
      }
    },
    "attachments": []
  },
  "status": "SUCCESS",
  "messages": [
    "Checkpoint found"
  ]
}

Here, the relevant information is:

  • date_iso: the date of the event occurence
  • title: a brief sentence summing up the status
  • description: a longer sentence explaining the status
  • tracking_code: an internal number identifying the tracking status on our side.
  • message: some addictional information if provided by the transporter

You can download here the list of Nobordist checkpoints.

11. Get tracking status history

If you are interested in seeing not only the last status, but the whole hostory of statuses, try calling GET/v1/orders/{order_id}/checkpoints (Get Order Tracking History) passing order_id. You will see the list of all received statuses. Here, you would see 2 statuses corresponding to Order Creation (tracking_code 100) and Order Dispatch (tracking code 300).

Carrier API

Overview

The Nobordist Carrier API V1 allows you to create and manage masterboxes and flight, passing all the necessary data in order to embark the packages.

Base URL

  • Production: https://api.nobordist.com
  • Homologation : https://hmlapi.nobordist.com

1. Preparation work

To test the Carrier API, you will need some test orders. 2 options:

  1. Use your Seller API credentials to:
  • Authenticate to the Seller API
  • Create 10 orders using the example body presented in the section 2.1 of the Seller API, replacing the contract_id by your real contract_id and changing the order_number for each order
  • Dispatch all 10 orders
  1. Ask for your CX contact to create 10 orders for in carrier account.

2. Authentication

First of all, let's authenticate to the Nobordist API. This step will give you a Bearer Token, that will be necessary to authenticate at each of your Carrier API requests.

You will need to use following request: POST/authenticate/{{platform}}/carrier (Authenticate)

IMPORTANT: Please note the url is slightly different than for Seller API integration

Please copy and paste the following request body and call the request, replacing by your credentials given by your CX contact. Remember to replace {{platform}} by your actual platform (your CX contact will provide you with this information).

IMPORTANT: Please note your seller api and carrier api credentials are NOT the same.

{
  "email": "MY EMAIL",
  "password": "MY PASS"
}

Just as in the Seller API, store you 24 hours valid token for future use.

3. View Volumes

Let's now see how we can see the available packages we can use to compose our flights.

3.1 See all packages

You will need to use following request: GET /v1/volumes (Generate the API Token) . You will see all your 10 packages appear.

Important: By default, this request will only show the 15 first packages found (most recent first). If you want to see more packages, please use thelimit and offset filters. For example, if you want to see all packages between the 31th and the 40th most recent, include this body:

{
  "offset": 30,
  "limit": 10
}

3.2 Apply a date filter

Let's see how to filter by date using these 2 filters:

  • start_registration_date : indicates that you want to see only the packages created on this date or after
  • end_registration_date : indicates that you want to see only the packages created on this date or before

Let's call the request passing this body:

{
  "start_registration_date": "2023-11-01",
  "end_registration_date": "2023-11-10"
}

You will get no package now, this is because you have not created any package between november 1st and november 10th, 2023. Change these dates to the current date, you will see all your orders in the response.

Important: The format is: YYYY-MM-DD

3.3 Find by package number

Let's see how to find a package by its package number.

Let's call the request passing this body:

{
"package_number":  "NB000101618CN"
}

where "NB000101618CN" is replaced by the number you want to find. This way, you will find all your package information.

4. Create Masterbox

The first step to embark shipments is to create a masterbox. You can understand this as a grouping of packages.

4.1 Understand validation errors

You will need to use following request: POST /v1/masterboxes (Create Masterbox)

Let's create a masterbox using 2 of the 10 packages you have in your account. The request is straightforward, you only have to inform the list of last mile tracking numbers of the packages.

IMPORTANT: In the Seller API, this is the field called last_mile_tracking_number inside the volumes objects. In the Carrier API, GET /v1/volumes request, it is the field called package_number inside the numbers object.

You'll use the following body.

{
  "package_numbers": ["ABC123","DEF345"]
}

You will get a response explaining there are no such packages. This is correct, as ABC123 and DEF345 don't correspond to actual packages

4.2 Correct validation errors

To solve the issue, replace ABC123 and DEF345 with actual last mile tracking numbers of 2 of your packages. (If you do not have this info, use GET /v1/volumes to see the packages information and get the numbers.

IMPORTANT: Only volumes from orders that have been dispatched (seller API) can be used to create a masterbox.

You will now receive a response like:

{
    "data": {
        "request_id": "274d5ed0b31e381132be62d38085da9dbc7f5d26"
    },
    "status": "SUCCESS",
    "messages": [
        "Request initiated. Please use the request_id to consult its status"
    ]
}

This show the masterbox creation has initiated.

4.3 Consult creation status

Now, we can take the request_id from the response and use it to consult the creation status. Please remember the masterbox creation can take up to a few seconds.

You will need to use following request: GET /v1/request_status/create_masterbox/{request_id} (Consult Create Masterbox) where request_id is the string you got in the last response.

You will get such a response:

{
  "data": {
    "reference": "BRNBSTNBAAAAAAA1700637267121",
    "masterbox_id": 1068,
    "pdf_label_url": "https://nb-logistics-production.s3.amazonaws.com/9na1b2bgd4asqotj544bn1sq27a3b5686556b9819ee635f2eccab1c65a5d0f60d20db1a0bbc53bc079",
    "zpl_label_url": "https://nb-logistics-production.s3.amazonaws.com/mlztec6g91zh1ajiq0lb49cd340343aa4cea4f646f2dd43d0e10360a7dbf936f14b60dd89eb742f"
  },
  "status": "SUCCESS",
  "messages": [
    [
      "Box successfully created"
    ]
  ]
}

Here, you see that the masterbox was succesfully created. You get:

  • The masterbox reference, that you will use to create the flights in the next steps
  • The masterbox id, an internal reference to the masterbox
  • pdf_label_url, a link to the masterbox label in pdf format
  • zpl_label_url, a link to the masterbox label in zpl format

5. Get Masterbox Information

Now, we will see how to retrieve the information of a masterbox we created, using its id.

To do that, please call a request to GET/v1/masterboxes/{id} (Find Masterbox) , where {id} is the id you got in the last step. You'll receive a response that contain the details of the specific masterbox, including the reference number, the links to the label (pdf and zpl format), the list f packages inside the masterbox.

6. See all Masterboxes

What if you want to retrieve various masterboxes of if you forgot your id? You can use the GET/v1/masterboxes (View Masterboxes) request

6.1 Create an other masterbox

Use the 4. Create Masterbox section to create another masterbox, using two other packages you have not used so far.

6.2 Get all the Masterboxes

Now call the GET /v1/masterboxes request and observe the response. You will see your 2 masterboxes.

Important: By default, this request will only show the 15 first masterboxes found (most recent first). If you want to see more masterboxes, please use thelimit and offsetfilters. For example, if you want to see all masterboxes between the 31th and the 40th most recent, include this body:

{
  "offset": 30,
  "limit": 10
}
  • Inside the ids field, you will see the list of all ids found, even the ones who are not displayed in the offset and limit filtering.
  • Inside the countfield, you will see the total amount of masterboxes found (in other words, the number of ids in the idsfield.

6.3 Apply a filter

Let us suppose we want to see the informations of an order whose id we don't know. We can find it using, for example, the referencefield. Let's call the request passing this body:

{
  "reference": "YOUR REFERENCE"
}

where YOUR REFERENCE will be the reference of the masterbox you want to fetch.

Here it is! You found your masterbox!

.

6.4 Apply date filter

Just like the GET /v1/volumes request, you can use date filters.

Let's call the request passing this body:

{
  "start_registration_date": "2023-11-01",
  "end_registration_date": "2023-11-10"
}

changing these dates to the current date, you will see all your masterboxes in the response.

7. Create Flight

We will know follow the process and create a flight grouping the 2 already created masterboxes.

You will need to use following request: POST /v1/flights (Create Flight)

The request is straightforward, you only have to inform the list of last mile tracking numbers of the packages.

You'll use the following body.

{
  "box_numbers": ["BR12333","BR44444"]
}

where BR12333 and BR44444 should be replaced by the actual references of the 2 masterboxes you created. You will get a response similar to this

{
    "data": {
        "flight_id": 313
    },
    "status": "SUCCESS",
    "messages": [
        "Flight successfully created"
    ]
}

Very good! You have now created your flight, you can already see its id, generated by Nobordist. Store it as you will need it for the next steps

8. Update Flight Information

Now, we will see how to fill the information of a flight we created, using its id.

To do that, please call a request to PUT/v1/flights/{id} (Update Masterbox) , where {id} is the id you got in the last step.

Here is a body that you will copy and paste and call the request:

  

{
"departure_date":  "2020-01-05",
"arrival_date":  "2020-01-05",
"departure_time":  "11:45",
"arrival_time":  "13:00",
"airline":  "EE",
"departure_airport":  "SZX",
"arrival_airport":  "RIO",
"flight_number":  "1234",
"freight_value": 3200,
"mawb_number":  "49846186617",
"mawb_file_format":  "link",
"mawb_file":  "https://web.stanford.edu/group/csp/cs21/htmlcheatsheet.pdf"
}

You will get a success response indicating the flight has been updated with the information.

IMPORTANT: Here, we informed the MAWB file as a pdf. You can also inform it as a Base64 string, to do that just fill "binary" instead of "link" in the mawb_file_format field.

IMPORTANT: You can update flight information as many times as needed, but for security purposes you will always have to pass, at least, the mawb file in the request.

9. Get Flight Information

Now, we will see how to retrieve the information of an order we created, using its id.

To do that, please call a request to GET/v1/flight/{id} (Find Flight) , where {id} is the id of the flight . You'll receive a response that contain the details of the specific flight, including the list of boxes.

10. Get All Flights

Now, we will see how to access various flights' information.

What if you want to retrieve various flights of if you forgot your id? You can use the GET/v1/flights (View Flights) request

10.1 Get all the Flights

Call the GET /v1/flights request and observe the response. You will see your flight.

Important: By default, this request will only show the 15 first flights found (most recent first). If you want to see more flights, please use thelimit and offsetfilters. For example, if you want to see all flight between the 31th and the 40th most recent, include this body:

{
  "offset": 30,
  "limit": 10
}

10.2 Apply a filter

Let us suppose we want to see the informations of a flight whose id we don't know. We can find it using, for example, the mawb_numberfield. Let's call the request passing this body:

{
  "mawb_number": "YOUR MAWB"
}

The request will return no flight. Now, change "YOUR MAWB" to "49846186617" and you will see your flight in the response.

10.3 Apply date filter

Just like the GET /v1/volumes, request, you can use date filters.

Let's call the request passing this body:

{
  "start_registration_date": "2023-11-01",
  "end_registration_date": "2023-11-10"
}

changing these dates to the current date, you will see your flight in the response.

11. Updating a Flight content

What happens if you want to add a package to one of the masterboxes of the flight? You will need to first cancel the flight, then cancel the masterbox before creating them all over again. Let's try this.

11.1 Cancel the flight

To do that, please call a request to DELETE /v1/flights/{id} (Remove Flight) , where {id} is the id of the flight .

IMPORTANT: Doing so, you will loose all data referring to the flight (mawb, flight number and dates, freight value, ...)

11.2 Cancel the masterbox

To do that, please call a request to DELETE /v1/masterboxes (Remove Masterbox) with following body:

{
"box_number":  "BRNBSTNBAAAAAAA9955309067372"
}

replacing by the box_number(reference) of the box you want to delete. You will now receive a response like:

{
    "data": {
        "request_id": "274d5ed0b31e381132be62d38085da9dbc7f5d26"
    },
    "status": "SUCCESS",
    "messages": [
        "Request initiated. Please use the request_id to consult its status"
    ]
}

This show the masterbox deletion has initiated.

11.3 Consult deletion status

Now, we can take the request_id from the response and use it to consult the deletion status. Please remember the masterbox creation can take up to a few seconds.

You will need to use following request: GET /v1/request_status/remove_masterbox/{request_id} (Consult Remove Masterbox) where request_idis the string you got in the last response.

You will get a response indicating that the masterbox was successfully removed.

11.4 Recreate masterbox and flight

Now, you can create everything again:

  1. Create the Masterbox, adding an additional volume as compared to the last masterbox
  2. Consult the Masterbox creation Status
  3. Create a flight with the 2 masterboxes you have
  4. Update the flight information

12. Closing a Flight Manifest

We reached the very last step of the flow. Closing Manifest is a way for you to give us the "green light" about the shipment, indicating you have finished all the operations on the flight and itis ready to embark.

12.1 Close the Manifest

To do that, please call a request to PUT /v1/flights/{id}/close_manifest (Close Manifest) , where {id} is the id of the flight .

You will now receive a response like:

{
    "data": {
        "request_id": "274d5ed0b31e381132be62d38085da9dbc7f5d26"
    },
    "status": "SUCCESS",
    "messages": [
        "Request initiated. Please use the request_id to consult its status"
    ]
}

This show the manifest closing has initiated.

12.2 Consult closing status

Now, we can take the request_id from the response and use it to consult the closing status. Please remember the manifest closing can take up to a few seconds.

You will need to use following request: GET /v1/request_status/close_manifest/{request_id} (Consult Close Manifest) where request_id is the string you got in the last response.

You will get a response indicating that the flight was successfully closed.

12.3 Removing a flight after closing manifest

Let's try to remove the flight. To do that, please call a request to DELETE /v1/flights/{id} , where {id} is the id of the flight .

You will get an error.

IMPORTANT: After Closing the Manifest, you can not remove the flight anymore, its contents (masterboxes and packages) are definitely fixed.

12.4 End of the process

If you reached this step, it means you ended the process and you are now fully integrated! Congratulations! If you have suggestions, comments or complains to make about this tutorial, please feel free to send your thoughts to [email protected] .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment