> ## 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, un registro sin campos o una columna de dinero mal marcada se rechazan con `422`, y Matcher nunca almacena esa plantilla.

<Note>Regla intocable del dinero: una columna de dinero **debe** declarar `kind: "decimal"`. El control de envío rechaza un campo de dinero que omite o marca mal su tipo. Ese campo nunca llega a la ruta de parseo.</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.
* `fields[].kind`: `string`, `decimal` (token literal de dinero o numérico, parseado más adelante) o `date`.
* `requiredFields`: 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                                                                                         |
| `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, sin campos, dinero mal marcado) |
| `503`  | El catálogo de formatos o el almacén de plantillas no está conectado en este despliegue                                             |