Consultar estado de un lote de cesión
Obtiene el estado agregado de un lote creado con POST /cessions/batch (identificado por el cession_batch_id recibido en el 202), junto con el detalle por documento — incluyendo el mensaje de error real del SII si alguna cesión falló. No requiere master_entity_id: el lote ya sabe a qué entidad pertenece.
¿Para qué se usa?
Sirve para consultar el resultado de un lote creado conPOST /cessions/batch, usando el cession_batch_id que ese endpoint devuelve en el 202. Es la forma correcta de confirmar si las cesiones realmente se generaron — el 202 solo indica que la solicitud fue aceptada y encolada, no que el SII las haya procesado con éxito.
Qué hace
- Devuelve el estado agregado del lote:
pending,processing,completed(todos los documentos se cedieron con éxito),failed(ninguno) opartial(una mezcla de éxitos y fallos). - Incluye
success_countyfailed_countpara saber de un vistazo cuántos documentos de lostotalterminaron bien. - Devuelve
batch_cessions: el detalle por documento, con sufolio,statusindividual, elcession_idsi tuvo éxito, y — muy importante — elerror_messagereal devuelto por el SII si falló (por ejemplo, un error transitorio del portal, credenciales inválidas, o un documento que no cumple los requisitos para cesión).
Por qué importa
Antes de este endpoint, si el SII fallaba (incluso de forma transitoria) al generar una cesión, no había ninguna forma de saberlo desde la API: no se creaba ninguna cesión, y el único registro del intento quedaba en logs internos de Tupana. Con este endpoint, cualquier integración puede hacer polling delcession_batch_id recibido y saber con certeza qué pasó con cada documento — sin depender de notificaciones en tiempo real ni de revisar manualmente.
Ejemplos de uso
- Después de llamar a
POST /cessions/batch, consultar este endpoint (con reintentos espaciados) hasta questatusdeje de serpending/processing. - Mostrar en tu sistema qué documentos de un lote fallaron y por qué, para poder reintentarlos o escalar el error.
- Auditar el historial de intentos de cesión de una integración sin depender de que el equipo de Tupana revise logs internos.
Authorizations
API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key)
Path Parameters
cession_batch_id devuelto por POST /cessions/batch
Response
Estado del lote y detalle por documento
completed = todos los documentos se cedieron con éxito. failed = ninguno. partial = una mezcla.
pending, processing, completed, failed, partial Error general del lote (ej. sin credenciales SII válidas), si aplica
Un item por documento incluido en el lote
