Perfiles de enrutamiento
Define cómo Tokeflow enruta cada transacción — los perfiles de enrutamiento, sus nodos de reglas ordenados, el conector predeterminado y el orden de reserva detrás de la cascada.
Un perfil de enrutamiento es el conjunto de reglas que Tokeflow evalúa al decidir qué proveedor conectado debe intentar un cobro. Contiene una lista ordenada de nodos — cada nodo coincide según condiciones como el método de pago, la marca de tarjeta, el país o la moneda, y apunta al conector que debe gestionar las coincidencias. Cuando ningún nodo coincide, el conector predeterminado del perfil realiza el cobro.
El orden es el punto central: los nodos se evalúan de arriba hacia abajo, y su orden también define la cadena de reserva que hace funcionar la cascada. Cuando un intento falla con un rechazo reintentable, Tokeflow pasa al siguiente nodo elegible en lugar de devolver un error. Consulta Cómo funciona Tokeflow para conocer el modelo de orquestación, y Conectores para las conexiones de proveedores a las que apuntan estas reglas.
Reordenar los nodos cambia el enrutamiento en vivo para la próxima transacción. Cambia el orden en una ventana de bajo tráfico y luego confirma el resultado en la línea de tiempo de una transacción — registra qué nodo generó cada intento en applied_routing_rule_id.
El objeto del perfil de enrutamiento
Un perfil de enrutamiento y sus nodos, tal como los devuelven los endpoints de listado y consulta.
| Field | Type | Description |
|---|---|---|
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 | Indica 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/merchants/:merchant_id/routing-profiles
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Un perfil de enrutamiento contiene un árbol de decisión que elige qué conector gestiona un pago, además de un conector predeterminado como respaldo.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
Parámetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Predeterminado 1, mínimo 1. |
limit | number | No | Cantidad de elementos por página. Predeterminado 20, mínimo 1, máximo 100. |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles \
-H "Authorization: Bearer sk_live_mer_…" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"Ejemplo de respuesta — 200
{
"data": [
{
"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"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"total_pages": 3,
"has_next": true,
"has_prev": false
}
}POST/api/v1/merchants/:merchant_id/routing-profiles
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Crea un perfil de enrutamiento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Sí | Nombre del perfil de enrutamiento. |
is_active | boolean | No | Indica si el perfil de enrutamiento está activo. |
payment_method | string | No | Alcance del método de pago. * = comodín. 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 nulo. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles \
-H "Authorization: Bearer sk_live_mer_…" \
-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/merchants/:merchant_id/routing-profiles/:profile_id
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Elimina un perfil de enrutamiento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Ejemplo de solicitud
curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
-H "Authorization: Bearer sk_live_mer_…"Ejemplo de respuesta — 204 No Content
Se devuelve un cuerpo vacío en caso de éxito.
GET/api/v1/merchants/:merchant_id/routing-profiles/:profile_id
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Obtiene un perfil de enrutamiento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
-H "Authorization: Bearer sk_live_mer_…"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/merchants/:merchant_id/routing-profiles/:profile_id
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Actualiza un perfil de enrutamiento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Nombre del perfil de enrutamiento. |
is_active | boolean | No | Indica si el perfil de enrutamiento está activo. |
deactivate_conflicting | boolean | No | Permite tomar el control del perfil que actualmente está 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 sola transacción. Se ignora cuando no hay conflicto. Requiere is_active=true. |
payment_method | string | No | Alcance del método de pago. * = comodín. 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 nulo. |
Ejemplo de solicitud
curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
-H "Authorization: Bearer sk_live_mer_…" \
-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"
}PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/default-connector
Auth: clave de Organization (con merchant_id) o clave de Merchant.
El conector usado cuando ninguna regla de enrutamiento del perfil coincide.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
merchant_connector_id | string | Sí | ID del conector de merchant a establecer como predeterminado del perfil. |
Ejemplo de solicitud
curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/default-connector \
-H "Authorization: Bearer sk_live_mer_…" \
-H "Content-Type: application/json" \
-d '{
"merchant_connector_id": "mc_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
}'GET/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Todos los nodos del árbol de decisión del perfil, en orden de evaluación. Se devuelven en el sobre paginado, pero sin paginar — una sola página contiene todo el árbol.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes \
-H "Authorization: Bearer sk_live_mer_…"Ejemplo de respuesta — 200
{}POST/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Agrega un nodo de condición o de conector al árbol de decisión del perfil.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
node_type | string | Sí | Tipo de nodo: condición o acción. Uno de condition, action. |
parent_node_id | string | null | No | ID del nodo padre. Nulo para nodos raíz. |
branch | string | null | No | Rama: then o else. Requerido cuando se define parent_node_id. Uno de then, else. |
position | number | Sí | Posición entre hermanos (con base 0). |
condition_field | string | No | Campo a evaluar. Requerido 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. Requerido 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, arreglo para in/not_in, float 0-1 para math/random. |
merchant_connector_id | string | No | Conector al que enrutar. Requerido 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 | Indica si el nodo está activo. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes \
-H "Authorization: Bearer sk_live_mer_…" \
-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"
}PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/reorder
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Establece el orden de evaluación de los nodos bajo un mismo padre. Envía la lista completa y ordenada de los ids hermanos de esa rama.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
profile_id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
parent_node_id | string | null | No | ID del nodo padre cuyos hijos se están reordenando. Nulo para nodos de nivel raíz. |
branch | string | null | No | Rama del nodo padre. Nulo para nodos de nivel raíz. Uno de then, else. |
ordered_node_ids | array | Sí | Lista ordenada de los IDs de los nodos hermanos en el orden deseado. |
Ejemplo de solicitud
curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes/reorder \
-H "Authorization: Bearer sk_live_mer_…" \
-H "Content-Type: application/json" \
-d '{
"parent_node_id": "rrn_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a",
"branch": "then",
"ordered_node_ids": [
"rrn_6d7b9a0e1f2c3d4e5f6a7b8c9d0e1f2a"
]
}'DELETE/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Elimina un nodo del árbol de enrutamiento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
node_id | string | Sí | — |
Ejemplo de solicitud
curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes/node_2 \
-H "Authorization: Bearer sk_live_mer_…"Ejemplo de respuesta — 204 No Content
Se devuelve un cuerpo vacío en caso de éxito.
PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id
Auth: clave de Organization (con merchant_id) o clave de Merchant.
Actualiza un nodo del árbol de enrutamiento.
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
merchant_id | string | Sí | — |
node_id | string | Sí | — |
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
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/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes/node_2 \
-H "Authorization: Bearer sk_live_mer_…" \
-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 sobre estándar. Los casos más comunes aquí:
| HTTP | type | Typical cause |
|---|---|---|
400 | validation_error | Campo requerido faltante, u operación que el estado actual no permite. |
401 | authentication_error | Clave de API faltante o inválida. |
403 | authorization_error | La clave carece del alcance requerido. |
404 | not_found_error | El recurso no existe o no pertenece a esta entidad. |
429 | rate_limit_error | Límite de tasa excedido — reintenta con retroceso exponencial. |
Consulta Errores para ver el catálogo completo.