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 integrado contiene estas claves de formato:

Familia	Claves de formato
Genérico (neutral respecto a la región)	`xx/delimited/generic` (CSV), `xx/json/generic`, `xx/xml/generic`, `xx/ofx/generic`, `xx/camt/camt053`
CNAB	`br/cnab240/febraban-base`, `br/cnab240/pagamento`, `br/cnab400/febraban-base`
EDI de adquirente	`br/acquirer_edi/cielo-v15`, `br/acquirer_edi/rede`, `br/acquirer_edi/getnet-v10-1`, `br/acquirer_edi/stone-xml`, `br/acquirer_edi/adyen`, `br/acquirer_edi/vero-bknfin1`, `br/acquirer_edi/vero-bknfin2`
CSV de adquirente	`br/acquirer_csv/stone-pix`, `br/acquirer_csv/mercadopago`
Cuentas por cobrar	`br/receivables/tag`

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, una columna de dinero mal marcada o un kind desconocido se rechazan con 422. Un registro sin campos se rechaza con 400. Matcher nunca almacena esa plantilla. Matcher no usa una plantilla cuya clave coincide con un formato integrado.

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.

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

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

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)
`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), un campo tiene un `kind` desconocido, 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

Resumen

Guías

Console

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