Comandos

Um comando é uma operação que a Kobana precisa executar no banco (ou provedor financeiro) sobre um recurso seu: registrar um boleto, cancelar um Pix, alterar o vencimento, aprovar um lote de pagamentos, sincronizar um extrato. Toda vez que você emite, altera ou cancela algo que depende do banco, a Kobana cria o comando correspondente e acompanha a resposta.

API ou remessa

Para cada comando, a Kobana verifica como o banco aceita a operação:

• Por API: quando a carteira ou conta tem a API habilitada e o banco suporta a operação, o comando é enviado na hora. Cada chamada ao banco fica registrada como um comando de API dentro do comando.
• Por remessa (EDI): quando a operação só pode ir por arquivo, o comando vira uma ocorrência pendente que entra na próxima remessa (veja Remessas). O comando é confirmado ou falha quando o retorno do banco chega.

Em boletos de carteira com CNAB disponível, um registro, cancelamento, alteração ou protesto recusado pela API pode seguir por remessa.

Sem assinatura ativa na Kobana, os comandos não são enviados ao banco.

Onde fica no painel

• Administração → Históricos → Comandos: todos os comandos da conta.
• Aba Comandos nas telas de boleto, Pix, pagamento, lote de pagamentos, transferência, lote de transferências, conta financeira e restrição de crédito: os comandos daquele recurso.

Lista de comandos

Colunas: ID, Recurso (tipo e número, com link para o recurso), Operação, Provedor, Criado em e Status.

Filtros: ID do Comando, Criação (de/até), Status, Tipo de Recurso, ID do Recurso, Operação e Provedor.

Exemplos de operação: Registro, Cancelamento, Alteração, Inclusão, Exclusão, Liberação, Rejeição, Reagendamento, Protesto, Devolução, Sincronização de Extrato, Sincronização de Saldo, Verificação de Pagamento, Verificação de Andamento, Consulta de Comprovante, Adicionar Pix ao Boleto.

Status

Status	Significado
Agendado	O comando foi criado para uma data futura (campo Agendado para) e vira Pendente nessa data.
Pendente	O comando está sendo enviado ao banco, ou aguarda o retorno de uma remessa.
Aguardando	O banco recebeu o pedido e a Kobana espera a conclusão do lado dele.
Confirmado	O banco confirmou a operação.
Falha	O banco recusou a operação ou as tentativas se esgotaram.
Interrompido	O comando foi parado antes de concluir, por exemplo porque uma ação posterior o tornou sem efeito (cancelar um lote interrompe a aprovação pendente dele).

Transições possíveis:

Agendado   -> Pendente | Aguardando | Interrompido
Pendente   -> Aguardando | Confirmado | Falha | Interrompido
Aguardando -> Confirmado | Falha | Interrompido
Falha      -> Aguardando | Confirmado
Interrompido -> Falha

Um comando em Falha ainda pode ser confirmado depois, por exemplo quando um retorno posterior do banco confirma a operação.

Detalhe do comando

A tela do comando tem três blocos:

• Informações do Comando: ID, Status, Tipo de Recurso, Recurso e Operação.
• Datas e Informações: Solicitado em, Atualizado em, Agendado para (quando houver), Quantidade de erros, Última mensagem de erro e Último aviso.
• Comandos de API Executados: cada chamada feita ao banco, da mais recente para a mais antiga.

Cada comando de API mostra Operação, Resultado, Provedor, as datas (Criado em, Sucesso em, Falhou em, Parado em ou Pulado em), Tentativas falhas, os dados da Requisição (Método, URL e Payload da Requisição) e da Resposta (Status HTTP, Código Lógico, Mensagem e Resposta do Banco). Os botões Baixar JSON e o ícone de cópia exportam o payload e a resposta. Dados sensíveis aparecem mascarados. Em consultas que deram certo, a resposta do banco pode não ser armazenada.

Resultado do comando de API	Significado
3001 - Aceito	O banco aceitou a chamada.
3002 - Rejeitado	O banco recusou a chamada.
3003 - Falha de comunicação	Erro de comunicação; a chamada é repetida.
3004 - Requisição em andamento	O banco ainda está processando.
3005 - Nada a fazer	Não havia o que fazer no banco.
3006 - Interrompido	A chamada foi parada.
3007 - Recuperado	A chamada foi recuperada depois de uma falha.
3008 - Continuação assíncrona	O banco responde em uma etapa posterior.

Falhas e novas tentativas

• Erros de comunicação com o banco (indisponibilidade, limite de requisições) são repetidos automaticamente, com intervalos crescentes. Quando uma tentativa falha sem resposta definitiva, a Quantidade de erros aumenta e o status não muda.
• Quando o banco recusa a operação de forma definitiva, ou as tentativas acabam, o comando vai para Falha. O motivo aparece em Última mensagem de erro e na Mensagem do comando de API.
• Um recurso não aceita dois comandos pendentes da mesma operação. Se dois forem criados ao mesmo tempo, o mais novo vai para Falha.

Permissões

A tela Comandos exige a permissão Integrações → Comandos, ação Ações Básicas.

Eventos de webhook

Os comandos geram eventos no formato recurso.operação.situação, com as situações requested (pedido), confirmed, failed e error (erro que não mudou o status). Exemplos: bank_billet.register.requested, bank_billet.register.confirmed, bank_billet.cancel.failed.

As operações Sincronização, Obtenção, Localização, Obter filho, Consultar Pix do Boleto, Adicionar Pix ao Boleto e Conclusão não geram eventos.

Pela API

Os comandos podem ser consultados na API v2.