Pular para o conteúdo principal
O Matcher analisa os arquivos recebidos contra um catálogo de formatos integrados 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 como explorar o catálogo de formatos e gerenciar templates de layout.

​
O catálogo de formatos

O catálogo é o inventário somente leitura dos formatos que o motor de ingestão consegue analisar. Ele é global primeiro e estático: os analisadores integrados não carregam tenant, então a resposta é idêntica para cada chamador autenticado. O catálogo é organizado como uma árvore region → family → variant, seguindo os eixos canônicos do descritor de formato. 
curl -X GET "https://api.matcher.example.com/v1/imports/formats" \
  -H "Authorization: Bearer $TOKEN"
Cada variante carrega a chave de registro canônica com namespace — a identidade que um upload ou uma declaração de fonte fixa: 
{
  "regions": [
    {
      "region": "BR",
      "families": [
        {
          "family": "cnab240",
          "variants": [
            { "variant": "febraban-base", "key": "br/cnab240/febraban-base" }
          ]
        }
      ]
    },
    {
      "region": "XX",
      "families": [
        {
          "family": "camt",
          "variants": [
            { "variant": "", "key": "xx/camt/camt053" }
          ]
        }
      ]
    }
  ]
}
As regiões usam o código ISO-3166 alpha-2 (em maiúsculas), ou XX para formatos neutros de região. Uma família de layout canônico único (por exemplo camt) produz uma única entrada com um variant vazio.
O catálogo não recebe parâmetros de path, query ou body — o tenant é irrelevante para o catálogo integrado.

​
Templates de layout

Quando um arquivo usa um layout de largura fixa específico de uma operadora ou marca que nenhum analisador integrado cobre, registre um template de layout. Um template atribui um namespace a um layout posicional sob os eixos {region, family, variant} e é resolvido pela rota de análise como uma fonte de layout aditiva para o seu tenant. Cada submissão e edição passa por uma verificação de boa formação antes do armazenamento. Um estouro, uma sobreposição, campos obrigatórios ausentes, um registro sem campos ou uma coluna de dinheiro mal marcada rejeitam com 422 e o template nunca é armazenado.
Terceiro trilho do dinheiro: uma coluna de dinheiro deve declarar kind: "decimal". Um campo de dinheiro que omite ou marca errado seu kind é rejeitado pela verificação de submissão — ele nunca chega à rota de análise.

​
Criar um template

curl -X POST "https://api.matcher.example.com/v1/imports/formats/templates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "BR",
    "family": "cnab400",
    "variant": "acme-cobranca",
    "discriminatorStart": 0,
    "discriminatorLength": 1,
    "records": [
      {
        "recordType": "1",
        "width": 33,
        "fields": [
          { "name": "external_id", "startByte": 1, "length": 10, "kind": "string" },
          { "name": "amount", "startByte": 11, "length": 12, "kind": "decimal" },
          { "name": "date", "startByte": 23, "length": 10, "kind": "date" }
        ]
      }
    ],
    "requiredFields": ["external_id", "amount", "date"]
  }'
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 atribui o namespace.
  • variant — eixo aberto de operadora/marca (não pode estar em branco).
  • discriminatorStart / discriminatorLength — o intervalo de bytes que o analisador lê para selecionar um tipo de registro.
  • records[] — cada tipo de registro com sua width fixa (bytes) e seus fields posicionais ordenados.
  • fields[].kind — string, decimal (token de dinheiro/numérico literal, analisado adiante) ou date.
  • requiredFields — nomes de campos que a variante deve declarar em seus tipos de registro.
Uma criação bem-sucedida retorna 201 com o template armazenado, incluindo sua formatKey (por exemplo br/cnab400/acme-cobranca), o discriminador, o layout posicional completo e recordWidths.

​
Listar e obter templates

# List every active template on the tenant (unpaginated)
curl -X GET "https://api.matcher.example.com/v1/imports/formats/templates" \
  -H "Authorization: Bearer $TOKEN"

# Get one template by id
curl -X GET "https://api.matcher.example.com/v1/imports/formats/templates/{templateId}" \
  -H "Authorization: Bearer $TOKEN"
A lista não é paginada: templates de layout são configuração de operadora limitada.

​
Atualizar e excluir um template

PUT é uma substituição completa, não um patch parcial — os invariantes de intervalo de bytes são propriedades de todo o layout. A substituição passa pela mesma verificação de boa formação que a rota de criação aplica; um layout que falha rejeita com 422 e o template armazenado permanece inalterado. 
curl -X PUT "https://api.matcher.example.com/v1/imports/formats/templates/{templateId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "region": "BR", "family": "cnab400", "variant": "acme-cobranca", "discriminatorStart": 0, "discriminatorLength": 1, "records": [ ... ] }'

# Soft-delete, freeing the format/variant key for reuse
curl -X DELETE "https://api.matcher.example.com/v1/imports/formats/templates/{templateId}" \
  -H "Authorization: Bearer $TOKEN"
A exclusão responde 204. Um template inexistente retorna 404; uma colisão de chave de formato com outro template ativo retorna 409.

​
Códigos de resposta

StatusSignificado
200Catálogo, lista de templates, obtenção ou atualização retornada
201Template criado
204Template excluído de forma lógica
400Campo/layout estruturalmente malformado
404Template não encontrado
409Chave de formato/variante já reivindicada
422O layout falhou na verificação de boa formação (estouro, sobreposição, obrigatório ausente, sem campos, dinheiro mal marcado)
503O catálogo de formatos ou o armazenamento de templates não está conectado neste deployment