--- title: "5-minute quickstart" description: "From zero to first signed e-CF: get your X-Api-Key, POST to /api/v1/consumer-invoices and receive the DGII webhook." canonical: https://factura.com.do/en/desarrolladores/quickstart lang: en generator: factura.com.do docs-index --- Quickstart # From zero to first signed e-CF in five minutes Four verifiable steps. If your team has the X-Api-Key and a customer loaded in the workspace, you will reach the `dgii.aprobado` webhook faster than it takes to read this page. ## Before you begin - An active [X-Api-Key](/en/desarrolladores/autenticacion) with a future expiry, issued in a workspace on the Corporativo plan. - Your workspace subdomain: if you open the app at `tuempresa.factura.com.do`, your base URL is `https://tuempresa.factura.com.do/api/v1`. - A `BranchId` from your workspace (found in Settings → Branches). - A `CurrencyId` and `UnitId` from the catalog (the API exposes [catalog endpoints](/en/desarrolladores/catalogo)). - A public endpoint that accepts POST and returns 200 (a Cloudflare Worker or minimal Lambda will do). ## Four verifiable steps 1. 01 Load X-Api-Key into your environment Store it as a secret variable (FACTURA\_API\_KEY). Do not embed it in the client or commit it to the repo. 2. 02 POST /api/v1/consumer-invoices Send the V1CreateInvoiceDto body: branchId, issuedAt, paymentTermId, limitDate, currencyId, currencyRate and lines. Optional fields are customerId (for E32), sequence (if omitted, the next NCF from the active sequence is used), externalReference, freight, notes and payments. If you omit payments, the invoice is settled with the default payment method. 3. 03 Read DocumentId and ConsultationUrl DocumentId is the internal ID; save it. ConsultationUrl is the DGII URL the recipient opens to verify the document. 4. 04 Subscribe to dgii.aprobado Configure a webhook with your receiver endpoint. When the DGII responds, you receive a POST with Event, Timestamp and data. ## Create the consumer invoice Call the `POST /api/v1/consumer-invoices` endpoint with the `X-Api-Key` header and the minimal body. The example line invoices **RD$ 4,500** of professional services with 18% ITBIS for a total of RD$ 5,310 collected in a single payment reference. Your base URL: https://tuempresa.factura.com.do/api/v1 `tuempresa` is a placeholder: replace it with your workspace subdomain, the one you chose when you signed up and use to open the app. If you open the app at `https://tuempresa.factura.com.do`, your base URL is `https://tuempresa.factura.com.do/api/v1`. The API identifies your company by that subdomain: with any other host it cannot find your workspace and responds `404` with no body. 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()) ``` Response response.json ``` { "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "consultationUrl": "https://fc.dgii.gov.do/ecf/consultatimbrefc?encf=E320000000001&montototal=5310.00&rncemisor=131000001&codigoseguridad=…" } ``` ## Read the immediate response When the POST is accepted, the API responds `200 OK` with two fields: `documentId` and `consultationUrl`. The final document status with the DGII arrives later via webhook. What to do with each field **DocumentId** is a UUID and is the only internal reference. Store it in your ERP before processing the next step. **ConsultationUrl** can be shown to the end customer inside your self-service portal: the DGII publishes the document detail so that anyone can verify it. Subscribe to the webhook before issuing for real The POST response confirms that the API received the document; it does not yet confirm the DGII acknowledgement. To know the final status (`aprobado`, `rechazado`, `aceptado_condicional`) you must subscribe to `dgii.aprobado` and its sibling events. Set up the receiver before issuing real documents. ## Next steps Next step ## Continue here - [ Invoices (E31, E32, cases) Details of each operation and the full DTO. ](/en/desarrolladores/facturas) - [ Webhooks Set up your receiver for the 28 events. ](/en/desarrolladores/webhooks) - [ Errors How to react when something fails. ](/en/desarrolladores/errores)