Certificados e chaves
Muitos bancos exigem um certificado digital na comunicação pela API. O certificado fica cadastrado na conta e é escolhido na criação da conexão bancária. Alguns bancos pedem também uma chave criptográfica, cadastrada em Chaves.
Certificados
Onde fica
Menu Administração > Certificados. A lista mostra ID, Identificação, CNPJ/CPF, Data de expiração, Situação e o número de conexões que usam cada certificado. O botão Filtrar abre a busca.
Situação do certificado
| Situação | Significado |
|---|---|
| Válido | Certificado processado com sucesso e pronto para uso nas conexões. |
| Rascunho | O certificado foi salvo, mas o processamento falhou (por exemplo, senha errada ou arquivo inválido). A mensagem de erro aparece ao salvar. |
| Requisitado | Você pediu um CSR. Falta enviar o certificado emitido pelo banco ou pela autoridade certificadora. |
| Expirado | A data de expiração passou. A situação é atualizada diariamente. |
Requisitado ──Fazer upload do CRT──> Válido ──vencimento──> Expirado
Novo certificado ──arquivo válido──> Válido
Novo certificado ──falha no processamento──> Rascunho
Cadastrar um certificado
Clique em Novo certificado, preencha os campos e clique em Salvar Certificado.
| Campo | Obrigatório | Descrição |
|---|---|---|
| Identificação | Sim | Nome para reconhecer o certificado. |
| CNPJ/CPF | Sim | Documento do titular do certificado. |
| Liberado nas subcontas | Não | Só na conta principal. Quando ligado, o certificado fica disponível para as conexões das subcontas. |
| Formato | Sim | Escolha uma das opções abaixo. |
Formatos aceitos:
| Opção na tela | Arquivos pedidos |
|---|---|
| Tenho um arquivo (.pfx, .p12) e uma senha | Arquivo .pfx/.p12 e Senha do certificado. |
| Tenho um arquivo da chave pública e outro da chave privada | Arquivo .crt, .pem e Arquivo .key. |
| Tenho um arquivo só com a chave pública e privada juntas | Arquivo .pem. |
| Tenho um arquivo da chave pública, outro da chave privada e uma senha | Arquivo .crt, .pem, Arquivo .key e Senha da chave privada. |
| Preciso de um CSR para requisitar o certificado | Nenhum arquivo. A Kobana gera o CSR. |
Requisitar um certificado por CSR
- Cadastre o certificado com a opção Preciso de um CSR para requisitar o certificado. A situação fica Requisitado.
- No menu do certificado, clique em Baixar CSR e envie o arquivo ao banco ou à autoridade certificadora.
- Quando receber o certificado emitido, clique em Fazer upload do CRT e envie o arquivo. Se ele for aceito, a situação passa a Válido.
Ações do certificado
| Ação | O que faz | Quando aparece |
|---|---|---|
| Alterar | Edita Identificação e Liberado nas subcontas. | Com a permissão Alterar. |
| Renovar | Pede a renovação do certificado ao banco pela API. A renovação roda em segundo plano e você recebe um alerta ao final. | Só quando o certificado pode ser renovado (veja abaixo). |
| Baixar CSR / Fazer upload do CRT | Fluxo de requisição por CSR. | Certificado Requisitado ou Rascunho. |
| Liberar na Subconta / Bloquear na Subconta | Libera ou bloqueia o uso do certificado nas conexões das subcontas. | Sempre. |
| Excluir | Apaga o certificado. | Só para certificado que você cadastrou e que não tem conexões vinculadas. |
Renovação
O botão Renovar só aparece quando todas as condições abaixo são atendidas:
- o certificado está Válido;
- ele está vinculado a pelo menos uma conexão cujo banco permite renovar certificado pela API;
- o vencimento está dentro da janela de renovação definida pelo banco;
- o certificado foi emitido pelo próprio banco.
Fora dessas condições, a renovação precisa ser feita junto ao banco, e o novo certificado é cadastrado como um certificado novo. Além do botão, a Kobana verifica diariamente os certificados vinculados a bancos que permitem renovação pela API e pode renová-los automaticamente perto do vencimento.
Aviso de vencimento
A Kobana envia um e-mail quando um certificado válido cadastrado por você está a 30, 15 e 5 dias do vencimento.
- O botão Notificações, na lista de certificados, mostra para qual e-mail os avisos vão e permite editar o endereço em E-mail para notificações de certificado.
- O endereço vale para todos os certificados da conta. Sem endereço informado, os avisos vão para o e-mail principal da conta.
- Em uma subconta, os avisos vão para o e-mail configurado nela e também para o e-mail de notificação (ou o e-mail principal) da conta principal.
Permissões
| Ação | Permissão |
|---|---|
| Ver certificados | Integrações > Certificados > Ações Básicas |
| Cadastrar, baixar CSR, enviar CRT | Integrações > Certificados > Criar |
| Alterar, liberar ou bloquear na subconta, alterar e-mail de notificação | Integrações > Certificados > Alterar |
| Renovar | Integrações > Certificados > Renovar |
| Excluir | Integrações > Certificados > Excluir |
Chaves
Alguns bancos pedem que você disponibilize uma chave pública para a comunicação. As chaves ficam em Administração > Chaves. A lista mostra ID, Identificação da chave, Origem, Algoritmo, Tamanho/Curva e a data em que foi gerada.
| Campo | Obrigatório | Descrição |
|---|---|---|
| Identificação da chave | Sim | Nome para reconhecer a chave. |
| Origem | Sim | Preciso gerar uma chave: a Kobana gera o par de chaves; escolha em "Defina a origem da solicitação de chave" o banco que vai usá-la. Tenho uma chave e quero fazer upload: informe a Chave privada e, se houver, a Senha. |
| Ativar nas subcontas | Não | Só na conta principal. Quando ligado, a chave fica disponível para as conexões das subcontas. |
Clique em Gerar Chave. Na lista, o ícone de download baixa a chave pública para enviar ao banco. Ao bloquear nas subcontas uma chave que já é usada por conexões de subcontas, o painel avisa quantas conexões a usam antes de confirmar.
Pela API
A API V2 tem endpoints para listar, cadastrar e excluir certificados. Veja a referência da API V2.