Sign in

v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB
Ingestion

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

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

Created

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