Integration Guide

What you'll build

By the end of this guide you will have a production-ready integration that:

Validates customer addresses before shipping
Discovers available carriers and services per route
Quotes rates, purchases labels, and tracks shipments
Receives real-time status updates via webhooks
Runs on production with live carriers

This guide walks you through the complete integration path. Follow it from top to bottom and you'll go from zero to production-ready shipping.

Where you are

flowchart LR
  A["1. Setup"] --> B["2. Validate"] --> C["3. Discover"] --> D["4. Ship"] --> E["5. Monitor"] --> F["6. Go Live"]
  style A fill:#1873dc,color:#fff
  style F fill:#1873dc,color:#fff

Phase 1 — Setup (15 minutes)

Get your credentials and make your first API call.

Step	What to do	API	Reference
Create a sandbox account	Sign up at accounts-sandbox.envia.com/signup	—	Auth & Environments
Generate an API key	Dashboard → Settings → API → Add	—	Auth & Environments
Test your token	Make a GET request to the Queries API	Queries	See below

Test that your token works:

curl --request GET \
  --url https://queries-test.envia.com/webhook-types \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN"

If you get a JSON response with webhook types, your token is working.

Phase 2 — Validate addresses (Geocodes API)

Before shipping, validate your customer's address to prevent failed deliveries.

Endpoint	Purpose	When to use
Validate Zip Code	Verify a postal code and get city/state	Address form submission
Locate City	Find city details by name	Autocomplete / fuzzy search

curl --request GET \
  --url "https://geocodes.envia.com/zipcode/MX/64060" \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN"

Phase 3 — Discover carriers and services (Queries API)

Find out which carriers serve a given route before quoting rates.

Endpoint	Purpose	When to use
Available Carriers	List carriers for a country	Build carrier selector
Available Services	List services for a carrier/country	Build service selector
Address Structure	Get required address fields per country	Build dynamic address forms

See Common Queries Endpoints for a focused guide on the most-used discovery endpoints.

Phase 4 — Ship (Shipping API)

This is the core loop your application will execute for every order:

flowchart LR
  Rate["Get Rates"] --> Label["Create Label"] --> Track["Track"]
  Label --> Pickup["Schedule Pickup"]
  Label --> Cancel["Cancel"]

Step	Endpoint	What it does
Get rates	Quote Shipments	Returns available services with prices for one carrier
Create label	Create Shipping Label	Purchases a label, returns tracking number and PDF
Track	Track Shipments	Returns status and event history for tracking numbers
Schedule pickup	Schedule Pickup	Requests carrier pickup at your address
Cancel	Cancel Shipment	Voids a label and releases the charge

For complete request/response examples of every step, see the Core Workflow guide.

💡
Tip: The rate endpoint accepts one carrier per request. To compare carriers, call it once per carrier or use the Queries API to narrow down your choices first.

Phase 5 — Monitor with webhooks

Instead of polling the tracking endpoint, register a webhook to receive real-time updates.

Step	API	Endpoint
List available webhook types	Queries	`GET /webhook-types`
Register your endpoint	Queries	`POST /webhooks`
Test delivery	Shipping	Test Webhook

curl --request POST \
  --url https://queries-test.envia.com/webhooks \
  --header "Authorization: Bearer $ENVIA_SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "type_id": 3,
    "url": "https://your-app.com/webhooks/envia",
    "active": 1
  }'

Phase 6 — Go to production

When your sandbox integration is working end-to-end, switch to production. See the full Production Readiness Checklist to make sure nothing is missed.

Quick summary:

Create a production account at accounts.envia.com/signup
Generate a production API key
Replace base URLs (api-test → api, queries-test → queries). Note: the Geocodes API already uses the production URL in both environments
Use separate webhook URLs for production
Fund your account balance before creating labels

What to read next

Ready to code? The Core Workflow guide walks through every API call with full request/response examples in cURL, JavaScript, and Python
Specific use case? Check the workflow guides for domestic, international, multi-package, or pickup & manifest shipping
Going live? Use the Production Readiness Checklist to make sure nothing is missed before switching to production
Need carrier details? See Supported Carriers for a full list of carriers, services, and label formats

🛟
Need Help?
Have questions or need assistance with your integration?
Our support team is ready to help 🚀
Create a support ticket here and we’ll guide you with setup, troubleshooting, or feature requests.