Enrutamiento del Merchant

Configura las reglas de enrutamiento inteligente de un Merchant desde el Dashboard — perfiles de enrutamiento, sus nodos ordenados, el conector predeterminado y la reordenación de nodos.

Estos endpoints respaldan la pantalla de enrutamiento del Dashboard. Un perfil de enrutamiento contiene una lista ordenada de nodos que deciden qué conector intenta cada cobro; el orden es también la cadena de fallback que impulsa el cascade. Cuando ningún nodo coincide, el conector predeterminado del perfil asume el cobro.

Reordenar nodos cambia el enrutamiento en vivo para la próxima transacción, por lo que es el control de mayor apalancamiento — y más sensible — aquí. Confirma el efecto en la cronología de una transacción, que registra el nodo que produjo cada intento.

Estos endpoints impulsan la interfaz del Tokeflow Dashboard. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-merchant-id, que identifica al Merchant en contexto, y el usuario que inició sesión debe ser miembro con acceso a él.

El objeto perfil de enrutamiento

Devuelto por los endpoints de listado y recuperación de esta página.

Campo	Tipo	Descripción
`id`	string	ID del perfil de enrutamiento.
`merchant_id`	string	ID del Merchant.
`name`	string	Nombre del perfil de enrutamiento.
`created_at`	string	Marca de tiempo de creación del perfil de enrutamiento. (ISO 8601 UTC).
`updated_at`	string	Marca de tiempo de la última actualización del perfil de enrutamiento. (ISO 8601 UTC).
`is_active`	boolean	Si el perfil de enrutamiento está activo.
`version`	number	Versión del perfil de enrutamiento.
`payment_method`	string	Alcance del método de pago.
`default_merchant_connector_id`	string \| null	ID del conector predeterminado usado cuando ningún nodo de regla coincide.

Endpoints

GET`/api/v1/merchant/routing/profiles`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Lista los perfiles de enrutamiento.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Cantidad de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/merchant/routing/profiles \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

POST`/api/v1/merchant/routing/profiles`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Crea un perfil de enrutamiento.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del perfil de enrutamiento.
`is_active`	boolean	No	Si el perfil de enrutamiento está activo.
`payment_method`	string	No	Alcance del método de pago. * = captura-todo. Uno de `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`, `*`.
`default_merchant_connector_id`	string	Sí	Conector predeterminado usado cuando ningún nodo de regla coincide. No puede ser null.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchant/routing/profiles \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Card Profile",
    "is_active": true,
    "payment_method": "*",
    "default_merchant_connector_id": "mc_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
  }'

Ejemplo de respuesta — 201

{
  "id": "rp_123abc...",
  "merchant_id": "mrc_123",
  "name": "Primary Routing Profile",
  "created_at": "2025-11-20T10:00:00Z",
  "updated_at": "2025-11-21T10:00:00Z",
  "is_active": true,
  "version": 1,
  "payment_method": "*",
  "default_merchant_connector_id": "string"
}

DELETE`/api/v1/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Elimina un perfil de enrutamiento.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

GET`/api/v1/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Obtiene un perfil de enrutamiento con reglas.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Ejemplo de respuesta — 200

{
  "id": "rp_123abc...",
  "merchant_id": "mrc_123",
  "name": "Primary Routing Profile",
  "created_at": "2025-11-20T10:00:00Z",
  "updated_at": "2025-11-21T10:00:00Z",
  "is_active": true,
  "version": 1,
  "payment_method": "*",
  "default_merchant_connector_id": "string"
}

PATCH`/api/v1/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Actualiza un perfil de enrutamiento.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	No	Nombre del perfil de enrutamiento.
`is_active`	boolean	No	Si el perfil de enrutamiento está activo.
`deactivate_conflicting`	boolean	No	Opta por asumir el lugar del perfil actualmente activo para este método de pago. Solo un perfil por (merchant, payment_method) puede estar activo, por lo que activar un segundo normalmente devuelve 409. Envía true para desactivar el perfil existente y activar este en una única transacción. Se ignora cuando no hay conflicto. Requiere is_active=true.
`payment_method`	string	No	Alcance del método de pago. * = captura-todo. Uno de `credit_card`, `debit_card`, `pix`, `boleto`, `wallet`, `*`.
`default_merchant_connector_id`	string	No	Conector predeterminado usado cuando ningún nodo de regla coincide. No puede ser null.

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Card Profile",
    "is_active": true,
    "deactivate_conflicting": false,
    "payment_method": "*",
    "default_merchant_connector_id": "mc_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
  }'

Ejemplo de respuesta — 200

{
  "id": "rp_123abc...",
  "merchant_id": "mrc_123",
  "name": "Primary Routing Profile",
  "created_at": "2025-11-20T10:00:00Z",
  "updated_at": "2025-11-21T10:00:00Z",
  "is_active": true,
  "version": 1,
  "payment_method": "*",
  "default_merchant_connector_id": "string"
}

GET`/api/v1/merchant/routing/profiles/:id/rules`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Obtiene el árbol de enrutamiento del perfil.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d/rules \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

POST`/api/v1/merchant/routing/profiles/:id/rules`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Crea una regla de enrutamiento.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	—

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`node_type`	string	Sí	Tipo de nodo: condition o action. Uno de `condition`, `action`.
`parent_node_id`	string \| null	No	ID del nodo padre. Null para nodos raíz.
`branch`	string \| null	No	Rama: then o else. Obligatorio cuando parent_node_id está definido. Uno de `then`, `else`.
`position`	number	Sí	Posición entre los hermanos (basada en 0).
`condition_field`	string	No	Campo a evaluar. Obligatorio para nodos de condición. Uno de `currency`, `amount`, `card_brand`, `bin_country`, `is_recurring`, `math/random`, `installments`.
`condition_operator`	string	No	Operador de comparación. Obligatorio para nodos de condición. Uno de `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `regex`.
`condition_value`	object	No	Valor de comparación. Escalar para eq/gt/lt, array para in/not_in, float 0-1 para math/random.
`merchant_connector_id`	string	No	Conector al que enrutar. Obligatorio para nodos de acción.
`require_3ds`	string	No	Requisito de 3DS para este nodo de acción. Uno de `never`, `if_supported`, `always`.
`is_active`	boolean	No	Si el nodo está activo.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/merchant/routing/profiles/obj_1a2b3c4d/rules \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "condition",
    "parent_node_id": "string",
    "branch": "then",
    "position": 0,
    "condition_field": "currency",
    "condition_operator": "eq",
    "condition_value": {},
    "merchant_connector_id": "string",
    "require_3ds": "never",
    "is_active": true
  }'

Ejemplo de respuesta — 201

{
  "id": "obj_1a2b3c4d",
  "routing_profile_id": "string",
  "parent_node_id": "string",
  "branch": "string",
  "position": 1,
  "node_type": "standard",
  "condition_field": "string",
  "condition_operator": "string",
  "condition_value": {},
  "merchant_connector_id": "string",
  "connector_name": "Acme Store",
  "require_3ds": "string",
  "is_active": true,
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z"
}

DELETE`/api/v1/merchant/routing/rules/:ruleId`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Elimina una regla de enrutamiento.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`ruleId`	string	Sí	—

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/routing/rules/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

PATCH`/api/v1/merchant/routing/rules/:ruleId`

Merchant

Auth: Dashboard session (JWT bearer). Se requiere membresía del Merchant.

Actualiza una regla de enrutamiento.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`ruleId`	string	Sí	—

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`parent_node_id`	string \| null	No	—
`branch`	string \| null	No	Uno de `then`, `else`.
`position`	number	No	—
`condition_field`	string	No	Uno de `currency`, `amount`, `card_brand`, `bin_country`, `is_recurring`, `math/random`, `installments`.
`condition_operator`	string	No	Uno de `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `regex`.
`condition_value`	object	No	—
`merchant_connector_id`	string	No	—
`require_3ds`	string	No	Uno de `never`, `if_supported`, `always`.
`is_active`	boolean	No	—

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/routing/rules/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_node_id": "string",
    "branch": "then",
    "position": 1,
    "condition_field": "currency",
    "condition_operator": "eq",
    "condition_value": {},
    "merchant_connector_id": "string",
    "require_3ds": "never",
    "is_active": true
  }'

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "routing_profile_id": "string",
  "parent_node_id": "string",
  "branch": "string",
  "position": 1,
  "node_type": "standard",
  "condition_field": "string",
  "condition_operator": "string",
  "condition_value": {},
  "merchant_connector_id": "string",
  "connector_name": "Acme Store",
  "require_3ds": "string",
  "is_active": true,
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z"
}

Errores

Los errores usan el envelope estándar. Los casos más comunes aquí:

HTTP	Significado
`400`	Parámetros inválidos o un estado que no permite esta operación.
`401`	Token de sesión del Dashboard ausente, expirado o inválido.
`403`	Autenticado, pero el usuario que inició sesión no tiene acceso a esta entidad.
`404`	El registro no existe o no es visible para esta entidad.

Enrutamiento del Merchant

El objeto perfil de enrutamiento

Endpoints

GET`/api/v1/merchant/routing/profiles`

POST`/api/v1/merchant/routing/profiles`

DELETE`/api/v1/merchant/routing/profiles/:id`

GET`/api/v1/merchant/routing/profiles/:id`

PATCH`/api/v1/merchant/routing/profiles/:id`

GET`/api/v1/merchant/routing/profiles/:id/rules`

POST`/api/v1/merchant/routing/profiles/:id/rules`

DELETE`/api/v1/merchant/routing/rules/:ruleId`

PATCH`/api/v1/merchant/routing/rules/:ruleId`

Errores

Relacionados

En esta página

Enrutamiento del Merchant

El objeto perfil de enrutamiento

Endpoints

GET/api/v1/merchant/routing/profiles

POST/api/v1/merchant/routing/profiles

DELETE/api/v1/merchant/routing/profiles/:id

GET/api/v1/merchant/routing/profiles/:id

PATCH/api/v1/merchant/routing/profiles/:id

GET/api/v1/merchant/routing/profiles/:id/rules

POST/api/v1/merchant/routing/profiles/:id/rules

DELETE/api/v1/merchant/routing/rules/:ruleId

PATCH/api/v1/merchant/routing/rules/:ruleId

Errores

Relacionados

En esta página

GET`/api/v1/merchant/routing/profiles`

POST`/api/v1/merchant/routing/profiles`

DELETE`/api/v1/merchant/routing/profiles/:id`

GET`/api/v1/merchant/routing/profiles/:id`

PATCH`/api/v1/merchant/routing/profiles/:id`

GET`/api/v1/merchant/routing/profiles/:id/rules`

POST`/api/v1/merchant/routing/profiles/:id/rules`

DELETE`/api/v1/merchant/routing/rules/:ruleId`

PATCH`/api/v1/merchant/routing/rules/:ruleId`