Autenticación y permisos
Todas las operaciones de negocio requieren una API key. Envíala en el header X-API-Key desde tu servidor:
X-API-Key: fc_test_...La especificación /api/v1/openapi.json es pública y no requiere autenticación.
Empieza con sandbox
Sección titulada «Empieza con sandbox»Crea las llaves de prueba en Configuración → API keys del ambiente sandbox. Ponles un nombre que permita reconocer qué sistema las utiliza. El secreto completo se muestra una sola vez.
La URL base de pruebas es https://sandbox.factucat.com/api/v1. Guarda la llave en un gestor de secretos o en las variables privadas de tu servidor (FACTUCAT_API_KEY). No la incluyas en URLs, repositorios ni código que se envía al navegador. Las sesiones de la webapp no autentican la API pública.
Permisos disponibles
Sección titulada «Permisos disponibles»| Permiso | Permite |
|---|---|
customer:read |
Consultar clientes |
customer:write |
Crear clientes |
invoice:read |
Consultar borradores, facturas, XML y PDF |
invoice:write |
Crear, modificar y eliminar borradores y conceptos |
invoice:stamp |
Timbrar una factura |
invoice:cancel |
Solicitar cancelaciones |
Cada llave actúa únicamente sobre los datos de su cuenta. El plan API ofrece estos permisos de clientes y facturas, correspondientes a la API pública actual.
Producción
Sección titulada «Producción»Cuando emitas CFDI reales, usa una llave fc_live_... creada en Configuración → API keys de tu cuenta productiva y la URL base https://factucat.com/api/v1. Las llaves fc_test_... y fc_live_... pertenecen a ambientes diferentes; no mezcles prefijo y origen.
Rotación y revocación
Sección titulada «Rotación y revocación»Crea una llave nueva, actualiza tu integración y confirma que puede consultar /me. Después revoca la anterior. Una llave revocada deja de autenticar inmediatamente.
El historial de idempotencia está asociado a la llave de integración. Tras una rotación, consulta el documento antes de repetir una operación pendiente; no asumas que la nueva llave comparte ese historial.