Config sync hacia DSI (propuesta)

Borrador para co-definir con DSI (Canales Digitales). Fire propone este contrato en base a su arquitectura; las rutas y el schema exacto se cierran con DSI. Se acompaña del dry-run que ya produce este mismo payload: GET /api/v1/admin/paybridge/dsi-config-sync/preview.La autenticación es la misma que usan las notificaciones (webhooks) — no se repite aquí.

Fire es la fuente de verdad de la configuración de pagos. Este contrato es del plano de configuración: Fire empuja a DSI la config del merchant de antemano para que la solicitud de pago viaje lean (DSI ya conoce al merchant y solo recibe el storeId, el terminalId, el monto y la referencia). Los atributos usan los nombres de XMART (accountId, vendorId, store, storeId, terminals, terminalId).

Principios

Dos planos, separados. Config (este contrato, async por eventos) vs transacción (la solicitud de pago no cambia).
Dos niveles, como ya lo modela DSI. Config a nivel organización (por cuenta) y tienda (por tienda / terminal — lo que DSI llama “aplicación”), igual que las guías de Pluxee/Amipass.
Idempotente y versionado. Cada scope lleva un version monotónico; reenviar el mismo version no duplica.
active, nunca borrar. Al apagar algo, se envía active: false.
Los canales no viajan. POS/Kiosco/Web/App son ruteo interno de Fire.
Identificadores compartidos. El storeId/terminalId sincronizado es el mismo que luego llega en la solicitud de pago.

Endpoints propuestos

Nivel	Método	Endpoint propuesto	Cuándo lo llama Fire
Organización	`PUT`	`/api/paybridge/v1/config/organizations/{accountId}`	cambia config a nivel marca (cuenta/vendor)
Tienda	`PUT`	`/api/paybridge/v1/config/stores/{storeId}`	cambia disponibilidad o config de tienda; alta/baja de tienda o terminal

{accountId} = UUID de la cuenta en Fire. {storeId} = UUID de la tienda en Fire.

Nivel organización

PUT /api/paybridge/v1/config/organizations/{accountId}
Authorization: Bearer <jwt>
Idempotency-Key: org:{accountId}:{version}

{
  "version": 142,
  "accountId": "acc-uuid",
  "vendorId": "ven-id",
  "providers": [
    { "provider": "pluxee", "config": { "basicAuth": "••••••", "accountNo": "12345678" } },
    { "provider": "deuna",  "config": { "codigo_unico": "987654321" } }
  ]
}

providers[].config es libre por proveedor: Fire manda las claves que el admin cargó a nivel marca. DSI define qué claves espera cada proveedor (ya están en sus guías).

Nivel tienda

PUT /api/paybridge/v1/config/stores/{storeId}
Authorization: Bearer <jwt>
Idempotency-Key: store:{storeId}:{version}

{
  "version": 87,
  "accountId": "acc-uuid",
  "vendorId": "ven-id",
  "store": {
    "storeId": "store-uuid",
    "storeCode": "K000",
    "terminals": [
      { "terminalId": "term-uuid-1", "code": "EC-K000-POS-1", "type": "POS", "active": true },
      { "terminalId": "kiosk-hex-id", "code": "kiosk-lab", "type": "KIOSK", "active": true }
    ]
  },
  "providers": [
    {
      "provider": "pluxee",
      "active": true,
      "config": { "merchantId": "76.543.210-9", "commerceCode": "CC-001", "branchCode": "BR-017" },
      "paymentMethods": [ { "paymentMethod": "DIGITAL", "code": "pluxee", "active": true } ]
    },
    {
      "provider": "deuna",
      "active": true,
      "config": {},
      "paymentMethods": [ { "paymentMethod": "DEUNA-BANCO-PICHINCHA", "code": "deuna_pichincha", "active": true } ]
    }
  ]
}

Semántica

Caso	Qué envía Fire
Se habilita un método en una tienda	`paymentMethods[].active: true` en el store
Se apaga un método	`active: false` (DSI lo marca inactivo, no lo borra)
Alta/baja de tienda o terminal	Fire reenvía el `store` completo actualizado
Cambian credenciales de proveedor (marca)	`PUT organizations/{accountId}` con el nuevo `config`
Reenvío con el mismo `version`	idempotente — DSI no duplica

Respuestas esperadas

200 OK
{ "accountId": "acc-uuid", "version": 142, "appliedAt": "2026-07-20T14:32:10Z" }

Código	Significado
`200`	Config aplicada (o ya estaba en ese `version`)
`400`	Payload inválido
`401`	Token inválido
`409`	`version` menor al ya aplicado — Fire lo ignora
`5xx`	Error de DSI — Fire reintenta con backoff

Mapeo desde las tablas de Fire

Campo del contrato	Origen en Fire
`accountId` / `vendorId`	contexto de la cuenta/vendor
`store.storeId` / `store.storeCode`	`stores.id` / `stores.store_code`
`store.terminals[]`	`ter_terminals` (POS) + devices de kiosco
`providers[].provider` / `paymentMethod`	`definition.dsi.{provider, payment_method}` del método
`active` (proveedor y método)	`enabled` efectivo (marca → tienda) de la matriz de disponibilidad
organización → `config`	campos de config a nivel marca
tienda → `config`	campos de config a nivel tienda

La UI de Fire (matriz de disponibilidad + editor de campos por nivel) es lo que puebla estas filas. El admin nunca escribe el payload a mano.

Descripción general

Tienda

Menú

Producto

Orden

Métodos de pago

Config sync hacia DSI (propuesta)

Principios

Endpoints propuestos

Nivel organización

Nivel tienda

Semántica

Respuestas esperadas

Mapeo desde las tablas de Fire

Relacionado

Configuración por nivel

Métodos soportados por país

​Principios

​Endpoints propuestos

​Nivel organización

​Nivel tienda

​Semántica

​Respuestas esperadas

​Mapeo desde las tablas de Fire

​Relacionado

Configuración por nivel

Métodos soportados por país

Principios

Endpoints propuestos

Nivel organización

Nivel tienda

Semántica

Respuestas esperadas

Mapeo desde las tablas de Fire

Relacionado