> ## 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). O catálogo embutido contém estas chaves de formato: | Família | Chaves de formato | | - | - | | Genérico (neutro de região) | `xx/delimited/generic` (CSV), `xx/json/generic`, `xx/xml/generic`, `xx/ofx/generic`, `xx/camt/camt053` | | CNAB | `br/cnab240/febraban-base`, `br/cnab240/pagamento`, `br/cnab400/febraban-base` | | EDI de adquirente | `br/acquirer_edi/cielo-v15`, `br/acquirer_edi/rede`, `br/acquirer_edi/getnet-v10-1`, `br/acquirer_edi/stone-xml`, `br/acquirer_edi/adyen`, `br/acquirer_edi/vero-bknfin1`, `br/acquirer_edi/vero-bknfin2` | | CSV de adquirente | `br/acquirer_csv/stone-pix`, `br/acquirer_csv/mercadopago` | | Recebíveis | `br/receivables/tag` | > [!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. ## 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. > [!NOTE] > > 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 ```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. 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 ```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`. ## 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 (incluindo um registro sem campos) | | `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, dinheiro mal marcado), um campo tem um `kind` desconhecido, ou falta um campo obrigatório do corpo | | `503` | Catálogo de formatos ou armazenamento de templates não conectado neste deploy | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.