> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Formatos e templates

> Explore o catálogo de formatos integrados que o Matcher consegue analisar e registre templates de layout de largura fixa por tenant para arquivos específicos de cada operadora.

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.

```bash theme={null}
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:

```json theme={null}
{
  "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.

<Note>O catálogo não recebe parâmetros de path, query ou body — o tenant é irrelevante para o catálogo integrado.</Note>

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

<Note>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.</Note>

### Criar um template

```bash theme={null}
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

```bash theme={null}
# 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.

```bash theme={null}
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": [ ... ] }'
```

```bash theme={null}
# 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

***

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