FAQs

This means your API token is missing, expired, or does not match the environment you are calling.

Checklist:

1. Verify the Authorization: Bearer <token> header is present in your request
2. Confirm the token belongs to the same environment as the base URL:
   • Sandbox tokens → api-test.envia.com / queries-test.envia.com
   • Production tokens → api.envia.com / queries.envia.com
3. Check that the token has not been revoked in Dashboard → Desarrolladores → Acceso de API

Tokens are not interchangeable between environments. See API Authentication for setup details.

1. Create a production account at accounts.envia.com/signup
2. Generate a production API key in the production dashboard
3. Replace your base URLs (api-test → api, queries-test → queries)
4. Use separate webhook URLs for each environment

See the full Production Readiness Checklist for every item to verify before going live.

No. The Geocodes API has a single production URL (https://geocodes.envia.com/) and does not require a Bearer token. You can call it directly from a browser or frontend application.

The most common cause is incorrect state codes. Envia uses its own 2-letter state codes, which may differ from codes used by other platforms (Shopify, WooCommerce, ISO 3166-2, etc.).

For example, in Argentina:

Fix: Always retrieve Envia's state codes from the Queries API — do not reuse codes from other platforms.

GET https://queries.envia.com/state?country_code=AR

Full reference → Get States by Country

Use the Geocodes API — no authentication required:

GET https://geocodes.envia.com/zipcode/{country}/{postalCode}

The response returns the correct city, state code, and locality for that postal code. Use these values in your rate and label requests to avoid address-related errors.

Full reference → Validate Zip Code

Yes. Required fields, formats, and validation rules vary by country. Some countries require a district or locality field; others do not. Use the address structure endpoint to get the exact requirements:

GET https://queries.envia.com/address-structure/{country}

Full reference → Get Address Structure

Each carrier validates addresses independently with different strictness levels. Some carriers are strict about state codes, while others rely on postal codes.

To avoid issues across all carriers:

1. Validate postal codes using the Geocodes API to get the canonical state, city, and locality
2. Use Envia's 2-letter state codes from the Queries API — not codes from external platforms
3. Check the address structure for the destination country to ensure all required fields are present

Use the Queries API to get carriers by country:

GET https://queries.envia.com/carrier?country_code=AR

Replace AR with any supported 2-letter country code (MX, BR, CO, CL, US, CA, ES, IN, etc.).

For a real-time check that accounts for your account configuration, use the rate endpoint directly — it only returns carriers and services that can actually fulfill the shipment.

Full reference → Get Carriers by Country

Yes. Add the carrier field to the shipment object in your rate request:

{
  "shipment": {
    "carrier": "correoArgentino",
    "type": 1
  }
}

Omit the carrier field to get rates from all available carriers for the route. The rate endpoint accepts one carrier per request — to compare multiple carriers, call it once per carrier.

The shipment.type field accepts these values:

Most carriers support Parcel (type 1) only. Sending an unsupported type returns an error. Check the Supported Carriers page — the LTL column shows which carriers support LTL.

FTL (Full Truckload) shipments are currently managed through the cargo.envia.com platform and are not yet available via API.

Use the Queries API to get carriers filtered by shipment type:

GET https://queries.envia.com/available-carrier/{country}/{international}/{shipment_type_id}

Full reference → Get Available Carriers (Detailed)

Empty rate results usually mean one of:

1. The carrier does not serve the route — Verify carrier availability with the Queries API
2. Invalid address data — Validate postal codes with the Geocodes API and state codes with the Queries API
3. Unsupported package dimensions or weight — Each carrier has its own limits; check the Supported Carriers page
4. Wrong shipment type — Confirm the carrier supports the shipment.type value you are sending (most only support 1 for parcel)

Sandbox returns simulated rates for testing purposes. Production returns real rates from carriers based on your account's negotiated pricing, carrier contracts, and current surcharges. Always do final price validation in production.

Yes. Include the currency field in the settings object of your rate request:

{
  "settings": {
    "currency": "USD"
  }
}

If omitted, rates are returned in the default currency for your account's country.

This is a known behavior of the Shipping API. Some errors return HTTP 200 with "meta": "error" in the body instead of a 4xx status code.

Always check the meta field in every Shipping API response — do not rely solely on the HTTP status code.

{
  "meta": "error",
  "error": {
    "code": 400,
    "description": "Invalid Option",
    "message": "The origin.postalCode field is required."
  }
}

See Error Response Formats for the full error shapes returned by each API and a normalization helper.

Use the cancel endpoint with the shipmentId returned when the label was created:

POST https://api.envia.com/ship/cancel/

Cancelling a label before the carrier scans it triggers an automatic refund to your account balance. Once a carrier has scanned the package, cancellation may no longer be possible.

Full reference → Cancel Shipment

Yes. Include multiple objects in the packages array of your label request. Each package gets its own tracking number in the response.

See the Shipping Multiple Packages workflow guide for a complete example.

Pickup behavior varies by carrier — some support standalone scheduling, others schedule automatically during label creation, and some only accept drop-offs at branches. Use Get Carrier Actions to check what each carrier supports.

Full guide → Pickups concept page

Yes. The POST /ship/pickup/ endpoint accepts multiple tracking numbers in a single request. All tracking numbers must belong to the same carrier and originate from the same address. For high-volume operations, see the Pickup & Manifest Workflow.

Use the tracking endpoint with one or more tracking numbers:

POST https://api.envia.com/ship/generaltrack/

{
  "trackingNumbers": ["7072262094"]
}

The response includes the current status, carrier name, and a chronological list of events.

Full reference → Track Shipments

Checklist:

1. Your endpoint URL must be publicly reachable via HTTPS (not HTTP, not localhost)
2. Your endpoint must respond with a 2xx status code within 5 seconds — slower responses may be treated as failures
3. Verify the webhook is registered and active using GET https://queries.envia.com/webhooks
4. Confirm you registered separate webhook URLs for sandbox and production
5. Test delivery with the Test Webhook endpoint to isolate whether the issue is in registration or in your endpoint

See the Webhooks Guide for setup and troubleshooting details.

Webhooks may be delivered more than once (e.g., due to network retries). Implement idempotency by tracking the shipmentId and event type you have already processed. If you receive a duplicate, acknowledge it with a 2xx response but skip reprocessing.

International shipments require customs information in the customsSettings object, including:

• HS codes for each item (see HS Codes)
• Declared value per package
• Country of origin for manufactured goods
• Commercial invoice for certain destinations (see Commercial Invoice)

See the International Shipping Workflow for a complete step-by-step example.

It depends on the carrier and destination. Some carriers generate the commercial invoice automatically from the customs data in your label request. Others require you to upload it as a separate document.

Use the Commercial Invoice endpoint when a separate document is needed.

Use the HS code classification utility to get the correct code for your product:

Full reference → Classify HS Code

For a detailed explanation of how HS codes work and why they matter, see the HS Codes guide.