Floid Developers Contáctanos

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ónRESTMCPCuándo usarla
credencial_tokenSíSí Recomendada. El titular conecta su cuenta en el widget de Floid y tu sistema recibe un token que reemplaza rut y clave.
rut + claveSíNo Solo desde tu backend, cuando tu sistema ya maneja las claves. Empresas agregan rut_empresa.
certificado + clave_certificadoSí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:

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.