Conexões bancárias

Uma conexão guarda as credenciais que a Kobana usa para falar com a API de um banco ou serviço: as chaves fornecidas pelo banco, o certificado digital, o ambiente e as permissões da API contratadas. Carteiras de cobrança, contas Pix, contas de pagamento, contas de transferência e o extrato de uma conta financeira só operam pela API do banco depois de associados a uma conexão ativa.

Os bancos e serviços disponíveis estão em Bancos suportados.

Onde fica

Menu Integrações > Kobana → Bancos e Serviços > API:

• Configurar Nova: lista os serviços disponíveis para conectar.
• Conexões Configuradas: lista as conexões da conta, com a situação de cada uma.

Situação da conexão

Situação	Significado
Ativa	Validada e habilitada. A tela mostra "Essa conexão está validada e pronta para uso."
Desabilitada	Validada, mas desligada. Não está em uso até ser habilitada.
Desativada	Ainda não validada. As credenciais precisam ser validadas antes do uso.

Criada ──Validar Conexão──> Ativa
                              │  ▲
                   Desabilitar│  │Habilitar
                              ▼  │
                          Desabilitada

Criar uma conexão

1. Em Configurar Nova, clique em Conectar este serviço no card do banco.
2. Preencha o formulário. Os campos variam conforme o banco.
3. Clique em Salvar. Para descartar e escolher outro serviço, use Recomeçar.

Campo	Obrigatório	Descrição
Nome da Conexão	Sim	Nome para identificar a conexão, até 100 caracteres.
Usar conexão global	Não	Só aparece para serviços que oferecem conexão global da Kobana. Quando ligado, as credenciais próprias não são pedidas.
Ambiente	Sim	Produção ou Homologação.
Permissões da API	Sim	Produtos que a conexão vai usar, como Boleto, Pix, Pix Automático, Extrato, Pagamento, Transferência e DDA. Só aparece quando o banco oferece mais de um produto.
Credenciais	Sim	Campos pedidos pelo banco (por exemplo, client ID, client secret, chaves ou arquivos). Os nomes aparecem como o banco os define.
Certificado	Depende	Aparece quando algum produto escolhido exige certificado digital. Escolha um certificado válido da conta.
Chave	Depende	Aparece quando o banco exige uma chave criptográfica. Escolha uma chave da conta.

Quando o banco exige certificado e a conta não tem nenhum certificado válido, o botão Salvar fica desabilitado e a tela oferece o link para cadastrar um. O mesmo vale para a chave. Veja Certificados e chaves.

Validar a conexão

A conexão recém-criada precisa ser validada. Na tela da conexão, clique em Validar Conexão. Há três comportamentos, conforme o banco:

Comportamento	O que acontece
Validação imediata	A Kobana testa as credenciais no banco. Se aceitas, a conexão fica Ativa ("A conexão foi ativada com sucesso!"). Se recusadas, você volta para a edição com a mensagem do banco. Se faltar credencial, a mensagem pede para rever a configuração.
Validação em segundo plano	A conexão é validada depois de criada, sem você esperar. Você recebe um alerta quando a validação termina. Pode levar de alguns segundos a poucos minutos, conforme o tempo de resposta do banco.
Autorização no banco	A tela avisa que a conexão precisa de autorização e redireciona você para o site do banco para autorizar o acesso.

Alterar, habilitar e excluir

Na tela da conexão, o menu Ações e os botões ao lado oferecem:

Ação	O que faz
Alterar	Edita nome, permissões da API, credenciais (com a opção Quero editar as credenciais), certificado e chave.
Desabilitar / Habilitar	Desliga ou religa uma conexão validada.
Validar	Valida uma conexão ainda não validada.
Revalidar Conexão	Para bancos com autorização no site do banco, remove os tokens de autorização atuais para autorizar de novo.
Excluir	Apaga a conexão. Exige marcar "Tenho certeza que quero excluir a conexão".

Regras:

• Alterar uma conexão ativa passa por uma tela Confirme as Informações e um aviso: a alteração pode interromper a comunicação com o banco. Faça a alteração só se a conexão ainda não estiver em produção. Para seguir, marque "TENHO CERTEZA que quero ALTERAR a conexão" e clique em Realizar Alteração. A conexão é validada de novo.
• Alterar as permissões da API de uma conexão validada que usa autorização no banco exige uma nova autorização.
• Alguns bancos não permitem mudar permissões, credenciais ou certificado depois da ativação. Nesses casos os campos aparecem bloqueados.
• Excluir não é possível enquanto houver carteiras, contas Pix ou contas financeiras associadas. O aviso lista os recursos que precisam ser desassociados antes.

Associar a conexão a carteiras e contas

A associação é feita a partir do recurso que vai usar a conexão. Na tela do recurso, abra a opção de conexão. Recursos que aceitam associação:

• carteira de cobrança;
• conta Pix;
• conta de pagamento;
• conta de transferência;
• extrato de uma conta financeira.

A tela Associar conexão lista as conexões ativas da conta para o mesmo banco e produto do recurso. Clique em Associar na conexão desejada. A conexão em uso aparece como Conexão atual, com a opção Desassociar quando o recurso permite.

• Quando a associação não pode ser feita (por exemplo, a conexão de uma conta de pagamento ou de transferência não tem a permissão da API do produto), o painel mostra a mensagem com o motivo.
• Associar uma conta de pagamento não associa a conta de transferência, e vice-versa. Associe cada uma.
• A associação e a desassociação ficam registradas na Auditoria.
• Sem conexão configurada para aquele banco, a tela oferece a lista de serviços para criar uma.

A aba Associações da tela da conexão mostra todos os recursos associados a ela.

Permissões

Ação	Permissão
Ver conexões	Integrações > Conexões > Ações Básicas
Criar e validar	Integrações > Conexões > Criar
Alterar, habilitar, desabilitar, revalidar	Integrações > Conexões > Alterar
Excluir	Integrações > Conexões > Excluir

Associar uma conexão exige a permissão do recurso associado, na área correspondente do módulo.

Pela API

A API V2 tem endpoints para criar, consultar, alterar e excluir conexões e para associá-las a recursos. Veja a referência da API V2.