Sandbox y simulador

Construye y prueba tu integración sin conductores, destinatarios ni dinero. Con un token de prueba, cada envío que creas es un envío de sandbox que tú mismo haces avanzar.

Pruébalo en cuatro pasos

Crea un token de prueba (atk_test_…) en Configuración → Desarrolladores. Los tokens de prueba solo ven y crean envíos de sandbox, aunque la empresa ya opere en real.
Crea y confirma un envío como en el inicio rápido. Los borradores no se simulan: confirmar le pone precio y número de seguimiento.
Avánzalo un paso a la vez con el simulador (abajo). Cada paso envía los mismos eventos y webhooks que una entrega real.
Revisa qué hizo tu sistema: tu endpoint de webhooks recibió mensajes con "livemode": false, y GET /v1/shipments/{id} muestra el estado y el historial.

Simulador

POST /v1/sandbox/shipments/{id}/advance lleva un envío de sandbox al estado indicado en to, por la misma máquina de estados que usan las entregas reales. La respuesta es el envío.

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

// antivio() es la función del inicio rápido.
const moved = await antivio("POST", `/v1/sandbox/shipments/${shipmentId}/advance`, {
  to: "picked_up",
});
console.log(moved.status); // "picked_up"

# antivio() es la función del inicio rápido.
moved = antivio("POST", f"/v1/sandbox/shipments/{shipment_id}/advance", {"to": "picked_up"})
print(moved["status"])  # "picked_up"

POST /v1/sandbox/shipments/{id}/advance
Authorization: Bearer atk_test_…
Idempotency-Key: 3f1c…
Content-Type: application/json

{ "to": "picked_up" }

Adónde puede mover el simulador un envío

Entrega

ready
pickup_assigned
picked_up
at_hubniveles de servicio con hub
out_for_delivery
delivered

Intento fallido

out_for_delivery
attempt_failed
out_for_deliveryquedan intentos

attempt_failed
return_in_transitintentos agotados
returned

Problemas

…cualquier estado abierto
exception
closed_exception

Todos los pasos que permiten las reglas:

Desde	`to`
`ready`	`pickup_assigned`, `at_hub` (entrega del cliente en el hub, niveles con hub)
`pickup_assigned`	`picked_up`
`picked_up`	`out_for_delivery` (niveles directos), `at_hub` (niveles con hub)
`at_hub`	`out_for_delivery`, `return_in_transit` (sin intentos restantes)
`out_for_delivery`	`delivered`, `attempt_failed`
`attempt_failed`	`out_for_delivery` (con intentos restantes), `at_hub`, `return_in_transit` (sin intentos)
`return_in_transit`	`returned`
cualquier estado abierto	`exception`
`exception`	`closed_exception`

Un paso que las reglas no permiten responde 409 con el código de la máquina de estados (por ejemplo shipment.hub_required o shipment.attempts_remaining).
Los tokens reales reciben 403 sandbox.live_token; los envíos reales 409 sandbox.live_shipment.
Solo se mueve el envío (su estado, intentos e historial); las tareas de conductor no cambian.

Qué es real en el sandbox

Un token de prueba solo ve y solo crea envíos de sandbox. Lo impone la base de datos, no solo la API.
Una empresa todavía en revisión crea envíos de sandbox con cualquier token.
Los envíos de sandbox son gratis, no se ofrecen a conductores y no envían nada a los destinatarios. Todo lo demás es real: validaciones, precios, números de seguimiento, etiquetas, eventos y webhooks.
Los mensajes de webhook de envíos de sandbox llevan "livemode": false y solo van a endpoints de prueba.
Un token de prueba lee la libreta de direcciones compartida pero solo cambia o archiva las ubicaciones que él creó, y nunca ve etiquetas ni endpoints reales.