# Facturación electrónica por API > Envías un JSON. Nosotros armamos el e-CF, lo revisamos, lo firmamos con el certificado digital de tu cliente y lo enviamos a la DGII. > Hoy: documentación en borrador. La API todavía no está abierta, ni para pruebas ni para producción. No cobramos nada hasta que la emisión real esté disponible. **Enviar un e-CF** cURL ```bash 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 ``` JavaScript ```js const 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() ``` PHP ```php $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); ``` C# ```csharp 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(); ``` Python ```python 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() ``` ## Lo que te damos - **Una sola llave, con el entorno dentro:** `num_test_…` para pruebas y `num_live_…` para producción. - **Valida sin gastar nada:** el XSD oficial de la DGII y nuestras reglas revisan tu JSON antes de firmar, sin certificado digital. - **Avisos (webhooks)** de cada cambio de estado, en todos los planes. - **PDF en carta o en rollo de 80 mm**, con su QR, cuando la DGII acepta. - **Varios clientes en una cuenta:** un RNC por cliente y una sola factura. - **Nunca te cortamos:** si emites más, sigues emitiendo. ## Precios previstos US$ 3 al mes por empresa con hasta 250 e-CF, + ITBIS. Pruebas, consultas y avisos, gratis. [Ver precios](https://developers.numetria.com/precios) --- # 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 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. **Enviar un e-CF** cURL ```bash 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 ``` JavaScript ```js const 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() ``` PHP ```php $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); ``` C# ```csharp 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(); ``` Python ```python 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() ``` **Respuesta · 202** ```json { "encf": "E320000000001", "estado": "recibida", "entorno": "pruebas" } ``` **Al consultar, unos segundos después** ```json { "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é: **POST /v1/validar · 200** ```json { "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](https://developers.numetria.com/precios) --- # Formato del e-CF > Un JSON con los mismos nombres de campo de la DGII. **En resumen** - Los campos se llaman como en el XML de la DGII: `Encabezado`, `IdDoc`, `Totales`… - Los montos van como texto, con punto decimal: `"5192.00"`. - Las fechas, `DD-MM-AAAA`. > Borrador v0 (16/11/2026): la API todavía no está abierta y las rutas y los nombres pueden cambiar. En esta versión envías los totales ya calculados. Los tres ejemplos pasan el XSD oficial de la DGII y nuestras reglas; el 34 trae un aviso porque, sin el 31 que modifica, no puede sumar las notas anteriores. ## Reglas comunes - Lo que se repite va en una lista: `Item: [ … ]`, `FormaDePago: [ … ]`. - Si un campo no aplica, quítalo. No mandes campos vacíos (el 32 de consumo lleva `Comprador: {}`). - Punto decimal, sin comas de miles. - Las cuentas deben cuadrar: líneas, ITBIS y `MontoTotal`. ## Ejemplos **Ejemplos por tipo** 31 · Crédito fiscal: Una venta a otra empresa con RNC, pagada por transferencia: dos líneas al 18 %. ```json { "Encabezado": { "Version": "1.0", "IdDoc": { "TipoeCF": "31", "eNCF": "E310000000001", "FechaVencimientoSecuencia": "31-12-2027", "IndicadorMontoGravado": "0", "TipoIngresos": "01", "TipoPago": "1", "TablaFormasPago": { "FormaDePago": [ { "FormaPago": "2", "MontoPago": "5192.00" } ] } }, "Emisor": { "RNCEmisor": "999000001", "RazonSocialEmisor": "Comercial Ficticia del Caribe, SRL", "DireccionEmisor": "Calle Imaginaria 123, Santo Domingo", "FechaEmision": "16-11-2026" }, "Comprador": { "RNCComprador": "999000002", "RazonSocialComprador": "Distribuidora Imaginaria, SA" }, "Totales": { "MontoGravadoTotal": "4400.00", "MontoGravadoI1": "4400.00", "ITBIS1": "18", "TotalITBIS": "792.00", "TotalITBIS1": "792.00", "MontoTotal": "5192.00" } }, "DetallesItems": { "Item": [ { "NumeroLinea": "1", "IndicadorFacturacion": "1", "NombreItem": "Servicio de consultoría", "IndicadorBienoServicio": "2", "CantidadItem": "2.00", "PrecioUnitarioItem": "1500.0000", "MontoItem": "3000.00" }, { "NumeroLinea": "2", "IndicadorFacturacion": "1", "NombreItem": "Resma de papel 8.5x11", "IndicadorBienoServicio": "1", "CantidadItem": "5.00", "UnidadMedida": "31", "PrecioUnitarioItem": "280.0000", "MontoItem": "1400.00" } ] } } ``` 32 · Consumo: Una venta a un consumidor final, en efectivo: una línea al 18 % y otra exenta. Es menor de RD$250,000, así que nosotros armamos el resumen (RFCE) que pide la DGII. ```json { "Encabezado": { "Version": "1.0", "IdDoc": { "TipoeCF": "32", "eNCF": "E320000000001", "IndicadorMontoGravado": "0", "TipoIngresos": "01", "TipoPago": "1", "TablaFormasPago": { "FormaDePago": [ { "FormaPago": "1", "MontoPago": "926.00" } ] } }, "Emisor": { "RNCEmisor": "999000001", "RazonSocialEmisor": "Comercial Ficticia del Caribe, SRL", "DireccionEmisor": "Calle Imaginaria 123, Santo Domingo", "FechaEmision": "16-11-2026" }, "Comprador": {}, "Totales": { "MontoGravadoTotal": "700.00", "MontoGravadoI1": "700.00", "MontoExento": "100.00", "ITBIS1": "18", "TotalITBIS": "126.00", "TotalITBIS1": "126.00", "MontoTotal": "926.00" } }, "DetallesItems": { "Item": [ { "NumeroLinea": "1", "IndicadorFacturacion": "1", "NombreItem": "Café molido 454 g", "IndicadorBienoServicio": "1", "CantidadItem": "2.00", "UnidadMedida": "43", "PrecioUnitarioItem": "350.0000", "MontoItem": "700.00" }, { "NumeroLinea": "2", "IndicadorFacturacion": "4", "NombreItem": "Pan de agua", "IndicadorBienoServicio": "1", "CantidadItem": "10.00", "UnidadMedida": "43", "PrecioUnitarioItem": "10.0000", "MontoItem": "100.00" } ] } } ``` 34 · Nota de crédito: Devuelve una resma del 31. `InformacionReferencia` dice qué comprobante modifica. ```json { "Encabezado": { "Version": "1.0", "IdDoc": { "TipoeCF": "34", "eNCF": "E340000000001", "IndicadorNotaCredito": "0", "IndicadorMontoGravado": "0", "TipoIngresos": "01", "TipoPago": "1" }, "Emisor": { "RNCEmisor": "999000001", "RazonSocialEmisor": "Comercial Ficticia del Caribe, SRL", "DireccionEmisor": "Calle Imaginaria 123, Santo Domingo", "FechaEmision": "18-11-2026" }, "Comprador": { "RNCComprador": "999000002", "RazonSocialComprador": "Distribuidora Imaginaria, SA" }, "Totales": { "MontoGravadoTotal": "280.00", "MontoGravadoI1": "280.00", "ITBIS1": "18", "TotalITBIS": "50.40", "TotalITBIS1": "50.40", "MontoTotal": "330.40" } }, "DetallesItems": { "Item": [ { "NumeroLinea": "1", "IndicadorFacturacion": "1", "NombreItem": "Resma de papel 8.5x11 (devolución)", "IndicadorBienoServicio": "1", "CantidadItem": "1.00", "UnidadMedida": "31", "PrecioUnitarioItem": "280.0000", "MontoItem": "280.00" } ] }, "InformacionReferencia": { "NCFModificado": "E310000000001", "FechaNCFModificado": "16-11-2026", "CodigoModificacion": "3", "RazonModificacion": "Devolución de una resma" } } ``` ## Tipos de e-CF Los diez: 31, 32, 33, 34, 41, 43, 44, 45, 46 y 47. Los ejemplos de los demás llegan con la versión 1. --- # Precios previstos > Por cada empresa (RNC) que emite en el mes, según lo que emite. En dólares, + ITBIS. > Producción: muy pronto. No cobramos nada hasta que la emisión real esté disponible. | e-CF aceptados en el mes | Al mes | | --- | --- | | Hasta 250 | US$ 3 | | De 251 a 10,000 | US$ 3 + US$ 4 por cada 1,000 más | | Más de 10,000 | US$ 42 + US$ 2 por cada 1,000 más | | Más de 500,000 | [Escríbenos](https://developers.numetria.com/#avisame) | ## Ejemplos | e-CF en el mes | Al mes | | --- | --- | | 250 | US$ 3 | | 1,000 | US$ 6 | | 2,500 | US$ 12 | | 10,000 | US$ 42 | | 25,000 | US$ 72 | ## 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. - Una empresa que en el mes no emitió en producción: US$ 0. ## Empresas de software - Una sola factura al mes, con una línea por empresa. - 10 % menos con 11 o más empresas activas en el mes, y 20 % con 51 o más. Sin códigos. ## Nunca te cortamos Si emites más, sigues emitiendo. Si quieres, pones un tope de gasto y te avisamos al 80 % y al 100 %. ## ¿Ya usas Numetría? Lo que emitas por la API cuenta en lo que incluye tu plan. No pagas dos veces. Precios en dólares, + ITBIS (18 %). Numetría es de Fuetiao SRL. --- # Usar con IA > Toda la documentación en Markdown, para ChatGPT, Claude o Cursor. > Borrador v0 (16/11/2026): la API todavía no está abierta y las rutas y los nombres pueden cambiar. - [`/llms.txt`](https://developers.numetria.com/llms.txt): el índice. - [`/llms-full.txt`](https://developers.numetria.com/llms-full.txt): todo en un solo archivo. - Cada página en Markdown: agrega `.md` a la dirección, como [`/precios.md`](https://developers.numetria.com/precios.md). ## Para empezar **Pídeselo así** ```text Lee https://developers.numetria.com/llms-full.txt y ayúdame a preparar mi sistema en PHP para enviar facturas de consumo (32). La API todavía es un borrador: deja la dirección y la llave en la configuración. ```