shipment_type EXTERNAL_SINGLE_CARD), es decir, los que no pasan por nuestra solución logística.
Gestión del estado de envíos externos
Mantén sincronizado el estado de tus envíos externos y recibe las novedades en tus sistemas, igual que con los envíos gestionados por nosotros.
Introducción
Cuando distribuyes tus tarjetas físicas con tu propio proveedor de logística, nosotros no vemos qué pasa con cada envío.
Con el endpoint Actualizar estado del envío, nos informas el estado de cada envío externo y lo gestionamos igual que uno propio.
Cada vez que nos reportas un estado, disparamos automáticamente el webhook configurado en tu integración, así tus sistemas reciben las novedades con el mismo formato que los envíos gestionados por nosotros.
Alcance
| Aspecto | Detalle |
|---|---|
| Tipo de envío | Solo EXTERNAL_SINGLE_CARD. |
| Propiedad | Solo puedes actualizar envíos que te pertenezcan. |
| Estados | Cualquier combinación válida de status y status_detail del catálogo. |
| Transiciones | Sin restricción de orden o secuencia. |
Si el envío no es de tipo EXTERNAL_SINGLE_CARD o no te pertenece, rechazaremos la solicitud.
Funcionamiento
- Creas el envío externo y obtienes su
shipment_id. - Tu proveedor de logística te informa una novedad (por ejemplo, la tarjeta salió a distribución).
- Nos reportas el nuevo estado con el endpoint Actualizar estado del envío.
- Actualizamos el envío y enviamos la notificación (webhook) configurada en tu integración.
- Cuando lo necesites, consultas el estado vigente con el endpoint Obtener envío o el histórico con Obtener histórico de envío.
Qué necesitas para reportar un estado
Para cada actualización, nos indicas el ID del envío externo, el estado (status) y su detalle (status_detail). Puedes ver el detalle de los parámetros y las respuestas posibles en la API Reference.
Estados que puedes reportar
Puedes reportar cualquier combinación válida de status y status_detail. Consulta el catálogo completo de estados, detalles y su significado en la guía de Estados de envío.
En los envíos gestionados por nosotros, los estados de entrega exitosa y de entrega fallida son finales. En los envíos externos no validamos el orden de las transiciones, por lo que te recomendamos reportar los estados en el orden en que ocurren.
Preguntas frecuentes
¿Puedo actualizar el estado de cualquier envío?
No. Solo puedes actualizar envíos de tipo EXTERNAL_SINGLE_CARD que te pertenezcan.
¿Tengo que respetar un orden entre los estados?
No. Puedes reportar cualquier combinación válida de status y status_detail, sin restricción de secuencia.
¿Recibo una notificación cuando actualizo un estado?
Sí. Cada actualización dispara el webhook configurado en tu integración.
¿Cómo consulto el estado actual de un envío?
Con el endpoint Obtener envío. Para ver todos los cambios, usa Obtener histórico de envío.
¿Qué pasa si envío un estado que no existe en el catálogo?
Rechazaremos la solicitud y responderemos con el código HTTP 400 (Request inválido). Consulta las respuestas posibles en la API Reference.