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:
curl "https://api.ecfhub.com.do/v1/invoices?limit=10" -H "X-Api-Key: $ECF_API_KEY"using var http = new HttpClient { BaseAddress = new Uri("https://api.ecfhub.com.do/") };http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("ECF_API_KEY"));
using var response = await http.GetAsync("v1/invoices?limit=10");Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");const response = await fetch("https://api.ecfhub.com.do/v1/invoices?limit=10", { headers: { "X-Api-Key": process.env.ECF_API_KEY },});console.log(response.status, await response.json());Sin key, o con una revocada o vencida, la respuesta es 401.
Crear una API key
Sección titulada «Crear una API key»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 es403 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.
Qué se puede hacer con una API key
Sección titulada «Qué se puede hacer con una API key»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.
Buenas prácticas
Sección titulada «Buenas prácticas»- 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.
Límite de solicitudes
Sección titulada «Límite de solicitudes»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.