Replace an operator fixed-width layout template

Fully replaces a stored per-tenant fixed-width layout template (records/fields/discriminator/recordWidths/requiredFields) by its id — a PUT full replace, not a sparse patch, since the byte-range invariants are whole-layout properties. The replacement is run through the SAME well-formedness gate the submission path enforces BEFORE storage: overrun, overlap, missing-required, zero-field, or a mis-marked money column (money MUST be kind=decimal) rejects with 422 and the stored template is left unchanged. Returns 404 when no active template matches, 409 when the new format key collides with another active template. Tenant from the JWT; never the body.

PUT /v1/imports/formats/templates/{templateId}

Replace an operator fixed-width layout template

cURL

curl --request PUT \
  --url https://matcher.sandbox.lerian.net/v1/imports/formats/templates/{templateId} \
  --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>"
  ]
}
'

200

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}")

Parámetros de ruta

templateId · string<uuid> · requerido

Layout template ID

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

200

application/json

OK

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"