Clientes Oficiales
Facturo ECF ofrece clientes oficiales, de un solo archivo y sin dependencias pesadas, que encapsulan la autenticación, las rutas, la serialización y el manejo de errores de la API.
| Lenguaje | Archivo | Requisitos | Guía |
|---|---|---|---|
| Python (scripts, microservicios) | ecf_client.py | Python 3.7+, requests | Python |
Odoo (l10n_do_ecf_connect) | ecf_client.py | Odoo 14 – 18 | Odoo |
| C# / .NET | FacturoClient.cs | .NET Standard 2.0+, .NET 6 – 9 | .NET |
| Node.js / TypeScript | facturo-client.ts | Node.js 18+, Bun, Deno, Workers | Node.js |
Copia el archivo en tu proyecto y úsalo directamente.
Configuración común
Todos los clientes comparten los mismos parámetros:
| Parámetro | Descripción | Valor por defecto |
|---|---|---|
| URL base | URL de la API de Facturo | https://ecf.facturord.app/ |
| API Key | Clave de integración, enviada en el header X-API-Key | — (requerida) |
| Company ID | UUID de la empresa por defecto. Puede sobrescribirse en cada llamada. | — |
| Timeout | Tiempo máximo por petición | 30 segundos |
Métodos disponibles
| Operación | Python | .NET | Node.js | Endpoint |
|---|---|---|---|---|
| Anular rangos (ANECF) | cancel_ranges | CancelRangesAsync | cancelRanges | POST /emission/cancel-ranges |
| Anular un e-NCF | cancel_single_sequence | CancelSingleSequenceAsync | cancelSingleSequence | POST /emission/cancel-ranges |
| Anular un rango continuo | cancel_sequence_range | CancelSequenceRangeAsync | cancelSequenceRange | POST /emission/cancel-ranges |
| Emitir e-CF | emit_rich_ecf | EmitRichECFAsync | emitRichECF | POST /emission/ecf |
| Estado por Track ID | get_tracking_status | GetTrackingStatusAsync | getTrackingStatus | GET /emission/invoices/{track_id}/status |
| XML firmado | get_signed_xml | GetSignedXmlAsync | getSignedXml | GET /emission/documents/{id}/signed-xml |
| Reintentar emisión | retry_emission | RetryEmissionAsync | retryEmission | POST /emission/documents/{id}/retry |
Todas las rutas son relativas a /api/v1/companies/{company_id}. Consulta la referencia de la API para el detalle de cada campo.
Constantes de la DGII
Los clientes incluyen constantes para los ambientes y tipos de e-CF:
| Tipo | Descripción | Python (ECFType) | .NET (EcfTypes) |
|---|---|---|---|
| 31 | Factura de Crédito Fiscal Electrónica | E31_CREDITO_FISCAL | FacturaCreditoFiscal |
| 32 | Factura de Consumo Electrónica | E32_CONSUMO | FacturaConsumo |
| 33 | Nota de Débito Electrónica | E33_NOTA_DEBITO | NotaDebito |
| 34 | Nota de Crédito Electrónica | E34_NOTA_CREDITO | NotaCredito |
| 41 | Compras Electrónico | E41_COMPRAS | Compras |
| 43 | Gastos Menores Electrónico | E43_GASTOS_MENORES | GastosMenores |
| 44 | Regímenes Especiales Electrónica | E44_REGIMENES_ESPECIALES | RegimenesEspeciales |
| 45 | Gubernamental Electrónico | E45_GUBERNAMENTAL | Gubernamental |
| 46 | Comprobante para Exportaciones Electrónico | E46_EXPORTACIONES | Exportaciones |
| 47 | Comprobante para Pagos al Exterior Electrónico | E47_PAGOS_EXTERIOR | PagosAlExterior |
| Ambiente | Python (DGIIEnv) | .NET (DgiiEnvironment) | Node.js (DGIIEnv) |
|---|---|---|---|
| Pruebas | DGIIEnv.TESTECF | DgiiEnvironment.TestECF | 'testecf' |
| Certificación | DGIIEnv.CERTECF | DgiiEnvironment.CertECF | 'certecf' |
| Producción | DGIIEnv.ECF | DgiiEnvironment.ECF | 'ecf' |
En Node.js, ECFType es un tipo numérico (31 | 32 | …).
Manejo de errores
Cada cliente lanza una excepción tipada cuando la API responde con un error HTTP:
| Lenguaje | Excepción | Propiedades |
|---|---|---|
| Python | FacturoAPIError | status_code, payload |
| .NET | FacturoApiException | StatusCode, RawPayload |
| Node.js | FacturoAPIError | statusCode, payload |
En Python y Node.js, los timeouts y fallos de red también se lanzan como FacturoAPIError. En .NET se propagan las excepciones estándar de HttpClient (TaskCanceledException por timeout, HttpRequestException por red).
Ver Manejo de errores.