> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Formatos y plantillas

> Explora el catálogo de formatos integrados que Matcher puede parsear y registra plantillas de layout de ancho fijo por tenant para archivos específicos de un operador.

Matcher parsea los archivos entrantes contra un catálogo de formatos integrados y, cuando un archivo no encaja en ninguno de ellos, contra las **plantillas de layout** de ancho fijo por tenant que tú defines. Esta guía cubre cómo explorar el catálogo de formatos y cómo administrar las plantillas de layout.

## El catálogo de formatos

***

El catálogo da un inventario de solo lectura de los formatos que el motor de ingesta puede parsear. Es **global primero y estático**: los parsers integrados no llevan tenant, así que cada llamador autenticado ve la misma respuesta. El catálogo usa un árbol `region → family → variant` que corresponde a los ejes del descriptor canónico de formato.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/formats" \
  -H "Authorization: Bearer $TOKEN"
```

Cada variante lleva la clave canónica del registro con su espacio de nombres, la identidad que fija una subida o una declaración de fuente:

```json theme={null}
{
  "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" }
          ]
        }
      ]
    }
  ]
}
```

Las regiones usan el código ISO-3166 alfa-2 (en mayúsculas), o `XX` para formatos neutrales respecto a la región. Incluso una familia con un único layout canónico (por ejemplo `camt`) nombra su layout como el `variant` (`camt053` arriba).

<Note>El catálogo no toma parámetros de ruta, de consulta ni de cuerpo. El tenant no afecta al catálogo integrado.</Note>

## Plantillas de layout

***

Cuando un archivo usa un layout de ancho fijo específico de un operador o de una marca que ningún parser integrado cubre, registra una **plantilla de layout**. Una plantilla ubica un layout posicional bajo los ejes `{region, family, variant}`. La ruta de parseo la resuelve como una fuente de layout aditiva para tu tenant.

Cada envío y cada edición pasan por un **control de buena formación** *antes* del almacenamiento. El desbordamiento, el solapamiento, la ausencia de campos obligatorios o una columna de dinero mal marcada se rechazan con `422`. Un registro sin campos o un `kind` desconocido se rechaza con `400`. Matcher nunca almacena esa plantilla. Matcher no usa una plantilla cuya clave coincide con un formato integrado.

<Note>Regla intocable del dinero: el campo llamado `amount` es la columna de dinero, y **debe** declarar `kind: "decimal"`. El control de envío rechaza un campo `amount` que omite o marca mal su tipo. Matcher lee `amount` como un número con punto decimal explícito y no aplica decimales implícitos: `000000010050` se lee como `10050`.</Note>

### Crear una plantilla

```bash theme={null}
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"]
  }'
```

Valores de los campos:

* `region`: región ISO alfa-2 (en mayúsculas) o `XX`.
* `family`: familia de formato de enumeración cerrada bajo la que se ubica la plantilla.
* `variant`: eje abierto de operador o marca (no debe estar en blanco).
* `discriminatorStart` / `discriminatorLength`: el rango de bytes que el parser lee para elegir un tipo de registro.
* `records[]`: cada tipo de registro con su `width` fijo (bytes) y sus `fields` posicionales ordenados. Los offsets empiezan en cero.
* `fields[].name`: `external_id`, `amount`, `currency`, `date` y `description` se asignan a la transacción. Todos los demás nombres van a los metadatos. Sin un campo `currency`, la moneda es `BRL`.
* `fields[].kind`: `string`, `decimal` (token literal de dinero o numérico, parseado más adelante) o `date`.
* `requiredFields` (opcional): nombres de campo que la variante debe declarar en sus tipos de registro.

Una creación exitosa devuelve `201` con la plantilla almacenada, incluida su `formatKey` (por ejemplo `br/cnab400/acme-cobranca`), el discriminador, el layout posicional completo y `recordWidths`.

### Listar y obtener plantillas

```bash theme={null}
# 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"
```

La lista no tiene paginación, porque las plantillas de layout forman una configuración de operador acotada.

### Actualizar y eliminar una plantilla

`PUT` es un **reemplazo completo**, no un parche parcial. Los invariantes de rango de bytes son propiedades de todo el layout. El reemplazo pasa por el mismo control de buena formación que aplica la ruta de creación. Un layout que falla se rechaza con `422`, y la plantilla almacenada queda sin cambios.

```bash theme={null}
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": [ ... ] }'
```

```bash theme={null}
# 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"
```

La eliminación responde `204`. Una plantilla ausente devuelve `404`. Una colisión de clave de formato con otra plantilla activa devuelve `409`.

## Códigos de respuesta

***

| Estado | Significado |
| - | - |
| `200` | Se devolvió el catálogo, la lista de plantillas, la obtención o la actualización |
| `201` | Plantilla creada |
| `204` | Plantilla eliminada de forma lógica |
| `400` | Campo o layout estructuralmente mal formado (incluido un registro sin campos o un `kind` desconocido) |
| `404` | Plantilla no encontrada |
| `409` | Clave de formato o variante ya reclamada |
| `422` | El layout no pasó el control de buena formación (desbordamiento, solapamiento, obligatorio ausente, dinero mal marcado), o falta un campo obligatorio del cuerpo |
| `503` | El catálogo de formatos o el almacén de plantillas no está conectado en este despliegue |