factadesarrolladores API 0.1.0-esqueleto

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.tipoDocumentosíIdentifica a quien recibe los bienes. Sin tipoDocumento se asume NIT (36); un DUI es 13.
receptor.nombresíEl esquema oficial lo exige.
receptor.codActividad (y descActividad)síEl esquema oficial lo exige.
receptor.bienTitulosí, sin valor por omisiónEs 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.direccionnoRegla 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.
itemssíComo un crédito fiscal: precioUni sin IVA, cantidad, tipoItem, y tipoVenta (gravada, exenta o no_sujeta) si no es gravada.
items[].numeroDocumentonoSi lo manda, debe ser uno de los documentos relacionados (400 si no). Nunca es obligatorio.
documentosRelacionadosnoLos 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.
descuentoGlobalno`{ "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.
observacionesnoTexto libre que viaja firmado en el documento.

bienTitulo (CAT-025)

CódigoTítulo
01Depósito
02Propiedad
03Consignación
04Traslado
05Otros

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

jsoncuerpo · nota de remisión a título de traslado, con descuento
{
  "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:

jsoncuerpo · nota de remisión mínima, en consignación
{
  "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

jsoncuerpo · remisión que acompaña una factura ya sellada
{
  "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í
receptorsí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).
itemssí, de 1 a 500Las retenciones. Más de 500 es 400 sobre items.
items[].montoSujetoGravsí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[].codigoRetencionMHsíEl código de retención, CAT-006, en la tabla siguiente.
items[].ivaRetenidosolo 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, tipoGeneraciongrupo de todo o nadaEl documento que respalda la compra. Vea «El grupo de referencia».
items[].descripcionnoTexto libre, hasta 1500 caracteres.
observacionesno

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ódigoQué esivaRetenido
22Retención del 1 % (art. 162 del Código Tributario)lo calcula el servidor: montoSujetoGrav × 1 %
C4Retención del 13 %lo calcula el servidor: montoSujetoGrav × 13 %
C9Otros casos, sin tasa fijalo 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

jsoncuerpo · comprobante de retención: una compra con crédito fiscal y otra en papel
{
  "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.

jsonrespuesta · parte de advertencias
{
  "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é contestaQué hacer
Un 04 sin receptor.bienTitulo400 invalid_request, details.field: "receptor.bienTitulo"Elija siempre el título (CAT-025).
bienTitulo fuera de 01 a 05422 validation_failed, details.catalog: "CAT-025"Use uno de los cinco códigos.
bienTitulo en otro tipo de documento400Solo existe en el 04.
Un 04 sin NIT, nombre o actividad del receptor400 invalid_request, details.missing lista lo que faltaMande esos tres (más bienTitulo); lo demás es opcional.
descuentoGlobal mayor que el subtotal del 04400, details.field: "descuentoGlobal" y details.subtotalBaje el monto. No gasta correlativo.
descuentoGlobal en un 07Se ignora, con advertenciaQuítelo.
pagos, formaPago, condicionOperacion en un 04 o 07Se ignoran, con campo_ignoradoQuítelos.
ivaRetenido con 22 o C4400Deje que lo calcule el servidor; use C9 para declararlo.
C9 sin ivaRetenido400Declare el monto retenido.
Solo parte del grupo tipoDte/numeroDocumento/fechaEmision400, nombra el miembro que faltaMande los tres, o ninguno.
cantidad o precioUni en una línea de 07Se ignoran, con campo_ignoradoUse montoSujetoGrav.
Más de 500 líneas, o montoSujetoGrav con tres decimales o ≤ 0400 / 422Divida el documento; dos decimales.
Un 07 de una empresa que no es agente403 retention_agent_requiredLa persona titular activa «agente de retención» en Cuenta → Perfil fiscal, solo si Hacienda la designó.
Una llave sin 04 o 07403 dte_type_not_allowedAcuñe otra llave con esos tipos.
Un 07 que relaciona un documento electrónico emitido a otra personaHacienda rechaza: [emisor.nit] DATO NO COINCIDE CON DTERelacione 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.

typescriptSDK · próxima versión · nota de remisión
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" });
typescriptSDK · próxima versión · comprobante de retención
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

Escriba para buscar Por ejemplo: idempotencia, contingencia, 422, emitir.

↑ ↓ moverse Enter abrir Esc cerrar