Welcome to the API Connect

The API Connect is Ocote's public HTTP interface for issuing Electronic Tax Documents (DTE) in El Salvador from your own system — ERP, e-commerce, POS, customer portal, etc. Every request creates a real fiscal document, signs it, transmits it to the Ministry of Finance (MH), and returns the result with the files ready to download.

What you can do

• Issue Invoices (01), Tax Credit Vouchers (CCF, 03), Export Invoices (11), Excluded Subject documents (14).
• Cancel and issue Credit Notes (05) against existing CCFs. If the CCF is more than three months old, the API automatically generates the credit note in compliance with regulation.
• Query the state of any document using the identifier you assigned (external_ref) or the UUID returned by Ocote.
• Download ticket PDF (for type 01) and signed JSON (all types) directly from the browser or your backend.

Everything covered by the full Ocote DTE platform — automatic 1% VAT withholding for Large Taxpayers and Government, email delivery, ticket generation, archival of the signed JSON with MH stamp — happens by default when you issue via the API. You don't have to ask for it.

API principles

The design of the API is optimized so your integration is robust without effort. The key concepts, which you will see repeated throughout this documentation, are:

Idempotency by external_ref

Each document is uniquely identified by the pair (company, external_ref). Retrying a request with the same external_ref never creates duplicates: either the API returns the already-issued document, or it retries the send if the prior attempt failed, preserving the same fiscal correlative.

Explicit, not implicit, states

The response from each endpoint tells you, with separate boolean flags, exactly what happened:

• success — the operation was registered in Ocote.
• dte_success — MH accepted and returned a stamp.
• contingency — MH did not respond; the document will be revalidated automatically.
• rejected — MH rejected the recipient data; you must correct and retry with the same external_ref.

You do not need to interpret strings or internal codes to know which path to take. See Responses and states.

Transparent contingency

If MH is down, you don't find out dramatically: the document is registered anyway with contingency: true, and Ocote revalidates it automatically when MH comes back. You don't have to implement queues or retries. See Contingency.

Fiscal correlatives are never regenerated

Once Ocote assigns a control_number to a document (DTE-01-M001P001-000000000000123), that number is fixed. Even if MH rejects and you correct and resend, the correlative stays. This complies with MH regulation on fiscal sequences and simplifies reconciliation.

Getting started

The shortest path:

1. Environment and base URL — where you talk to the API.
2. Authentication — get your odt_… API key.
3. Quickstart — issue your first DTE in 30 seconds.

Already in production?

If you are already consuming the API and saw that we added new response fields (contingency, rejected, dte_success, observaciones…), you don't need to change anything. The old fields keep working exactly as before. See Changelog.

Structure of this documentation

Section	Purpose
Getting started	Setup, auth, first call
Conventions	General API rules (UUIDs, dates, HTTP semantics)
Documents (DTE)	Reference by document type
Responses and states	Master table of what each flag combination means
Retry and idempotency	How to retry safely
Contingency	What happens when MH fails
Rate limits	Limits and control headers
Appendices	MH catalogs, error codes