Credenciales API
Para integrarte con Facturo ECF necesitas dos datos:
| Credencial | Descripción |
|---|---|
| API Key | Clave secreta de integración. Se envía en el header X-API-Key en cada petición. |
| Company ID | UUID de tu empresa en Facturo (ej.: a1b2c3d4-e5f6-7890-abcd-ef1234567890). Forma parte de todas las rutas: /api/v1/companies/{company_id}/... |
Generar una API Key
- En el portal, navega a Configuración → Desarrolladores → API Keys
- Presiona + Nueva API Key
- Asigna un nombre descriptivo (ej.: "ERP Producción", "Odoo")
- Selecciona los permisos (scopes) que necesita la integración, por ejemplo:
documents.emit— emisión de documentosdocuments.view— consulta de documentos y su estado
- Clic en Generar
Copia la clave inmediatamente
La API Key se muestra una sola vez. Guárdala en un gestor de secretos o en variables de entorno. Si la pierdes, genera una nueva y revoca la anterior.
Anota también el UUID de la empresa (Company ID), que necesitarás en cada llamada.
Usar las credenciales
export FACTURO_API_KEY="tu_api_key"
export FACTURO_COMPANY_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
curl "https://ecf.facturord.app/api/v1/companies/$FACTURO_COMPANY_ID/emission/invoices/$TRACK_ID/status" \
-H "X-API-Key: $FACTURO_API_KEY"
No hay que intercambiar la API Key por un token: la misma clave se envía en todas las peticiones. Más detalles en Autenticación y Ambientes.
Ambiente de la DGII
El ambiente no depende de la API Key, sino del campo dgii_env de cada petición:
dgii_env | Ambiente |
|---|---|
testecf | Pruebas |
certecf | Certificación |
ecf | Producción |
Seguridad de credenciales
✅ Buenas prácticas
// CORRECTO: variables de entorno
const apiKey = process.env.FACTURO_API_KEY;
# CORRECTO: archivo .env excluido del control de versiones (.gitignore)
FACTURO_API_KEY=tu_api_key
FACTURO_COMPANY_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
❌ Malas prácticas
// NUNCA hardcodees la clave
const apiKey = "tu_api_key";
// NUNCA la incluyas en archivos versionados ni en código del navegador o apps móviles
Rotación de credenciales
¿Cuándo rotar?
- Periódicamente (por ejemplo cada 90 días)
- Al cambiar el personal con acceso
- Ante sospecha de compromiso
- Tras una auditoría de seguridad
Procedimiento seguro:
- Genera una nueva API Key (mantén la anterior activa)
- Actualiza tus aplicaciones con la nueva clave
- Verifica en el ambiente
testecf - Despliega a producción
- Monitorea durante 24 horas
- Revoca la API Key antigua