English

Português

English

Português

Appearance

On this page

Quick Start Guide ​

Welcome to the TriStar Express API! This page will guide you through the essential steps to start integrating and testing our platform. Follow the steps below to quickly set up your test environment, create shipments, and attach documents.

1. Create a Test Account ​

To access the API, you first need to create a test account. Use the endpoint below to register and receive your authentication token:

http
POST /v1/create-account HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: x-www-form-urlencoded
Accept: application/json

name=John Doe&email=john.doe%40example.com&password=123456

The response will include your bearer_token. Store this token securely, as it is required for authenticating all API requests.

json
{
    "id": 1,
    "bearer_token": "1|mRxEle6EDfp4mtS4LwSMvPZt8OdAMBxEMY3CTtMm"
}

For more details, see Creating Test Account.

2. Create a Shipment ​

With your token, you can now create a shipment. Send a POST request to the /v1/shipments endpoint with the required shipment data. Be sure to include your token in the Authorization header:

http
POST /v1/shipments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer 1|mRxEle6EDfp4mtS4LwSMvPZt8OdAMBxEMY3CTtMm

{
    "integration_code": "1",
    "order_number": "1",
    "from_person_type": 1,
    "from_name": "Sender name",
    "from_document_type": 1,
    "from_document": "123456789",
    "from_country_code": "US",
    "from_postcode": "33013",
    "from_state_code": "FL",
    "from_address_1": "Av. Test",
    "from_address_number": "123",
    "from_city": "Miami",
    "from_email": "sender@example.com",
    "from_phone": "+1234567890",
    "to_person_type": 1,
    "to_name": "Jane Doe",
    "to_document_type": 1,
    "to_document": "07173967970",
    "to_address_1": "Avenida Presidente Kennedy",
    "to_address_number": "759",
    "to_city": "São Paulo",
    "to_country_code": "BR",
    "to_state_code": "SP",
    "to_postcode": "13334170",
    "to_email": "janedoe@example.com",
    "to_phone": "+5511999999999",
    "package_width": 12,
    "package_height": 14,
    "package_length": 13,
    "package_weight": 1.100,
    "package_freight": 0.01,
    "total": 100,
    "total_freight": 10,
    "total_tax": 5,
    "with_insurance": false,
    "items": [
        {
            "shipment_item_type": 10,
            "description": "PROTECTION FILM",
            "quantity": 1,
            "unit_price": 10
        }
    ]
}

The response will return the shipment details, including the id and tracking_code. These identifiers are used for further operations, such as attaching documents.

json
{
    "data": {
        "id": 1234,
        "order_number": "1",
        "integration_code": "1",
        "tracking_code": "TR000001234BR",
        "tracking_code_label": null,
        "to_usd_rate": null,
        "to_brl_rate": null,
        "created_by_id": 1,
        "updated_by_id": null,
        "created_at": "2025-06-23T15:38:40.000000Z",
        "updated_at": "2025-06-23T15:38:40.000000Z",
        "shipment_status": 1,
        "shipment_status_text": "Draft"
    }
}

For more details, see Create Shipment.

3. Attach Documents to a Shipment ​

You can attach documents to your shipment using either public URLs (JSON) or by uploading binary files (multipart/form-data). The shipment_id parameter in the endpoint can be either the shipment ID or the tracking code.

Attach using URLs (JSON) ​

http
POST /v1/shipments/{shipment_id}/attachments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer 1|mRxEle6EDfp4mtS4LwSMvPZt8OdAMBxEMY3CTtMm

{
    "attachments": [
        {
            "url": "https://example.com/documents/invoice.pdf",
            "document_code": "DOCUMENT"
        }
    ]
}

Attach using Binary Files (multipart/form-data) ​

http
POST /v1/shipments/{shipment_id}/attachments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: multipart/form-data
Accept: application/json
Authorization: Bearer 1|mRxEle6EDfp4mtS4LwSMvPZt8OdAMBxEMY3CTtMm

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="attachments[0][file]"; filename="invoice.pdf"
Content-Type: application/pdf

(binary data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="attachments[0][document_code]"

DOCUMENT
------WebKitFormBoundary7MA4YWxkTrZu0gW--

For more details, see Attach Documents to a Shipment.

4. Homologation Test Shipments ​

To complete the homologation process, you must create the following test shipments:

  1. Shipment with 2 items:

    • Item 1: USD 100.00
    • Item 2: USD 112.29

  2. Shipment with 3 items of different quantities:

    • Item 1: 2 units at USD 100.00 each
    • Item 2: 3 units at USD 110.10 each
    • Item 3: 5 units at USD 120.20 each

After creating these shipments, contact our IT team at support@tristarexpress.com to confirm your integration and homologation.