> ## 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 analizar y registra plantillas de layout de ancho fijo por tenant para archivos específicos de cada operador.

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

## El catálogo de formatos

***

El catálogo es el inventario de solo lectura de los formatos que el motor de ingesta puede analizar. Es **global primero y estático**: los analizadores integrados no tienen tenant, así que la respuesta es idéntica para cada llamador autenticado. El catálogo se organiza como un árbol `region → family → variant`, siguiendo los ejes canónicos del descriptor 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 de registro canónica con espacio de nombres — la identidad que fija una carga 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": "", "key": "xx/camt/camt053" }
          ]
        }
      ]
    }
  ]
}
```

Las regiones usan el código ISO-3166 alpha-2 (en mayúsculas), o `XX` para formatos neutrales de región. Una familia de layout canónico único (por ejemplo `camt`) produce una sola entrada con un `variant` vacío.

<Note>El catálogo no toma parámetros de ruta, consulta ni cuerpo — el tenant es irrelevante para el catálogo integrado.</Note>

## Plantillas de layout

***

Cuando un archivo usa un layout de ancho fijo específico de un operador o marca que ningún analizador integrado cubre, registra una **plantilla de layout**. Una plantilla asigna un espacio de nombres a un layout posicional bajo los ejes `{region, family, variant}` y se resuelve mediante la ruta de análisis como una fuente de layout aditiva para tu tenant.

Cada envío y edición pasa por una **verificación de buena formación** *antes* del almacenamiento. Un desbordamiento, un solapamiento, campos obligatorios faltantes, un registro sin campos o una columna de dinero mal marcada rechazan con `422` y la plantilla nunca se almacena.

<Note>Tercer riel del dinero: una columna de dinero **debe** declarar `kind: "decimal"`. Un campo de dinero que omite o marca mal su kind es rechazado por la verificación de envío — nunca llega a la ruta de análisis.</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 alpha-2 (en mayúsculas) o `XX`.
* `family` — familia de formato de enum cerrado bajo la que la plantilla asigna el espacio de nombres.
* `variant` — eje abierto de operador/marca (no debe estar en blanco).
* `discriminatorStart` / `discriminatorLength` — el rango de bytes que el analizador lee para seleccionar un tipo de registro.
* `records[]` — cada tipo de registro con su `width` fijo (bytes) y sus `fields` posicionales ordenados.
* `fields[].kind` — `string`, `decimal` (token de dinero/numérico literal, analizado más adelante) o `date`.
* `requiredFields` — nombres de campos 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 está paginada: las plantillas de layout son 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 la misma verificación de buena formación que aplica la ruta de creación; un layout que falla 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 inexistente devuelve `404`; una colisión de clave de formato con otra plantilla activa devuelve `409`.

## Códigos de respuesta

***

| Estado | Significado                                                                                                                             |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Catálogo, lista de plantillas, obtención o actualización devuelta                                                                       |
| `201`  | Plantilla creada                                                                                                                        |
| `204`  | Plantilla eliminada de forma lógica                                                                                                     |
| `400`  | Campo/layout estructuralmente mal formado                                                                                               |
| `404`  | Plantilla no encontrada                                                                                                                 |
| `409`  | Clave de formato/variante ya reclamada                                                                                                  |
| `422`  | El layout falló la verificación de buena formación (desbordamiento, solapamiento, obligatorio faltante, sin campos, dinero mal marcado) |
| `503`  | El catálogo de formatos o el almacén de plantillas no está conectado en este despliegue                                                 |