Ir al contenido

Autenticación (API keys)

Cada solicitud lleva la API key en el header X-Api-Key. En los ejemplos se lee de la variable de entorno ECF_API_KEY:

Ventana de terminal
curl "https://api.ecfhub.com.do/v1/invoices?limit=10" -H "X-Api-Key: $ECF_API_KEY"

Sin key, o con una revocada o vencida, la respuesta es 401.

En el portal, API keys → Crear (rol Owner o Admin). Puedes elegir:

  • Restringida a una empresa (recomendada): solo emite y consulta comprobantes de esa empresa, y no hace falta enviar companyId. Si lo envías con otra empresa, la respuesta es 403 company.not_in_key.
  • Para todas las empresas de la cuenta: cada envío debe indicar companyId (si no, 422 company.required). El ID de cada empresa se copia en su ficha.

La key se muestra una sola vez. Si la pierdes, crea otra y revoca la anterior. La lista de API keys dice si cada una es de prueba o de producción, según el ambiente de tu empresa.

Enviar y reenviar comprobantes; consultarlos (estado, XML firmado, PDF, acuses); leer tus empresas y secuencias; consultar los e-CF recibidos de proveedores y enviar aprobaciones comerciales. La lista completa está en la referencia.

La administración de la cuenta (usuarios, certificados, secuencias, webhooks y API keys) se hace en el portal.

  • Guárdala como un secreto (variable de entorno o almacén de secretos), nunca en el código ni en el navegador.
  • Usa una key por sistema o por sucursal: así puedes revocar una sin detener las demás.
  • Llama a la API desde tu servidor, no desde el navegador de tus usuarios.

Cada API key puede hacer 120 solicitudes por minuto, contando juntos los envíos y las consultas de comprobantes (/v1/invoices…). El límite puede cambiar según tu plan. Si lo superas, la respuesta es 429 con el header Retry-After (los segundos que debes esperar). Para seguir el estado de muchos comprobantes usa webhooks o el listado, en lugar de consultar uno por uno.