APIs Públicas: integração segura com sistemas terceiros
A nova funcionalidade de APIs Públicas permite que sistemas terceiros se conectem ao Banqer de forma segura e controlada. Chatbots de negociação, painéis de BI, motores de propostas, ferramentas internas do cliente e qualquer outro sistema que precise consumir dados da cobrança passam a contar com uma interface estável, documentada e governável.
Para que serve
Pense em todos os pontos em que a cobrança precisa conversar com sistemas externos: um chatbot que precisa consultar o saldo atualizado da dívida antes de propor uma negociação, um data warehouse que consolida indicadores de várias operações, um motor de propostas que decide a oferta com base na carteira e no histórico, ou um aplicativo do cliente final que mostra o status do acordo. Em todos esses cenários, a API Pública é o canal oficial para que esses sistemas leiam dados do Banqer sem precisar de acesso ao banco de dados nem ao painel operacional.
Como funciona
A API Pública é exposta em dois protocolos a partir da mesma especificação: REST sobre HTTPS para integradores que preferem trabalhar com chamadas HTTP convencionais, e gRPC sobre HTTP/2 para integradores que precisam de chamadas binárias eficientes e contratos fortemente tipados. O integrador escolhe o protocolo que melhor se encaixa em sua stack técnica e os dois compartilham a mesma definição de campos e regras de validação.
A autenticação segue o padrão OAuth 2.0 com fluxo client credentials, adotado pelo mercado para comunicação entre sistemas (machine-to-machine). Cada integrador recebe um par próprio de identificador e segredo, gerados em um cofre de identidades isolado por cliente Banqer. Não há compartilhamento de credenciais entre integradores, e uma revogação afeta apenas o integrador específico, sem impactar os demais.
Permissões organizadas por sensibilidade dos dados
O coração da governança está no modelo de permissões. Cada permissão libera um conjunto específico de rotas da API e carrega um indicador visual do nível de sensibilidade dos dados que ela expõe:
| Permissão | Sensibilidade | O que libera |
|---|---|---|
| Catálogos do CRM | Sem dados pessoais | Listas de referência: credores, produtos, carteiras, situações de dívida, tipos de telefone. |
| Listagem e análise de fichas | Sem dados pessoais | Fichas de cobrança com saldo, atraso, situação e indicadores analíticos. Sem identificação do devedor. |
| Dados financeiros da cobrança | Dados operacionais | Contratos, títulos, acordos, parcelas, pagamentos e boletos em PDF. Sem identidade nem contatos do devedor. |
| Identidade pessoal do devedor | Dados pessoais | Documento, nome, data de nascimento, filiação, profissão e estado civil. |
| Contatos do devedor | Dados pessoais | Telefones, e-mails e endereços. Complemento à permissão de Identidade. |
O modelo aplica o princípio do menor privilégio recomendado pela LGPD: o integrador recebe apenas o conjunto mínimo de dados necessário para o seu caso de uso. Um chatbot que consulta saldo não precisa de identidade nem de contatos. Uma ferramenta de BI analítico não precisa nem mesmo de saldo individualizado. A permissão de Contatos exige a permissão de Identidade como pré-requisito, evitando combinações que não fazem sentido do ponto de vista de tratamento de dados pessoais.
Emissão guiada de credenciais
A emissão de credenciais para um novo integrador segue um processo em quatro etapas: identificação do integrador (nome, descrição e contato responsável), seleção das permissões, seleção dos produtos cuja operação ficará visível e uma tela final de revisão antes da emissão.
A tela de revisão consolida tudo que será compartilhado e, quando há permissões que tocam em dados pessoais, exige confirmação explícita do operador de que existe base legal e contrato de tratamento com o integrador, em linha com o que a LGPD requer do controlador de dados. O segredo de cliente é gerado apenas após essa confirmação e exibido uma única vez, evitando que fique gravado de forma persistente em qualquer interface do CRM.
Lista, gestão e auditoria
Todas as APIs emitidas ficam reunidas em uma lista única no painel de controle, com busca, filtros por status e visão imediata das permissões concedidas a cada integrador:
A partir da lista o operador acessa os detalhes de cada integrador, gerencia as credenciais (rotação ou desativação) e consulta o histórico completo de eventos da API:
O histórico registra criação, alterações de metadados, rotações de segredo, desativações e exclusões, com data, autor e detalhes do evento. Esse registro atende ao princípio da prestação de contas previsto na LGPD: a operação consegue demonstrar quem autorizou cada compartilhamento, quando e em que circunstâncias.
Documentação automática para a equipe de integração
A especificação da API gera automaticamente a documentação no formato OpenAPI, com interface interativa Swagger. Isso facilita a vida da equipe técnica do integrador: a documentação fica sempre sincronizada com o contrato real da API, ferramentas comuns de mercado conseguem gerar clientes em diversas linguagens a partir do arquivo OpenAPI, e a equipe consegue testar chamadas direto da interface antes de escrever uma linha de código de produção.
Além da referência OpenAPI, publicamos um guia de integração para desenvolvedores com tutoriais de autenticação, catálogo de permissões, exemplos prontos em Python, JavaScript, Java, C# e Go e receitas para os cenários mais comuns (consulta de devedor por CPF, listagem paginada de fichas em atraso, emissão de boleto, pull diário de pagamentos). O conteúdo é mantido em paralelo à evolução da API.
Versionamento e estabilidade
A versão atualmente disponível é a V1, em período de validação com integradores parceiros. Durante essa fase pode haver pequenos ajustes incrementais conforme o retorno dos primeiros clientes. Após a validação, o contrato da V1 passa a ser garantido: integrações escritas contra a V1 continuam funcionando enquanto a V1 estiver disponível. Mudanças que quebrariam essa garantia entram em uma V2 publicada em paralelo, seguindo o padrão de versionamento adotado pelo mercado para APIs públicas.
Como ativar
A funcionalidade está disponível para todos os clientes Banqer, mas vem desativada por padrão. Para habilitar a emissão de APIs na sua operação, entre em contato com o suporte. Nossa equipe ajuda na ativação, na avaliação dos casos de uso pretendidos e nas boas práticas de governança das credenciais emitidas.