Aceptar o rechazar la factura de un proveedor
POST /api/v1/mensajes-receptor
Emite el mensaje receptor: la declaración que se presenta ante Hacienda sobre la factura electrónica enviada por un proveedor. Es el otro lado de la facturación — en este caso no se registra una venta, sino que se responde por una compra. Mediante esta declaración se informa al fisco si la factura se acepta (y, por lo tanto, se toma como gasto), se acepta parcialmente o se rechaza.
Reúne en una sola llamada lo que en el POS son dos pasos —cargar el XML y luego procesarlo—: un integrador no necesita el estado intermedio.
Este documento no se emite en segundo plano. A diferencia de
POST /facturas, en este endpoint la generación, la firma y el envío a Hacienda ocurren dentro del mismo request. La respuesta ya refleja un mensaje generado y firmado, no unprocesando.
Autenticación y permisos
| Atributo | Valor |
|---|---|
| Esquema | API key (X-Api-Key) |
| Scope requerido | mensajes:write |
| Idempotente | No acepta Idempotency-Key, pero reenviar el mismo comprobante da 409 |
| Rate limit | 120 req/min por API key |
| Body máximo | 7 MB — el XML admite hasta 5 MB; el resto es el sobrecosto de base64 y del JSON |
Request body
{
"xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
"tipo": 1,
"codigoActividad": "6209.0"
}| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
xml | string | Sí | El comprobante del proveedor, en base64 o como XML crudo. El formato se detecta automáticamente: si el valor no comienza con <, se intenta interpretar como base64. |
tipo | number | Sí | 1 aceptado · 2 aceptado parcialmente · 3 rechazado. |
codigoActividad | string | Opcional | Actividad económica propia del tenant bajo la cual se declara la compra. Si se omite, se usa la principal del tenant. Debe existir en GET /catalogos/actividades. |
Respuestas
201 Created
{
"clave": "50601012600310161019800100024010058611013200000000",
"consecutivo": 148,
"numeroConsecutivo": "00100001050000000148",
"cedulaEmisor": "3101610198",
"nombreEmisor": "PROVEEDOR EJEMPLO S.A.",
"montoTotal": 11300.00,
"estado": "Aceptado"
}clavees la del comprobante del proveedor, no una clave nueva del tenant.numeroConsecutivoes el consecutivo fiscal del mensaje emitido (20 dígitos), el que viaja comoNumeroConsecutivoReceptoren el XML firmado. El tipo de documento va en las posiciones 9–10:05aceptación,06aceptación parcial,07rechazo.consecutivoes el correlativo interno; sirve como referencia de la operación.estadocorresponde a lo declarado por el emisor del mensaje, no a la confirmación de Hacienda: ese acuse no se almacena por mensaje, al igual que en el POS.
409 Conflict
El comprobante ya había sido cargado y respondido con anterioridad. Corresponde un único mensaje receptor por comprobante.
400 Bad Request
Además de los errores de validación de modelo, el XML pasa por un validador de seguridad antes de ser procesado, dado que se trata del análisis de un archivo proveniente de un tercero. Si no supera la validación, se rechaza sin procesarlo.
401 / 403 / 429 / 500
Igual que el resto de la API. Ver Códigos HTTP.