--- title: "Quickstart en 5 minutos" description: "De cero a primer e-CF firmado: obtener X-Api-Key, hacer POST a /api/v1/consumer-invoices y recibir el webhook de la DGII." canonical: https://factura.com.do/desarrolladores/quickstart lang: es generator: factura.com.do docs-index --- Quickstart # De cero a primer e-CF firmado en cinco minutos Cuatro pasos verificables. Si tu equipo tiene la X-Api-Key y un cliente cargado en el espacio de trabajo, llegas al webhook `dgii.aprobado` en menos tiempo del que toma este readme. ## Antes de empezar - Una [X-Api-Key](/desarrolladores/autenticacion) activa con vigencia futura, emitida en un espacio de trabajo con plan Corporativo. - El subdominio de tu espacio de trabajo: si entras a la app por `tuempresa.factura.com.do`, tu URL base es `https://tuempresa.factura.com.do/api/v1`. - Un `BranchId` del espacio de trabajo (lo encuentras en Configuración → Sucursales). - Un `CurrencyId` y `UnitId` del catálogo (la API expone [endpoints de catálogo](/desarrolladores/catalogo)). - Un endpoint público que acepte POST y responda 200 (puede ser un Cloudflare Worker o un Lambda mínimo). ## Cuatro pasos verificables 1. 01 Carga la X-Api-Key en tu entorno Guárdala como variable secreta (FACTURA\_API\_KEY). No la pegues en el cliente ni la commits al repo. 2. 02 POST /api/v1/consumer-invoices Envía el cuerpo de V1CreateInvoiceDto: branchId, issuedAt, paymentTermId, limitDate, currencyId, currencyRate y lines. Son opcionales customerId (en E32), sequence (si lo omites, se usa el siguiente NCF de la secuencia activa), externalReference, freight, notes y payments. Si omites payments, la factura queda saldada con la forma de pago por defecto. 3. 03 Lee DocumentId y ConsultationUrl DocumentId es el id interno; guárdalo. ConsultationUrl es la URL DGII que el receptor abre para verificar el comprobante. 4. 04 Suscribe dgii.aprobado Configura un webhook con tu endpoint receptor. Cuando la DGII responde, te llega un POST con Event, Timestamp y data. ## Crear la factura de consumo Llama al endpoint `POST /api/v1/consumer-invoices` con la cabecera `X-Api-Key` y el cuerpo mínimo. La línea de ejemplo factura **RD$ 4 500** de servicios profesionales con ITBIS al 18% y total RD$ 5 310 cobrados en una sola referencia. Tu URL base: https://tuempresa.factura.com.do/api/v1 `tuempresa` es un ejemplo: cámbialo por el subdominio de tu espacio de trabajo, el que elegiste al registrarte y con el que entras a la app. Si abres la app en `https://tuempresa.factura.com.do`, tu URL base es `https://tuempresa.factura.com.do/api/v1`. La API identifica tu empresa por ese subdominio: con cualquier otro host no encuentra tu espacio de trabajo y responde `404` sin cuerpo. POST /api/v1/consumer-invoices cURL TypeScript Python create-invoice.sh ``` curl -X POST https://tuempresa.factura.com.do/api/v1/consumer-invoices \ -H "X-Api-Key: $FACTURA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab", "sequence": "E320000000001", "issuedAt": "2026-05-08T10:00:00Z", "paymentTermId": 1, "limitDate": "2026-05-08T10:00:00Z", "currencyId": 1, "currencyRate": 1, "lines": [ { "code": "SRV-001", "order": 1, "description": "Consultoría", "isService": true, "quantity": 1, "unitId": 1, "unitPrice": 4500.00, "isExempt": false, "taxes": [{ "taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1 }] } ], "payments": [ { "reference": "REF-1", "amount": 5310.00 } ] }' ``` create-invoice.ts ``` // 02-create-consumer-invoice.ts const res = await fetch( "https://tuempresa.factura.com.do/api/v1/consumer-invoices", { method: "POST", headers: { "X-Api-Key": process.env.FACTURA_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ branchId: "b1a2c3d4-e5f6-4789-abcd-1234567890ab", sequence: "E320000000001", issuedAt: new Date().toISOString(), paymentTermId: 1, limitDate: new Date().toISOString(), currencyId: 1, currencyRate: 1, lines: [ { code: "SRV-001", order: 1, description: "Consultoría", isService: true, quantity: 1, unitId: 1, unitPrice: 4500, isExempt: false, taxes: [{ taxId: "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", rate: 18.0, taxTypeId: 1 }], }, ], payments: [{ reference: "REF-1", amount: 5310 }], }), }, ); if (!res.ok) throw new Error(`factura.com.do: ${res.status}`); const { documentId, consultationUrl } = await res.json(); console.log({ documentId, consultationUrl }); ``` create\_invoice.py ``` # 02_create_consumer_invoice.py import os import httpx payload = { "branchId": "b1a2c3d4-e5f6-4789-abcd-1234567890ab", "sequence": "E320000000001", "issuedAt": "2026-05-08T10:00:00Z", "paymentTermId": 1, "limitDate": "2026-05-08T10:00:00Z", "currencyId": 1, "currencyRate": 1, "lines": [{ "code": "SRV-001", "order": 1, "description": "Consultoría", "isService": True, "quantity": 1, "unitId": 1, "unitPrice": 4500.00, "isExempt": False, "taxes": [{"taxId": "3a5e98e0-33ff-44be-bd37-e3f9b35a25e2", "rate": 18.0, "taxTypeId": 1}], }], "payments": [{"reference": "REF-1", "amount": 5310.00}], } with httpx.Client(headers={"X-Api-Key": os.environ["FACTURA_API_KEY"]}) as c: r = c.post("https://tuempresa.factura.com.do/api/v1/consumer-invoices", json=payload) r.raise_for_status() print(r.json()) ``` Respuesta response.json ``` { "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "consultationUrl": "https://fc.dgii.gov.do/ecf/consultatimbrefc?encf=E320000000001&montototal=5310.00&rncemisor=131000001&codigoseguridad=…" } ``` ## Leer la respuesta inmediata Cuando el POST se acepta, la API responde `200 OK` con dos campos: `documentId` y `consultationUrl`. El estado final del comprobante en la DGII llega después por webhook. Qué hacer con cada campo **DocumentId** es UUID y es la única referencia interna. Guárdalo en tu ERP antes de procesar el siguiente paso. **ConsultationUrl** puede mostrarse al cliente final dentro de tu portal de auto-servicio: la DGII publica el detalle del comprobante para que cualquier persona lo verifique. Suscribe el webhook antes de emitir en serio La respuesta del POST confirma que la API recibió el comprobante; no confirma todavía el acuse de la DGII. Para conocer el estado final (`aprobado`, `rechazado`, `aceptado_condicional`) necesitas suscribir `dgii.aprobado` y los eventos hermanos. Configura el receptor antes de emitir comprobantes reales. ## Siguientes pasos Siguiente paso ## Continúa por aquí - [ Facturas (E31, E32, casos) Detalles de cada operación y DTO completo. ](/desarrolladores/facturas) - [ Webhooks Configura tu receptor para los 28 eventos. ](/desarrolladores/webhooks) - [ Errores Cómo reaccionar cuando algo falla. ](/desarrolladores/errores)