Cómo funcionaMenú

/como-funciona · Ver en Markdown

Cómo funciona

Entornos, llaves, varios clientes y estados, en una página.

En resumen

  • Cambias de entorno cambiando la llave, no el código.
  • Cada e-CF lleva una clave tuya (Idempotency-Key): repetirla nunca emite dos veces.
  • La DGII responde en segundos: te avisamos o consultas gratis.

Borrador v0 (16/11/2026): la API todavía no está abierta y las rutas y los nombres pueden cambiar.

Entornos

EntornoPara quéLlave
TesteCFDesarrollo y pruebas. Sin validez fiscal.num_test_…
CerteCFLas pruebas que pide la DGII antes de que tu cliente emita. Te guiamos.num_test_…
eCFProducción: comprobantes reales.num_live_…

Tu código es el mismo en los tres. Solo cambia la llave.

Llaves de API

  • Las creas en tu panel (muy pronto). Se ven una sola vez.
  • Van en el encabezado Authorization: Bearer num_test_….
  • Guárdala en tu servidor, nunca en una app ni en el navegador.

Varios clientes

  • Tu cuenta agrupa a tus clientes. Cada uno es una empresa con su RNC y su certificado digital (.p12).
  • La ruta lleva el RNC: /v1/empresas/{rnc}/ecf. Ningún cliente ve los documentos de otro.
  • Una sola factura al mes, con una línea por empresa.

El recorrido

  1. Validas el JSON con POST /v1/validar. No necesita certificado digital ni gasta nada.
  2. Envías el e-CF con tu Idempotency-Key. Responde 202 con el estado recibida.
  3. Lo revisamos, lo firmamos con el certificado digital de tu cliente y lo enviamos a la DGII.
  4. La DGII responde en segundos. Te avisamos por webhook, o consultas el estado.
  5. Descargas el XML firmado y el PDF.
curl https://api.numetria.com/v1/empresas/999000001/ecf \
  -H "Authorization: Bearer $NUMETRIA_LLAVE" \
  -H "Idempotency-Key: venta-1042" \
  -H "Content-Type: application/json" \
  -d @e32.json
Respuesta · 202
{
  "encf": "E320000000001",
  "estado": "recibida",
  "entorno": "pruebas"
}
Al consultar, unos segundos después
{
  "encf": "E320000000001",
  "estado": "aceptada",
  "entorno": "pruebas",
  "documentos": {
    "xml": "/v1/empresas/999000001/ecf/E320000000001/xml",
    "pdf": "/v1/empresas/999000001/ecf/E320000000001/pdf?formato=rollo"
  }
}

Estados

EstadoQué significa¿Final?
recibidaLo tenemos y lo estamos revisando.No
no-pasa-la-revisionTiene errores. No se firmó ni se gastó la secuencia.Sí
enviadaFirmado y en la DGII.No
aceptadaLa DGII lo aceptó.Sí
aceptada-condicionalLa DGII lo aceptó con observaciones.Sí
rechazadaLa DGII lo rechazó. El motivo viene en la respuesta.Sí

Validar antes de enviar

Si algo no pasa la revisión, te decimos qué campo es y por qué:

POST /v1/validar · 200
{
  "listo": false,
  "hallazgos": [
    {
      "codigo": "sumas.monto-total",
      "severidad": "condicional",
      "ruta": "ECF/Encabezado/Totales/MontoTotal",
      "mensaje": "MontoTotal no cuadra con MontoGravadoTotal + MontoExento + TotalITBIS: la diferencia es 92. La DGII lo recibiría como «Aceptado Condicional»."
    }
  ],
  "erroresXsd": [
    {
      "ruta": "ECF/Encabezado/IdDoc/FechaVencimientoSecuencia",
      "mensaje": "falta: es obligatorio"
    }
  ]
}

Idempotencia

  • Manda una clave tuya en Idempotency-Key: el número de tu venta, por ejemplo.
  • Misma clave y mismo JSON: te devolvemos lo mismo, sin emitir otra vez.
  • Misma clave y otro JSON: error 409.
  • No uses el e-NCF como clave.

Gratis

  • Todo en TesteCF y en CerteCF.
  • Validar tu JSON (POST /v1/validar).
  • Consultar el estado, las veces que quieras.
  • Los avisos (webhooks) de cada cambio de estado.
  • El XML firmado y el PDF, en carta o en rollo de 80 mm.
  • Los e-CF que te envían otras empresas.
  • Los rechazados por la DGII.

Solo se cobra lo que la DGII acepta en producción. Ver precios

SiguienteFormato del e-CF