Operaciones asíncronas

Elige entre la respuesta síncrona predeterminada y la compra asíncrona opcional de guías.

Una operación asíncrona acepta el trabajo y devuelve un recurso que puedes consultar. No necesitas mantener abierta la conexión hasta recibir la guía.

Hoy este patrón es opcional para la compra de guías. El mismo endpoint admite los dos modos.

Esta página explica cómo elegir y operar cada modo. Consulta Guías para ver el contrato completo, todos los campos y los errores del endpoint.

Elige el modo correcto

Modo	Cómo pedirlo	Respuesta inicial	Úsalo cuando
Síncrono	Omite `async` o envía `false`	`201 Created` con la guía	Compras pocas guías y quieres el resultado en la misma petición
Asíncrono	Envía `async: true`	`202 Accepted` con un intento	Procesas volumen o necesitas liberar la conexión pronto

El modo síncrono es el predeterminado. No necesitas cambiar una integración existente.

Inicia una compra asíncrona

curl -i -X POST https://api.sendit.mx/v1/shipments/clxq1w2e3r4t5y6u7i8o9p0a/label \
  -H "X-API-Key: sk_test_..." \
  -H "Idempotency-Key: 1f0e6f0e-59a4-4a6f-9d2e-9b1a7b2c3d4e" \
  -H "Content-Type: application/json" \
  -d '{ "rateId": "DHL_standard_a1b2c3", "async": true }'

La respuesta 202 incluye Location, Retry-After: 2 y statusUrl. Retry-After es una sugerencia, no una garantía de finalización. Este extracto muestra los campos necesarios para empezar a consultar; la página de Guías contiene el recurso completo.

{
  "success": true,
  "data": {
    "id": "lat_550e8400-e29b-41d4-a716-446655440000",
    "object": "label_purchase_attempt",
    "shipmentId": "clxq1w2e3r4t5y6u7i8o9p0a",
    "status": "pending",
    "livemode": false,
    "async": true,
    "statusUrl": "/v1/label-purchase-attempts/lat_550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-08-01T10:00:00.000Z",
    "updatedAt": "2026-08-01T10:00:00.000Z",
    "completedAt": null
  }
}

Consulta el resultado

Envía GET al statusUrl con una llave que tenga labels:read:

curl https://api.sendit.mx/v1/label-purchase-attempts/lat_550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: sk_test_..."

`status`	Qué significa	Qué haces
`pending`	La compra fue aceptada	Espera antes de consultar otra vez
`processing`	La compra está en curso	Sigue consultando con espera gradual
`succeeded`	La guía está lista	Usa `label` y termina el sondeo
`failed`	La compra falló y el intento terminó	Lee `error`; puedes corregir la causa y hacer una compra nueva
`action_required`	El resultado no es concluyente	No compres otra guía para ese envío; conserva el intento y contacta a soporte

El endpoint oculta si un ID pertenece a otra organización o a otro modo. Esos casos y un ID inexistente devuelven el mismo 404.

Recibe la finalización por webhook

Suscríbete a label.purchase.completed para evitar sondeo continuo. El evento cubre succeeded, failed y action_required.

Las entregas de webhook son al menos una vez. Deduplica con el id del evento y vuelve a consultar el intento antes de actualizar tu estado final.

Reintenta sin duplicar la compra

Envía un Idempotency-Key y conserva la llave con tu operación. Una repetición exacta devuelve el mismo intento activo.

Si cambias el rateId, el formato, la referencia externa o el valor de async, la API devuelve 409 SHIPMENT_LABEL_IN_PROGRESS. Consulta el intento existente.

Un saldo insuficiente devuelve 402 INSUFFICIENT_BALANCE antes de aceptar trabajo. No queda un intento pendiente.

Consulta el contrato completo en Guías y la protección de reintentos en Idempotencia.