Accept or reject a supplier’s invoice
POST /api/v1/mensajes-receptor
Issues the receiver message (mensaje receptor): the declaration filed with Hacienda regarding the electronic invoice sent by a supplier. It’s the other side of invoicing — in this case no sale is recorded; instead, you are responding to a purchase. This declaration tells the tax authority whether the invoice is accepted (and therefore counted as an expense), partially accepted, or rejected.
It combines into a single call what in the POS are two steps — uploading the XML and then processing it: an integrator doesn’t need the intermediate state.
This document is not issued in the background. Unlike
POST /facturas, in this endpoint generation, signing, and submission to Hacienda happen within the same request. The response already reflects a message that has been generated and signed, not aprocesandostatus.
Authentication and permissions
| Attribute | Value |
|---|---|
| Scheme | API key (X-Api-Key) |
| Required scope | mensajes:write |
| Idempotent | Doesn’t accept Idempotency-Key, but resubmitting the same document returns 409 |
| Rate limit | 120 req/min per API key |
| Max body size | 7 MB — the XML allows up to 5 MB; the rest is the base64 and JSON overhead |
Request body
{
"xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
"tipo": 1,
"codigoActividad": "6209.0"
}| Field | Type | Required | Description |
|---|---|---|---|
xml | string | Yes | The supplier’s document, in base64 or as raw XML. The format is detected automatically: if the value doesn’t start with <, it’s treated as base64. |
tipo | number | Yes | 1 accepted · 2 partially accepted · 3 rejected. |
codigoActividad | string | Optional | The tenant’s own economic activity under which the purchase is declared. If omitted, the tenant’s primary activity is used. It must exist in GET /catalogos/actividades. |
Responses
201 Created
{
"clave": "50601012600310161019800100024010058611013200000000",
"consecutivo": 148,
"numeroConsecutivo": "00100001050000000148",
"cedulaEmisor": "3101610198",
"nombreEmisor": "PROVEEDOR EJEMPLO S.A.",
"montoTotal": 11300.00,
"estado": "Aceptado"
}claveis the supplier’s document key, not a new key for the tenant.numeroConsecutivois the fiscal consecutive number of the issued message (20 digits), the one that travels asNumeroConsecutivoReceptorin the signed XML. The document type sits in positions 9–10:05acceptance,06partial acceptance,07rejection.consecutivois the internal running number; it serves as a reference for the operation.estadoreflects what was declared by the sender of the message, not Hacienda’s confirmation: that acknowledgment isn’t stored per message, just as in the POS.
409 Conflict
The document had already been uploaded and answered previously. Only one receiver message is allowed per document.
400 Bad Request
In addition to model validation errors, the XML goes through a security validator before being processed, since it involves analyzing a file coming from a third party. If it fails validation, it is rejected without being processed.
401 / 403 / 429 / 500
Same as the rest of the API. See HTTP status codes.