Guías
Autenticación y credenciales
Hay dos llaves distintas: el token Floid, que identifica a tu empresa, y la credencial del titular, que abre su banco, el SII o su Clave Única.
Token Floid
Va en cada llamada, por REST y por MCP, en el encabezado:
Authorization: Bearer <token Floid>
Floid lo valida en cada consulta y define qué servicios puedes usar. La capa no lo guarda: solo lo reenvía a Floid.
Si no tiene contratado un servicio, la respuesta es 403 con el código METHOD_NOT_AUTH.
Credencial del titular
Las credenciales nunca pasan por un modelo de IA
Por MCP solo se acepta credencial_token. El agente recibe los datos que pide, pero nunca las claves para obtenerlos.
| Opción | REST | MCP | Cuándo usarla |
|---|---|---|---|
| credencial_token | Sí | Sí | Recomendada. El titular conecta su cuenta en el widget de Floid y tu sistema recibe un token que reemplaza rut y clave. |
| rut + clave | Sí | No | Solo desde tu backend, cuando tu sistema ya maneja las claves. Empresas agregan rut_empresa. |
| certificado + clave_certificado | Sí | No | SII con certificado digital (tipo_login: certificado), en base64. |
No se pueden mezclar: si envías credencial_token junto con datos de acceso, la respuesta es CREDENCIALES_MEZCLADAS.
Cómo se entra al SII
Las herramientas del SII aceptan tipo_login:
sii(por defecto): RUT y clave tributaria.clave_unica: RUT y Clave Única.certificado: certificado digital y su clave, solo por REST.
Algunas herramientas aceptan una sola forma; su ficha lo indica y la capa la elige sola.
Cuidado con los bloqueos
Una clave errada no se reintenta
- Personas: tras intentos fallidos, Floid bloquea la credencial por 1 hora.
- Empresas: el bloqueo no se libera solo; hace falta una validación exitosa con la clave correcta.
- El banco o el SII también pueden bloquear la clave en su sitio.
Por eso los errores de clave traen reintentable: false y una sugerencia para confirmar la clave con el titular. En empresas, valida primero con banco_empresa.credenciales.validar.