Elige cómo integrar tu sistema

Tu sistema puede cobrar con Timbro, emitir facturas electrónicas con Timbro o hacer las dos cosas. El pago y la factura son recursos separados, y cada guía de esta documentación parte de una situación concreta de venta. Busca en la tabla la que se parece a la de tu negocio y abre su guía.

Situación del negocio	Qué hace tu sistema
Tu sistema emite la factura y el cliente la paga después, con un link de pago o un QR	Emite la factura y crea un pago con su invoiceId
Una venta a crédito que el cliente paga en abonos	Emite la factura a crédito y crea un pago por cada abono
El cliente paga en línea y Timbro emite la factura cuando se confirma el pago	Crea el pago con los artículos de la venta y el tipo de comprobante
El cliente paga primero y tu sistema emite la factura después	Crea el pago y luego relaciona con él la factura que emitiste
Tu sistema factura y el cliente paga fuera de Timbro: en efectivo, por transferencia o en la terminal de tarjeta	Emite la factura e indica en ella cómo pagó el cliente
Solo necesitas cobrar, sin factura	Crea un pago por monto
Devuelves dinero de una venta que ya facturaste	Crea el reembolso, emite la nota de crédito y relaciónalos

Facturar no requiere una afiliación de Azul, CardNet o Portal. Cobrar con tarjeta sí la requiere. Puedes hacer las dos cosas con la misma clave de API si le das acceso a Cobra y a Facturación.

Qué guarda tu sistema

Cada venta puede tener un pago, una factura o los dos. Guarda estos valores junto a la venta para consultar cada recurso y para repetir una solicitud sin duplicarla:

Valor	Para qué sirve
paymentReference	Tu sistema la define para identificar el pago. Si repites la solicitud con la misma referencia, recibes el mismo pago
id del pago	Timbro lo asigna. Con él consultas, cancelas o reembolsas el pago
invoiceReference	Tu sistema la define para identificar la factura. Si repites la solicitud con la misma referencia, recibes la misma factura
invoiceId	Timbro lo asigna. Con él consultas la factura, descargas sus archivos y la cobras
e-NCF	Timbro lo asigna. Es el número fiscal que imprimes; tu sistema no lo calcula

Un pago en succeeded confirma que el cliente pagó, pero no que la DGII aceptó la factura ni que su PDF esté listo. Consulta cada recurso por separado.

Cómo se entera tu sistema de un cambio

Timbro avisa a tu servidor con un webhook cuando cambia un pago, un reembolso o una factura. El aviso solo dice qué cambió; tu servidor consulta después el recurso para conocer su estado actual. Si tu servidor no puede recibir avisos, consulta periódicamente los pagos y las facturas que siguen pendientes.