Bienvenido al API Connect
El API Connect es la interfaz pública HTTP de Ocote para emitir Documentos Tributarios Electrónicos (DTE) en El Salvador desde tu propio sistema — ERP, e-commerce, POS, cartera de clientes, etc. Cada petición crea un documento fiscal real, lo firma, lo transmite al Ministerio de Hacienda (MH) y te devuelve el resultado con los archivos listos para descargar.
¿Qué puedes hacer?
- Emitir Facturas (01), Comprobantes de Crédito Fiscal (03), Facturas de Exportación (11), Sujetos Excluidos (14).
- Anular y emitir Notas de Crédito (05) sobre CCF existentes. Si el CCF tiene más de tres meses de emitido, el API genera la NC automáticamente respetando la normativa.
- Consultar el estado de cualquier documento con el identificador que tú asignaste (
external_ref) o con el UUID que devuelve Ocote. - Descargar ticket PDF (para tipo 01) y JSON firmado (todos los tipos) directamente desde el navegador o tu backend.
Todo lo que está cubierto en la plataforma Ocote DTE — cálculo automático de retención IVA del 1 % a Grandes Contribuyentes y Gobierno, envío por correo, generación de tickets, archivado del JSON firmado con sello MH — ocurre por defecto cuando emites vía API. No tienes que pedirlo.
Principios del API
El diseño del API está optimizado para que tu integración sea robusta sin esfuerzo. Los conceptos clave, que vas a encontrar repetidos a lo largo de la documentación, son:
Idempotencia por external_ref
Cada documento se identifica de forma única por la combinación (empresa, external_ref). Reintentar una petición con el mismo external_ref nunca crea duplicados: o te devuelve el documento ya emitido, o reintenta el envío si el intento anterior falló conservando el mismo correlativo fiscal.
Estados explícitos, no implícitos
El response de cada endpoint te dice, con flags booleanos separados, exactamente qué pasó:
success— la operación quedó registrada en Ocote.dte_success— el MH aceptó y devolvió sello.contingency— el MH no respondió; el documento se validará automáticamente.rejected— el MH rechazó por datos del receptor; debes corregir y reintentar con el mismoexternal_ref.
No necesitas interpretar strings ni códigos internos para saber qué camino tomar. Ver Respuestas y estados.
Contingencia transparente
Si el MH está caído, no te enteras de forma dramática: el documento se registra igual, con contingency: true, y Ocote lo revalida automáticamente cuando el MH vuelve. Tú no tienes que implementar colas ni reintentos. Ver Contingencia.
Los correlativos fiscales no se regeneran
Una vez que Ocote asigna un control_number a un documento (DTE-01-M001P001-000000000000123), ese número queda fijo. Aun si el MH rechaza y lo corriges y reenvías, el correlativo se mantiene. Esto cumple con la normativa MH de secuencias fiscales y simplifica tu conciliación.
Cómo empezar
La ruta más corta:
- Ambiente y URL base — dónde hablas con el API.
- Autenticación — obtén tu API key
odt_…. - Quickstart — emite tu primer DTE en 30 segundos.
Si ya estás consumiendo el API y viste que agregamos campos nuevos en el response (contingency, rejected, dte_success, observaciones…), no necesitas cambiar nada. Los campos viejos siguen funcionando igual. Ver Changelog.
Estructura de esta documentación
| Sección | Para qué sirve |
|---|---|
| Primeros pasos | Setup, auth, primer llamado |
| Convenciones | Reglas generales del API (UUIDs, fechas, semántica HTTP) |
| Documentos (DTE) | Referencia por tipo de documento |
| Respuestas y estados | Tabla maestra de qué significa cada combinación de flags |
| Retry e idempotencia | Cómo reintentar con seguridad |
| Contingencia | Qué pasa cuando el MH falla |
| Rate limits | Límites y headers de control |
| Apéndices | Catálogos MH, códigos de error |