Formats and templates

Matcher parses incoming files against a catalog of built-in formats and, when a file does not fit one of them, against per-tenant fixed-width layout templates you define. This guide covers browsing the format catalog and managing layout templates.

The format catalog

The catalog gives a read-only inventory of the formats the ingestion engine can parse. It is global-first and static: built-in parsers carry no tenant, so every authenticated caller sees the same response. The catalog uses a region → family → variant tree that matches the canonical format descriptor axes.

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

Each variant carries the canonical namespaced registry key, the identity an upload or source declaration pins:

{
  "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" }
          ]
        }
      ]
    }
  ]
}

Regions use the ISO-3166 alpha-2 code (uppercased), or XX for region-neutral formats. Even a single-canonical-layout family (for example camt) names its layout as the variant (camt053 above). The built-in catalog holds these format keys:

Family	Format keys
Generic (region-neutral)	`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`
Acquirer EDI	`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`
Acquirer CSV	`br/acquirer_csv/stone-pix`, `br/acquirer_csv/mercadopago`
Receivables	`br/receivables/tag`

The catalog takes no path, query, or body parameters. The tenant has no effect on the built-in catalog.

Layout templates

When a file uses an operator- or brand-specific fixed-width layout that no built-in parser covers, register a layout template. A template namespaces a positional layout under the {region, family, variant} axes. The parse path resolves it as an additive layout source for your tenant. Every submission and edit runs through a well-formedness gate before storage. Overrun, overlap, missing-required fields, a mis-marked money column, or an unknown kind reject with 422. A zero-field record rejects with 400. Matcher never stores that template. Matcher does not use a template whose key matches a built-in format.

Money third rail: the field named amount is the money column, and it must declare kind: "decimal". The submission gate rejects an amount field that omits or mis-marks its kind. Matcher reads amount as a number with an explicit decimal point and applies no implied decimal places: 000000010050 reads as 10050.

Create a 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"]
  }'

Field values:

region: ISO alpha-2 region (uppercased) or XX.
family: closed-enum format family the template namespaces under.
variant: open operator/brand axis (must be non-blank).
discriminatorStart / discriminatorLength: the byte range the parser reads to select a record type.
records[]: each record type with its fixed width (bytes) and ordered positional fields. Offsets are zero-based.
fields[].name: external_id, amount, currency, date, and description map to the transaction. Every other name goes into metadata. Without a currency field, the currency is BRL.
fields[].kind: string, decimal (money/numeric verbatim token, parsed downstream), or date.
requiredFields (optional): field names the variant must declare across its record types.

A successful create returns 201 with the stored template, including its formatKey (for example br/cnab400/acme-cobranca), the discriminator, the full positional layout, and recordWidths.

List and get 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"

The list has no pagination, because layout templates form a bounded operator config.

Update and delete a template

PUT is a full replace, not a sparse patch. The byte-range invariants are whole-layout properties. The replacement runs through the same well-formedness gate the create path enforces. A failing layout rejects with 422, and the stored template stays unchanged.

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"

Delete responds 204. A missing template returns 404.

Response codes

Status	Meaning
`200`	Catalog, template list, get, or update returned
`201`	Template created
`204`	Template soft-deleted
`400`	Structurally malformed field/layout (including a zero-field record)
`404`	Template not found
`409`	Format/variant key already claimed
`422`	Layout failed the well-formedness gate (overrun, overlap, missing-required, mis-marked money), a field has an unknown `kind`, or a required body field is missing
`503`	Format catalog or template store not wired on this deployment

Overview

Guides

Console

MCP Server

Operations

Formats and templates

The format catalog

Layout templates

Create a template

List and get templates

Update and delete a template

Response codes

​The format catalog

​Layout templates

​Create a template

​List and get templates

​Update and delete a template

​Response codes

The format catalog

Layout templates

Create a template

List and get templates

Update and delete a template

Response codes