Guía de inicio

Tu primer comprobante en cuatro llamadas

La API recibe los datos de una venta y se encarga del resto: calcula los montos, genera el XML de la DGII, lo firma con tu certificado, lo envía y guarda el resultado. Todo funciona sobre HTTPS con JSON.

URL BASE

Cada empresa tiene su propia llave y sus datos están aislados de las demás. El emisor de cada comprobante es siempre tu empresa: el RNC viene de tu cuenta, no de la petición.

Autenticación

Mammoth da de alta tu empresa y te entrega una llave que empieza con ecf_. Envíala en cada petición:

Authorization: Bearer ecf_xxxxxxxxxxxxxxxx

La llave se muestra una sola vez; guárdala en un lugar seguro. Puedes crear otras y desactivar las que no uses desde el panel o con POST /llaves y DELETE /llaves/:id. No puedes desactivar la única llave activa.

No pongas la llave en código que corra en un navegador o una app móvil. Llama a la API desde tu servidor.

1. Carga tu certificado digital

Para firmar necesitas el certificado digital de tu empresa (archivo .p12 o .pfx) y su contraseña. Se guarda cifrado y no se vuelve a mostrar. El certificado debe ser el de la persona que actúa en representación de tu empresa ante la DGII (el representante registrado o un delegado). Por eso su titular puede no coincidir con el RNC de la empresa; si no coincide, la respuesta incluye una advertencia informativa, no un error.

curl -X PUT /certificado \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d "{\"p12_base64\": \"$(base64 -w0 certificado.p12)\", \"password\": \"tu-contraseña\"}"

RESPUESTA

{ "ok": true, "titular_id": "131880600", "valido_hasta": "2027-10-02T00:00:00.000Z", "advertencias": [] }

Subir otro certificado reemplaza al anterior. Un certificado vencido o con la contraseña incorrecta se rechaza.

2. Registra tus secuencias de e-NCF

La DGII te autoriza rangos de numeración por tipo de comprobante (se piden en la Oficina Virtual). Regístralos tal como te los autorizaron:

curl -X POST /secuencias \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{ "tipo": 31, "desde": 1, "hasta": 1000, "vence": "2027-12-31" }'

El motor entrega los números en orden, sin repetirlos, y rechaza una secuencia agotada, vencida o que se solape con otra. vence es obligatorio para los tipos 31 y 33; los tipos 32 y 34 no vencen.

3. Emite un comprobante

Envías la venta sin e-NCF: el motor reserva el siguiente número, calcula, genera y firma. Responde 202 porque el envío a la DGII ocurre después.

curl -X POST /comprobantes \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "orden-5521",
    "tipo": 31,
    "tipoPago": 1,
    "emisor": { "razonSocial": "MI EMPRESA SRL", "direccion": "Av. Winston Churchill 10, Santo Domingo" },
    "comprador": { "rnc": "101672919", "razonSocial": "Cliente SRL" },
    "formasPago": [{ "forma": 1, "monto": 118 }],
    "items": [
      { "nombre": "Consultoría", "tipo": 2, "cantidad": 1, "precio": 100, "itbis": 18 }
    ]
  }'

RESPUESTA 202

{ "id": "25c72c31-…", "encf": "E310000000001", "estado": "pendiente", "monto_total": 118,
  "codigo_seguridad": "kP3x9Q", "via_resumen": false,
  "totales": { "montoGravadoTotal": "100.00", "totalItbis": "18.00", "montoTotal": "118.00" } }
  • Los precios van sin ITBIS. El motor calcula el impuesto por línea y el total.
  • Idempotencia. Si repites la petición con la misma idempotency_key (por un corte de red, por ejemplo), recibes el mismo comprobante con "repetido": true y no se gasta otro número.
  • Si los datos no cumplen el esquema de la DGII, recibes 422 con el detalle y no se consume ningún e-NCF.

Después consulta el resultado con GET /comprobantes/{id} (también acepta el e-NCF en lugar del id). El XML firmado se descarga en GET /comprobantes/{id}/xml, y la representación impresa (con el código QR de la DGII) en GET /comprobantes/{id}/impresion, lista para imprimir en A4 o, con ?formato=ticket, en ticket de 80 mm. Se entrega como texto HTML: guárdalo como archivo .html o muéstralo desde tu sistema (el panel ya lo abre listo para imprimir).

Factura de consumo (tipo 32)

No necesita comprador ni fecha de vencimiento; sin comprador se usa «Consumidor Final». Las facturas de consumo menores de RD$250,000 no se envían completas a la DGII: se envía un resumen (RFCE) y el comprobante completo se conserva. El motor lo hace por ti; la respuesta trae "via_resumen": true y puedes descargar el resumen en GET /comprobantes/{id}/resumen. Tú debes conservar el comprobante completo y ponerlo a disposición de tu cliente.

Nota de crédito (tipo 34)

Requiere la referencia al comprobante que modifica:

{ "tipo": 34, "tipoPago": 1,
  "emisor": { "razonSocial": "MI EMPRESA SRL", "direccion": "Av. Winston Churchill 10" },
  "referencia": { "ncfModificado": "E310000000001", "fecha": "02-10-2026", "codigoModificacion": 3, "razon": "Corrección de importe" },
  "items": [{ "nombre": "Consultoría (ajuste)", "tipo": 2, "cantidad": 1, "precio": 10, "itbis": 18 }] }

Los códigos de modificación son los de la tabla del Formato e-CF de la DGII: 1 anula el documento, 2 corrige texto, 3 corrige montos, 4 reemplaza un e-NCF emitido en contingencia y 5 referencia una factura de consumo. El tipo 33 (nota de débito) funciona igual, con su secuencia propia.

Campos del comprobante

CampoObligatorioDescripción
tipoSí31 crédito fiscal, 32 consumo, 33 nota de débito, 34 nota de crédito.
tipoPagoSí1 contado, 2 crédito.
emisorSírazonSocial y direccion obligatorios. Opcionales: nombreComercial, sucursal, correo, telefonos, actividadEconomica, numeroFacturaInterna. El RNC es el de tu empresa.
comprador31, 33: sírnc, razonSocial, correo, direccion, contacto.
items[]SíHasta 1,000 líneas. Ver abajo.
fechaEmisionNoDD-MM-AAAA. Por defecto, hoy en hora de República Dominicana.
formasPago[]No{ forma, monto }, hasta 7. Formas: 1 efectivo, 2 cheque/transferencia/depósito, 3 tarjeta, 4 venta a crédito, 5 bonos o certificados de regalo, 6 permuta, 7 nota de crédito, 8 otras.
tipoIngresosNoPor defecto "01" (ingresos por operaciones). Otros: 02 financieros, 03 extraordinarios, 04 arrendamientos, 05 venta de activo depreciable, 06 otros.
fechaLimitePagoNoDD-MM-AAAA, para ventas a crédito.
referencia33, 34: síncfModificado, fecha, codigoModificacion, y opcionales razon, rncOtroContribuyente.
indicadorNotaCreditoNoSolo tipo 34: 0 dentro de 30 días, 1 pasados 30 días.
idempotency_keyNoTexto único por venta (hasta 120 caracteres). Recomendado.

Cada línea (items)

CampoObligatorioDescripción
nombreSíNombre del bien o servicio.
tipoSí1 bien, 2 servicio.
cantidadSíMayor que cero, hasta 2 decimales.
precioSíPrecio unitario sin ITBIS, hasta 4 decimales.
itbisSí18, 16, 0 o "exento".
descuentoNoMonto total del descuento de la línea (no porcentaje).
unidadMedidaNoCódigo de unidad de la tabla de la DGII.
descripcionNoTexto adicional.
propinaLegalNotrue si a esa línea se le aplica la propina legal del 10 % (negocios que la cobran, como restaurantes y hoteles).

Los montos se calculan con aritmética exacta y el redondeo de la DGII (el tercer decimal de 5 o más sube al segundo).

Recibir comprobantes y anular números

Recibir. Cuando otro emisor (o la DGII) le factura a tu empresa, el motor atiende tres servicios por ti: un «portero» que verifica quién envía, un «buzón» que recibe el e-CF y devuelve el acuse de recibo firmado, y un «buzón de respuestas» para las aprobaciones que tus clientes den a tus comprobantes. Las direcciones que debes registrar en la DGII aparecen en el panel, pestaña Recibidos (y en GET /me, campo direcciones_dgii). Lo recibido se consulta en GET /recibidos.

Responder comercialmente. Un comprobante recibido se acepta o se rechaza con POST /recibidos/{id}/aprobacion (el rechazo exige un motivo). Se firma con tu certificado y se envía a la DGII; si esta no responde, el motor reintenta solo. Cada comprobante se responde una sola vez.

curl -X POST /recibidos/ID/aprobacion \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{ "estado": "rechazado", "motivo": "El monto no corresponde a la orden de compra" }'

Anular números. POST /anulaciones anula rangos de e-NCF que nunca se usaron. No sirve para cancelar una factura ya emitida: esa se anula con una nota de crédito (tipo 34, código de modificación 1). El motor envía la anulación a la DGII y solo si esta confirma marca los números como usados en tus secuencias.

curl -X POST /anulaciones \
  -H "Authorization: Bearer $LLAVE" -H "Content-Type: application/json" \
  -d '{ "rangos": [{ "tipo": 31, "desde": 41, "hasta": 50 }] }'

Estados de un comprobante

EstadoQué significa
pendienteGenerado y firmado, esperando su envío a la DGII.
enviadoLa DGII lo recibió (tiene track_id) y aún lo está validando. Se consulta solo hasta tener resultado.
aceptadoLa DGII lo validó. El comprobante es válido.
aceptado_condicionalNo cumplió algún punto menor, pero no ameritó rechazo; es válido. Revisa dgii_mensajes.
rechazadoLa DGII lo anuló. Mira dgii_mensajes y ultimo_error. secuencia_reutilizable indica si ese e-NCF puede volver a usarse.
errorNo se pudo completar después de varios reintentos. ultimo_error explica la causa.

Si la DGII no responde, el motor reintenta con esperas cada vez más largas. En ese tiempo el comprobante sigue pendiente y ultimo_error muestra el último fallo temporal. Por ahora el seguimiento se hace consultando el comprobante; aún no hay avisos automáticos a tu sistema.

Errores

Las respuestas de error siempre llevan { "error": "mensaje" }.

CódigoCuándo
400Petición mal formada o campos faltantes.
401Falta la llave, es inválida, está desactivada o tu empresa está desactivada.
404El comprobante o la ruta no existen (o son de otra empresa).
409No hay certificado cargado, no hay secuencia disponible para ese tipo (agotada, vencida o sin registrar), o hay un conflicto (rango solapado, última llave activa).
422Los datos no cumplen el esquema de la DGII o el certificado no se pudo abrir. El campo detalle.problemas indica la etiqueta y el motivo. No se consume e-NCF.
500Error interno. Si persiste, avisa a Mammoth con la hora aproximada.

Alcance y límites

  • Tipos de e-CF: 31 (crédito fiscal), 32 (consumo), 33 (nota de débito), 34 (nota de crédito), 41 (compras), 43 (gastos menores), 44 (regímenes especiales), 45 (gubernamental), 46 (exportaciones) y 47 (pagos al exterior). Cada tipo valida lo que admite: por ejemplo, el 43 y el 47 solo aceptan líneas exentas y el 46 solo ITBIS 0 %.
  • Impuestos: ITBIS (18 %, 16 %, 0 %, exento), propina legal, retenciones (tipos 41 y 47) y otros impuestos adicionales (002 a 004 con su tasa fija; placa e ISC con el monto y la tasa que mandes).
  • Moneda extranjera: los montos principales van siempre en pesos; con otraMoneda se informa la moneda, la tasa de cambio y los montos en esa moneda, como pide la DGII.
  • Los precios se entienden sin ITBIS.
  • Ambientes: cada empresa trabaja en uno de los tres ambientes de la DGII: testecf (pre-certificación), certecf (certificación) y ecf (producción). Cada ambiente tiene sus propias secuencias de e-NCF. El ambiente se cambia con una llamada de administración; no hay que tocar nada más.
  • Hasta 1,000 líneas por comprobante. La representación impresa en A4 se reparte en páginas (totales y QR en la última).
  • Límites de uso: 300 solicitudes por minuto por empresa y 120 comprobantes por minuto. Pasado el límite se responde 429 con la cabecera retry-after; cada respuesta trae x-ratelimit-remaining.

La referencia completa de la API se genera desde la especificación OpenAPI, que también puedes descargar para generar un cliente en tu lenguaje.

Contingencia

Si no hay conexión con la DGII (caída de internet o de los servicios de la DGII), el motor sigue generando y firmando los e-CF y los envía en cuanto vuelva la conexión, dentro del plazo de 72 horas que fija la DGII. El motor detecta la falta de conexión por sí solo (tres fallos seguidos en diez minutos) y sale solo de la contingencia cuando un envío vuelve a funcionar. También puedes activarla o terminarla tú con POST /contingencia ({"activa": true, "motivo": "…"}).

Los comprobantes generados en contingencia quedan marcados, tienen su límite de envío y su representación impresa lleva la leyenda «e-CF emitido en modalidad de contingencia». GET /me informa si la contingencia está activa, cuántos comprobantes esperan y cuál vence primero.

Avisos automáticos (webhooks)

Registra una dirección https con PUT /webhook ({"url": "https://…"}). La respuesta trae el secreto de la firma una sola vez. Cuando un comprobante queda aceptado, aceptado_condicional, rechazado o con error, el motor hace un POST JSON a esa dirección con las cabeceras x-mammoth-event y x-mammoth-signature: t=<segundos>,v1=<firma>.

La firma es el HMAC-SHA256, en hexadecimal, de <t>.<cuerpo> con tu secreto. Verifícala y rechaza avisos con más de 5 minutos de antigüedad. Se reintenta con espera creciente hasta 12 veces; responde con cualquier código 2xx para confirmar. GET /webhook muestra la dirección y los últimos avisos; POST /webhook/prueba manda uno de prueba; DELETE /webhook lo quita.