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. Cada paso viene en curl, Node (18 o posterior) y Python.

1. Crea un token de prueba

Abre Configuración → Desarrolladores → Tokens de API en el panel (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. Guárdalo en una variable de entorno y prepara una pequeña función que lo envíe como token bearer y añada un Idempotency-Key a cada escritura:

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

# Cada petición envía el token como token bearer. Necesitas curl, jq y uuidgen.
curl -s "$ANTIVIO/v1/shipments?limit=5" -H "Authorization: Bearer $ANTIVIO_TOKEN"

// quickstart.mjs: ejecútalo con ANTIVIO_TOKEN=atk_test_... node quickstart.mjs
const ANTIVIO = "https://api.antivio.app";

async function antivio(method, path, body, idempotencyKey = crypto.randomUUID()) {
  const res = await fetch(ANTIVIO + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.ANTIVIO_TOKEN}`,
      ...(method === "GET" ? {} : { "Idempotency-Key": idempotencyKey }),
      ...(body ? { "Content-Type": "application/json" } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.status} ${data.code}: ${data.detail}`);
  return data;
}

console.log(await antivio("GET", "/v1/shipments?limit=5"));

# quickstart.py: pip install requests, luego ANTIVIO_TOKEN=atk_test_... python quickstart.py
import os
import uuid

import requests

ANTIVIO = "https://api.antivio.app"
http = requests.Session()
http.headers["Authorization"] = f"Bearer {os.environ['ANTIVIO_TOKEN']}"


def antivio(method, path, body=None, idempotency_key=None):
    headers = {} if method == "GET" else {"Idempotency-Key": idempotency_key or str(uuid.uuid4())}
    res = http.request(method, ANTIVIO + path, json=body, headers=headers)
    data = res.json()
    if not res.ok:
        raise RuntimeError(f"{data['status']} {data['code']}: {data.get('detail')}")
    return data


print(antivio("GET", "/v1/shipments?limit=5"))

Los pasos de Node y Python que siguen se añaden al mismo archivo y reutilizan antivio().

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. Regístrala y envíale un mensaje de prueba:

# 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)

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

const WEBHOOK_URL = "https://..."; // la URL HTTPS del inspector o del túnel

const { endpoint, secret } = await antivio("POST", "/v1/webhook-endpoints", {
  url: WEBHOOK_URL,
  event_types: ["shipment.created", "shipment.status_changed", "shipment.delivered"],
});
console.log("Secreto de firma (guárdalo):", secret);

console.log(
  await antivio("POST", `/v1/webhook-endpoints/${endpoint.id}/test`, {
    event_type: "shipment.delivered",
  }),
);

WEBHOOK_URL = "https://..."  # la URL HTTPS del inspector o del túnel

created = antivio("POST", "/v1/webhook-endpoints", {
    "url": WEBHOOK_URL,
    "event_types": ["shipment.created", "shipment.status_changed", "shipment.delivered"],
})
print("Secreto de firma (guárdalo):", created["secret"])

print(antivio("POST", f"/v1/webhook-endpoints/{created['endpoint']['id']}/test",
              {"event_type": "shipment.delivered"}))

La primera respuesta trae secret (whsec_…): guárdalo para verificar las firmas. La respuesta de prueba muestra lo que contestó tu servidor.

3. Crea un envío

Los envíos van entre dos ubicaciones de tu libreta de direcciones. Crea las dos, luego un envío en borrador y luego confírmalo: confirmar le pone precio y número de seguimiento.

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.
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"

// Dónde se recoge el paquete y a dónde va.
const origin = await antivio("POST", "/v1/locations", {
  label: "Almacén",
  location: { lat: 18.4607, lng: -69.9177 },
});
const destination = await antivio("POST", "/v1/locations", {
  label: "Ana Pérez",
  location: { lat: 18.4719, lng: -69.8923 },
  address_text: "Calle El Conde 101",
  contact_phone: "+18095550199",
});

// Un borrador, y luego confírmalo. Tu número de pedido es un buen Idempotency-Key.
const shipment = await antivio(
  "POST",
  "/v1/shipments",
  {
    origin_location_id: origin.id,
    destination_location_id: destination.id,
    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 }],
  },
  "order-1001",
);
console.log(await antivio("POST", `/v1/shipments/${shipment.id}/confirm`, null, "confirm-1001"));

# Dónde se recoge el paquete y a dónde va.
origin = antivio("POST", "/v1/locations", {
    "label": "Almacén",
    "location": {"lat": 18.4607, "lng": -69.9177},
})
destination = antivio("POST", "/v1/locations", {
    "label": "Ana Pérez",
    "location": {"lat": 18.4719, "lng": -69.8923},
    "address_text": "Calle El Conde 101",
    "contact_phone": "+18095550199",
})

# Un borrador, y luego confírmalo. Tu número de pedido es un buen Idempotency-Key.
shipment = antivio("POST", "/v1/shipments", {
    "origin_location_id": origin["id"],
    "destination_location_id": destination["id"],
    "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}],
}, idempotency_key="order-1001")
print(antivio("POST", f"/v1/shipments/{shipment['id']}/confirm", 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

for (const to of ["pickup_assigned", "picked_up", "out_for_delivery", "delivered"]) {
  const moved = await antivio("POST", `/v1/sandbox/shipments/${shipment.id}/advance`, { to });
  console.log(moved.status);
}

for to in ["pickup_assigned", "picked_up", "out_for_delivery", "delivered"]:
    moved = antivio("POST", f"/v1/sandbox/shipments/{shipment['id']}/advance", {"to": to})
    print(moved["status"])

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").