Quickstart

What you'll build

By the end of this guide you will have:

1. Quoted shipping rates from a carrier in the sandbox
2. Purchased a shipping label with a tracking number and PDF
3. Tracked the shipment to see status updates

All in 3 API calls using your sandbox token — no real charges, no real packages.

Visual flow

flowchart LR
  Quote["Get Quote"]
  Generate["Generate Label"]
  Track["Track Shipment"]

  Quote --> Generate --> Track

Before you begin

• Create a sandbox account and token (see Auth & Environments).
• Choose a carrier to quote. Note: The rate endpoint supports one carrier per request.

Step 1 — Quote rates

Description

Retrieve available services and prices for a single carrier based on origin, destination, and package details.

Required parameters

• origin (address object)
• destination (address object)
• packages (array with at least one package)
• shipment (object with type and carrier)

Optional parameters

• settings (currency, comments)
• customsSettings (international shipments)
• shipment.service (quote a specific service only)

curl --request POST \
  --url https://api-test.envia.com/ship/rate/ \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": {
      "name": "Warehouse MX",
      "phone": "+52 8180000000",
      "street": "Av. Benito Juarez",
      "city": "Monterrey",
      "state": "NL",
      "country": "MX",
      "postalCode": "64060"
    },
    "destination": {
      "name": "Luis Perez",
      "phone": "+52 5511111111",
      "street": "Insurgentes Sur",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "03100"
    },
    "packages": [
      {
        "type": "box",
        "content": "T-shirts",
        "amount": 1,
        "declaredValue": 1200,
        "lengthUnit": "CM",
        "weightUnit": "KG",
        "weight": 2.5,
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 10
        }
      }
    ],
    "shipment": {
      "type": 1,
      "carrier": "dhl"
    }
  }'

Response example

{
  "meta": "rate",
  "data": [
    {
      "carrier": "dhl",
      "service": "ground",
      "serviceDescription": "DHL Economy",
      "deliveryEstimate": "3-5 business days",
      "deliveryDate": {
        "date": "2025-10-11",
        "timeUnit": "days",
        "dateDifference": 3
      },
      "totalPrice": "185.20",
      "currency": "MXN"
    }
  ]
}

Step 2 — Create a shipping label

Description

Purchase a label using the selected carrier service. This returns a tracking number and label URL.

Required parameters

• origin
• destination
• packages
• shipment (must include carrier and service)

Optional parameters

• settings (currency, comments)
• customsSettings (international shipments)
• packages[].additionalServices (insurance, COD, signature)

curl --request POST \
  --url https://api-test.envia.com/ship/generate/ \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": {
      "name": "Warehouse MX",
      "phone": "+52 8180000000",
      "street": "Av. Benito Juarez",
      "city": "Monterrey",
      "state": "NL",
      "country": "MX",
      "postalCode": "64060"
    },
    "destination": {
      "name": "Luis Perez",
      "phone": "+52 5511111111",
      "street": "Insurgentes Sur",
      "city": "Ciudad de Mexico",
      "state": "CMX",
      "country": "MX",
      "postalCode": "03100"
    },
    "packages": [
      {
        "type": "box",
        "content": "T-shirts",
        "amount": 1,
        "declaredValue": 1200,
        "lengthUnit": "CM",
        "weightUnit": "KG",
        "weight": 2.5,
        "dimensions": {
          "length": 30,
          "width": 20,
          "height": 10
        }
      }
    ],
    "shipment": {
      "type": 1,
      "carrier": "dhl",
      "service": "ground"
    }
  }'

Response example

{
    "meta": "generate",
    "data": [
        {
            "carrier": "dhl",
            "service": "ground",
            "shipmentId": 166819,
            "trackingNumber": "7072262094",
            "folio": "",
            "trackUrl": "https:\/\/test.envia.com\/rastreo?label=7072262094&cntry_code=mx",
            "label": "https:\/\/s3.us-east-2.amazonaws.com\/envia-staging\/uploads\/dhl\/70722620941331699ce80043013.pdf",
            "packages": [
                {
                    "trackingNumber": "7072262094",
                    "trackUrl": "https:\/\/test.envia.com\/rastreo?label=7072262094&cntry_code=mx",
                    "content": "paquete 2",
                    "weight": 1,
                    "weightUnit": "KG"
                }
            ],
            "additionalFiles": [],
            "totalPrice": 271.65,
            "currentBalance": 9840370,
            "currency": "MXN"
        }
    ]
}

Step 3 — Track the shipment

Description

Retrieve status updates for one or more tracking numbers.

Required parameters

• trackingNumbers (array)

curl --request POST \
  --url https://api-test.envia.com/ship/generaltrack/ \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"trackingNumbers": ["7072262094"]}'

Response example

{
  "meta": "track",
  "data": [
    {
      "trackingNumber": "7072262094",
      "status": "In transit",
      "carrier": "dhl",
      "events": [
        {
          "timestamp": "2025-10-08T12:30:00Z",
          "location": "Monterrey, MX",
          "description": "Shipment picked up"
        },
        {
          "timestamp": "2025-10-09T17:15:00Z",
          "location": "San Luis Potosi, MX",
          "description": "In transit"
        }
      ]
    }
  ]
}

Errors & troubleshooting

Sandbox vs production notes

• Sandbox base URL: https://api-test.envia.com/
• Production base URL: https://api.envia.com/
• Use separate tokens for each environment; tokens are not interchangeable.

You just shipped your first package!

You have successfully completed the core shipping flow in the sandbox:

1. Quoted rates from a carrier
2. Created a shipping label with a tracking number
3. Tracked the shipment status

You're ready to build this into your application. Here's where to go next:

Next steps

• Build the full flow – The Core Workflow guide adds pickups, cancellations, manifests, and webhooks to what you just learned.
• Plan your integration – The Integration Guide walks through every phase from address validation to going live.
• Try a specific scenario – Follow the domestic, international, or multi-package workflow guides for end-to-end examples.