Quickstart

You will make a test token, create a shipment, receive its webhooks and walk it to delivered, without a driver or real money. You need curl and jq.

1. Make a test token

In the Antivio dashboard open Settings → Developers → API tokens (merchants: Portal → Developers) and choose Create token:

Mode: Test. Test tokens only see and create sandbox shipments.
Scopes: shipments:write, rates:read, webhooks:write.

Copy the token (atk_test_…). It is shown once.

export ANTIVIO_TOKEN=atk_test_...
export ANTIVIO=https://api.antivio.app

Every request sends it as a bearer token:

curl -s "$ANTIVIO/v1/shipments?limit=5" -H "Authorization: Bearer $ANTIVIO_TOKEN"

2. Receive webhooks

Any public HTTPS URL works. For a first try use a request inspector (for example https://webhook.site) or expose your local server with a tunnel.

# Your receiver: the inspector's or the tunnel's HTTPS URL.
export WEBHOOK_URL=https://...

ENDPOINT=$(curl -s "$ANTIVIO/v1/webhook-endpoints" \
  -H "Authorization: Bearer $ANTIVIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url": "'"$WEBHOOK_URL"'",
       "event_types": ["shipment.created", "shipment.status_changed", "shipment.delivered"]}')
echo "$ENDPOINT"            # keep .secret
ENDPOINT_ID=$(echo "$ENDPOINT" | jq -r .endpoint.id)

The answer has secret (whsec_…): keep it to verify signatures. Check the endpoint with a test message:

curl -s "$ANTIVIO/v1/webhook-endpoints/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $ANTIVIO_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{"event_type": "shipment.delivered"}'

The answer shows what your server replied.

3. Create a shipment

Shipments go between two locations of your address book.

A merchant's token (made in the customer portal) always acts for that merchant's account. A company token (made under Settings) acts for the whole company: add "customer_account_id": "…" to say which customer each location and shipment belongs to.

# Where the parcel is picked up, and where it goes.
ORIGIN=$(curl -s "$ANTIVIO/v1/locations" -H "Authorization: Bearer $ANTIVIO_TOKEN" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"label": "Warehouse", "location": {"lat": 18.4607, "lng": -69.9177}}' | jq -r .id)
DESTINATION=$(curl -s "$ANTIVIO/v1/locations" -H "Authorization: Bearer $ANTIVIO_TOKEN" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"label": "Ana Pérez", "location": {"lat": 18.4719, "lng": -69.8923},
       "address_text": "Calle El Conde 101", "contact_phone": "+18095550199"}' | jq -r .id)

# A draft, then confirm it (prices it and gives it a tracking number).
SHIPMENT=$(curl -s "$ANTIVIO/v1/shipments" -H "Authorization: Bearer $ANTIVIO_TOKEN" \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-1001" \
  -d '{"origin_location_id": "'$ORIGIN'", "destination_location_id": "'$DESTINATION'",
       "recipient_name": "Ana Pérez", "recipient_phone": "+18095550199",
       "external_ref": "ORDER-1001",
       "parcels": [{"weight_g": 1000, "length_mm": 300, "width_mm": 200, "height_mm": 100}]}' | jq -r .id)
curl -s -X POST "$ANTIVIO/v1/shipments/$SHIPMENT/confirm" \
  -H "Authorization: Bearer $ANTIVIO_TOKEN" -H "Idempotency-Key: confirm-1001"

Your endpoint gets shipment.created, then shipment.status_changed (draft → ready).

Tip: use your order number as the Idempotency-Key. If the request times out, send it again with the same key: you get the first answer instead of a second shipment.

4. Walk it to delivered

In test mode the simulator moves a sandbox shipment one step at a time through the same rules a real delivery follows:

for to in pickup_assigned picked_up out_for_delivery delivered; do
  curl -s "$ANTIVIO/v1/sandbox/shipments/$SHIPMENT/advance" \
    -H "Authorization: Bearer $ANTIVIO_TOKEN" -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" -d '{"to": "'$to'"}'
done

Each step sends shipment.status_changed, and the last one shipment.delivered.

5. Go live

Make a live token with the scopes you need and a live endpoint pointing at your production URL. Live and test tokens use the same routes and messages; test endpoints only receive sandbox events and live endpoints only live ones ("livemode").

All guides