Perfis de roteamento
Defina como o Tokeflow roteia cada transação — perfis de roteamento, seus nós de regra ordenados, o conector padrão e a ordem de fallback por trás do cascade.
Um perfil de roteamento é o conjunto de regras que o Tokeflow avalia ao decidir qual provedor conectado deve tentar uma cobrança. Ele contém uma lista ordenada de nós — cada nó verifica condições como método de pagamento, bandeira do cartão, país ou moeda, e aponta para o conector que deve tratar as correspondências. Quando nenhum nó corresponde, o conector padrão do perfil assume a cobrança.
A ordem é o ponto central: os nós são avaliados de cima para baixo, e sua ordem também define a cadeia de fallback que faz o cascade funcionar. Quando uma tentativa falha com uma recusa passível de nova tentativa, o Tokeflow passa para o próximo nó elegível em vez de retornar uma falha. Veja Como o Tokeflow funciona para o modelo de orquestração, e Conectores para as conexões de provedor às quais essas regras apontam.
Reordenar nós altera o roteamento em produção para a próxima transação. Altere a ordem em uma janela de baixo tráfego e, em seguida, confirme o resultado na linha do tempo de uma transação — ela registra qual nó produziu cada tentativa em applied_routing_rule_id.
O objeto perfil de roteamento
Um perfil de roteamento e seus nós, conforme retornado pelos endpoints de listagem e recuperação.
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID do perfil de roteamento. |
merchant_id | string | ID do Merchant. |
name | string | Nome do perfil de roteamento. |
created_at | string | Timestamp de criação do perfil de roteamento (ISO 8601 UTC). |
updated_at | string | Timestamp da última atualização do perfil de roteamento (ISO 8601 UTC). |
is_active | boolean | Se o perfil de roteamento está ativo. |
version | number | Versão do perfil de roteamento. |
payment_method | string | Escopo do método de pagamento. |
default_merchant_connector_id | string | null | ID do conector padrão usado quando nenhum nó de regra corresponde. |
Endpoints
GET/api/v1/merchants/:merchant_id/routing-profiles
Auth: Chave de Organization (com merchant_id) ou chave de Merchant.
Um perfil de roteamento contém uma árvore de decisão que escolhe qual conector trata um pagamento, além de um conector padrão para recorrer.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
Parâmetros de consulta
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | number | Não | Número da página (indexado a partir de 1). Padrão 1, mín. 1. |
limit | number | Não | Número de itens por página. Padrão 20, mín. 1, máx. 100. |
Exemplo de requisição
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"Exemplo de resposta — 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: Chave de Organization (com merchant_id) ou chave de Merchant.
Cria um perfil de roteamento.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome do perfil de roteamento. |
is_active | boolean | Não | Se o perfil de roteamento está ativo. |
payment_method | string | Não | Escopo do método de pagamento. * = abrangente. Um de credit_card, debit_card, pix, boleto, wallet, *. |
default_merchant_connector_id | string | Sim | Conector padrão usado quando nenhum nó de regra corresponde. Não pode ser nulo. |
Exemplo de requisição
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"
}'Exemplo de resposta — 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: Chave de Organization (com merchant_id) ou chave de Merchant.
Exclui um perfil de roteamento.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Exemplo de requisição
curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
-H "Authorization: Bearer sk_live_mer_…"Exemplo de resposta — 204 No Content
Um corpo vazio é retornado em caso de sucesso.
GET/api/v1/merchants/:merchant_id/routing-profiles/:profile_id
Auth: Chave de Organization (com merchant_id) ou chave de Merchant.
Recupera um perfil de roteamento.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Exemplo de requisição
curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c \
-H "Authorization: Bearer sk_live_mer_…"Exemplo de resposta — 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: Chave de Organization (com merchant_id) ou chave de Merchant.
Atualiza um perfil de roteamento.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Não | Nome do perfil de roteamento. |
is_active | boolean | Não | Se o perfil de roteamento está ativo. |
deactivate_conflicting | boolean | Não | Opte por assumir o lugar do perfil que está atualmente ativo para este método de pagamento. Apenas um perfil por (merchant, payment_method) pode estar ativo, então ativar um segundo normalmente retorna 409. Envie true para desativar o perfil existente e ativar este em uma única transação. Ignorado quando não há conflito. Requer is_active=true. |
payment_method | string | Não | Escopo do método de pagamento. * = abrangente. Um de credit_card, debit_card, pix, boleto, wallet, *. |
default_merchant_connector_id | string | Não | Conector padrão usado quando nenhum nó de regra corresponde. Não pode ser nulo. |
Exemplo de requisição
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"
}'Exemplo de resposta — 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: Chave de Organization (com merchant_id) ou chave de Merchant.
O conector usado quando nenhuma regra de roteamento do perfil corresponde.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_connector_id | string | Sim | ID do merchant connector a definir como padrão do perfil. |
Exemplo de requisição
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: Chave de Organization (com merchant_id) ou chave de Merchant.
Todos os nós da árvore de decisão do perfil, na ordem de avaliação. Retornados no envelope paginado, mas sem paginação — uma página contém a árvore inteira.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Exemplo de requisição
curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/routing-profiles/rpf_5f6a7b8c/nodes \
-H "Authorization: Bearer sk_live_mer_…"Exemplo de resposta — 200
{}POST/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes
Auth: Chave de Organization (com merchant_id) ou chave de Merchant.
Adiciona um nó de condição ou conector à árvore de decisão do perfil.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
node_type | string | Sim | Tipo do nó: condição ou ação. Um de condition, action. |
parent_node_id | string | null | Não | ID do nó pai. Nulo para nós raiz. |
branch | string | null | Não | Ramo: then ou else. Obrigatório quando parent_node_id está definido. Um de then, else. |
position | number | Sim | Posição entre os irmãos (baseada em 0). |
condition_field | string | Não | Campo a avaliar. Obrigatório para nós de condição. Um de currency, amount, card_brand, bin_country, is_recurring, math/random, installments. |
condition_operator | string | Não | Operador de comparação. Obrigatório para nós de condição. Um de eq, neq, gt, gte, lt, lte, in, not_in, regex. |
condition_value | object | Não | Valor de comparação. Escalar para eq/gt/lt, array para in/not_in, float 0-1 para math/random. |
merchant_connector_id | string | Não | Conector para o qual rotear. Obrigatório para nós de ação. |
require_3ds | string | Não | Requisito de 3DS para este nó de ação. Um de never, if_supported, always. |
is_active | boolean | Não | Se o nó está ativo. |
Exemplo de requisição
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
}'Exemplo de resposta — 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: Chave de Organization (com merchant_id) ou chave de Merchant.
Define a ordem de avaliação dos nós sob um mesmo pai. Envie a lista ordenada completa dos ids irmãos daquele ramo.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
profile_id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
parent_node_id | string | null | Não | ID do nó pai cujos filhos estão sendo reordenados. Nulo para nós de nível raiz. |
branch | string | null | Não | Ramo do nó pai. Nulo para nós de nível raiz. Um de then, else. |
ordered_node_ids | array | Sim | Lista ordenada dos IDs dos nós irmãos na ordem desejada. |
Exemplo de requisição
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: Chave de Organization (com merchant_id) ou chave de Merchant.
Exclui um nó da árvore de roteamento.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
node_id | string | Sim | — |
Exemplo de requisição
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_…"Exemplo de resposta — 204 No Content
Um corpo vazio é retornado em caso de sucesso.
PATCH/api/v1/merchants/:merchant_id/routing-profiles/:profile_id/nodes/:node_id
Auth: Chave de Organization (com merchant_id) ou chave de Merchant.
Atualiza um nó da árvore de roteamento.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
merchant_id | string | Sim | — |
node_id | string | Sim | — |
Campos da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
parent_node_id | string | null | Não | — |
branch | string | null | Não | Um de then, else. |
position | number | Não | — |
condition_field | string | Não | Um de currency, amount, card_brand, bin_country, is_recurring, math/random, installments. |
condition_operator | string | Não | Um de eq, neq, gt, gte, lt, lte, in, not_in, regex. |
condition_value | object | Não | — |
merchant_connector_id | string | Não | — |
require_3ds | string | Não | Um de never, if_supported, always. |
is_active | boolean | Não | — |
Exemplo de requisição
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
}'Exemplo de resposta — 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"
}Erros
Os erros usam o envelope padrão. Os casos mais comuns aqui:
| HTTP | type | Causa típica |
|---|---|---|
400 | validation_error | Campo obrigatório ausente, ou uma operação que o estado atual não permite. |
401 | authentication_error | Chave de API ausente ou inválida. |
403 | authorization_error | A chave não possui o escopo necessário. |
404 | not_found_error | O recurso não existe ou não pertence a esta entidade. |
429 | rate_limit_error | Limite de taxa excedido — recue exponencialmente. |
Veja Erros para o catálogo completo.