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.

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 RNC o la cédula del certificado debe coincidir con el RNC de tu empresa; si no coincide, la respuesta incluye una advertencia.

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.

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

Cada línea (items)

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).

Estados de un comprobante

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" }.

Límites actuales

• Tipos soportados: 31, 32, 33 y 34. Aún no están los tipos 41 y 43 al 47.
• Impuestos: ITBIS (18 %, 16 %, 0 %, exento) y propina legal. Todavía no hay ISC ni otros impuestos adicionales, ni moneda extranjera.
• Los precios se entienden sin ITBIS.
• Ambiente de pruebas (testecf) hasta completar la certificación.
• El seguimiento es por consulta; los avisos automáticos (webhooks) no están disponibles.

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.