Lotes y manifiestos

Compra guías en lote de forma asíncrona, con resultados parciales y manifiestos por paquetería.

Un lote (batch) compra guías para hasta 100 envíos en una sola llamada. El procesamiento es asíncrono: la petición regresa de inmediato con un batchId y tú consultas el avance.

Compra en lote

Parámetros del cuerpo

PropType

shipmentIdsstring[]

Hasta 100 IDs de envíos de tu organización. Los duplicados se deduplican; los que ya tienen guía se saltan.

Typestring[]

curl -X POST https://api.sendit.mx/v1/batches \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "shipmentIds": ["clxship_aaa", "clxship_bbb", "clxship_ccc"] }'

Respuesta 202 Accepted:

{
  "success": true,
  "data": {
    "id": "bat_xyz",
    "status": "PENDING",
    "totalShipments": 3,
    "purchasedCount": 0,
    "failedCount": 0,
    "createdAt": "2026-07-17T12:00:00.000Z"
  }
}

Reglas del lote:

Máximo 100 envíos por lote; todos de tu organización.
Los IDs duplicados se deduplican automáticamente.
Los envíos que ya tienen guía válida se saltan (cuentan como exitosos).

Sigue el avance

PENDING → PROCESSING → COMPLETED | PARTIAL | FAILED

Estado	Significado
`PENDING`	En cola, aún no inicia
`PROCESSING`	Comprando guías
`COMPLETED`	Todas las guías compradas
`PARTIAL`	Algunas compradas, otras fallaron
`FAILED`	Ninguna guía comprada

Consulta con GET /v1/batches/:id:

{
  "success": true,
  "data": {
    "id": "bat_xyz",
    "status": "PARTIAL",
    "totalShipments": 3,
    "purchasedCount": 2,
    "failedCount": 1,
    "purchasedShipmentIds": ["clxship_aaa", "clxship_bbb"],
    "failedItems": [
      {
        "shipmentId": "clxship_ccc",
        "errorCode": "INSUFFICIENT_BALANCE",
        "errorMessage": "Wallet balance too low for this shipment"
      }
    ]
  }
}

Un manifiesto agrupa varias guías de la misma paquetería en un solo documento que el repartidor escanea una vez al recolectar. Se genera automáticamente al completarse el lote cuando todas las guías compradas son de la misma paquetería.

El manifiesto viene en la respuesta del lote cuando está disponible:

{
  "scanForm": {
    "id": "scf_abc",
    "carrierCode": "DHL",
    "formUrl": "https://labels.sendit.mx/scan-forms/scf_abc.pdf",
    "formNumber": "MAN-DHL-20260717",
    "status": "GENERATED"
  }
}

Imprime formUrl y entrégalo al repartidor junto con los paquetes.

Endpoints bulk

Para operaciones masivas de lectura y validación, y no de compra, usa los endpoints bulk. Tienen la misma semántica de éxito parcial, aceptan hasta 100 elementos y devuelven un resultado por elemento en el mismo orden:

Método	Ruta	Descripción
`POST`	`/v1/bulk/addresses/validate`	Validar hasta 100 direcciones
`POST`	`/v1/bulk/tracking/lookup`	Consultar eventos de hasta 100 números de rastreo
`POST`	`/v1/bulk/shipments/fetch`	Traer hasta 100 envíos por ID
`POST`	`/v1/bulk/orders/fetch`	Traer hasta 100 órdenes por ID

curl -X POST https://api.sendit.mx/v1/bulk/shipments/fetch \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["clxship_aaa", "clxship_bbb", "clxship_zzz"] }'

{
  "success": true,
  "data": [
    { "id": "clxship_aaa", "found": true, "data": { "...": "..." } },
    { "id": "clxship_bbb", "found": true, "data": { "...": "..." } },
    { "id": "clxship_zzz", "found": false, "data": null }
  ]
}

Un ID inexistente, o de otra organización, regresa found: false y nunca tumba el lote completo. Los recursos borrados cuentan como no encontrados.