Skip to content

In this guide you issue an Invoice (Factura, 01) in the MH test environment. Nothing you do here has fiscal value.

  1. 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.

  2. 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 M001 and the point of sale P001. You can edit them later under Company & Tax Authority → Tax details.

  3. 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.

  4. Create a test API key.

    Under API keys → New key, choose test mode and the dte:read and dte:emit permissions. Copy the of_test_… key: it is shown only once.

    Ventana de terminal
    export OPENFACTURA_API_KEY=of_test_...
  5. Validate and issue your first invoice.

    On an Invoice, precioUni includes 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 problemas comes back empty, issue with your own Idempotency-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 }] }
    }'

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).

The recipient gets the official JSON and its graphic representation (PDF):

Ventana de terminal
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"

For AI assistants: llms.txt ·llms-full.txt ·every page as Markdown by adding .md to its path.