Autenticación

La API del Financeiro Inteligente usa Bearer Token para autenticar todas las solicitudes. Cada token se emite para un Workspace y limita automáticamente los datos devueltos.

Obteniendo el token

Genera tokens en la interfaz de la plataforma, en Integraciones → Token de API. Cada token tiene:

• Identificador UUID público para rastreo.
• Secret mostrado una única vez en el momento de la creación — cópialo y guárdalo en un lugar seguro.
• Alcances (scopes) que limitan qué recursos puede acceder el token.
• Expiración opcional.

Cómo enviar el token

Incluye el encabezado Authorization: Bearer <token> en cada solicitud.

export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

curl -i \
  -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mi Sistema (contacto@miempresa.com.br)' \
  -X GET 'https://api.finance.kobana.com.br/v1/accounts'

Alcances (scopes)

Cada token debe declarar los alcances necesarios. Uno por recurso, en pares lectura/escritura:

Recurso	Lectura	Escritura
Cuentas financieras	finance.accounts	finance.accounts.write
Catálogo de bancos	finance.banks	— (solo lectura)
Cuentas por pagar	finance.payables	finance.payables.write
Envío de cuenta por pagar al banco	—	finance.payables.dispatch
Cuentas por cobrar	finance.receivables	finance.receivables.write
Transacciones	finance.transactions	finance.transactions.write (incluye transferencias)
Conciliaciones	finance.reconciliations	finance.reconciliations.write (creación y disolución)
Flujo de caja proyectado	finance.cash_flow	— (solo lectura)
Empresas	finance.companies	finance.companies.write
Personas	finance.people	finance.people.write
Categorías	finance.categories	finance.categories.write
Centros de clasificación	finance.cost_centers	finance.cost_centers.write
Reglas automáticas	finance.automatic_rules	finance.automatic_rules.write (incluye reordenación)
Impuestos	finance.taxes	finance.taxes.write
Adjuntos	finance.attachments	finance.attachments.write (subida y gestión)
Comodín	finance.all (toda lectura)	finance.all.write (todo)

Reglas de resolución:

• Un alcance .write incluye la lectura del mismo recurso — no es necesario conceder ambos.
• finance.all concede toda lectura, y nada de escritura. finance.all.write concede todo.

aviso

Los alcances de dinero están separados por seguridad. finance.payables.dispatch (envío al banco) nunca se concede junto al .write por defecto, y el comodín de lectura finance.all no lo satisface — solo el grant exacto o finance.all.write. Así un token de lectura no mueve dinero.

Buenas prácticas

• Nunca versiones tokens en git. Usa variables de entorno o bóvedas (AWS Secrets Manager, Vault, etc.).
• Usa tokens distintos por integración — facilita rotarlos/revocarlos sin tumbar todo.
• Define los alcances mínimos necesarios (principio del menor privilegio).
• Revoca inmediatamente cualquier token filtrado.
• HTTPS obligatorio — las llamadas en HTTP son rechazadas.