# Pixel Bill API v1 > Dominican Republic electronic invoicing (DGII e-CF) as a service. A billing system sends a neutral JSON document; Pixel Bill numbers it (e-NCF), builds the DGII XML, signs it with the company's certificate, sends it to the DGII (as an RFCE summary for a type 32 under RD$250,000), and reports the DGII's verdict by webhook. The human guide, in Spanish, is at /docs. ## Conventions - Base path: /v1. JSON in and out. Errors: {"error": ""}; a refused document adds "fields": [{"field": "lines[0].itbis", "message": "..."}] with HTTP 422. - Money is integer cents (118000 = RD$1,180.00), quantities integer milli-units (1000 = 1), rates basis points (1800 = 18%). Never floats. - Unknown JSON fields in a document are refused with 400. ## Authentication - Send an API key in X-API-Key (or Authorization: Bearer). - pbk_c_... is a company key: reaches only its company. pbk_i_... is an integrator key: reaches the companies linked to the integrator. - Scopes: documents:write (emit, annul, retry), documents:read (read documents and reports), received (supplier e-CF and commercial approval), config (company setup, webhooks, registering companies). - A company outside the key's reach answers 404. Keys are created in the portal and shown once. ## Companies (integrator) - POST /v1/integrators/{integratorId}/companies {"rnc": "131000002", "legal_name": "...", "external_ref": ""} registers and links a company. RNC already registered: 409 (the owner must link you). - GET /v1/integrators/{integratorId}/companies[?external_ref=...] - GET /v1/companies/{companyId}: status. "signing" (bool), "types" (numbers left per e-CF type in the live environment), certificate, sequences, pending queue, receptor URLs. - PUT /v1/companies/{companyId}/profile, POST .../certificate (multipart: certificate, password), POST .../sequences {ecf_type, range_from, range_to, expires_on}, POST .../activate, POST .../suspend. - Certificate upload: 201 when it names the company's RNC (active at once). A certificate of an accredited CA naming another identifier (a person's cédula, the DGII tax-procedures certificate) answers 202 with status "pending_review": it signs nothing until Pixel Bill approves it; GET status shows it in "certificate_review" (with holder_name, holder_id, holder_id_type, and rejection_reason once rejected). Activation meanwhile answers 422 ECF_CERT_PENDING; a self-signed or untrusted certificate is 422 ECF_CERT_UNTRUSTED. - GET /v1/rnc/{rnc}: the DGII taxpayer registry (name, status, activity). ## Emit a document POST /v1/companies/{companyId}/documents Headers: Idempotency-Key (required, <=100 chars, use your sale id). Body: { "type": "32", // 31 credito fiscal, 32 consumo, 33 debit note, 34 credit note, 41 compras, 43 gastos menores, 44 regimenes especiales, 45 gubernamental, 46 exportaciones, 47 pagos al exterior "issued_on": "2026-10-10", // optional, today by default "income_type": 1, // 1..6, optional "payment_kind": 1, // 1 cash, 2 credit, 3 free; optional "due_on": "2026-11-09", // REQUIRED with payment_kind 2 (not on a 43; optional on a 47), never before issued_on "currency": "USD", "exchange_rate": "58.7550", // optional: another currency (USD, EUR, CAD, GBP, CHF, JPY, MXN, COP, BRL, HTG...) and its rate in pesos per unit, up to 4 decimals (string or number). Amounts stay in peso cents; Pixel Bill writes the other-currency ones (each / rate, half up). A currency without a rate is a 422. export.currency is an alias. "buyer": {"rnc": "131000012", "foreign_id": "", "name": "Comprador SRL", "email": ""}, // rnc AND name required for 31, 41, 45; name for 44 and 46; foreign_id for 47; rnc (or foreign_id) and name for a 32 of RD$250,000 or more and for a note that modifies one; omit for a smaller 32 to a final consumer "lines": [{ "name": "Item", "description": "", "is_service": false, "quantity_milli": 1000, "unit_code": 0, "gross_cents": 100000, // price x quantity, WITHOUT ITBIS "discount_cents": 0, "itbis": "18", // "18", "16", "0" or "exempt" "itbis_cents": 18000, // optional; computed when absent; when sent, within RD$1.00 (100 cents) of rate x base "itbis_base_cents": 115000, // optional: the amount the ITBIS is computed on when selective taxes (ISC, alcohol and tobacco) are part of it; from the net (gross - discount) to the net plus the line's taxes. The DGII counts the ISC of Tabla I codes 006 to 039 "taxes": [{"code": "001", "rate_bp": 1000, "amount_cents": 10000, "isc": false, "specific": false}], // non-ITBIS taxes by DGII Tabla I code (001 = propina legal) "itbis_retained_cents": 0, "isr_retained_cents": 0 // only where the XML carries them: both on a 31, 33, 34, 41; ISR on a 47; anywhere else a retention is a 422 (never dropped). "taxes" only on 31, 32, 33, 34, 44, 45 (two codes per line, each with rate_bp > 0) }], "payments": [{"form": 1, "amount_cents": 118000}], // 1 cash, 2 check/transfer, 3 card, 4 credit, 5 vouchers, 6 barter, 7 credit note, 8 other "reference": {"document_id": "", "code": 3, "reason": "..."}, // required for 33 and 34; or {"encf": "...", "date": "YYYY-MM-DD", "code": 1..5, "reason": "..."} "internal_number": "8812", "external_ref": "", "total_cents": 118000 // optional guard: must equal what the lines add up to } - 201 response: the document with id, encf, security_code, signed_at, status "pending", summary, deferred, and "printed" {encf, type_name, security_code, signed_at, sequence_expires, qr_url, status, environment, reference} for the printed invoice (print the QR of qr_url). - Same Idempotency-Key and same document: 200 with header Idempotent-Replayed: true and the first result; no second number is taken. "Same" is by meaning: the JSON's canonical form (keys sorted, no insignificant whitespace, numbers as written), so another key order or spacing is the same request. Same key, different document: 409 IDEMPOTENCY_MISMATCH. - Everything the type requires is checked BEFORE a number is taken: a refusal is 422 VALIDATION with "fields": [{"field", "message"}]. - A reference with code 4 and a paper NCF (B + 10 digits, of the series equivalent to the type: B01 for a 31, B02 for a 32...) replaces a comprobante issued in a declared contingency: any type takes it, and the e-CF goes to the DGII only. A 34's 30-day indicator is computed from the dates (over_30_days is ignored). - ?validate=true: dry run, no number taken. Returns {valid, total_cents, itbis_cents, summary, available}. - If the DGII is down, documents are still signed (deferred: true) and sent later. ## Read, annul, retry - GET .../documents?ecf_type=&status=&kind=&external_ref=&from=&to=&search=&page=&limit= - GET .../documents/{id}; GET .../documents/{id}/xml[?summary=true] - GET .../documents/{id}/pdf[?format=letter|a4|ticket_80|ticket_58]: the printed representation (RI) built from the signed XML, with the DGII's QR (letter by default) - POST .../documents/status {"ids": [...]} (max 100) - POST .../documents/{id}/annul {"reason": "...", "void_code": 1..10}: unsent -> voided by ANECF (608 code, default 4); sent -> a type 34 that annuls it whole (a 33 for a 34). Idempotent. - POST .../documents/{id}/retry; GET|POST .../voids {"encf_from", "encf_to", "reason"} gives up the next unused numbers of a range. - A document carries: buyer_delivery ("" | none | pending | delivered | rejected | failed) with delivery_attempts, delivery_next_attempt_at and delivery_error (the delivery to the buyer's receptor is retried for 3 days; POST .../retry tries again); sequence_used (false when the DGII rejected it WITHOUT consuming the number: annul it to give the number up, or emit again); send_error, send_failures, alert_since (the DGII refused it without a verdict - 403, 404, 408, 413, a gateway page: it is retried, never rejected; after 10 in a row the webhook document.alert); currency, exchange_rate. - Annulling a pending document that was already tried asks the DGII first: 409 ECF_UNDECIDED if it holds it, 409 ECF_UNCONFIRMED if it cannot be asked (try again in minutes). - Lists (documents, received) show the company's current environment; ?environment=test|cert|prod|all names another. - Statuses: pending -> sent -> accepted | conditional | rejected; or voided; or blocked. Rejected has no fiscal value and its number is never reused. A 33/34 whose modified e-NCF is in Pixel Bill waits (pending) until that one is accepted; if it was rejected the note is blocked (never sent; annul it to void the number). - A refused DGII authentication pauses the company's sending for 10 minutes, in order: the company carries dgii_auth_paused_until and dgii_auth_error. ## Webhooks - POST /v1/integrators/{id}/webhooks or /v1/companies/{id}/webhooks {"url": "https://...", "events": []}. Response includes "secret" (whsec_...) once. - Events: document.status_changed (data carries sequence_used), document.alert, received.created, company.contingency ({contingency, since}; and at 48 and 72 hours of the oldest unsent document {unsent_hours, oldest_unsent_signed_at, deadline_at, overdue}), company.auth_failed ({failed, message, since}), certificate.expiring (at 60, 30, 7 and 1 days), certificate.approved, certificate.rejected, sequence.low (under 100 numbers of a type), sequence.expiring (30 days before). The warnings among them (certificate.*, sequence.*, the 48 and 72 hour marks, company.auth_failed with failed true, document.alert) are also emailed, once each, to the company's owners and admins and to the company's own address. - GET /v1/companies/{id} carries "contingency" {active, since, unsent, oldest_unsent_signed_at, deadline_at, alert_hours} and "auth_error" {message, since, paused_until} or null. - Body: {id, event, created_at, company_id, company_external_ref, data}. Headers: X-PixelBill-Event, X-PixelBill-Delivery, X-PixelBill-Signature: t=,v1=. - Verify: hex(HMAC-SHA256(secret, "." + raw_body)) == v1, compared in constant time; reject old timestamps. - Non-2xx is retried at 1m, 5m, 30m, 2h, 12h, then given up. GET .../webhooks/{id}/deliveries, POST .../deliveries/{id}/redeliver. ## Received documents (from suppliers) - GET .../received[?status=pending|approved|rejected], GET .../received/{id}, GET .../received/{id}/xml - POST .../received/{id}/decide {"approve": true} or {"approve": false, "reason": "..."} - PUT .../received/{id}/external-ref {"external_ref": ""} (once) ## Reports - GET .../reports/608?period=YYYYMM; GET .../reports/607?period=YYYYMM, or POST .../reports/607 {"period": "YYYYMM", "withholdings": [{"encf", "itbis_cents", "isr_cents", "date"}]}. Returns the DGII TXT file. ## HTTP statuses 400 bad JSON / unknown field / missing Idempotency-Key; 401 bad key; 403 missing scope; 404 out of reach; 409 idempotency mismatch, duplicate RNC, overlapping sequence; 422 validation or configuration (no live sequence, inactive company, expired certificate); 429 rate limited (retry with the same Idempotency-Key; an API key is limited by key and company, not by address).