Pixel BillAPI v1Entrar al portal

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

  1. La empresa se certifica como emisor electrónico ante la DGII nombrando a Pixel Bill como su software externo.
  2. 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 202 con status: "pending_review", el estado lo muestra en certificate_review y no firma hasta que Pixel Bill lo apruebe.
  3. 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.
  4. 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.
  5. 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:write emitir, anular y reintentar.
  • documents:read consultar comprobantes y reportes.
  • received comprobantes recibidos de suplidores y su aprobación comercial.
  • config datos 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_cents es precio por cantidad sin ITBIS; discount_cents lo lleva al neto. itbis es "18", "16", "0" o "exempt"; itbis_cents se 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ía itbis_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 (001 propina 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.rnc es obligatorio en 31, 41 y 45; un 47 lleva buyer.foreign_id. Un 32 a consumidor final no lleva comprador.
  • reference es obligatorio en 33 y 34: { "document_id": "<id en Pixel Bill>", "code": 3, "reason": "..." } o, para un comprobante de fuera, encf y date.
  • total_cents es 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 /documents con filtros ecf_type, status, external_ref, from, to, search, page, limit.
  • GET /documents/{id} y GET /documents/{id}/xml (el XML firmado; ?summary=true el 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_80 o ticket_58.
  • POST /documents/status con { "ids": [...] }: hasta 100 a la vez.
  • POST /documents/{id}/retry lo 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-Key con 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.