Submit an operator fixed-width layout template

Validates and stores a per-tenant fixed-width layout template (region/family/variant-namespaced). The layout is run through the well-formedness gate BEFORE storage: overrun, overlap, missing-required, zero-field, or a mis-marked money column (money MUST be kind=decimal) rejects with 422 and the template is never stored. An approved template is resolved by the parse path as an additive layout source. Tenant from the JWT; never the body.

POST /v1/imports/formats/templates

Submit an operator fixed-width layout template

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/imports/formats/templates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "discriminatorLength": 1,
  "discriminatorStart": 0,
  "family": "cnab400",
  "records": [
    {
      "fields": [
        {
          "kind": "decimal",
          "length": 12,
          "name": "amount",
          "startByte": 11
        }
      ],
      "recordType": "1",
      "width": 33
    }
  ],
  "region": "BR",
  "variant": "acme-cobranca",
  "requiredFields": [
    "<string>"
  ]
}
'

201

Example

{
  "createdAt": "2025-01-15T10:30:00Z",
  "discriminator": {
    "length": 1,
    "startByte": 0
  },
  "formatKey": "br/cnab400/acme-cobranca",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "recordTypeCount": 1,
  "recordWidths": {},
  "records": [
    {
      "fields": [
        {
          "kind": "decimal",
          "length": 12,
          "name": "amount",
          "startByte": 11
        }
      ],
      "recordType": "1",
      "width": 33
    }
  ],
  "requiredFields": [
    "<string>"
  ],
  "variantKey": "acme-cobranca"
}

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Cuerpo

application/json

discriminatorLength · integer<int64> · requerido

Discriminator width in bytes

Rango requerido: x >= 1

Ejemplo:

1

discriminatorStart · integer<int64> · requerido

Zero-based byte offset of the record-type discriminator

Rango requerido: x >= 0

Ejemplo:

0

family · string · requerido

Format family the template namespaces under

Minimum string length: 1

Ejemplo:

"cnab400"

records · object[] | null · requerido

Record types declared by the layout

Minimum array length: 1

Show child attributes

region · string · requerido

ISO alpha-2 region (uppercased) or XX

Minimum string length: 1

Ejemplo:

"BR"

variant · string · requerido

Operator/brand variant axis

Minimum string length: 1

Ejemplo:

"acme-cobranca"

requiredFields · string[] | null

Field names the variant must declare

Respuesta

201

application/json

Created

createdAt · string<date-time> · requerido

Creation timestamp (RFC 3339, UTC)

Ejemplo:

"2025-01-15T10:30:00Z"

discriminator · object · requerido

Record-type discriminator byte range the parser reads to select a record type

Show child attributes

formatKey · string · requerido

Canonical format descriptor key (region/family/variant) the template registers under

Ejemplo:

"br/cnab400/acme-cobranca"

id · string<uuid> · requerido

Template identifier

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

recordTypeCount · integer<int64> · requerido

Number of record types the layout declares

Ejemplo:

1

recordWidths · object · requerido

Per-record-type fixed width in bytes, keyed by record type

Show child attributes

records · object[] | null · requerido

Record types the layout declares, each with its fixed width and ordered byte-range fields, sorted by record type

Show child attributes

requiredFields · string[] | null · requerido

Field names the variant must declare across its record types

variantKey · string · requerido

In-file variant key the layout is keyed by

Ejemplo:

"acme-cobranca"