/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
| Entorno | Para qué | Llave |
|---|---|---|
| TesteCF | Desarrollo y pruebas. Sin validez fiscal. | num_test_… |
| CerteCF | Las pruebas que pide la DGII antes de que tu cliente emita. Te guiamos. | num_test_… |
| eCF | Producció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
- Validas el JSON con
POST /v1/validar. No necesita certificado digital ni gasta nada. - Envías el e-CF con tu
Idempotency-Key. Responde202con el estadorecibida. - Lo revisamos, lo firmamos con el certificado digital de tu cliente y lo enviamos a la DGII.
- La DGII responde en segundos. Te avisamos por webhook, o consultas el estado.
- 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.jsonconst respuesta = await fetch('https://api.numetria.com/v1/empresas/999000001/ecf', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NUMETRIA_LLAVE}`,
'Idempotency-Key': 'venta-1042',
'Content-Type': 'application/json',
},
body: JSON.stringify(ecf),
})
const resultado = await respuesta.json()$ch = curl_init('https://api.numetria.com/v1/empresas/999000001/ecf');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NUMETRIA_LLAVE'),
'Idempotency-Key: venta-1042',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($ecf),
]);
$resultado = json_decode(curl_exec($ch), true);using var cliente = new HttpClient();
var solicitud = new HttpRequestMessage(HttpMethod.Post, "https://api.numetria.com/v1/empresas/999000001/ecf")
{
Content = new StringContent(json, Encoding.UTF8, "application/json"),
};
solicitud.Headers.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("NUMETRIA_LLAVE"));
solicitud.Headers.Add("Idempotency-Key", "venta-1042");
var respuesta = await cliente.SendAsync(solicitud);
var resultado = await respuesta.Content.ReadAsStringAsync();import os, requests
respuesta = requests.post(
"https://api.numetria.com/v1/empresas/999000001/ecf",
headers={
"Authorization": f"Bearer {os.environ['NUMETRIA_LLAVE']}",
"Idempotency-Key": "venta-1042",
},
json=ecf,
)
resultado = respuesta.json(){
"encf": "E320000000001",
"estado": "recibida",
"entorno": "pruebas"
}{
"encf": "E320000000001",
"estado": "aceptada",
"entorno": "pruebas",
"documentos": {
"xml": "/v1/empresas/999000001/ecf/E320000000001/xml",
"pdf": "/v1/empresas/999000001/ecf/E320000000001/pdf?formato=rollo"
}
}Estados
| Estado | Qué significa | ¿Final? |
|---|---|---|
recibida | Lo tenemos y lo estamos revisando. | No |
no-pasa-la-revision | Tiene errores. No se firmó ni se gastó la secuencia. | Sí |
enviada | Firmado y en la DGII. | No |
aceptada | La DGII lo aceptó. | Sí |
aceptada-condicional | La DGII lo aceptó con observaciones. | Sí |
rechazada | La 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é:
{
"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