Processar, Consultar e Baixar CNAB

Essa funcionalidade permite que os clientes da Celcoin realizem a criação e o gerenciamento de cobranças para seus próprios clientes. As cobranças podem ser emitidas por meio de Boleto Registrado e Pix Cobrança (Bolepix), possibilitando maior flexibilidade nos meios de pagamento, padronização dos processos de cobrança e integração com os fluxos financeiros via CNAB.

Pré requisitos para implementação:

1. Possuir uma chave api da Celcoin, para mais informações acessar esse link
2. Ter familiaridade com o padrão REST usando o protocolo OAuth 2.0.
3. Ter o produto/solução contratado e habilitado em produção.
   1. Caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.
4. Possuir uma conta no BaaS da Celcoin (Conta essa responsável por receber o valor da cobrança)

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Enviar o CNAB para processamento - [API Reference]
3. Consultar Status do Arquivo CNAB - [API Reference]
4. Baixar o arquivo de Remessa - [API Reference]
5. Baixar o arquivo de Retorno - [API Reference]

🚧

Importante

Após o processamento do arquivo com sucesso, você receberá os Webhooks de cada serviço (Pagamentos de Contas, Pagamentos Pix, TED e Emissão de Cobrança)

Quais tipos de arquivos e produtos são aceitos em cada formato CNAB?

Os arquivos CNAB seguem o padrão para troca de informações entre Bancos e Empresas. A Celcoin suporta dois formatos principais:

CNAB 240 (padrão Febraban) - Layout Oficial Febraban

1. Pagamento de Títulos registrados na Núclea
2. Pagamento de Convênios e Tributos
3. Emissão de boletos
4. Envio de TED
5. Geração de Cobranças Pix
6. Envio de Pagamentos Pix
   1. Dados Manuais
   2. Chave
   3. Copia e Cola

CNAB 400 (formato personalizado):

1. Pagamento de Títulos registrados na Núclea
2. Pagamento de Convênios e Tributos
3. Emissão de boletos

🚧

Importante

A identifação do tipo de arquivo é automática, ou seja, não é necessário informar o tipo de arquivo, pois o sistema da Celcoin interpreta automaticamente se é um CNAB 240, CNAB 400 ou fora de padrão (que será rejeitado). Arquivos em codificação UTF-8 ou Windows-1252 são aceitos, com detecção automática de encoding.

Fluxos existentes para Pagamento de Contas e Emissão de Cobranças:

1. Pagamento de Contas:
   1. Envio do arquivo remessa
   2. Geração do arquivo retorno (D0) com validação da integridade do arquivo e lotes
   3. Geração do arquivo retorno (D0) com o status do processamento de cada título e eventuais erros
2. Emissão de Cobranças:
   1. Envio do arquivo remessa
   2. Geração do arquivo retorno (D0) com validação da integridade do arquivo e lotes
   3. Geração de arquivo retorno (D1 útil do pagamento) com a confirmação de que o pagamento foi recebido e creditado na conta

Quais são os padrões de nomenclatura para arquivos de remessa e retorno?

Para garantir processamento eficiente e evitar rejeições, siga estas regras críticas para nomenclatura:

1. Arquivos de Remessa:
   1. Formato: REMESSA_[DATA_YYYYMMDD][HORA_HHMMSS][CLIENT_REQUEST_ID].[EXT]
      1. Exemplo: REMESSA_20250915_143022_c8301b5d-4ffa-4288.txt
   2. Data e hora: Baseadas na geração do arquivo (obrigatório para auditoria e evitar duplicatas).
   3. ClientRequestId: UUID único para rastreamento (gerado pelo cliente).
   4. Extensão: .txt, .rem ou .cnab (UTF-8 ou Windows-1252).
   5. Limitações: Máximo 50 caracteres; sem espaços ou caracteres especiais (exceto underscore).
2. Arquivos de Retorno: (DESCREVER O FRMATO CERTO)
   1. Formato: Retorna em um formato Plaintext, portanto, a nomenclatura ficará a critério do usuário no momento em que fizer a conversão.

Atenção para Regras de duplicidade: Arquivos com o mesmo ClientRequestId + data são rejeitados. Sempre use data/hora atuais para evitar conflitos.

Como funcionam os arquivos de Remessa e Retorno?

1. Arquivos de Remessa: São os arquivos enviados via API (POST para /baas/v2/dev-cnab-reader/cnab-file). Após upload, recebem um fileId para rastreamento. O processamento é assíncrono, com status via consulta ou webhooks.
2. Arquivos de Retorno: Gerados automaticamente pela Celcoin após processamento bem-sucedido. Exemplos:
   1. Para emissão de boletos: Arquivo D0 (mesmo dia) com status de processamento; arquivo D1 com confirmação de liquidações/baixas.
   2. Para Pix/TED: Retorno em D0 com status de processamento e confirmação de liquidação.
3. Armazenamento: Arquivos de remessa e retorno ficam disponíveis para download via API ou dashboard. Os arquivos ficam salvos internamente por 5 anos para Compliance.

Quais são as regras de rejeição para arquivos, lotes e registros?

O sistema prioriza consistência para evitar erros parciais:

1. Nível Arquivo: Header e Trailer são validados (ex.: soma de valores, quantidade de registros). Inconsistência total rejeita o arquivo inteiro (status ERROR com código PCE100).
2. Nível Lote (apenas CNAB 240): Cada lote tem seu próprio header/trailer. Inconsistência rejeita o lote, mas processa os demais.
3. Nível Registro: Erros isolados (ex.: CPF inválido, valor negativo) rejeitam apenas o registro/linha, processando o restante do lote. Caso utilize a API de Consulta de Status, poderá visualizar nos campos errorCode e message.

Exemplo de rejeição:

1. Arquivo: "Quantidade de registros no trailer não bate com header" → Rejeição total
2. Lote: "Lote sem registro ou inconsistência entre header/traile" → Rejeição do Lote e processamento dos demais
3. Registro: "Data de vencimento inválida" → Rejeição do Registro e processamento dos demais

Obs.: Sempre valide localmente antes do envio para minimizar rejeições.

Como é identificada a Conta de Origem para débitos de pagamentos e créditos de cobranças?

Embora o layout CNAB inclua campos para conta de origem nos registros, a Celcoin ignora esses campos e usa exclusivamente o valor informado no parâmetro account da requisição API (via clientRequestId ou body do POST).

1. Para múltiplas contas: Gere arquivos separados, cada um com um account diferente. Um único arquivo processa apenas uma conta.
2. Exemplo na API: No cURL, passe -F 'account=123456-7' para definir a conta BaaS usada.

Isso simplifica a integração, mas exige cuidado ao gerar remessas multi-contas.

Quais são as grades (cronogramas) de processamento de arquivos?

O processamento segue horários fixos, conforme abaixo:

1. Fins de semana/feriados:
   1. Liquidação Pix e Geração Pix: Funcionam 24/7
   2. Liquidação TED: Funcionam apenas em dias úteis, até 16h30
   3. Liquidação de Boletos: Processamento das 7h00 às 23h00 nos dias úteis. Caso o pagamento ocorra fora deste horário ou em dias não-úteis, a solicitação de baixa do boleto será feita normalmente, mas a liquidação será agendada para o próximo dia útil.
   4. Emissão de Boletos:
2. Monitoramento: Use status PROCESSING para rastrear; webhooks notificam conclusão.

Como consultar arquivos processados anteriormente (Remessa e Retorno)?

Use a API de consulta por fileId ou clientRequestId:

1. Endpoint: GET /baas/v2/dev-cnab-reader/files/{fileId}
2. Parâmetros: Inclua clientRequestId para filtros
3. Retorno: retorna todos os dados atrelados ao fileId ou clientRequestId informados, retornando um text/plain para conversão no Arquivo de Retorno

Como visualizar no Arquivo de Retorno quais são os status de cada Boleto registrado anteriormente?

No CNAB 400, o Arquivo de Retorno devolverá nas posições 109-110 (Segmento Obrigatório) a "Identificação de Ocorrência", vide tabela abaixo:

Qual o limite de tamanho para arquivos CNAB?

Máximo 10 MB por arquivo (até 50.000 registros). Para maiores volumes, divida em múltiplos arquivos.

CNAB400 - Detalhamento Técnico

O CNAB 400 da Celcoin é utilizado para os processos de Remessa e Retorno de cobranças bancárias, onde a estrutura do arquivo é composta por registros de tamanho fixo, totalizando 400 posições.

Alterações Celcoin no CNAB 400

A especificação adotada pela Celcoin contempla algumas alterações em relação ao layout de outros players, conforme descrito a seguir:

1. Cabeçalho do Arquivo: O campo referente ao número da conta recebedora foi expandido para 7 caracteres, passando a ocupar as posições 31 a 37. O campo preenchido com zeros, anteriormente localizado nas posições 31 a 32, foi removido.
2. Segmento Obrigatório Principal: O campo de 10 caracteres localizado nas posições 265 a 274 foi redefinido para armazenar o complemento de endereço. O campo de logradouro teve seu tamanho reduzido de 40 para 30 caracteres, passando a ocupar as posições 275 a 304. Além disso, foi adicionado um novo campo para o número do endereço do pagador, nas posições 305 a 314.
3. Segmento Sacador/Avalista: Este segmento passou a ser obrigatório. O campo anteriormente reservado com 180 caracteres, localizado nas posições 215 a 394, foi reduzido para 78 caracteres, ocupando agora as posições 317 a 394, permitindo a inclusão de informações relacionadas ao Pix. Também foram adicionados dois novos campos específicos para a chave Pix:
   1. Tipo da Chave Pix: posições 215 a 216.
   2. Chave de Endereçamento Pix: posições 217 a 316.

CNAB400 - Tabelas de Posições: Layout Arquivo de Remessa

CABEÇALHO (HEADER)

SEGMENTO OBRIGATÓRIO

SEGMENTO JUROS

SEGMENTO DE MULTA

SEGMENTO SACADOR AVALISTA

RODAPÉ (TRAILER)

CNAB400 - Tabelas de Posições: Layout Arquivo de Retorno

CABEÇALHO (HEADER)

SEGMENTO OBRIGATÓRIO

DETALHE REGISTRO

RODAPÉ (TRAILER)

Exemplos - Enviar Arquivo CNAB (POST)

🚧

Atenção

1. Idempotência: O sistema utiliza um fingerprint do arquivo. Se o mesmo conteúdo (file + account) for enviado novamente pelo mesmo usuário, o sistema retornará a resposta do envio anterior
2. Conta: O campo account altera o fingerprint do arquivo

Requisição HTTP

POST https://sandbox.openfinance.celcoin.dev/cnab/v1/cnab-file

Parâmetros de Requisição

Body (multipart/form-data)

cURL da chamada

curl --request POST \
 --url https://sandbox.openfinance.celcoin.dev/cnab/v1/cnab-file \
 --header 'Authorization: Bearer SEU_TOKEN' \
 --header 'Content-Type: multipart/form-data' \
 --form '[email protected];type=text/plain' \
 --form 'clientRequestId=10213123' \
 --form 'account='

Exemplo de retorno

👍

Sucesso 200 - Arquivo Recebido

{
 "status": "PENDING",
 "entity": "cnab-process",
 "body": {
 "fileId": "ab09ab09ab09ab09ab09ab09",
 "fileType": "Cnab400CelcoinChargeOutboundModel",
 "clientRequestId": "c8301b5d-4ffa-4288-8061-b0af4189f823"
 }
}

❗

Error 400 - Erro de Leitura

{
 "entity": "cnab-process",
 "status": "PENDING",
 "error": {
 "errorCode": "PCE100",
 "message": "Error while parsing CNAB."
 }
}

Exemplos - Consultar Arquivo CNAB (GET)

Status Possíveis

Requisição HTTP

GET https://sandbox.openfinance.celcoin.dev/cnab/v1/cnab-file/{id}

Parâmetros de Requisição

Path Params (Parâmetros de Caminho)

cURL da chamada

curl --request GET \
 --url https://sandbox.openfinance.celcoin.dev/cnab/v1/cnab-file/102030 \
 --header 'accept: application/json' \
 --header 'Authorization: Bearer SEU_TOKEN'

Exemplo de retorno

👍

Sucesso 200 - Processamento Pendente/Parcial (PENDING)

{
 "status": "PENDING",
 "entity": "cnab-process",
 "body": {
 "fileId": "ab09ab09ab09ab09ab09ab09",
 "fileType": "Cnab400CelcoinChargeOutboundModel",
 "error": "There are some errors on your cnab file",
 "errorClientIds": [
 {
 "clientRequestId": "cnab:ID_OPERACAO_1",
 "error": {
 "errorCode": "PCE421",
 "message": "Missing clientRequestId"
 }
 }
 ],
 "successClientIds": []
 }
}

👍

Sucesso 200 - Processamento Concluído (GENERATED_OUTPUT)

{
 "status": "GENERATED_OUTPUT",
 "entity": "cnab-process",
 "body": {
 "fileId": "68b0a02933294b50e8dcd71f",
 "fileType": "Cnab400CelcoinChargeOutboundModel",
 "clientRequestId": "102030",
 "errorClientIds": [
 {
 "clientRequestId": "undefined",
 "error": {
 "errorCode": "CBE050",
 "message": "Número da conta do recebedor não localizada ou inativa."
 },
 "lines": [2, 3]
 }
 ],
 "successClientIds": []
 }
}

❗️

Erro 400 - Arquivo Não Encontrado

{
  "status": "ERROR",
  "entity": "cnab-process",
  "error": {
    "errorCode": "PCE406",
    "message": "Couldn't find id/clientRequestId ab09ab09ab09ab09ab09ab09"
  }
}

Exemplos - Baixar Arquivo Remessa (GET)

Parâmetros de Requisição

Headers (Cabeçalhos)

Path Params (Parâmetros de Caminho)

cURL da chamada

curl --request GET \
 --url https://sandbox.openfinance.celcoin.dev/cnab/v1/cnab-file/ab09ab09ab09ab09ab09ab09/fileinput \
 --header 'accept: binary' \
 --header 'Authorization: Bearer SEU_TOKEN'

Exemplo de retorno

👍

Sucesso 200 - Plaintext

01REMESSA00COBRANCA 0001300544676 Empresa Doce de Leite Teste 509CELCOIN
170425 000001
[email protected] 21999999999163
00000000000323004250000000012.115090000199A310325 0000000001.0025042500000002.11
0199999999999 Empresa XPTO Alameda Teste
0000000310Teste Bairro99999999São Paulo SP 310525 000002
9
000015

❗️

Erro 404 - Não Encontrado

{
 "status": "ERROR",
 "entity": "cnab-process",
 "error": {
 "errorCode": "PCE404",
 "message": "File with \"id/clientRequestId\" = \"ab09ab09...\" not found"
 }
}

Exemplos - Baixar Arquivo Retorno (GET)

Parâmetros de Requisição

Headers (Cabeçalhos)

Path Params (Parâmetros de Caminho)

cURL da chamada

curl --request GET \
 --url https://sandbox.openfinance.celcoin.dev/cnab/v1/cnab-file/ab09ab09ab09ab09ab09ab09/fileoutput \
 --header 'accept: text/plain' \
 --header 'Authorization: Bearer SEU_TOKEN'

Exemplo de retorno

👍

Sucesso 200 - Plaintext

50900000 201030419000159 00001 300545084232 0CLIENTE TESTE
CELCOIN IP 11903202515460000000010300000
50900011C2031040 201030419000159 00001 300545084232 0CLIENTE TESTE
N.SRA. COPACABANA,978 00000SOBRELOJAS RIO DE JANEIRO 22060000RJ
50999999 000001000010 

❗️

Erro 404 - Não Encontrado

{
  "status": "ERROR",
  "entity": "cnab-process",
  "error": {
    "errorCode": "PCE404",
    "message": "File with \"id/clientRequestId\" = \"ab09ab09ab09ab09ab09ab09\" not found"
  }
}