Quickstart
In this guide you issue an Invoice (Factura, 01) in the MH test environment. Nothing you do here has fiscal value.
-
Create your account and organization.
Go to app.openfactura.co, sign up (the password must be at least 10 characters long), and create an organization. You become its owner, with every permission.
-
Register the issuer.
When you create the organization, guided onboarding asks for your tax details exactly as they appear on your NRC card: NIT, NRC, name, economic activity, address (department, municipality, and district), phone, and email. Saving creates the establishment
M001and the point of saleP001. You can edit them later under Company & Tax Authority → Tax details. -
Connect to Hacienda.
In the last onboarding step, upload the following for environment
00:- the test certificate (
.crt) and the password of your private key, - the API password you set in Hacienda’s issuer portal (Sitio Emisores DTE).
When you click Connect to Hacienda, Open Factura checks that the password opens the key and that the certificate’s NIT matches the issuer’s, then authenticates against the MH. Secrets are stored encrypted and the API never returns them. If you choose “I’ll do it later”, onboarding stays available from Home, and you can also upload the credentials under Company & Tax Authority → MH credentials.
- the test certificate (
-
Create a test API key.
Under API keys → New key, choose test mode and the
dte:readanddte:emitpermissions. Copy theof_test_…key: it is shown only once.Ventana de terminal export OPENFACTURA_API_KEY=of_test_... -
Validate and issue your first invoice.
On an Invoice,
precioUniincludes VAT (IVA). Open Factura calculates the VAT, the rounding, and the total.Validate first: it doesn’t consume a control number, sign, or transmit.
Ventana de terminal curl https://app.openfactura.co/api/v1/dte/validar \-H "Authorization: Bearer $OPENFACTURA_API_KEY" \-H "Content-Type: application/json" \-d '{"tipoDte": "01","datos": { "items": [{ "descripcion": "Servicio", "cantidad": 2, "precioUni": 11.3 }] }}'If
problemascomes back empty, issue with your ownIdempotency-Key:Ventana de terminal curl https://app.openfactura.co/api/v1/dte \-H "Authorization: Bearer $OPENFACTURA_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: primera-factura-001" \-d '{"tipoDte": "01","datos": { "items": [{ "descripcion": "Servicio", "cantidad": 2, "precioUni": 11.3 }] }}'Ventana de terminal npm i -g @openfactura/cliopenfactura login --url https://app.openfactura.co # prompts for the key without echoing itSave the body as
factura.json:{"tipoDte": "01","datos": { "items": [{ "descripcion": "Servicio", "cantidad": 2, "precioUni": 11.3 }] }}Ventana de terminal openfactura dte validar factura.jsonopenfactura dte emitir factura.jsonThe CLI generates and prints an
Idempotency-Keybefore sending.Connect your agent (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Zed, Cline, or Goose) with the CLI, which uses the key saved by
login:Ventana de terminal npx @openfactura/cli loginnpx @openfactura/cli mcp install --todos # or a single agent: cursor, codex, vscode…Any other MCP client connects to
https://openfactura.co/mcpwith the headerAuthorization: Bearer of_test_.... Per-agent configuration is in Connect your agent.Then ask it, for example:
Issue a final-consumer invoice for 2 services at $11.30 each, VAT included.
The assistant uses
dte_validar, shows you the summary, and callsdte_emitironly once you confirm.
Response
Section titled “Response”201 Created with the Documento processed by the MH:
{ "id": "…", "codigoGeneracion": "0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4", "numeroControl": "DTE-01-M001P001-000000000000001", "tipoDte": "01", "ambiente": "00", "estado": "procesado", "fechaEmision": "2026-11-12", "horaEmision": "01:38:12", "receptorNombre": null, "receptorDocumento": null, "total": 22.6, "selloRecibido": "20265EE94C1B2C4CBB56F56121E37F5AC8CA7D27", "origen": "api", "error": null, "creado": 1794469092559, "urlConsulta": "https://admin.factura.gob.sv/…"}If the MH doesn’t respond, you get 202 Accepted with status contingencia: the document is already
signed and valid, and it is transmitted later (see Contingency).
Deliver the document
Section titled “Deliver the document”The recipient gets the official JSON and its graphic representation (PDF):
curl -o factura.json https://app.openfactura.co/api/v1/dte/0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4/json \ -H "Authorization: Bearer $OPENFACTURA_API_KEY"curl -o factura.pdf https://app.openfactura.co/api/v1/dte/0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4/pdf \ -H "Authorization: Bearer $OPENFACTURA_API_KEY"openfactura dte json 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 -o factura.jsonopenfactura dte pdf 0862382B-0BB8-42A0-BB6B-B42DCCDF1EA4 -o factura.pdfdte_obtener with the codigoGeneracion returns the status, the stamp, and the MH response. For the
files, use the CLI or the API.
Next steps
Section titled “Next steps”- Issue each document type
- Idempotency: retry without issuing twice.
- Environments: go to production.
For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.