Formatos e templates

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.

curl -X GET "https://api.matcher.example.com/v1/imports/formats" \
  -H "Authorization: Bearer $TOKEN"

Cada variante carrega a chave canônica de registro 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": "camt053", "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. Mesmo uma família com um único layout canônico (por exemplo, camt) nomeia o layout dela como variant (camt053 acima).

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, um registro sem campos ou uma coluna de dinheiro mal marcada rejeitam com 422, e o Matcher nunca armazena esse template.

Regra inegociável do dinheiro: uma coluna de dinheiro deve declarar kind: "decimal". A verificação de envio rejeita um campo de dinheiro que omite ou marca errado o kind dele. Esse campo nunca chega ao caminho de parse.

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 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.
fields[].kind: string, decimal (token literal de dinheiro/numérico, interpretado adiante) ou date.
requiredFields: 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

# 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 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.

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"

O delete responde 204. Um template ausente retorna 404. Uma colisão de chave de formato com outro template ativo retorna 409.

Códigos de resposta

Status	Significado
`200`	Catálogo, lista de templates, obtenção ou atualização retornados
`201`	Template criado
`204`	Template excluído em soft-delete
`400`	Campo/layout estruturalmente malformado
`404`	Template não encontrado
`409`	Chave de formato/variante já tomada
`422`	O layout falhou na verificação de boa formação (estouro, sobreposição, obrigatório ausente, sem campos, dinheiro mal marcado)
`503`	Catálogo de formatos ou armazenamento de templates não conectado neste deploy

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Formatos e templates

O catálogo de formatos

Templates de layout

Criar um template

Listar e obter templates

Atualizar e excluir um template

Códigos de resposta

​O catálogo de formatos

​Templates de layout

​Criar um template

​Listar e obter templates

​Atualizar e excluir um template

​Códigos de resposta

O catálogo de formatos

Templates de layout

Criar um template

Listar e obter templates

Atualizar e excluir um template

Códigos de resposta