curl --request POST \
--url https://api.tupana.ai/v1/documents/{document_id}/states \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"event_code": "ERM"
}
'{
"success": true,
"event_registered": true,
"message": "Documento marcado como pagado. Se generó el asiento contable de cierre de cuentas por cobrar.",
"document": {
"id": 12345,
"folio": "42",
"date_issued": "2025-01-15",
"document_status": {
"paid_status": "PAID"
}
}
}Registrar estado de documento
Registrar un nuevo estado cuando ocurre un evento relevante sobre el documento. Admite eventos del SII (ERM, ACD, RCD, RFT, RFP) y eventos internos de cobranza: PAID (marcar factura emitida como pagada) y UNPAID (marcar como no pagada). Para PAID y UNPAID solo el emisor del documento puede usarlos; aplican a facturas emitidas (tipo 33, 34, 39, 41). PAID genera un asiento contable de cierre de cuentas por cobrar (CxC); UNPAID revierte ese asiento si existe. También admite ANNULLED para anular una guía de despacho (DTE 52) emitida con folio, con reason obligatorio (Res. Ex. SII N°154: la guía que se reemplaza por otra queda registrada como anulada). Solo el emisor; la respuesta indica en annulment.registry dónde queda registrada la anulación: delivery_note_book (Libro de Guías, facturador de mercado) o portal_follow_up (facturador gratuito del SII: además hay que anotarla en “Seguimiento del documento” del portal mientras el SII no habilite el Registro de Guías). Errores 400 con code: annulment_only_for_delivery_notes, annulment_only_for_issued_delivery_notes, annulment_reason_required.
curl --request POST \
--url https://api.tupana.ai/v1/documents/{document_id}/states \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"event_code": "ERM"
}
'{
"success": true,
"event_registered": true,
"message": "Documento marcado como pagado. Se generó el asiento contable de cierre de cuentas por cobrar.",
"document": {
"id": 12345,
"folio": "42",
"date_issued": "2025-01-15",
"document_status": {
"paid_status": "PAID"
}
}
}Qué hace
- Crea un nuevo estado asociado al documento
- Agrega el evento al historial del documento
- No reemplaza ni elimina estados anteriores
- Permite registrar eventos manuales o automáticos
Ejemplos de uso
- Marcar un documento como pagado
- Registrar un acuse de recibo
- Registrar un rechazo
- Asociar un evento proveniente del SII
- Registrar mérito ejecutivo o eventos de cobranza
- Anular una guía de despacho (DTE 52) con
event_codeANNULLED
Anular una guía de despacho (ANNULLED)
La Resolución Exenta SII N°154 pide que, cuando cambia lo informado en una guía, se emita una nueva que la referencie y la original quede registrada como anulada. Se registra con este mismo endpoint, enviando el motivo:
{
"event_code": "ANNULLED",
"reason": "Reemplazada por guía folio 1051: cambió la cantidad de bultos"
}
200:
{
"success": true,
"annulment": {
"annulled": true,
"already_annulled": false,
"registry": "delivery_note_book",
"registry_note": "La guía queda como anulada en el Libro de Guías de Despacho del período."
}
}
- Sólo el emisor de la guía puede anularla (
403). - Sólo guías (DTE 52) emitidas con folio y siempre con
reason(hasta 200 caracteres). Si no,400concode:annulment_only_for_delivery_notes,annulment_only_for_issued_delivery_notesoannulment_reason_required. registrydice dónde queda registrada la anulación mientras el SII no habilite el Registro de Guías:delivery_note_book(Libro de Guías, facturador de mercado) oportal_follow_up(facturador gratuito del SII: además hay que anotarla en “Seguimiento del documento” del portal, como explicaregistry_note).- Anular una guía ya anulada responde
200conalready_annulled: true.
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
ID único del documento (integer)
Body
Código del evento a registrar:
- ERM: Acuse de Recibo de Mercaderías y Servicios
- ACD: Acepta Contenido del Documento
- RCD: Reclama Contenido del Documento
- RFT: Reclamo por Falta Total
- RFP: Reclamo por Falta Parcial
- PAID: Marcar factura emitida como pagada (genera asiento cierre CxC; solo emisor; tipos 33, 34, 39, 41)
- UNPAID: Marcar factura emitida como no pagada (revierte asiento cierre CxC; solo emisor)
- ANNULLED: Anular una guía de despacho (52) emitida, con motivo en reason (Res. Ex. SII N°154; solo emisor)
ERM, ACD, RCD, RFT, RFP, PAID, UNPAID, ANNULLED "ERM"
Razón del rechazo (opcional, solo para eventos de rechazo: RCD, RFT, RFP)
"Error en el monto facturado"
Motivo de la anulación. Obligatorio con ANNULLED (por ejemplo, el folio de la guía que la reemplaza). Se guarda con la guía anulada y se informa en el Libro de Guías.
200"Reemplazada por guía folio 1051: cambió la cantidad de bultos"
Response
Estado registrado exitosamente
Indica si la operación fue exitosa
true
Indica si el evento fue registrado exitosamente
true
Mensaje descriptivo del resultado
"Acuse de Recibo registrado. Este acuse rebajará el IVA del próximo mes."
Datos adicionales del evento registrado (proporcionados por el SII)
Show child attributes
Show child attributes
Datos para preview de email (solo para aprobaciones, rechazos o acuses de recibo)
Show child attributes
Show child attributes