Nota de remisión (04) y comprobante de retención (07)
Son los dos tipos que más preguntas generan, porque ninguno de los dos es una venta. Esta página explica para qué sirve cada uno, quién puede emitirlo, qué lleva cada campo y por qué, con un ejemplo completo de cada uno. Todo el contrato exacto está en la referencia de POST /v1/dte.
Antes de empezar: la llave tiene que llevar el tipo
Cada llave de API se acuña con una lista de tipos de DTE. Una llave acuñada antes de que existieran el 04 y el 07 lleva solo los seis anteriores (01, 03, 05, 06, 11 y 14): pedir un 04 o un 07 con ella contesta 403 dte_type_not_allowed. No se corrige editando la llave; acuñe otra con los tipos marcados (en Cuenta → API, el 07 solo se ofrece si la empresa es agente de retención).
Nota de remisión (04)
Para qué sirve
Una nota de remisión acompaña mercadería que cambia de lugar o de manos sin venderse en ese momento: bienes enviados en consignación, un traslado entre dos establecimientos de la misma empresa, bienes que van en camino a un cliente antes de facturarlos, bienes dejados en depósito. Lleva el valor de los bienes (líneas y totales), pero no cobra nada: no tiene pagos, ni condición de la operación, ni plazo. La venta, cuando ocurre, se documenta aparte con una factura (01), un crédito fiscal (03) o una exportación (11).
Quién puede emitirla
Cualquier empresa que pueda emitir documentos por la API, con una llave que lleve el tipo 04.
Campos
| Campo | ¿Obligatorio? | Por qué | |
|---|---|---|---|
tipoDte: "04" | sí | ||
receptor.numDocumento y receptor.tipoDocumento | sí | Identifica a quien recibe los bienes. Sin tipoDocumento se asume NIT (36); un DUI es 13. | |
receptor.nombre | sí | El esquema oficial lo exige. | |
receptor.codActividad (y descActividad) | sí | El esquema oficial lo exige. | |
receptor.bienTitulo | sí, sin valor por omisión | Es lo que el documento afirma legalmente: a qué título viajan los bienes. Facta no lo adivina ni lo toma de un cliente guardado. Vea la tabla siguiente. | |
receptor.nrc, receptor.correo, receptor.direccion | no | Regla de Facta, sobre lo que permite el esquema oficial del 04, donde estos campos pueden ir nulos; la Normativa v2.0 pide el NIT del receptor solo en el crédito fiscal y en el DCLE. Si los omite, el documento los lleva en null. Un nrc mal formado se omite en lugar de rechazar el documento. Un cliente guardado (customerId) al que le faltan estos datos sirve igual. | |
items | sí | Como un crédito fiscal: precioUni sin IVA, cantidad, tipoItem, y tipoVenta (gravada, exenta o no_sujeta) si no es gravada. | |
items[].numeroDocumento | no | Si lo manda, debe ser uno de los documentos relacionados (400 si no). Nunca es obligatorio. | |
documentosRelacionados | no | Los documentos sellados con los que viajan los bienes: solo 01, 03 y 11. Forma corta { "codigoGeneracion": "…" } (el servidor completa tipo y fecha desde su índice y exige que esté sellado) o la forma entera. | |
descuentoGlobal | no | `{ "modo": "monto" \ | "porcentaje", "valor": n }, la misma forma y las mismas reglas que en 01, 03, 11 y 14. Regla de la Normativa: la Normativa v2.0 lista los descuentos globales por clase de venta (descuNoSuj, descuExenta, descuGravada) como válidos para FE, CCF y NRE, y el esquema oficial del 04 los pide en resumen`. La nota no cobra, pero el valor que lleva puede tener descuento. |
observaciones | no | Texto libre que viaja firmado en el documento. |
bienTitulo (CAT-025)
| Código | Título |
|---|---|
01 | Depósito |
02 | Propiedad |
03 | Consignación |
04 | Traslado |
05 | Otros |
Falta → 400 invalid_request con details.field: "receptor.bienTitulo". Un código fuera del catálogo → 422 validation_failed con details.catalog: "CAT-025" y details.supported. En cualquier otro tipo de documento, bienTitulo es 400.
Lo que no se manda
condicionOperacion, formaPago, pagos, plazo y periodo no existen en el esquema del 04, porque no se cobra. Si su sistema manda un mismo cuerpo para todos los tipos y los incluye, no es un error: se ignoran, el documento sale sin ellos y la respuesta trae una advertencia campo_ignorado por campo. Las líneas con noGravado y el apendice sí se rechazan (400 non_taxed_not_supported, 400 sobre apendice): el 04 no tiene dónde ponerlos y descartar en silencio datos firmados no es aceptable.
Ejemplo completo: emisión
{
"tipoDte": "04",
"receptor": {
"nombre": "Comercial Ejemplo, S.A. de C.V.",
"tipoDocumento": "36",
"numDocumento": "05110606161016",
"nrc": "2513113",
"codActividad": "46510",
"descActividad": "Venta al por mayor de repuestos",
"direccion": { "departamento": "06", "municipio": "20", "distrito": "01", "complemento": "Bodega 2, San Miguel" },
"correo": "bodega@example.com",
"bienTitulo": "04"
},
"items": [
{ "descripcion": "Caja de repuestos", "cantidad": 2, "precioUni": 25, "tipoItem": 1 }
],
"descuentoGlobal": { "modo": "porcentaje", "valor": 10 }
}Con ese cuerpo resumen.totalGravada es 50, el descuento (descuGravada) 5 y subTotal 45; el IVA (13 %, 5.85) va como tributo 20 y montoTotalOperacion es 50.85. En el índice de Facta el documento queda como «no aplica» para cobro.
Y la versión mínima, a un destinatario del que solo se conoce lo indispensable:
{
"tipoDte": "04",
"receptor": {
"nombre": "Bodega Santa Ana",
"tipoDocumento": "36",
"numDocumento": "05110606161016",
"codActividad": "46510",
"descActividad": "Venta al por mayor de repuestos",
"bienTitulo": "03"
},
"items": [{ "descripcion": "Caja de repuestos", "cantidad": 2, "precioUni": 25, "tipoItem": 1 }]
}Con documentos relacionados
{
"tipoDte": "04",
"receptor": { "customerId": "374114b6-e957-4c7a-8911-dd6381b1e0ea", "bienTitulo": "04" },
"documentosRelacionados": [{ "codigoGeneracion": "1BC3E8A1-1111-4111-8111-11111111ABCD" }],
"items": [{ "descripcion": "Caja de repuestos", "cantidad": 2, "precioUni": 25, "tipoItem": 1 }]
}Un codigoGeneracion que no está en su índice es 404 y uno que Hacienda nunca selló es 400; ambos se rechazan antes de reservar el correlativo.
Comprobante de retención (07)
Para qué sirve
Lo emite un agente de retención designado por Hacienda cuando compra a un proveedor: retiene una parte del IVA de esa compra y le entrega al proveedor este comprobante, que el proveedor usa para reclamar lo retenido. Sus «líneas» no son productos: cada una dice sobre cuánto se retuvo y con qué código.
Quién puede emitirlo
Solo una empresa marcada como agente de retención. Cualquier otra recibe 403 retention_agent_required, antes de reservar ningún correlativo (no se gasta nada). La persona titular activa «agente de retención» en Cuenta → Perfil fiscal de Facta, y solo si Hacienda designó a la empresa como tal. Además, la llave tiene que llevar el tipo 07 (vea arriba).
Campos
| Campo | ¿Obligatorio? | Por qué |
|---|---|---|
tipoDte: "07" | sí | |
receptor | sí | El proveedor al que se le retiene: contribuyente inscrito, con numDocumento (NIT), nrc, nombre, codActividad, direccion y correo, o un customerId. A diferencia del 04, aquí se piden completos (regla de Facta, igual que un crédito fiscal). |
items | sí, de 1 a 500 | Las retenciones. Más de 500 es 400 sobre items. |
items[].montoSujetoGrav | sí | El monto sobre el que se retiene, sin IVA (regla de la Normativa, Anexo IV, campo 103): mayor que cero y con dos decimales como máximo. |
items[].codigoRetencionMH | sí | El código de retención, CAT-006, en la tabla siguiente. |
items[].ivaRetenido | solo con C9 (y allí obligatorio) | Con 22 y C4 lo calcula el servidor y mandarlo es 400; vea «Por qué» más abajo. |
items[].tipoDte, numeroDocumento, fechaEmision, tipoGeneracion | grupo de todo o nada | El documento que respalda la compra. Vea «El grupo de referencia». |
items[].descripcion | no | Texto libre, hasta 1500 caracteres. |
observaciones | no |
Las líneas no tienen cantidad, precioUni, productId ni noGravado. Si su sistema manda cantidad, precioUni, uniMedida o tipoItem en una línea de retención, se ignoran con una advertencia campo_ignorado por nombre de campo, sin importar en cuántas líneas aparezcan.
Los códigos de retención (CAT-006)
| Código | Qué es | ivaRetenido |
|---|---|---|
22 | Retención del 1 % (art. 162 del Código Tributario) | lo calcula el servidor: montoSujetoGrav × 1 % |
C4 | Retención del 13 % | lo calcula el servidor: montoSujetoGrav × 13 % |
C9 | Otros casos, sin tasa fija | lo declara usted; es obligatorio |
Otro código es 422 validation_failed con la lista soportada.
Por qué el servidor calcula ivaRetenido en 22 y C4 (regla de Facta). El código fija la tasa, y la Normativa solo exige que el resultado cuadre con una tolerancia de ±$0.01 (Anexo IV, campo 105). Facta decide que un cliente de la API nunca manda dinero calculado, así que lo deriva el servidor, igual que hace la aplicación. Límite conocido: una diferencia de un centavo de redondeo contra el documento de su proveedor solo se puede ajustar con C9, donde usted declara el monto.
El grupo de referencia
tipoDte (01 o 03), numeroDocumento (hasta 36 caracteres; el código de generación si el documento es electrónico) y fechaEmision (AAAA-MM-DD) viajan juntos o no viajan. tipoGeneracion (1 papel, 2 electrónico; por omisión 2) solo va junto con ellos.
- Los cuatro ausentes = una compra sin documento electrónico (en papel, o a un sujeto excluido). El documento los lleva en
null. - Un grupo a medias es
400, y el error nombra el miembro que falta. - Si la referencia es electrónica, la factura o el crédito fiscal referido tuvo que emitirlo ese proveedor a esta empresa. Si el documento fue emitido a otra persona, Hacienda rechaza con
[emisor.nit] DATO NO COINCIDE CON DTE. No es un problema del certificado: el emisor del 07 (el agente) debe ser el receptor del documento relacionado.
resumen.totalIva siempre va en 0.00
El 07 lleva un campo resumen.totalIva. La Normativa (Anexo IV, campo 157) dice que con el código C4 sería el 13 % del monto, pero el validador del ambiente de pruebas de Hacienda rechaza ese cálculo ([resumen.totalIva] CALCULO INCORRECTO) y sella el documento cuando el campo va en 0.00, tanto con 22 como con C4. Facta envía 0.00 porque es lo que el validador acepta hoy (tres transmisiones de prueba lo confirman). Sigue siendo una regla empírica: antes del primer 07 en producción hay que volver a probarlo, porque el texto de la Normativa dice otra cosa. Usted no escribe totalIva; es solo para que lo entienda al leer el documento.
Ejemplo completo: emisión
{
"tipoDte": "07",
"receptor": {
"nombre": "ZD, S.A DE C.V.",
"tipoDocumento": "36",
"numDocumento": "05110606161016",
"nrc": "2513113",
"codActividad": "46510",
"descActividad": "Venta al por mayor de equipo",
"direccion": { "departamento": "06", "municipio": "20", "distrito": "01", "complemento": "Colonia Centro, San Miguel" },
"correo": "proveedor@example.com"
},
"items": [
{
"tipoDte": "03",
"numeroDocumento": "1BC3E8A1-1111-4111-8111-11111111ABCD",
"fechaEmision": "2026-10-05",
"montoSujetoGrav": 1000,
"codigoRetencionMH": "22"
},
{ "montoSujetoGrav": 250.5, "codigoRetencionMH": "C9", "ivaRetenido": 2.5, "descripcion": "Compra en papel" }
]
}La primera línea retiene 1 % de 1,000.00: ivaRetenido 10.00. La segunda es una compra en papel (sin referencia) y declara su retención de 2.50. resumen.totalIvaRetenido es 12.50 y totalSujetoRetencion 1,250.50.
Notas de crédito y débito sobre un 07
Una nota de crédito (05) o de débito (06) puede relacionar un 07 sellado, igual que relaciona un crédito fiscal: documentosRelacionados: [{ "codigoGeneracion": "…" }].
Qué se ignora, y por qué
Ninguno de los dos documentos se cobra, así que condicionOperacion, formaPago, pagos, plazo y periodo se ignoran en ambos con una advertencia por campo. El 07 además ignora descuentoGlobal (no tiene bloque de descuentos); el 04 sí lo acepta.
{
"advertencias": [
{
"codigo": "campo_ignorado",
"campo": "pagos",
"mensaje": "La nota de remisión (04) no liquida nada: «pagos» se ignoró y no forma parte del documento."
}
]
}En un borrador (POST /v1/drafts) pasa lo mismo, y el campo ignorado no queda en el borrador.
Borradores
Ambos tipos se pueden dejar como borrador (POST /v1/drafts) con el mismo cuerpo, para que una persona de la empresa los revise y los emita en la aplicación con «Revisar y emitir». No se firma nada ni se gasta número. Un 07 solo se emite desde un borrador si la empresa es agente de retención; si no, la aplicación explica por qué y no deja emitir. Los tipos 04 y 07 no se ofrecen en el modo operador (Caja).
Errores frecuentes
| Qué pasó | Qué contesta | Qué hacer |
|---|---|---|
Un 04 sin receptor.bienTitulo | 400 invalid_request, details.field: "receptor.bienTitulo" | Elija siempre el título (CAT-025). |
bienTitulo fuera de 01 a 05 | 422 validation_failed, details.catalog: "CAT-025" | Use uno de los cinco códigos. |
bienTitulo en otro tipo de documento | 400 | Solo existe en el 04. |
| Un 04 sin NIT, nombre o actividad del receptor | 400 invalid_request, details.missing lista lo que falta | Mande esos tres (más bienTitulo); lo demás es opcional. |
descuentoGlobal mayor que el subtotal del 04 | 400, details.field: "descuentoGlobal" y details.subtotal | Baje el monto. No gasta correlativo. |
descuentoGlobal en un 07 | Se ignora, con advertencia | Quítelo. |
pagos, formaPago, condicionOperacion en un 04 o 07 | Se ignoran, con campo_ignorado | Quítelos. |
ivaRetenido con 22 o C4 | 400 | Deje que lo calcule el servidor; use C9 para declararlo. |
C9 sin ivaRetenido | 400 | Declare el monto retenido. |
Solo parte del grupo tipoDte/numeroDocumento/fechaEmision | 400, nombra el miembro que falta | Mande los tres, o ninguno. |
cantidad o precioUni en una línea de 07 | Se ignoran, con campo_ignorado | Use montoSujetoGrav. |
Más de 500 líneas, o montoSujetoGrav con tres decimales o ≤ 0 | 400 / 422 | Divida el documento; dos decimales. |
| Un 07 de una empresa que no es agente | 403 retention_agent_required | La persona titular activa «agente de retención» en Cuenta → Perfil fiscal, solo si Hacienda la designó. |
Una llave sin 04 o 07 | 403 dte_type_not_allowed | Acuñe otra llave con esos tipos. |
| Un 07 que relaciona un documento electrónico emitido a otra persona | Hacienda rechaza: [emisor.nit] DATO NO COINCIDE CON DTE | Relacione solo documentos que ese proveedor le emitió a esta empresa, o trate la compra como en papel (sin referencia). |
Con el SDK de TypeScript
Los tipos 04 y 07 llegan en la próxima versión del SDK (la que sigue a la publicada en npm que este portal tiene fijada). Con ella, facta.issue() y facta.createDraft() los reciben con sus campos tipados: receptor.bienTitulo obligatorio y de tipo BienTitulo en el 04, y RetentionLine[] en el 07, donde el compilador rechaza cantidad y precioUni. Las advertencias campo_ignorado llegan en result.ignoredFields y con ignoredFieldWarnings(result). Mientras tanto, mande el mismo cuerpo por HTTP directo: el contrato es el mismo.
const nre = await facta.issue({
tipoDte: "04",
receptor: {
nombre: "Comercial Ejemplo, S.A. de C.V.",
tipoDocumento: "36",
numDocumento: "05110606161016",
codActividad: "46510",
bienTitulo: "04", // obligatorio: Traslado
},
items: [{ descripcion: "Caja de repuestos", cantidad: 2, precioUni: 25, tipoItem: 1 }],
descuentoGlobal: { modo: "porcentaje", valor: 10 },
}, { idempotencyKey: "traslado-0042" });const cr = await facta.issue({
tipoDte: "07",
receptor: { /* el proveedor, completo */ },
items: [
{ tipoDte: "03", numeroDocumento: "1BC3E8A1-1111-4111-8111-11111111ABCD", fechaEmision: "2026-10-05",
montoSujetoGrav: 1000, codigoRetencionMH: "22" },
{ montoSujetoGrav: 250.5, codigoRetencionMH: "C9", ivaRetenido: 2.5, descripcion: "Compra en papel" },
],
}, { idempotencyKey: "retencion-0099" });Vea también Emitir un DTE y Preparar y firmar por separado.
Otras guías
Emitir un DTE
Cómo llamar a POST /v1/dte, qué llega firmado por dentro y las tres respuestas que puede recibir.
Leer →Preparar y firmar por separado
Por qué separar la reserva del correlativo de la firma, el prepareToken y sus 15 minutos, y qué pasa si el documento cambia entre las dos llamadas.
Leer →