01 / Guía
Usa un lote cuando la decisión ya está tomada
Un lote sirve para comprar muchas guías pendientes con una sola solicitud. Es útil después de cerrar pedidos, validar sus datos y decidir que todos están listos para preparación.
No es la mejor opción cuando necesitas escoger una paquetería o servicio específico para cada paquete. El lote compra cada guía con la opción disponible de menor total; para controlar un rateId concreto, compra esa guía individualmente.
| Necesidad | Flujo recomendado | Motivo |
|---|---|---|
| Elegir un rateId específico | Compra individual | Conservas el control de la opción elegida. |
| Procesar pedidos listos con el menor total disponible | Lote | Una solicitud inicia hasta 100 compras. |
| Varios paquetes para un destino | Un envío por paquete y después un lote | Cada shipment representa exactamente un paquete. |
| Corregir una compra fallida | Reintentar solo ese envío | Las guías correctas del lote ya deben conservarse. |
02 / Guía
Prepara cada envío antes de agruparlo
El lote recibe identificadores de envíos ya creados. Antes de agruparlos, confirma que cada dirección, paquete y referencia de pedido corresponde al envío que quieres comprar.
Todos los shipmentIds deben pertenecer a la misma organización. Si uno está ausente, eliminado o no es accesible, la creación se rechaza con SHIPMENTS_NOT_FOUND para evitar procesar una selección incompleta.
Entre 1 y 100 shipmentIds por lote.
Un shipment por cada paquete físico.
Peso y dimensiones finales, incluido el empaque.
Direcciones verificadas y asociadas con el pedido correcto.
Saldo suficiente para las compras que esperas completar.
03 / Guía
Inicia la compra sin esperar todas las guías
POST /v1/batches responde de inmediato con el identificador del lote y estado PENDING. La compra continúa de forma asíncrona, por lo que una respuesta 201 confirma que el lote fue aceptado, no que todas las guías ya existen.
Los shipmentIds repetidos dentro de la misma solicitud se deduplican. Una guía válida que ya existe se considera resuelta y no se vuelve a comprar.
POST /v1/batches
X-API-Key: sk_test_...
Idempotency-Key: 34fc820a-b568-4d39-a3ac-85f7b0875326
Content-Type: application/json
{
"shipmentIds": [
"shp_aaa",
"shp_bbb",
"shp_ccc"
]
}04 / Guía
Entiende qué opción compra el lote
Cada envío usa la opción disponible de menor total. Si la cotización guardada sigue vigente, se utiliza desde el mismo envío; si venció después de 24 horas, SendIt vuelve a solicitar opciones antes de continuar.
Este comportamiento hace que el lote sea adecuado para una regla clara de ahorro. Si tu promesa al cliente depende de un servicio, una paquetería o un tiempo específico, revisa las opciones y compra individualmente con POST /v1/shipments/:id/label.
05 / Guía
Consulta el estado hasta llegar a un resultado final
Guarda batchId y consulta GET /v1/batches/:id con un intervalo controlado. Detén las consultas cuando el lote llegue a COMPLETED, PARTIAL o FAILED.
PENDING y PROCESSING son estados intermedios. No crees otro lote porque el primero todavía no termina; muestra el avance con totalShipments, purchasedCount y failedCount.
- 01
PENDING
El lote fue aceptado y espera procesamiento.
- 02
PROCESSING
Las compras avanzan y sus contadores se actualizan.
- 03
COMPLETED
Todos los envíos terminaron con una guía válida.
- 04
PARTIAL
Algunas guías se compraron y otras requieren una acción.
- 05
FAILED
Ningún envío del lote terminó con una compra nueva correcta.
06 / Guía
Un resultado parcial no se reinicia desde cero
PARTIAL es un resultado deliberado. purchasedShipmentIds contiene los envíos que ya tienen guía y failedItems identifica los que no terminaron, junto con errorCode y errorMessage.
No repitas el lote completo: podrías crear trabajo innecesario y ocultar qué pedidos ya están listos. Actualiza los pedidos correctos, resuelve la causa de cada falla y vuelve a procesar únicamente los shipmentIds pendientes.
| Resultado | Qué revisar | Siguiente acción |
|---|---|---|
| INSUFFICIENT_BALANCE | Saldo disponible para esa compra. | Agrega saldo y reintenta solo el envío fallido. |
| SHIPMENT_NOT_DRAFT | Estado actual del envío y existencia de una guía. | Concilia el pedido; no compres otra guía sin entender el estado. |
| CARRIER_ERROR | Disponibilidad del servicio y contexto del error. | Confirma que no existe guía y decide si reintentas ese envío. |
| Envío comprado | shipmentId dentro de purchasedShipmentIds. | Guarda la guía y exclúyelo de cualquier reintento. |
07 / Guía
Usa el manifiesto como documento de entrega a la paquetería
Cuando todas las guías compradas en el lote pertenecen a la misma paquetería, SendIt genera automáticamente un ScanForm o manifiesto. El campo scanForm aparece dentro de GET /v1/batches/:id y formUrl está disponible cuando su estado es GENERATED.
El manifiesto agrupa las guías para un solo escaneo durante la entrega o recolección. No reemplaza las etiquetas individuales: cada paquete conserva su propia guía impresa y colocada correctamente.
El ScanForm no se crea mediante un endpoint público separado. Si el lote mezcla paqueterías, no fuerces un documento común; separa físicamente los paquetes según el proceso que corresponda a cada una.
Confirma que scanForm.status sea GENERATED antes de abrir formUrl.
Imprime la guía individual de cada paquete además del manifiesto.
Verifica que todos los paquetes incluidos se entreguen juntos a la misma paquetería.
Conserva batchId y formNumber para la conciliación operativa.
08 / Guía
Valida el lote con saldo virtual antes de usar pedidos reales
Una llave sk_test_ procesa el lote con saldo virtual y recursos separados de producción. Prueba un resultado completo, shipmentIds duplicados y una selección con fallas antes de conectar el cierre diario de tu ecommerce.
Idempotency-Key sigue siendo opcional. Generarla antes de POST /v1/batches y conservarla para una repetición idéntica ayuda a recuperar una solicitud interrumpida sin convertirla en otro lote intencional.
09 / Guía
Convierte el lote en un cierre operativo verificable
La automatización termina cuando cada pedido tiene un resultado conocido, no cuando POST /v1/batches responde. Usa la siguiente lista antes de imprimir y entregar los paquetes.
10 / Guía
Pasa de pedidos listos a una salida controlada
SendIt permite iniciar hasta 100 compras de guía en un lote, revisar el avance y separar los resultados correctos de los fallidos sin revertir lo que ya funcionó. Cuando las guías usan la misma paquetería, el mismo resultado puede incluir el manifiesto.
La API completa está incluida en todos los planes, también en Free. SendIt está en pre-lanzamiento y el modo de prueba permite validar el flujo con saldo virtual antes de procesar pedidos reales.
Siguiente paso
Completa la tarea.
Preguntas frecuentes
Respuestas rápidas.
¿Cuántas guías puedo comprar en un lote?
Hasta 100 envíos por solicitud. Cada identificador representa un shipment de la misma organización y cada shipment contiene un paquete.
¿Puedo elegir una paquetería distinta para cada guía del lote?
El lote usa la opción disponible de menor total para cada envío. Si necesitas controlar una paquetería, servicio o rateId concreto, compra esa guía individualmente.
¿Debo repetir todo el lote si una guía falla?
No. Conserva purchasedShipmentIds y corrige únicamente los envíos incluidos en failedItems. PARTIAL significa que las compras correctas ya permanecen vigentes.
¿El lote espera a que todas las guías estén listas?
No. POST /v1/batches responde con PENDING y un batchId. Consulta GET /v1/batches/:id hasta obtener COMPLETED, PARTIAL o FAILED.
¿Cuándo se genera el manifiesto?
Se genera automáticamente cuando las guías compradas en el lote pertenecen a una sola paquetería. Aparece como scanForm dentro del resultado del batch.
¿Existe un endpoint separado para crear ScanForms?
No. Consulta el campo scanForm de GET /v1/batches/:id cuando el lote sea elegible.
¿Puedo probar lotes sin usar saldo real?
Sí. Una llave sk_test_ usa el saldo virtual y mantiene los lotes y envíos de prueba separados de producción.