Hacienda certification tests
To authorize you as an issuer, Hacienda requires that you successfully transmit a minimum number of documents in the test environment, within your 2-month window. Open Factura issues them for you:
| Test | Minimum |
|---|---|
| Invoice (01) | 90 |
| Tax Credit Invoice (03) | 75 |
| Invalidation event | 5 |
| Contingency event | 5 |
These are mandatory for every issuer on the Transmission System (Sistema de Transmisión). If you are going to issue other documents, click Certify the other documents too when you finish: it also issues the tests for Delivery Note (50), Credit Note (50), Debit Note (25), Withholding Receipt (50), Settlement Receipt (75), Settlement Accounting Document (50), Export Invoice (90), Excluded Subject Invoice (25), Donation Receipt (25), and the return (5) and special operations (5) events. That way you can request authorization for everything at once.
Before you begin
Section titled “Before you begin”- Hacienda’s test credentials loaded (certificate and API password).
- A recipient for the test Tax Credit Invoices: Open Factura or another taxpayer (see below).
- The issuer’s responsible person: Hacienda requires it on invalidation and contingency events. The page asks for it if it’s missing.
How it works
Section titled “How it works”- Dry run. It issues one Invoice, one Tax Credit Invoice, one invalidation, and one contingency cycle. If something is wrong, it shows up here and not on document 60. The dashboard pauses when the dry run ends so you can check the counter in the Sitio Emisores DTE.
- Volume. It issues the rest: up to 90 Invoices and 75 Tax Credit Invoices, then the remaining invalidations and contingencies. An invalidated Invoice still counts, just as in Hacienda’s counter.
- If Hacienda rejects a test, it stops and shows you the MH code and observations. It doesn’t spend any more control numbers. Fix the cause and resume: it continues where it left off.
- When complete, go to the Sitio Emisores DTE, check the counter, and open Solicitar Autorización (Request Authorization).
Test Tax Credit Invoices need another taxpayer as the recipient: Hacienda rejects the ones
addressed to your own company ([receptor.nit] VALOR NO VALIDO). Under Certification, choose the
recipient before starting:
- Open Factura (recommended): the test recipient built into Open Factura. You don’t have to find anyone.
- Another taxpayer: type their NIT, NRC, name, economic activity, address, and email right there.
The recipient isn’t saved as a customer: there are no saved customers in test mode. If you choose
your own company, certification responds receptor_propio. With real credentials, starting without
a recipient responds 409 receptor_ccf_requerido.
Open Certification and click Start. You can pause and resume whenever you want.
openfactura certificacion ejecutar --receptor openfactura # the mandatory testsopenfactura certificacion ejecutar --completo # every document and eventopenfactura certificacion ejecutar --desde-cero # discards progress and counts from nowopenfactura certificacion estado--receptor takes openfactura, or a JSON file (or - to read it from stdin) with another
taxpayer’s details. You only need to pass it the first time; it’s remembered afterwards.
--desde-cero is for when Hacienda opens a new window for you.
ejecutar exits with 0 on completion and with 1 if Hacienda rejected a test or stopped responding.
receptor is "openfactura" or an object with another taxpayer’s nit, nrc, nombre,
codActividad, descActividad, direccion, and correo. It also accepts alcance (minimo or
completo) and desdeCero: true.
curl -X POST https://app.openfactura.co/api/v1/ext/certificacion/iniciar \ -H "Authorization: Bearer $OPENFACTURA_API_KEY" \ -H "Content-Type: application/json" -d '{"receptor": "openfactura"}'
# Repeat while "estado" is "en_curso":curl -X POST https://app.openfactura.co/api/v1/ext/certificacion/avanzar \ -H "Authorization: Bearer $OPENFACTURA_API_KEY"The key needs dte:read, dte:emit, and dte:invalidate.
Ask your agent: “run my Hacienda certification tests”. It uses certificacion_avanzar until
completion and shows you the rejection, if any. The first call carries the receptor argument
("openfactura" or another taxpayer’s details).
For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.