Documentación de la API

La API de EdFactura es REST sobre HTTPS. Todas las respuestas son JSON en UTF-8, con el mismo formato, y las fechas usan ISO 8601 (AAAA-MM-DD).

1. Cree una cuenta gratis (su solicitud se aprueba en breve).
2. En el panel, vaya a API keys y genere una llave. Guárdela: se muestra una sola vez.
3. Envíela en la cabecera X-API-Key en cada petición.

curl "https://api.edfactura.com/v1/rnc/{rnc}" \
  -H "X-API-Key: SU_API_KEY"

Autenticación

Cada petición debe incluir su API key en una de estas cabeceras:

X-API-Key: edf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# o bien
Authorization: Bearer edf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La llave no se acepta en la URL (?api_key=): quedaría guardada en historiales, bitácoras de servidores y proxies.

Buenas prácticas

• Guarde la llave en una variable de entorno o en un gestor de secretos, nunca en el código fuente ni en un repositorio.
• Use una llave por sistema o entorno (producción, pruebas) para poder revocarlas por separado.
• Asigne solo los permisos que el sistema necesita y una fecha de expiración cuando sea posible.
• Si su servidor tiene IP fija, agréguela en IPs permitidas.

Uso desde el navegador (CORS)

Por seguridad, una llave solo funciona desde un navegador si el dominio de la página está en sus Orígenes permitidos (admite comodín: *.midominio.com). Aun así, cualquier visitante podría ver la llave en el código de la página: prefiera llamar a la API desde su servidor.

Sandbox y producción

Hay dos tipos de llave. La URL es la misma: el ambiente lo determina la llave.

Cada respuesta indica el ambiente en meta.ambiente y en la cabecera X-API-Environment. Ambas llaves respetan el límite por minuto del plan. Integre y pruebe todos los casos (incluidos los errores) en sandbox; cambie a la llave de producción al desplegar.

Formato de respuesta

Toda respuesta tiene success. Si es true, los datos están en data; si es false, el detalle está en error. Programe contra error.code (estable), no contra el texto de error.message (puede cambiar).

{
  "success": true,
  "data": { "...": "..." },
  "meta": {
    "request_id": "9f1c2a7b3e4d5f60",
    "timestamp": "2026-09-25T10:15:00-04:00"
  }
}

{
  "success": false,
  "error": {
    "code": "rnc_not_found",
    "message": "El RNC 101000000 no está registrado en la DGII."
  },
  "meta": { "request_id": "c41d09e2a7b3f851", "...": "..." }
}

Cada respuesta incluye la cabecera X-Request-Id, igual a meta.request_id. Inclúyala al reportar un problema.

Errores

Límites y cuotas

Hay dos límites: peticiones por minuto (por cuenta y ambiente: todas sus llaves suman) y consultas por mes (por cuenta). Solo las respuestas exitosas (2xx) consumen la cuota mensual. Cada respuesta informa el estado del límite por minuto:

Módulos

Cada módulo tiene su página, con sus endpoints.

Estado del servicio

Endpoint público para monitoreo. Responde 200 si el servicio está operativo, o 503 si hay degradación.

{ "success": true, "data": { "status": "ok" }, "meta": { "request_id": "…", "timestamp": "…" } }

Versionado

La versión va en la ruta (/v1) y cada respuesta la informa en la cabecera X-API-Version. Dentro de una versión solo se hacen cambios compatibles: endpoints nuevos, parámetros opcionales o campos nuevos en las respuestas. Su integración debe ignorar los campos que no conozca.

Los cambios incompatibles se publican como una versión nueva (/v2) que convive al menos 12 meses con la anterior. Cuando una versión se declara obsoleta, sus respuestas incluyen las cabeceras estándar Deprecation y Sunset (fecha de retiro); después de esa fecha responde 410 version_retired.