Pular para o conteúdo principal
O Matcher interpreta os arquivos recebidos contra um catálogo de formatos embutidos e, quando um arquivo não se encaixa em nenhum deles, contra templates de layout de largura fixa por tenant que você define. Este guia cobre a navegação pelo catálogo de formatos e a gestão dos templates de layout.

​
O catálogo de formatos

O catálogo dá um inventário somente leitura dos formatos que o motor de ingestão consegue interpretar. Ele é global primeiro e estático: os parsers embutidos não carregam tenant, então cada chamador autenticado vê a mesma resposta. O catálogo usa uma árvore region → family → variant que corresponde aos eixos do descritor canônico de formato.
Cada variante carrega a chave canônica de registro com namespace, a identidade que um upload ou uma declaração de fonte fixa:
As regiões usam o código ISO-3166 alpha-2 (em maiúsculas), ou XX para formatos neutros de região. Mesmo uma família com um único layout canônico (por exemplo, camt) nomeia o layout dela como variant (camt053 acima). O catálogo embutido contém estas chaves de formato:
O catálogo não recebe parâmetros de path, de query nem de corpo. O tenant não tem efeito sobre o catálogo embutido.

​
Templates de layout

Quando um arquivo usa um layout de largura fixa específico de um operador ou de uma marca que nenhum parser embutido cobre, registre um template de layout. Um template coloca um layout posicional sob o namespace dos eixos {region, family, variant}. O caminho de parse o resolve como uma fonte de layout aditiva para o seu tenant. Cada envio e edição passa por uma verificação de boa formação antes do armazenamento. Estouro, sobreposição, campos obrigatórios ausentes, uma coluna de dinheiro mal marcada ou um kind desconhecido rejeitam com 422. Um registro sem campos rejeita com 400. O Matcher nunca armazena esse template. O Matcher não usa um template cuja chave coincide com um formato embutido.
Regra inegociável do dinheiro: o campo chamado amount é a coluna de dinheiro, e ele deve declarar kind: "decimal". A verificação de envio rejeita um campo amount que omite ou marca errado o kind dele. O Matcher lê amount como um número com ponto decimal explícito e não aplica casas decimais implícitas: 000000010050 é lido como 10050.

​
Criar um template

Valores dos campos:
  • region: região ISO alpha-2 (em maiúsculas) ou XX.
  • family: família de formato de enum fechado sob a qual o template entra no namespace.
  • variant: eixo aberto de operador/marca (não deve ficar em branco).
  • discriminatorStart / discriminatorLength: a faixa de bytes que o parser lê para escolher um tipo de registro.
  • records[]: cada tipo de registro com a width fixa dele (em bytes) e os fields posicionais ordenados. Os offsets começam em zero.
  • fields[].name: external_id, amount, currency, date e description vão para a transação. Todos os outros nomes vão para os metadados. Sem um campo currency, a moeda é BRL.
  • fields[].kind: string, decimal (token literal de dinheiro/numérico, interpretado adiante) ou date.
  • requiredFields (opcional): nomes de campo que a variante deve declarar em seus tipos de registro.
Uma criação bem-sucedida retorna 201 com o template armazenado, incluindo o formatKey dele (por exemplo, br/cnab400/acme-cobranca), o discriminador, o layout posicional completo e recordWidths.

​
Listar e obter templates

A lista não tem paginação, porque os templates de layout formam uma configuração de operador limitada.

​
Atualizar e excluir um template

PUT é uma substituição completa, não um patch parcial. As invariantes de faixa de bytes são propriedades do layout inteiro. A substituição passa pela mesma verificação de boa formação que o caminho de criação aplica. Um layout que falha é rejeitado com 422, e o template armazenado continua inalterado.
O delete responde 204. Um template ausente retorna 404.

​
Códigos de resposta