DOCSEARCHbyAlgolia
Submit Docs

TriStar Express API

website·Indexed 31 days ago

https://api-documentation.tristarexpress.com

API documentation for TriStar Express, providing tools for fast air freight management. Features include shipment creation (v1/shipments), bulk shipment processing, tracking (v1/tracking/{id}), shipment label downloads, and document attachments. The API also supports webhook configurations for event notifications, stock management, and lookup endpoints for countries, states, airports, and currencies.

Tokens
9.7K
Snippets
55
Records
60
Agent score
49%

What's inside TriStar Express

  1. Retrieve detailed stock information by ID

    Use the /v1/stocks/{id} endpoint to get detailed information about a specific stock record, such as the amount of items currently in stock and associated provider details. The request requires a bearer token for authorization and expects a JSON response.
    GET /v1/stocks/1 HTTP/1.1
Host: sandbox.tristarexpress.com
Accept: application/json
Authorization: {{ token }}

  2. Retrieve shipment details by ID or order number

    Retrieve detailed information about a specific shipment using the /v1/shipment/{id} endpoint. You must provide at least one identifier: either the Tristar ID as a path parameter or the order number as a URL query parameter.
    GET /v1/shipment/1?order_number=031045 HTTP/1.1
Host: sandbox.tristarexpress.com
Accept: application/json
Authorization: {{ token }}

  3. Create a TriStar Express test account

    To begin integrating with the TriStar Express API, you must first create a test account to obtain a bearer_token. This token is required for authenticating all subsequent API requests. Send a POST request to the /v1/create-account endpoint on the sandbox host using x-www-form-urlencoded content type.
    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

  4. Configure Webhooks in the system

    Webhooks are automated notifications sent via HTTP POST requests to a specified URL when system events occur (e.g., when a shipment is created). To set up a webhook, navigate to the Integrations menu and select the Create webhook button to define the destination URL.

  5. Create a shipment in TriStar Express

    Create a shipment by sending a POST request to /v1/shipments. You must include your bearer_token in the Authorization header as a Bearer token. The request body requires detailed sender and receiver information, package dimensions, weights, and an array of items. The response provides a shipment id and tracking_code used for further operations.
    POST /v1/shipments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_TOKEN_HERE

{
    "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
        }
    ]
}

  6. General requirements for Tristar Express API requests

    All API requests must be made using the HTTPS protocol. The request body must be sent in JSON format, unless performing a file upload, in which case multipart/form-data must be used.
    POST /api/v1/shipments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: application/json
Accept: application/json

  7. Complete the Homologation Test process

    To finalize integration and achieve homologation, you must create two specific test shipments in the sandbox environment:

    1. Two-item shipment: Item 1 (USD 100.00) and Item 2 (USD 112.29).
    2. Three-item shipment with varying quantities:
      • Item 1: 2 units @ USD 100.00 each
      • Item 2: 3 units @ USD 110.10 each
      • Item 3: 5 units @ USD 120.20 each

    Once these shipments are created, contact the IT team at support@tristarexpress.com for confirmation.

  8. Upload binary documents to a shipment

    Upload binary files to a shipment using multipart/form-data. The {shipment_id} path parameter can be either the shipment ID or the tracking code. Each file must be accompanied by a document_code.
    POST /v1/shipments/{shipment_id}/attachments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: multipart/form-data
Accept: application/json
Authorization: Bearer YOUR_TOKEN_HERE

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

  9. Create a shipment via the /v1/shipments endpoint

    To create a shipment, send a POST request to the /v1/shipments endpoint. The request requires detailed sender and receiver information, package dimensions, and item details.

    Key Parameter Requirements:

    • Sender/Receiver Person Type: Use 1 for Individual and 2 for Legal entities.
    • Sender Document Type: Use 1 for TAX_ID and 2 for PASSPORT.
    • Country Codes: Use ISO3166 codes (e.g., US/USA, BR/BRA, PT/PRT).
    • Dimensions: Width, height, and length must be provided in centimeters. Weight must be in Kilograms using a dot (.) as the decimal separator.
    • Financials: Total declared value, freight, and tax are required. Use a dot (.) as the decimal separator for all decimal fields.
    • Insurance: The with_insurance boolean indicates if insurance should be added.
    {
  "from_person_type": 1,
  "from_name": "John Doe",
  "from_address_1": "123 Main St",
  "from_address_number": "100",
  "from_city": "New York",
  "from_country_code": "US",
  "from_state_code": "NY",
  "from_postcode": "10001",
  "from_email": "sender@example.com",
  "from_phone": "+123456789",
  "to_person_type": 1,
  "to_name": "Jane Doe",
  "to_document_type": 1,
  "to_document": "123456789",
  "to_company_name": "Recipient Co",
  "to_trading_name": "Recipient Trading",
  "to_br_ie": "IE12345",
  "to_address_1": "456 Ave B",
  "to_address_number": "200",
  "to_city": "Sao Paulo",
  "to_country_code": "BR",
  "to_state_code": "SP",
  "to_postcode": "01000-000",
  "to_email": "receiver@example.com",
  "to_phone": "+551199999999",
  "package_width": 20,
  "package_height": 15,
  "package_length": 30,
  "package_weight": 1.5,
  "total": 100.00,
  "total_freight": 20.00,
  "total_tax": 5.00,
  "with_insurance": true,
  "items": []
}

  10. Attach documents to a shipment via URL

    Attach documents to a shipment by providing public URLs in a JSON request. The {shipment_id} path parameter can be either the numeric shipment ID or the alphanumeric tracking code.
    POST /v1/shipments/{shipment_id}/attachments HTTP/1.1
Host: sandbox.tristarexpress.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_TOKEN_HERE

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

  11. Authenticate API requests using Bearer tokens

    To identify your application and access API resources, include your authentication token in the Authorization header of every request using the Bearer scheme.
    POST /v1/authentication HTTP/1.1
Host: sandbox.tristarexpress.com
Authorization: Bearer {token}

  12. Handle shipment tracking event additions

    When a tracking event is appended to a shipment (shipment.tracking_event_appended), the payload provides the shipment_id, tracking_id, tracking_event_id, the current state of the shipment, and the detailed tracking_event object including localized titles and descriptions.
    {
    "event": "shipment.tracking_event_appended",
    "payload": {
        "shipment_id": 4,
        "tracking_id": 7,
        "tracking_event_id": 79,
        "shipment": {
            "id": 4,
            "order_number": "716142",
            "tracking_code": "TR150262",
            "tracking_code_label": "LBL913636",
            "created_by_id": 1,
            "updated_by_id": 3,
            "created_at": "2023-06-28T20:57:23+00:00",
            "updated_at": "2023-07-06T13:28:58+00:00",
            "shipment_status": 10,
            "shipment_status_text": "Confirmed"
        },
        "tracking_event": {
            "id": 7,
            "tracking_event_id": 79,
            "code": "PCD",
            "title_locale": {
                "en-US": "Order confirmed.",
                "pt-BR": "Pedido confirmado."
            },
            "short_description_locale": {
                "pt-BR": "Pedido confirmado."
            },
            "note": null,
            "country_id": null,
            "state_id": null,
            "event_at": "2023-07-06T13:28:58.000000Z",
            "created_at": "2023-07-06T13:28:58.000000Z",
            "created_by_id": 3,
            "updated_at": "2023-07-06T13:28:58.000000Z",
            "updated_by_id": null
        }
    },
    "event_at": "2023-07-06T13:28:59+00:00"
}