Disponível para quem tem a capacidade Integrações — na prática, quem administra a organização.

Para que serve

A tela Integrações permite que a sua OSC libere, para um sistema parceiro (um site institucional, um painel de doadores, uma ferramenta interna da organização), a leitura do próprio resumo financeiro — sem dar acesso à plataforma e sem criar um usuário para ninguém de fora.

É diferente da Página Pública: a Página Pública é um endereço aberto para qualquer pessoa ver; a integração é um canal técnico, autenticado por credencial, para outro sistema consultar os números e exibi-los do jeito que fizer sentido para ele.

Como gerar uma credencial

  1. Em Configurações → Integrações, clique em Gerar credencial.
  2. No campo Sistema parceiro, dê um nome que identifique o uso (ex.: “Site institucional”, “Painel do conselho”).
  3. Escolha a Validade: Sem validade, 30 dias, 90 dias, 6 meses ou 1 ano. Depois da validade, a credencial para de funcionar sozinha e o sistema parceiro deixa de receber os dados.
  4. Clique em Gerar. A credencial aparece uma única vez, na hora da criação.

💡 Por que escolher uma validade

Credencial sem validade funciona até alguém lembrar de revogá-la — e, na prática, ninguém lembra: o voluntário que configurou o site sai, o contrato com o parceiro termina, e a chave continua aberta por anos. Com validade, o esquecimento se corrige sozinho: no dia marcado o acesso se fecha. Use Sem validade só para integrações permanentes e conhecidas; para um parceiro temporário, um projeto com prazo ou um teste, escolha 30 ou 90 dias.

⚠️ Atenção · Organização em análise não gera credencial

Se a sua organização foi aberta pelo próprio cadastro e ainda está em análise pela equipe da RIT, a criação de credenciais fica indisponível (a tela pode mostrar apenas “Não foi possível concluir a operação”). Passa a funcionar depois da aprovação — veja Primeiros Passos da Organização.

⚠️ Atenção · A credencial não pode ser recuperada depois

Assim que você sai da tela (ou atualiza a página), o valor completo da credencial não é mostrado de novo em lugar nenhum — nem para você, nem para o suporte. Copie e guarde num lugar seguro (cofre de senhas da OSC) antes de sair da tela. Se perder, a única saída é revogar aquela credencial e gerar uma nova, e então atualizar o sistema parceiro com o valor novo.

Como revogar

Na lista de credenciais, escolha Revogar na credencial que não deve mais funcionar. A revogação vale a partir da chamada seguinte e é definitiva — não existe “reativar”, só gerar uma credencial nova.

Revogue sempre que: a integração deixar de ser usada, houver suspeita de vazamento, ou a pessoa/empresa responsável pelo sistema parceiro mudar.

Quando a credencial vence

Uma credencial com validade deixa de funcionar sozinha no fim do prazo: na lista ela passa a Vencida, e o sistema parceiro recebe a recusa de credencial (resposta 401, com error_code expired_credential). Não há “renovar”: como na revogação, o caminho é gerar uma credencial nova e colocar o valor novo no sistema parceiro.

⚠️ Atenção · Anote a data de vencimento

O vencimento não avisa ninguém: o primeiro sinal costuma ser o parceiro reclamando que “os números sumiram do site”. Anote a data na hora de gerar e crie o hábito de trocar a credencial uma semana antes: gere a nova, atualize o parceiro, confira que está funcionando e só então deixe a antiga vencer (ou revogue-a). A coluna Validade da lista mostra a data de cada uma.

O que a lista mostra

Para cada credencial gerada, a tela mostra:

  • Sistema — o nome dado na criação (com o início do código, para você reconhecer qual é qual)
  • Criada em — a data de criação
  • Último uso — quando a credencial foi usada pela última vez para consultar dados (“Nunca usada” se ainda não foi)
  • Validade — a data de vencimento, ou “Sem validade”
  • Situação — Ativa, Revogada ou Vencida

Trate como senha

⚠️ A credencial dá acesso de leitura aos números financeiros da sua organização

Quem tiver a credencial em mãos consegue consultar o resumo financeiro da OSC pela API, sem precisar de login. Compartilhe apenas com quem vai efetivamente configurar o sistema parceiro, nunca por canal inseguro (não cole em grupo de WhatsApp, chat público, planilha compartilhada sem controle de acesso). Se a pessoa responsável pela integração sair da organização, revogue e gere uma nova.

Para quem desenvolve o sistema parceiro

Esta seção é o contrato técnico da API. Ela é a mesma para qualquer organização que gerar uma credencial — a organização em si nunca é um parâmetro da chamada, ela vem embutida na credencial.

Especificação OpenAPI

Além desta descrição em prosa, existe a especificação formal em OpenAPI 3.1, disponível em:

https://docs.financeiro.rit360.org.br/assets/api/integration-finance-summary.yaml

Ela pode ser usada para gerar cliente automaticamente (ex.: openapi-generator, openapi-typescript) e é a fonte formal do contrato — o que está descrito em prosa nesta página é o mesmo contrato, em texto corrido.

Endpoint 

GET https://jswyzxutdkrbrleotklo.supabase.co/functions/v1/integration_finance_summary

Existe apenas este endpoint.

⚠️ O endereço das funções não é o mesmo do aplicativo. O RIT360 Financeiro é um serviço único (não há instalação por cliente), então o endereço acima vale para todas as organizações — mas ele aponta para o servidor de funções, não para financeiro.rit360.org.br. Chamar o endereço do aplicativo devolve HTTP 200 com a página HTML do sistema, não os dados: parece que funcionou e não funcionou. Use exatamente o endereço acima.

Autenticação

Cabeçalho Authorization: Bearer <credencial>.

Formato da credencial: rit_ seguido de 8 caracteres hexadecimais, _ e mais 64 caracteres hexadecimais.

Parâmetros de consulta

Parâmetro Obrigatório Descrição
from Sim Data inicial do período, no formato AAAA-MM-DD
to Sim Data final do período, no formato AAAA-MM-DD — deve ser igual ou posterior a from
group_by Não category ou project — abre a composição do período por categoria ou por projeto

Não há parâmetro de organização: ela é determinada sempre pela credencial usada na chamada.

Exemplo de chamada 

curl -H "Authorization: Bearer rit_3b95e9fe_..." \
  "https://jswyzxutdkrbrleotklo.supabase.co/functions/v1/integration_finance_summary?from=2026-07-01&to=2026-07-31"

Exemplo de resposta 

{
  "organization_id": "c121b5a6-...",
  "period": { "from": "2026-07-01", "to": "2026-07-31" },
  "currency": "BRL",
  "balance": { "total": 82643.47, "available": 61210.30, "restricted": 21433.17 },
  "realized": { "receitas": 595.02, "despesas": 7790, "resultado": -7194.98 },
  "budget": [
    { "fiscal_year": 2026, "available": false, "reason": "sem_versao_vigente_aprovada" }
  ],
  "group_by": null,
  "breakdown": null
}

Com group_by=category (ou project), o campo group_by ecoa o valor pedido e breakdown passa a trazer uma lista de itens, cada um com id, name, receitas e despesas. A soma dos itens da quebra fecha exatamente com os totais de realized — é uma garantia da API, não uma aproximação.

Sobre o saldo

O campo balance é sempre o saldo de hoje das contas ativas — ele não muda com o período from/to consultado (o período vale para realized, budget e breakdown).

  • total soma todas as contas ativas;
  • available é o saldo disponível: exclui as contas marcadas para não compor o saldo disponível da organização (recurso carimbado de convênio, emenda ou fundo restrito, e cartão de crédito) — ver Compõe o saldo disponível da organização;
  • restricted é exatamente o que ficou de fora: total − available.

Para mostrar “quanto a organização pode usar”, use available, não total.

Sobre o orçamento

O orçamento do RIT360 Financeiro é anual. O campo budget traz um item para cada exercício coberto pelo período consultado. Quando não existe uma versão de orçamento aprovada e vigente para aquele ano, o item vem com available: false e o motivo em reason — o campo nunca vem zerado nesse caso, justamente para não sugerir que o orçamento é igual a zero.

Respostas

Código Significado
200 Sucesso
401 Credencial ausente, inválida, revogada ou vencida (error_code: invalid_credential, revoked_credential ou expired_credential)
403 Escopo insuficiente para a operação pedida
422 Período ou group_by inválido
429 Limite de requisições excedido (ver Retry-After)
500 Falha interna

Toda resposta de erro traz um corpo com error_code e message.

Limite de requisições

60 requisições por hora, por credencial. Contam apenas as requisições atendidas com sucesso (resposta 200). Recusas — por credencial inválida, por parâmetro inválido ou pelo próprio limite — não realimentam a janela, então um cliente mal configurado não fica bloqueado indefinidamente por insistir.

Sobre os cabeçalhos, atenção ao que vem em cada caso:

  • na resposta 200, vêm X-RateLimit-Limit e X-RateLimit-Remaining, com o limite total e quanto resta na janela;
  • na resposta 429, vêm X-RateLimit-Limit e Retry-After, este último com os segundos a esperar antes de tentar de novo;
  • nas demais respostas de erro (401, 403, 422, 500) não vem nenhum cabeçalho de limite.

Ou seja: não use a presença desses cabeçalhos para decidir se houve erro — use o código de resposta.

O que a API nunca devolve

Assim como a Página Pública, esta API trabalha só com totais. Ela nunca devolve:

  • Lançamento individual
  • Contraparte (quem pagou, quem recebeu)
  • Nome de pessoa física
  • Chave Pix ou dados bancários
  • CPF
  • Nome de fornecedor
  • Anexos ou comprovantes

Isso não é uma limitação temporária — é a garantia que permite a qualquer OSC liberar essa integração sem avaliar risco de exposição de dado pessoal caso a caso.

Provedores de Inteligência Artificial (Superadmin)

Disponível para quem tem papel de Superadministrador da Plataforma na rota /superadmin/configuracoes.

O RIT360 Financeiro utiliza inteligência artificial multimodal de ponta para leitura e extração automática de dados de comprovantes, notas fiscais e recibos enviados pelos usuários, e para o Assistente, que responde perguntas e prepara registros no sistema e pelo Telegram.

Configuração de Provedores de Inteligência Artificial em cascata no Desktop Configurações da Plataforma: Cascata de IA com reordenação de prioridade, seleção assistida de modelos e teste de latência

Configuração de Provedores de Inteligência Artificial no Celular Ajuste de provedores e modelos no celular

Cascata e redundância inteligente

Para garantir disponibilidade contínua e tolerância a falhas, os provedores operam em cascata ordenada:

  1. Google Gemini (Gemini 2.5 Flash, Gemini 1.5 Pro)
  2. Anthropic Claude (Claude 3.5 Sonnet, Claude 3.5 Haiku)
  3. OpenAI (GPT-4o, GPT-4o-mini)

Se a chamada ao primeiro provedor da fila atingir limite de cota, timeout ou indisponibilidade temporária, o sistema chaveia automaticamente para o próximo provedor ativo da sequência, sem interromper a experiência do usuário final.

Como configurar e testar

  1. Ativação e Chave de API: Ative o toggle do provedor e informe a chave de API correspondente. As chaves são armazenadas com segurança no cofre de segredos da plataforma.
  2. Teste de conexão: Clique em Testar para validar a chave em tempo real. O sistema exibe o status de resposta e a latência em milissegundos medida pela Edge Function (test_ai_provider).
  3. Seleção assistida de modelos: Após o teste bem-sucedido, o seletor lista os modelos compatíveis e ativos daquele provedor, com o modelo recomendado pré-selecionado (e identificação clara do recomendado para facilitar o retorno futuro).
  4. Reordenação visual: Utilize as setas de subida e descida (↑ e ↓) para reordenar a prioridade da cascata visualmente, eliminando digitação manual de índices.

Por onde seguir