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

> Navegue pelo catálogo de formatos embutidos que o Matcher consegue interpretar e registre templates de layout de largura fixa por tenant para arquivos específicos de um operador.

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.

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

```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": "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).

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

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

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

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

```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"
```

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                                                 |