Configurar la facturación

Antes de emitir facturas, el negocio necesita su certificado digital y, para facturar en vivo, las secuencias de e-NCF que le otorgó la DGII. Una persona propietaria o administradora puede importar el certificado y registrar las secuencias en Portal Timbro, o tu sistema puede hacerlo con la API. Si el negocio ya completó estos pasos en Portal Timbro, pasa a Emitir una factura desde tu sistema.

Estas operaciones están en /v1/business y requieren una clave de administrador. Envía el certificado y su contraseña solo desde tu servidor, y no los guardes en registros.

Prepara el modo de prueba

1. Llama a POST /v1/business/configure-invoicing con {"mode":"test"} y una clave de idempotencia (Idempotency-Key) que no cambie entre intentos.
2. Llama a POST /v1/business/import-signing-certificate con el certificado en certificateP12Base64 y su contraseña en password. El negocio tiene un solo certificado, que Timbro usa en los dos modos. Si importas otro certificado vigente, reemplaza al anterior en ambos modos.
3. Llama a POST /v1/business/issue-test-invoice para emitir la factura de prueba. documentType es opcional.

Las facturas de prueba van al ambiente de pruebas de la DGII y no tienen valor fiscal. En modo de prueba no tienes que registrar secuencias de e-NCF, porque Timbro las asigna.

Comprueba qué tipos puedes emitir

Lee el negocio con GET /v1/business. capabilities.invoices.test.status y capabilities.invoices.live.status dicen si cada modo está active. Dentro de invoicing.test y invoicing.live, documentTypes trae una entrada por tipo de e-CF:

• Puedes emitir un tipo ready, y su numbering muestra cuántos números le quedan y cuándo vence la secuencia.
• Un tipo actionRequired lista en reasons lo que falta, como signing_certificate_missing o authorization_missing, en el orden en que debes resolverlo.

La lista está vacía hasta que configures la facturación de ese modo, y es null cuando Timbro no pudo consultarla en ese momento. En ese caso, vuelve a leer el negocio. Antes de ofrecer un tipo en tu sistema, comprueba que esté ready.

Pasa al modo en vivo

1. Llama a POST /v1/business/configure-invoicing con {"mode":"live"} y su propia clave de idempotencia (Idempotency-Key), que no cambie entre intentos. El certificado que ya importaste también sirve en vivo.
2. Registra cada secuencia de e-NCF que la DGII le otorgó al negocio en su Oficina Virtual con POST /v1/business/record-sequence. Envía documentType, firstNumber, lastNumber y expiresOn. Las secuencias de Factura de Consumo (E32) y de nota de crédito (E34) no vencen, así que no llevan expiresOn. nextNumber es opcional y, si no lo envías, es igual a firstNumber.
3. Lee el negocio de nuevo. La facturación en vivo está active cuando el certificado está vigente y al menos un tipo está ready.

La respuesta de record-sequence es el negocio completo, así que puedes ver enseguida si el tipo quedó ready o qué le falta. Mientras el modo en vivo no esté activo, cada entrada de requirements con mode: "live" dice qué falta, como el perfil del emisor, el certificado, las secuencias o la confirmación de la DGII, y qué tipos afecta (documentTypes).

En Portal Timbro, la persona propietaria o administradora puede registrar las mismas secuencias con una guía que explica cómo solicitarlas a la DGII.

Cuando un tipo esté ready en vivo, crea en Portal Timbro una clave de API en vivo con acceso a Facturación. Esa clave da acceso a la API, pero no reemplaza el certificado ni las secuencias.