Ir al contenido
Documentación
Empieza gratis

Cobrar y facturar

Facturar al momento del pago

Si tu cliente paga en línea y tu sistema no emite facturas, Timbro puede emitir la factura en cuanto se confirma el pago. En Checkout, tu cliente puede elegir si quiere una Factura de Consumo o una Factura de Crédito Fiscal y escribir su RNC; Timbro emite la factura con los artículos del pago.

Si tu sistema ya emite la factura antes de cobrar, no necesitas esta guía: cobra la factura que ya emitiste.

Para facturar al crear el pago necesitas:

  • Una clave de API con acceso a Cobra y a Facturación. En estos ejemplos la guardas en TIMBRO_API_KEY.
  • La facturación configurada en el modo que vas a usar.
  • Los artículos de la venta, en pesos dominicanos (DOP), con su unidad de medida (unit) y si son un bien o un servicio (kind). Un pago que solo lleva amount no puede facturarse.

Timbro emite la factura

Sección titulada «Timbro emite la factura»

Envía los artículos y, en invoicing, el modo automatic y el tipo de comprobante que Checkout muestra elegido al abrir:

import { createTimbroInvoices } from "@timbro/invoices";
import { createTimbroPayments } from "@timbro/payments";


const timbro = createTimbroPayments({ apiKey: process.env.TIMBRO_API_KEY! });
const timbroInvoices = createTimbroInvoices({ apiKey: process.env.TIMBRO_API_KEY! });
const automaticPayment = await timbro.payments.create({
  paymentReference: "venta-124",
  currency: "DOP",
  items: [{
    description: "Servicio",
    quantity: "1",
    unit: "unit",
    kind: "service",
    unitPrice: "1250.00",
    tax: { kind: "itbis_18", included: true },
  }],
  returnUrl: "https://merchant.example/ventas/124",
  invoicing: { mode: "automatic", type: "E32", recipientEmail: "comprador@example.com" },
});

type puede ser Factura de Consumo (E32), Factura de Crédito Fiscal (E31) o Comprobante Gubernamental (E45). El cliente puede cambiarlo en Checkout. Para limitar los tipos que puede elegir, envía allowedTypes; para que no pueda cambiarlo, envía isTypeLocked: true. Si ya conoces al comprador, envíalo en buyer, y isBuyerLocked: true impide que el cliente lo cambie. Un Comprobante Gubernamental también necesita governmentEligibility.

recipientEmail es opcional. Con él, Timbro le envía la factura al cliente por correo cuando la DGII la acepta.

Cuando el pago llega a succeeded, Timbro emite la factura y el pago muestra su invoiceId. Consulta la factura para conocer su estado y sus archivos; que el pago esté en succeeded no confirma que la DGII ya aceptó la factura:

const paid = await timbro.payments.retrieve(automaticPayment.id);
const invoice = paid.invoiceId ? await timbroInvoices.invoices.retrieve(paid.invoiceId) : undefined;

La guía Descargar y enviar la factura explica los estados de la factura y cómo descargar el XML y el PDF.

Cuando tu sistema emite la factura después del pago

Sección titulada «Cuando tu sistema emite la factura después del pago»

Si tu sistema debe emitir la factura, pero quieres que el cliente elija el tipo de comprobante en Checkout, crea el pago con el modo merchant. Timbro guarda la elección del cliente y no emite la factura; tu sistema la emite con la API de facturación cuando el pago se confirma, y después la relaciona con el pago.

Primero crea el pago y guarda su id junto a la venta:

const merchantPayment = await timbro.payments.create({
  paymentReference: "venta-125",
  currency: "DOP",
  items: [{
    description: "Servicio",
    quantity: "1",
    unit: "unit",
    kind: "service",
    unitPrice: "1250.00",
    tax: { kind: "itbis_18", included: true },
  }],
  invoicing: { mode: "merchant", type: "E32" },
});

Cuando el pago esté en succeeded, lee en invoicing el tipo y el comprador que eligió el cliente, emite la factura con esos datos y los mismos artículos, y espera a que la DGII la acepte. Después relaciónala con el pago:

const currentPayment = await timbro.payments.retrieve(merchantPayment.id);
if (currentPayment.status !== "succeeded") throw new Error("Payment not yet confirmed");
const linked = await timbro.payments.attachInvoice(merchantPayment.id, {
  invoiceId: "f35b7ae4-c484-4c63-981e-4f0f15e913b5",
});

La factura debe ser del mismo negocio y del mismo modo que el pago, y sus datos fiscales deben coincidir con la venta. Si no coinciden, la API rechaza la relación y la factura sigue siendo válida en la DGII.

Cambia el correo de la factura

Sección titulada «Cambia el correo de la factura»

El pago muestra en invoicing.recipientEmail el correo al que Timbro enviará la factura, o null si no hay ninguno. Para cambiarlo antes de que se envíe, usa PUT /v1/payments/{paymentId}/invoice-recipient:

await timbro.payments.updateInvoiceRecipient({
  paymentId: automaticPayment.id,
  recipientEmail: "comprador@example.com",
  idempotencyKey: "venta-124-correo-1",
});

Timbro o tu sistema le envía la factura al cliente, nunca los dos. Si tu sistema la envía, no indiques recipientEmail ni llames a esta operación. Para enviar por correo una factura que ya existe, sigue Envía la factura por correo.

Facturar en vivo

Sección titulada «Facturar en vivo»

En modo en vivo, Timbro solo acepta un pago con automatic o merchant cuando tu negocio ya puede emitir en vivo cada tipo que el pago permite. Si falta algo, la API responde 409 business_fiscal_setup_incomplete, y su detail dice qué falta; Configurar la facturación explica cómo completarlo. Si Timbro no puede comprobarlo en ese momento, responde 503 business_fiscal_setup_unavailable: repite la misma solicitud más tarde.

Un pago sin factura, o un pago por una factura que ya existe, no necesita esta comprobación. Por eso un sistema de caja que emite sus propias facturas puede seguir cobrando aunque la facturación de Timbro no esté disponible.