Autenticación
Toda solicitud a la API INFI requiere autenticación mediante Bearer token.
Encabezado
Authorization: Bearer <TU_API_KEY>Las solicitudes sin este encabezado reciben 401:
{ "error": "API key obrigatória. Use: Authorization: Bearer <key>" }Clave inválida o revocada:
{ "error": "API key inválida ou revogada." }Formato de la API key
Toda API key tiene el formato:
infi_<64 caracteres hexadecimales>Total: 69 caracteres. Los primeros 16 caracteres (infi_ + 11 hex) forman el prefijo público, mostrado en el panel para que identifiques cada clave sin exponer el secreto.
Generación y revocación
Las API keys se generan en el panel de INFI, en Dispositivos / API keys. La generación exige:
- Cuenta con KYC aprobado.
- Correo del responsable verificado.
El secreto completo se muestra una sola vez en el momento de la creación. Si lo pierdes, genera una nueva clave y revoca la anterior.
La API key vale como contraseña. No la subas a Git, no la envíes por mensaje, no la publiques en un frontend. En caso de exposición, revócala inmediatamente en el panel.
La revocación tiene efecto en segundos. Tras revocarla, las solicitudes con esa clave reciben 401.
Precondiciones de la cuenta
En cada llamada, INFI valida:
- KYC aprobado. Si no:
403 "Conta não está aprovada para uso da API." - Cuenta no bloqueada. Si no:
403 "Conta suspensa. Contate o suporte."
Estas verificaciones usan caché de hasta 30 s — los cambios en el panel se reflejan en segundos, no en minutos.
Idempotencia
En POST /v1/pix, envía un externalRef en el cuerpo para garantizar que los reenvíos no creen cobros duplicados. Ver Idempotencia.
Lista de IPs permitidos
Tu cuenta puede tener lista de IPs permitidos (configurada por el equipo de INFI). Cuando está activa, los IPs fuera de la lista reciben:
{ "error": "IP de origem não autorizado para esta chave." }Ver Lista IP permitida.
Relación con el 2FA del panel
La autenticación en dos pasos (TOTP) disponible en el panel del comerciante no se aplica a la API REST. Las protecciones de la API son:
- API key (Bearer token).
- Lista de IPs permitidos (opcional).
- Rate limit por clave.
Puedes tener 2FA activo en el panel sin alterar el comportamiento de tus integraciones por API. Los retiros iniciados desde el panel pasan a exigir código TOTP; los retiros por POST /v1/withdraw siguen exigiendo solo la API key.