Caixa Postal

A Caixa Postal é uma pasta de troca de arquivos entre o seu sistema e a Kobana. Cada caixa tem uma Caixa de Entrada (arquivos que você envia para a Kobana) e uma Caixa de Saída (arquivos que a Kobana entrega para você). Os arquivos entram e saem pelos canais que você ativa na caixa: AWS S3, SFTP, e-mail, WhatsApp e Syncthing. Todo arquivo também pode ser enviado e consultado pela API.

Não confunda com a conexão EDI com o banco, que no menu também se chama Caixas Postais: aquela liga a Kobana ao banco; esta liga o seu sistema à Kobana.

Onde fica no painel

Integrações → Seu Sistema → Kobana → EDI → Caixas Postais:

• Gerenciar: lista as caixas postais.
• Nova Caixa Postal: abre o formulário de cadastro.

O item aparece no menu quando a Caixa Postal está liberada para a conta, e as telas exigem que o produto Caixa Postal faça parte do plano contratado.

Tipos de caixa

O tipo define o que acontece com os arquivos de cada lado.

Tipo	Caixa de Entrada	Caixa de Saída
Guarda de Documentos	Os arquivos ficam guardados na caixa.	A Kobana não coloca arquivos automaticamente.
Importação/Exportação	Cada arquivo vira uma importação, que aparece em Administração → Históricos → Importações.	As exportações da conta, assim que ficam prontas.
EDI (CNAB Remessa/CNAB Retorno)	Cada arquivo vira um retorno CNAB, que aparece em Arquivos de Retorno (veja Retornos).	Uma cópia de cada remessa processada da conta (veja Remessas).

As cópias de remessas e exportações vão só para caixas do tipo certo que estejam Ativada e Habilitada.

Importação/Exportação: como a Kobana reconhece o arquivo

O tipo de importação é detectado pelo nome do arquivo. O nome precisa conter uma das palavras abaixo (maiúsculas ou minúsculas tanto faz). A verificação segue a ordem da tabela e para no primeiro tipo que combinar.

Tipo de importação	Exemplos de palavra no nome
Pagamento de Pix	pagamento...pix, pagar...pix, pix...pago
Pagamento de Boleto	pagamento...boleto, pagar...boleto, boleto...pago
Pagamento de DARF	darf, imposto...federal
Pagamento de Conta	conta...luz, conta...agua, conta...gas, concessionaria, pagamento...conta
Pagamento de GRU	gru, guia...recolhimento
Carnês	carne, parcelamento, mensalidade
Senha do cliente	senha...cliente, cliente...senha
Assinatura	assinatura, subscription
Cliente	cliente, customer
Boleto	boleto, cobranca, titulo
Extrato / Transação	extrato, transacao, movimento
Transferência	transferencia, ted, doc
Pix	pix, qrcode

Exemplos: cliente_novo_20241020.csv vira importação de clientes; extrato_20241231.csv, importação de extrato. Nas caixas de Importação/Exportação, a Caixa de Entrada aceita arquivos .csv, .txt, .rem, .ret, .tab, .tsv, .dsv, .psv e .dat. A tela da caixa tem o painel Instruções com a lista completa.

Cadastrar uma caixa postal

Em Nova Caixa Postal:

Campo	Obrigatório	Descrição
Nome	Sim	Nome descritivo da caixa postal.
Tipo	Sim	Guarda de Documentos, Importação/Exportação ou EDI (CNAB Remessa/CNAB Retorno). Não pode ser trocado depois.
Etiquetas (Tags)	Não	Etiquetas separadas por vírgula.

Ao salvar, o painel mostra "Caixa Postal cadastrada com sucesso!" e a caixa é ativada em instantes. A Kobana cria para ela um usuário de acesso, usado pelos canais S3 e SFTP, e um endereço de e-mail próprio, usado pelo canal de e-mail. Com a caixa ativa, configure os canais (veja Canais da Caixa Postal).

Ativada e Habilitada

A caixa mostra duas marcações independentes:

Marcação	Significado
Ativada / Inativa	Se o acesso da caixa está criado. Os canais só podem ser ativados numa caixa Ativada.
Habilitada / Desabilitada	Chave controlada por você no campo Habilitada? da edição. Uma caixa Desabilitada não recebe cópias de remessas nem exportações.

No menu da caixa (ícone de três pontos):

• Desativar: pede confirmação e desativa a caixa em instantes.
• Ativar: pede confirmação e ativa de novo uma caixa inativa.
• Editar: altera Nome, Etiquetas e Habilitada?.
• Excluir: só fica disponível com a caixa desativada e sem nenhum arquivo. Uma caixa com arquivos não pode ser excluída.
• Mais Informações: mostra UID, Slug, ID externo (quando houver), Nome, Tipo, Etiquetas e as datas de criação e atualização.
• Instruções: explica o uso da caixa de Importação/Exportação.

Lista de caixas postais

Colunas: UID, Nome, Slug, Tipo, Canais (os canais configurados, além de API, que está sempre disponível), Arquivos (quantidade) e o status (Ativada ou Inativa, Habilitada ou Desabilitada). Um ícone marca as caixas criadas pela API.

Tela da caixa postal

À esquerda ficam as abas Caixa de Entrada e Caixa de Saída, com os arquivos de cada lado (veja Arquivos da Caixa Postal). À direita ficam os cartões dos canais disponíveis.

Permissões

Módulo Caixa Postal:

Produto da permissão	Ações
Caixas Postais	Ações Básicas (ver), Criar, Alterar (editar, ativar, desativar e configurar canais), Excluir
Arquivos	Ações Básicas (ver e baixar), Alterar, Excluir

Eventos de webhook

Código	Quando
mailbox.entry.db.created, mailbox.entry.db.updated, mailbox.entry.db.deleted	A caixa foi criada, alterada ou excluída.
mailbox.entry.file.received	Um arquivo chegou na Caixa de Entrada.
mailbox.entry.file.sent	Um arquivo foi para a Caixa de Saída.

Navegação

• Arquivos da Caixa Postal
• Canais da Caixa Postal

Pela API

Caixas postais e arquivos têm endpoints na API v2.