Set up invoicing

Before issuing invoices, the business needs its digital certificate and, to invoice Live, the e-NCF sequences the DGII granted it. An owner or administrator can import the certificate and record the sequences in Portal Timbro, or your system can do it with the API. If the business already completed these steps in Portal Timbro, go to Issue an invoice from your system.

These operations are under /v1/business and require an administrator key. Send the certificate and its password only from your server, and do not store them in logs.

Prepare Test mode

1. Call POST /v1/business/configure-invoicing with {"mode":"test"} and an idempotency key (Idempotency-Key) that does not change between attempts.
2. Call POST /v1/business/import-signing-certificate with the certificate in certificateP12Base64 and its password in password. The business has a single certificate, which Timbro uses in both modes. If you import another valid certificate, it replaces the previous one in both modes.
3. Call POST /v1/business/issue-test-invoice to issue the test invoice. documentType is optional.

Test invoices go to the DGII test environment and have no fiscal value. In Test mode you do not have to record e-NCF sequences, because Timbro assigns them.

Check which types you can issue

Read the business with GET /v1/business. capabilities.invoices.test.status and capabilities.invoices.live.status say whether each mode is active. Inside invoicing.test and invoicing.live, documentTypes has one entry per e-CF type:

• A ready type can be issued, and its numbering shows how many numbers it has left and when the sequence expires.
• An actionRequired type lists in reasons what is missing, such as signing_certificate_missing or authorization_missing, in the order you must resolve them.

The list is empty until you set up invoicing for that mode, and it is null when Timbro could not retrieve it at that moment. In that case, read the business again. Before offering a type in your system, check that it is ready.

Switch to Live mode

1. Call POST /v1/business/configure-invoicing with {"mode":"live"} and its own idempotency key (Idempotency-Key) that stays the same across retries. The certificate you already imported also works Live.
2. Record each e-NCF sequence the DGII granted the business in its Oficina Virtual with POST /v1/business/record-sequence. Send documentType, firstNumber, lastNumber, and expiresOn. Consumer Invoice (E32) and credit note (E34) sequences do not expire, so they take no expiresOn. nextNumber is optional and, if you do not send it, it equals firstNumber.
3. Read the business again. Live invoicing is active when the certificate is valid and at least one type is ready.

The record-sequence response is the complete business, so you can see right away whether the type is ready or what it still needs. While Live mode is not active, each requirements entry with mode: "live" says what is missing, such as the issuer profile, the certificate, the sequences, or the DGII confirmation, and which types it affects (documentTypes).

In Portal Timbro, the owner or an administrator can record the same sequences with a guide that explains how to request them from the DGII.

When a type is ready Live, create a Live API key with Invoicing access in Portal Timbro. That key gives access to the API, but it does not replace the certificate or the sequences.