Formatos y plantillas

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

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.

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:

{
  "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 alpha-2 (en mayúsculas), o XX para formatos neutrales de región. Incluso una familia de layout canónico único (por ejemplo camt) nombra su layout como el variant — camt053 arriba.

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

​

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.

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.

​

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

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

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