Saltar al contenido principal

Autenticación y Ambientes

La API de Facturo ECF se autentica con una API Key enviada en cada petición. No hay intercambio de tokens ni sesiones: la misma clave se usa en todas las llamadas.

URL base​

https://ecf.facturord.app

Todas las rutas de la API cuelgan de /api/v1/ y están agrupadas por empresa:

https://ecf.facturord.app/api/v1/companies/{company_id}/emission/...
ElementoDescripción
company_idUUID de tu empresa en Facturo (ej.: a1b2c3d4-e5f6-7890-abcd-ef1234567890). Lo obtienes en el portal junto con tu API Key.

Header de autenticación​

Incluye tu API Key en el header X-API-Key:

X-API-Key: tu_api_key
Accept: application/json
Content-Type: application/json

Content-Type: application/json solo es necesario en peticiones con cuerpo (POST).

Ejemplo​

curl -X GET \
  "https://ecf.facturord.app/api/v1/companies/$FACTURO_COMPANY_ID/emission/invoices/$TRACK_ID/status" \
  -H "X-API-Key: $FACTURO_API_KEY" \
  -H "Accept: application/json"

Permisos (scopes) de la API Key​

Cada API Key se emite con los permisos (scopes) que necesita tu integración, por ejemplo:

ScopePermite
documents.emitOperaciones de emisión de documentos
documents.viewConsulta de documentos y de su estado

Asigna a cada clave solo los permisos que usa la integración.

Si la clave no tiene el permiso requerido, la API responde con un error 4xx (consulta Manejo de errores).

Ambientes de la DGII​

Facturo ECF opera contra los tres ambientes de la DGII. El ambiente se indica con el campo dgii_env (en el cuerpo de la petición o como parámetro de consulta, según el endpoint):

dgii_envAmbiente DGIIUso
testecfPruebas (TesteCF)Desarrollo e integración. Sin validez fiscal.
certecfCertificación (CerteCF)Proceso de certificación como emisor electrónico ante la DGII.
ecfProducción (eCF)Comprobantes reales con validez fiscal.

Si no envías dgii_env, Facturo usa el ambiente configurado para la empresa.

Separa tus ambientes

Usa testecf mientras desarrollas y cambia a ecf solo cuando tu integración esté validada. Los comprobantes emitidos en ecf tienen validez fiscal y no pueden "deshacerse" (solo anularse según las reglas de la DGII).

Buenas prácticas con la API Key​

# ✅ Variables de entorno
export FACTURO_API_KEY="tu_api_key"
export FACTURO_COMPANY_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  • Nunca incluyas la API Key en código fuente, repositorios o aplicaciones del lado del cliente (navegador o móvil).
  • Llama a la API solo desde tu backend.
  • Usa claves distintas por ambiente y por aplicación.
  • Rota las claves periódicamente y revoca las que ya no uses.

Próximos pasos​