Autenticación y ambientes
Factumel usa API keys Bearer, no login mediante correo y contraseña ni cookies de sesión. Cada clave pertenece a una organización y a un ambiente. Generala desde el panel de API; el secreto completo aparece una sola vez.
Authorization: Bearer fmk_test_TU_SECRETO| Prefijo | Ambiente | Resultado fiscal |
|---|---|---|
fmk_test_ | TEST | Pruebas internas, sin validez fiscal. |
fmk_hom_ | HOMOLOGATION | Pruebas según el proceso de DGI, sin emisión fiscal de producción. |
fmk_live_ | PRODUCTION | Operaciones fiscales reales cuando están configuradas y autorizadas. |
Una API key de producción permite intentar operaciones reales. Nunca uses claves de producción para probar ejemplos, y no copies claves a código de frontend, repositorios, logs ni herramientas de analítica.
Permisos (scopes)
| Scope | Autoriza |
|---|---|
documents:read | Consultar empresas, comprobantes, XML firmado y directorio de emisores. |
documents:write | Crear borradores. |
documents:issue | Preparación, asignación de CAE y firma. |
documents:submit | Enviar comprobantes a DGI; al emitir la clave se incluyen permisos de emisión y consulta de estado. |
documents:status | Actualizar el estado ante DGI. |
received:read | Listar y consultar CFE recibidos, incluido XML original. Permiso independiente de documents:read y restringido por empresa/ambiente. |
webhooks:manage | Crear, consultar, actualizar, archivar y rotar secretos de webhooks de toda la organización. No disponible para claves de una empresa. |
Ahora podés elegir el alcance al generar una clave: una empresa concreta o todas las empresas de la organización. Para integraciones externas, recomendamos una clave de empresa con los scopes mínimos. Las claves existentes anteriores a esta función siguen teniendo acceso a toda la organización hasta ser revocadas. Si restringís una clave, las consultas a otras empresas devuelven 404 y las listas se filtran automáticamente, también en XML, PDF y operaciones con DGI.
Rotación y aislamiento
El alcance no se amplía al cambiar la empresa ni al eliminarla: para reemplazar una clave, creá otra con el alcance correcto y revocá la anterior. Nunca compartas una clave de toda la organización con un proveedor que sólo debe integrar una empresa.
Límites de consumo
Las claves comparten cuotas distribuidas por minuto y categoría: 120 lecturas, 30 creaciones y 12 operaciones fiscales por minuto, salvo configuración del operador. Recibir 429 implica esperar el encabezado Retry-After. Los límites por clave no sustituyen un WAF o el control de intentos con credenciales inválidas en el proxy.
Respuestas HTTP
401 significa clave inválida, vencida o revocada; 403 significa permiso insuficiente; 404 puede indicar un recurso inexistente o ajeno a la organización/ambiente. 409 señala conflicto de estado o idempotencia; 422 indica una validación fallida. No vuelvas a emitir ante un timeout sin consultar primero el comprobante asociado al externalId.