FISCALISTO / API
Autenticación y llaves
Cómo se identifica su sistema con su llave secreta, cómo limitarla a ciertos emisores, a solo lectura o a un plazo, y cómo cambiarla sin cortes.
Cada solicitud lleva su llave secreta en el encabezado Authorization:
curl https://api.fiscalisto.com/v1/account \
-H "Authorization: Bearer $FISCALISTO_API_KEY"También se acepta como usuario de HTTP Basic, sin contraseña (curl -u "$FISCALISTO_API_KEY:"), para las herramientas que solo saben de esa forma.
Formato
Una llave es fk_test_ o fk_live_ seguido de 40 letras y números. El prefijo dice el modo (vea Pruebas y producción). Fiscalisto guarda solo su huella: si la pierde, cree otra.
Dónde guardarla
- En una variable de entorno o en el gestor de secretos de su servidor, nunca en el código ni en el repositorio.
- Nunca en el navegador ni en una app que se instala en teléfonos: quien la tenga timbra a su nombre. La API no contesta a solicitudes del navegador (las rechaza con
browser_not_supported); la excepción es Probar en la referencia de esta documentación, y solo con llaves de pruebas. - Una llave por sistema o por ambiente, con un nombre que diga dónde vive, para revocar solo la que se filtró.
Llaves limitadas a algunos emisores
Al crear una llave en Desarrolladores › Llaves puede marcar Solo para algunos emisores. Esa llave solo ve y timbra con esos RFC; lo que toca a otro emisor, crea emisores nuevos o es de toda la cuenta (como los webhooks) responde 403 con key_restricted. Sirve, por ejemplo, para darle a cada sucursal o a cada cliente de su plataforma una llave que solo factura con su RFC.
Llaves de solo lectura
En Permisos elija Solo lectura para una llave que consulta y no cambia nada: todas las solicitudes GET (facturas, PDF, XML, saldo, catálogos, eventos) y tres POST que solo revisan: POST /v1/tax_ids/validate, POST /v1/sat_lists/check y POST /v1/payroll_receipts/preview. Lo demás (timbrar, cancelar, enviar, crear o cambiar datos) responde 403 con key_read_only. Sirve para un tablero, un reporte o la herramienta de su equipo de soporte. Se puede combinar con Solo para algunos emisores.
Llaves que vencen
En Vence elija si la llave deja de funcionar en 30 días, 90 días, 6 meses o 1 año (Nunca, si no). Le avisamos por correo 7 días y 1 día antes, a los propietarios y administradores de la cuenta. Al vencer responde 401 con invalid_api_key. Cambiar llave le da una nueva con el mismo plazo, contado desde ese día. GET /v1/account dice de la llave que hizo la solicitud si es de solo lectura (key.read_only) y cuándo vence (key.expires_at), para que su sistema avise antes.
Elegir el emisor
Lo que crea comprobantes, clientes o productos lleva el emisor (iss_…) en issuer, en el cuerpo; las listas lo llevan en la consulta (?issuer=iss_…). Si la cuenta, o la llave, tiene un solo emisor, puede omitirlo. Si tiene varios y no lo manda, la API responde issuer_required. Los ids de lo demás (inv_…, cus_…) ya dicen de qué emisor son.
Cambiar una llave sin cortes
En Desarrolladores › Llaves elija Cambiar llave en su menú. Le damos una nueva con el mismo nombre y los mismos permisos, y usted elige cuándo deja de servir la anterior: ahora mismo, en 1 hora, en 24 horas o en 7 días. Ponga la nueva en su servidor dentro de ese plazo. Si una llave se filtró, cámbiela con Ahora mismo o revóquela.
Límites
- Hasta 50 llaves por modo.
- Crear llaves de producción pide verificación en dos pasos del usuario.
- Una dirección IP que manda muchas llaves inválidas seguidas recibe
429por un minuto; nunca afecta a las llaves válidas.
Errores de autenticación
| Código | Qué pasó |
|---|---|
missing_api_key | No llegó el encabezado Authorization. |
invalid_api_key | La llave no existe, se revocó o ya expiró. |
key_restricted | La llave está limitada a otros emisores. |
key_read_only | La llave es de solo lectura y la solicitud cambia algo. |
livemode_mismatch | El objeto es del otro modo. |