Emitir e-CF · Documentación

POST/v1/ecf

Crea y envía un e-CF. Responde 202 con el e-CF en estado pendiente y lo procesa en segundo plano. Con ?wait=true espera hasta 20 segundos al resultado final y responde 200.

Manda siempre un header Idempotency-Key para poder reintentar sin duplicar. Ver Idempotencia.

Cuerpo de la solicitud (EmitirEcfInput)#

Campo	Tipo	Descripción
`tipo`	número, obligatorio	Tipo de e-CF: 31, 32, 33, 34, 41, 43, 44, 45, 46 o 47. Ver Tipos de e-CF.
`encf`	texto	e-NCF: `E` + tipo (2 dígitos) + secuencia (10 dígitos), por ejemplo `E310000000001`. Si se omite, Firmo asigna la siguiente secuencia disponible.
`fechaEmision`	fecha AAAA-MM-DD	Por defecto, hoy en America/Santo_Domingo.
`tipoIngresos`	texto	Por defecto `"01"`. 01 Operacionales, 02 Financieros, 03 Extraordinarios, 04 Arrendamientos, 05 Venta de activo depreciable, 06 Otros.
`tipoPago`	número	Por defecto 1. 1 Contado, 2 Crédito, 3 Gratuito.
`fechaLimitePago`	fecha AAAA-MM-DD	Fecha límite de pago (ventas a crédito).
`terminoPago`	texto, máx. 15	Término de pago, por ejemplo "30 días".
`formasPago`	lista, máx. 7	Cada elemento es `{ forma, monto }`. Ver la tabla de formas de pago abajo.
`comprador`	objeto	Datos del comprador. Ver Comprador.
`items`	lista, obligatorio	De 1 a 1,000 ítems. Ver Item.
`referencia`	objeto	Obligatoria en notas de débito (33) y de crédito (34). Ver Referencia.
`moneda`	objeto	`{ tipo, tasaCambio }`: código de moneda de 3 letras (por ejemplo `USD`) y tasa de cambio positiva.
`idExterno`	texto, máx. 100	Tu identificador interno. Único por empresa.
`enviarCorreo`	booleano	Por defecto `false`. Envía el PDF al correo del comprador.
`metadata`	objeto	Pares clave/valor de texto que quieras guardar con el e-CF.

Comprador

Campo	Tipo	Descripción
`rnc`	texto	RNC (9 dígitos) o cédula (11 dígitos), sin guiones.
`identificadorExtranjero`	texto, máx. 20	Identificación de un comprador extranjero.
`razonSocial`	texto, máx. 150	Nombre o razón social.
`correo`	correo	Correo al que se envía el PDF si enviarCorreo es true.
`direccion`	texto, máx. 100	Dirección.
`municipio`	texto	Código DGII de municipio (6 dígitos).
`provincia`	texto	Código DGII de provincia (6 dígitos).
`telefono`	texto, máx. 12	Teléfono.

Item

Campo	Tipo	Descripción
`codigo`	texto, máx. 35	Código del producto o servicio en tu sistema.
`descripcion`	texto, 1 a 80, obligatorio	Descripción del ítem.
`cantidad`	número > 0, obligatorio	Cantidad.
`unidadMedida`	texto	Código de unidad de medida de la DGII.
`precioUnitario`	monto, obligatorio	Precio unitario sin ITBIS. Montos no negativos con hasta 2 decimales.
`descuento`	monto	Descuento del ítem.
`indicadorFacturacion`	número	Por defecto 1. 1 ITBIS 18%, 2 ITBIS 16%, 3 ITBIS 0%, 4 Exento, 0 No facturable.
`indicadorBienServicio`	número	Por defecto 1. 1 Bien, 2 Servicio.
`retencion`	objeto	`indicadorAgente` (1 Retención, 2 Percepción), `montoItbisRetenido` y `montoIsrRetenido`.

Referencia

Obligatoria en las notas de débito (33) y de crédito (34). Indica qué comprobante modificas.

Campo	Tipo	Descripción
`encfModificado`	texto, obligatorio	e-NCF del comprobante que se modifica.
`fechaModificado`	fecha AAAA-MM-DD, obligatorio	Fecha de emisión de ese comprobante.
`codigoModificacion`	número 1 a 5, obligatorio	Código de modificación de la DGII.
`razon`	texto, máx. 90	Razón de la modificación.

Formas de pago

forma	Significado
1	Efectivo
2	Cheque, transferencia o depósito
3	Tarjeta de débito o crédito
4	Venta a crédito
5	Bonos o certificados de regalo
6	Permuta
7	Nota de crédito
8	Otras formas de pago

Ejemplo: nota de crédito#

Cuerpo

{
  "tipo": 34,
  "comprador": { "rnc": "131000000", "razonSocial": "Ferretería El Puente SRL" },
  "referencia": {
    "encfModificado": "E310000000001",
    "fechaModificado": "2026-10-06",
    "codigoModificacion": 3,
    "razon": "Devolución de 2 sacos"
  },
  "items": [
    { "descripcion": "Cemento gris 42.5 kg", "cantidad": 2, "precioUnitario": 500 }
  ],
  "idExterno": "NC-2026-0042"
}

Respuesta (Ecf)#

200 con ?wait=true

{
  "id": "0f8c2a9e-6b1d-4c2a-9a51-3e7d1b2c4f60",
  "encf": "E310000000001",
  "tipo": 31,
  "estado": "aceptado",
  "ambiente": "sandbox",
  "esRfce": false,
  "trackId": "b1c7e4d2-5f3a-4e8b-9c0d-2a6f1e3b7d90",
  "codigoSeguridad": "Xk3P9a",
  "fechaEmision": "2026-10-06",
  "fechaFirma": "2026-10-06T10:14:03-04:00",
  "comprador": { "rnc": "131000000", "razonSocial": "Ferretería El Puente SRL" },
  "montoGravadoTotal": 10000,
  "montoExento": 0,
  "totalItbis": 1800,
  "montoTotal": 11800,
  "mensajes": [],
  "urls": {
    "xml": "https://api.firmo.do/v1/ecf/E310000000001/xml",
    "pdf": "https://api.firmo.do/v1/ecf/E310000000001/pdf",
    "qr": "https://api.firmo.do/v1/ecf/E310000000001/qr",
    "consultaDgii": null
  },
  "idExterno": null,
  "metadata": null,
  "creadoEn": "2026-10-06T14:14:02.511Z",
  "actualizadoEn": "2026-10-06T14:14:03.902Z"
}

Campo	Descripción
`id`	UUID del e-CF en Firmo.
`encf`	e-NCF asignado.
`estado`	Ver la tabla de estados.
`ambiente`	`sandbox`, `test`, `cert` o `prod`.
`esRfce`	true si es una factura de consumo menor de RD$250,000 enviada como resumen. Ver RFCE.
`trackId`	Identificador de seguimiento de la DGII, o null.
`codigoSeguridad`	Los 6 primeros caracteres del SignatureValue. Va en la representación impresa.
`fechaEmision`	Fecha de emisión.
`fechaFirma`	Fecha y hora de la firma, o null.
`comprador`	Datos del comprador, o null.
`montoGravadoTotal`, `montoExento`, `totalItbis`, `montoTotal`	Totales calculados por Firmo.
`mensajes`	Mensajes de la DGII: lista de `{ codigo, valor }`.
`urls`	`xml`, `pdf`, `qr` y `consultaDgii` (null si no aplica).
`idExterno`, `metadata`	Lo que mandaste, o null.
`creadoEn`, `actualizadoEn`	Fechas ISO 8601.

Estados de un e-CF#

estado	Qué significa
`pendiente`	Firmo lo recibió y está en cola.
`en_proceso`	Enviado a la DGII, esperando el resultado.
`aceptado`	La DGII lo aceptó.
`aceptado_condicional`	La DGII lo aceptó con observaciones. Revisa `mensajes`.
`rechazado`	La DGII lo rechazó. Revisa `mensajes`, corrige y emite un e-CF nuevo.
`error`	Error técnico: no llegó a la DGII. Se reintenta solo; también puedes forzarlo con `POST /v1/ecf/{idOEncf}/resend`.

Los cambios de estado llegan por webhook: ecf.aceptado, ecf.aceptado_condicional, ecf.rechazado y ecf.error.