Facturación electrónica de la DGII por API
Pixel Bill numera, arma, firma y envía los comprobantes fiscales electrónicos (e-CF) de la República Dominicana por tu software. Tú envías lo que vendiste en un JSON simple; Pixel Bill responde al instante con el e-NCF, el código de seguridad y el QR para imprimir, y te avisa lo que diga la DGII.
Cómo funciona
- La empresa se certifica como emisor electrónico ante la DGII nombrando a Pixel Bill como su software externo.
- En Pixel Bill configura sus datos, sube su certificado digital (.p12), agrega las secuencias de e-NCF que la DGII le autorizó y activa. Un certificado de una entidad acreditada que no es a nombre del RNC (el de la persona que administra la empresa, con su cédula) queda en revisión: la subida responde
202constatus: "pending_review", el estado lo muestra encertificate_reviewy no firma hasta que Pixel Bill lo apruebe. - Tu software envía cada venta a
POST /v1/companies/{id}/documents. La respuesta trae el e-NCF y el bloque para la representación impresa. - Un proceso de Pixel Bill la envía a la DGII (como resumen RFCE si es una factura de consumo menor de RD$250,000), pregunta el resultado y entrega la factura al receptor del comprador.
- Tu sistema se entera por webhook (o consultando) cuando la DGII acepta o rechaza.
Los montos van siempre en enteros: centavos (118000 es RD$1,180.00), cantidades en milésimas (1000 es 1) y tasas en puntos básicos (1800 es 18%). Nunca decimales de punto flotante.
Autenticación y llaves
Cada solicitud lleva una llave en X-API-Key (o en Authorization: Bearer). Hay dos clases:
pbk_c_...: de una empresa; solo alcanza esa empresa. La crea el dueño en Integraciones.pbk_i_...: de un integrador (un software de facturación con muchas empresas); alcanza las empresas vinculadas a él mientras el vínculo siga activo.
Cada llave tiene permisos:
documents:writeemitir, anular y reintentar.documents:readconsultar comprobantes y reportes.receivedcomprobantes recibidos de suplidores y su aprobación comercial.configdatos de la empresa, certificado, secuencias, webhooks y, para un integrador, registrar empresas.
La llave se muestra una sola vez; Pixel Bill guarda solo su huella. Una empresa fuera de tu alcance responde 404, no 403. Las llaves no crean llaves ni usuarios: eso se hace en el portal.
Empresas
Un integrador registra una empresa por su RNC (validado con su dígito verificador) y queda vinculado a ella:
POST /v1/integrators/{integratorId}/companies
{ "rnc": "131000002", "legal_name": "Empresa SRL", "external_ref": "empresa-77" }external_ref es tu propio id de la empresa: vuelve en cada webhook y sirve para buscarla con GET /v1/integrators/{id}/companies?external_ref=empresa-77. Si el RNC ya está en Pixel Bill la respuesta es 409: el dueño de la empresa debe autorizarte.
GET /v1/companies/{id} dice si la empresa está emitiendo (signing), el ambiente, el certificado y, en types, cuántos números quedan por tipo. Consúltalo antes de ofrecer un tipo en tu punto de venta.
GET /v1/rnc/{rnc} busca un contribuyente en el registro de la DGII (nombre, estado, actividad).
El documento neutro
Una factura de consumo (32):
POST /v1/companies/{companyId}/documents
X-API-Key: pbk_i_...
Idempotency-Key: venta-8812
Content-Type: application/json
{
"type": "32",
"issued_on": "2026-10-10",
"lines": [
{
"name": "Instalación de equipos",
"is_service": true,
"quantity_milli": 1000,
"gross_cents": 100000,
"discount_cents": 0,
"itbis": "18"
}
],
"payments": [{ "form": 1, "amount_cents": 118000 }],
"internal_number": "8812",
"external_ref": "factura-8812",
"total_cents": 118000
}Una factura de crédito fiscal (31) a crédito, con descuento y propina legal:
{
"type": "31",
"income_type": 1,
"payment_kind": 2,
"due_on": "2026-11-09",
"buyer": { "rnc": "131000012", "name": "Comprador SRL", "email": "pagos@comprador.do" },
"lines": [
{
"name": "Resmas de papel",
"quantity_milli": 10000,
"gross_cents": 250000,
"discount_cents": 10000,
"itbis": "18",
"itbis_cents": 43200
},
{
"name": "Servicio",
"is_service": true,
"quantity_milli": 1000,
"gross_cents": 50000,
"itbis": "18",
"taxes": [{ "code": "001", "rate_bp": 1000, "amount_cents": 5000 }]
}
],
"payments": [{ "form": 4, "amount_cents": 347200 }],
"external_ref": "factura-8813"
}type: 31 crédito fiscal, 32 consumo, 33 nota de débito, 34 nota de crédito, 41 compras, 43 gastos menores, 44 regímenes especiales, 45 gubernamental, 46 exportaciones, 47 pagos al exterior.gross_centses precio por cantidad sin ITBIS;discount_centslo lleva al neto.itbises"18","16","0"o"exempt";itbis_centsse calcula si no lo envías y, si lo envías, debe estar a RD$1.00 del cálculo (la tolerancia por línea de la DGII). Cuando un impuesto selectivo (ISC de alcoholes o tabaco) forma parte de la base del ITBIS, envíaitbis_base_cents: entre el neto de la línea y el neto más sus impuestos adicionales.taxes: otros impuestos con su código de la Tabla I de la DGII (001propina legal, códigos de ISC...).payments: forma 1 efectivo, 2 cheque o transferencia, 3 tarjeta, 4 a crédito, 5 bonos, 6 permuta, 7 nota de crédito, 8 otras.buyer.rnces obligatorio en 31, 41 y 45; un 47 llevabuyer.foreign_id. Un 32 a consumidor final no lleva comprador.referencees obligatorio en 33 y 34:{ "document_id": "<id en Pixel Bill>", "code": 3, "reason": "..." }o, para un comprobante de fuera,encfydate.total_centses opcional: si lo envías, debe ser lo que suman las líneas. Una red de seguridad contra diferencias de redondeo.- Un campo desconocido se rechaza (400): un error de escritura nunca pasa en silencio.
Emitir
El encabezado Idempotency-Key es obligatorio (hasta 100 caracteres; usa el id de la venta en tu sistema). Si la red se cae y repites la solicitud con la misma llave, Pixel Bill responde el primer resultado (200 con Idempotent-Replayed: true) y nunca toma un segundo número. La misma llave con otro documento es 409. Se compara el contenido, no los bytes: el mismo JSON con las llaves en otro orden o con otros espacios es la misma solicitud.
HTTP/1.1 201 Created
{
"id": "6f1c...",
"ecf_type": "32",
"encf": "E320000000001",
"status": "pending",
"summary": true,
"deferred": false,
"security_code": "A1B2C3",
"signed_at": "2026-10-10T14:03:22Z",
"total_cents": 118000,
"itbis_cents": 18000,
"external_ref": "factura-8812",
"printed": {
"encf": "E320000000001",
"type_name": "Factura de Consumo Electrónica",
"security_code": "A1B2C3",
"signed_at": "10-10-2026 10:03:22",
"sequence_expires": "",
"qr_url": "https://fc.dgii.gov.do/...",
"status": "pending",
"environment": "test",
"reference": ""
}
}Imprime el bloque printed en la representación impresa: tipo, e-NCF, vencimiento de la secuencia, código de seguridad, fecha de firma y el QR de qr_url (al menos 22 mm).
?validate=true revisa el documento sin tomar número ni firmar, y responde { valid, total_cents, itbis_cents, summary, available }: úsalo en tus pruebas y antes de cobrar.
Si la DGII no responde, Pixel Bill sigue firmando (en contingencia, deferred: true) y envía todo cuando vuelve. Tu venta nunca espera a la DGII.
Estados y consulta
pending (firmado, por enviar) → sent (la DGII lo tiene) → accepted, conditional o rejected. Un número anulado antes de enviarse queda voided. Un rechazado no tiene valor fiscal y su número no se reutiliza: emite otro. Una nota de crédito o débito (33, 34) espera en pending a que la DGII acepte el comprobante que modifica; si ese fue rechazado, la nota queda blocked (no se envía) y su número se anula con annul. Si la DGII rechaza la autenticación de la empresa, sus envíos se pausan 10 minutos (dgii_auth_paused_until y dgii_auth_error en la empresa).
GET /documentscon filtrosecf_type,status,external_ref,from,to,search,page,limit.GET /documents/{id}yGET /documents/{id}/xml(el XML firmado;?summary=trueel RFCE).GET /documents/{id}/pdf: la representación impresa (RI) armada del XML firmado, con el QR de la DGII;?format=letter(por defecto),a4,ticket_80oticket_58.POST /documents/statuscon{ "ids": [...] }: hasta 100 a la vez.POST /documents/{id}/retrylo pone en cola ya.
Anular
POST /v1/companies/{companyId}/documents/{id}/annul
{ "reason": "Error en el precio", "void_code": 4 }Si todavía no se envió, su número se anula ante la DGII (ANECF) y se reporta en el 608 con void_code (1 a 10; 4 corrección de la información si no lo envías). Si la DGII ya lo tiene, Pixel Bill emite una nota de crédito (34) que lo anula entero, o una nota de débito (33) si lo anulado es una 34. Anular dos veces responde la primera anulación.
POST /voids con encf_from, encf_to y reason da de baja los próximos números de una secuencia que no se van a usar.
Webhooks
Regístralos en el portal o con POST /v1/integrators/{id}/webhooks (o en la empresa). El secreto (whsec_...) se muestra una vez. Eventos: document.status_changed, document.alert, received.created, company.contingency (también a las 48 y 72 horas del comprobante más antiguo sin enviar), company.auth_failed, certificate.expiring (a 60, 30, 7 y 1 días), certificate.approved, certificate.rejected, sequence.low y sequence.expiring. De estos, los avisos (certificado, secuencias, las 48 y 72 horas, autenticación rechazada y document.alert) también llegan por correo a los dueños y administradores de la empresa y al correo de la empresa.
{
"id": "a3f9...",
"event": "document.status_changed",
"created_at": "2026-10-10T14:03:40Z",
"company_id": "1d2e...",
"company_external_ref": "empresa-77",
"data": {
"id": "6f1c...",
"encf": "E320000000001",
"ecf_type": "32",
"kind": "document",
"status": "accepted",
"external_ref": "factura-8812",
"dgii_messages": [],
"decided_at": "2026-10-10T14:03:39Z"
}
}Cada POST lleva X-PixelBill-Event, X-PixelBill-Delivery (el id, para no procesarlo dos veces) y X-PixelBill-Signature: t=<unix>,v1=<hex>, el HMAC-SHA256 de <unix>.<cuerpo> con el secreto. Verifícalo así en Node:
import crypto from "node:crypto";
// raw: el cuerpo tal como llegó (Buffer), antes de JSON.parse.
export function verifyPixelBill(raw, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.`)
.update(raw)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(parts.v1 ?? "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// En Express: app.post("/webhooks/pixel-bill", express.raw({ type: "application/json" }), (req, res) => {
// if (!verifyPixelBill(req.body, req.get("X-PixelBill-Signature"), process.env.PIXEL_BILL_WEBHOOK_SECRET)) return res.sendStatus(401);
// const event = JSON.parse(req.body); // { id, event, created_at, company_id, company_external_ref, data }
// res.sendStatus(204); // responde rápido; procesa aparte
// });Lo que no responda 2xx se reintenta a 1 min, 5 min, 30 min, 2 h y 12 h; después se abandona y se puede reenviar a mano desde el portal o con .../deliveries/{id}/redeliver. En producción solo se aceptan direcciones https://.
Recibidos
Los suplidores que también son emisores envían sus e-CF al receptor de la empresa en Pixel Bill, que responde el acuse de recibo solo. GET /received los lista; POST /received/{id}/decide con { "approve": true } o { "approve": false, "reason": "..." } firma la aprobación comercial y la envía a la DGII y al suplidor. Cuando tu software registre la compra, anótalo con PUT /received/{id}/external-ref.
Reportes
GET /reports/608?period=202610 y GET /reports/607?period=202610 devuelven el TXT de la DGII. Lo que retuvieron tus clientes solo lo sabe tu software: envíalo con POST /reports/607 y { "period": "202610", "withholdings": [{ "encf": "E31...", "itbis_cents": 10000, "isr_cents": 0, "date": "2026-10-20" }] }. El 606 de compras lo genera quien lleva las compras.
Errores
Todo error responde { "error": "<frase en español>" }, lista para mostrar. Un documento rechazado antes de numerarse dice además qué campo falla:
HTTP/1.1 422 Unprocessable Entity
{
"error": "El documento tiene errores.",
"fields": [
{ "field": "buyer.rnc", "message": "Este tipo de comprobante necesita el RNC o la cédula del comprador." },
{ "field": "lines[0].itbis", "message": "El ITBIS de la línea es \"18\", \"16\", \"0\" o \"exempt\"." }
]
}- 400: JSON inválido, un campo desconocido o falta
Idempotency-Key. - 401: llave inválida, revocada o vencida. 403: la llave no tiene el permiso. 404: fuera de tu alcance.
- 409: la misma
Idempotency-Keycon otro cuerpo, un RNC ya registrado, una secuencia que se cruza. - 422: el documento o la configuración no lo permiten (sin secuencia vigente, empresa sin activar, certificado vencido).
- 429: demasiadas solicitudes; espera y reintenta con la misma
Idempotency-Key.
Para agentes de IA: un resumen en texto plano está en /llms.txt.