Formatos y plantillas

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.

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:

{
  "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).

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

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.

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.

Crear una plantilla

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

# 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.

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": [ ... ] }'

# 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

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Formatos y plantillas

El catálogo de formatos

Plantillas de layout

Crear una plantilla

Listar y obtener plantillas

Actualizar y eliminar una plantilla

Códigos de respuesta

​El catálogo de formatos

​Plantillas de layout

​Crear una plantilla

​Listar y obtener plantillas

​Actualizar y eliminar una plantilla

​Códigos de respuesta

El catálogo de formatos

Plantillas de layout

Crear una plantilla

Listar y obtener plantillas

Actualizar y eliminar una plantilla

Códigos de respuesta