Sign in

v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB
Ingestion

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}

Path parameters

templateIdstring uuid required

Layout template ID

Layout template ID

Request body

discriminatorLengthinteger required

Discriminator width in bytes

discriminatorStartinteger required

Zero-based byte offset of the record-type discriminator

familystring required

Format family the template namespaces under

regionstring required

ISO alpha-2 region (uppercased) or XX

requiredFieldsstring[] nullable

Field names the variant must declare

variantstring required

Operator/brand variant axis

Example request

{
  "discriminatorLength": 1,
  "family": "cnab400",
  "records": [
    {
      "fields": [
        {
          "kind": "decimal",
          "length": 12,
          "name": "amount",
          "startByte": 11
        }
      ],
      "recordType": "1",
      "width": 33
    }
  ],
  "region": "BR",
  "variant": "acme-cobranca"
}

Response

OK

createdAtstring date-time required

Creation timestamp (RFC 3339, UTC)

formatKeystring required

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

idstring uuid required

Template identifier

recordTypeCountinteger required

Number of record types the layout declares

recordWidthsobject required

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

requiredFieldsstring[] nullable required

Field names the variant must declare across its record types

variantKeystring required

In-file variant key the layout is keyed by

Example response

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