Inicio rápido

Vas a crear un token de prueba, crear un envío, recibir sus webhooks y llevarlo hasta entregado, sin conductor ni dinero real. Necesitas curl y jq.

1. Crea un token de prueba

En el panel de Antivio abre Configuración → Desarrolladores → Tokens de API (comercios: Portal → Desarrolladores) y elige Crear token:

Modo: Prueba. Los tokens de prueba solo ven y crean envíos de sandbox.
Permisos: shipments:write, rates:read, webhooks:write.

Copia el token (atk_test_…). Solo se muestra una vez.

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

Cada petición lo envía como token bearer:

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

2. Recibe webhooks

Sirve cualquier URL HTTPS pública. Para una primera prueba usa un inspector de peticiones (por ejemplo https://webhook.site) o expón tu servidor local con un túnel.

# Tu receptor: la URL HTTPS del inspector o del túnel.
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"            # guarda .secret
ENDPOINT_ID=$(echo "$ENDPOINT" | jq -r .endpoint.id)

La respuesta trae secret (whsec_…): guárdalo para verificar las firmas. Comprueba el endpoint con un mensaje de prueba:

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"}'

La respuesta muestra lo que contestó tu servidor.

3. Crea un envío

Los envíos van entre dos ubicaciones de tu libreta de direcciones.

El token de un comercio (creado en el portal de clientes) siempre actúa para la cuenta de ese comercio. Un token de la empresa (creado en Configuración) actúa para toda la empresa: añade "customer_account_id": "…" para indicar de qué cliente es cada ubicación y cada envío.

# Dónde se recoge el paquete y a dónde va.
ORIGIN=$(curl -s "$ANTIVIO/v1/locations" -H "Authorization: Bearer $ANTIVIO_TOKEN" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"label": "Almacén", "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)

# Un borrador, y luego confírmalo (le pone precio y número de seguimiento).
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"

Tu endpoint recibe shipment.created y luego shipment.status_changed (draft → ready).

Consejo: usa tu número de pedido como Idempotency-Key. Si la petición se queda sin respuesta, envíala de nuevo con la misma clave: recibes la primera respuesta en lugar de un segundo envío.

4. Llévalo hasta entregado

En modo de prueba el simulador mueve un envío de sandbox un paso a la vez, con las mismas reglas que sigue una entrega real:

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

Cada paso envía shipment.status_changed, y el último también shipment.delivered.

5. Pasa a producción

Crea un token real con los permisos que necesites y un endpoint real apuntando a tu URL de producción. Los tokens reales y de prueba usan los mismos endpoints y mensajes; los endpoints de prueba solo reciben eventos de sandbox y los reales solo eventos reales ("livemode").

Todas las guías