Roteamento do Merchant

Configure as regras de roteamento inteligente de um Merchant a partir do Dashboard — perfis de roteamento, seus nós ordenados, o conector padrão e a reordenação de nós.

Esses endpoints dão suporte à tela de roteamento do Dashboard. Um perfil de roteamento contém uma lista ordenada de nós que decidem qual conector tenta cada cobrança; a ordem também é a cadeia de fallback que alimenta o cascade. Quando nenhum nó corresponde, o conector padrão do perfil assume a cobrança.

Reordenar nós altera o roteamento ao vivo para a próxima transação, portanto é o controle de maior alavancagem — e mais sensível — aqui. Confirme o efeito na linha do tempo de uma transação, que registra o nó que produziu cada tentativa.

Esses endpoints alimentam a interface do Tokeflow Dashboard. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As solicitações também carregam o header x-merchant-id, identificando o Merchant em contexto, e o usuário autenticado deve ser membro com acesso a ele.

O objeto perfil de roteamento

Retornado pelos endpoints de listagem e recuperação desta página.

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/merchant/routing/profiles`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Lista os perfis de roteamento.

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/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). É necessário ser membro do Merchant.

Cria um perfil de roteamento.

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. * = captura-tudo. 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 null.

Exemplo de requisição

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"
  }'

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/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Exclui um perfil de roteamento.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

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). É necessário ser membro do Merchant.

Obtém um perfil de roteamento com regras.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

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

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/merchant/routing/profiles/:id`

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Atualiza um perfil de roteamento.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`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 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. * = captura-tudo. 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 null.

Exemplo de requisição

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"
  }'

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"
}

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

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Obtém a árvore de roteamento do perfil.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Exemplo de requisição

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). É necessário ser membro do Merchant.

Cria uma regra de roteamento.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	—

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`node_type`	string	Sim	Tipo de nó: condition ou action. Um de `condition`, `action`.
`parent_node_id`	string \| null	Não	ID do nó pai. Null 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/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
  }'

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"
}

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

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Exclui uma regra de roteamento.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`ruleId`	string	Sim	—

Exemplo de requisição

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). É necessário ser membro do Merchant.

Atualiza uma regra de roteamento.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`ruleId`	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/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
  }'

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	Significado
`400`	Parâmetros inválidos ou um estado que não permite esta operação.
`401`	Token de sessão do Dashboard ausente, expirado ou inválido.
`403`	Autenticado, mas o usuário autenticado não tem acesso a esta entidade.
`404`	O registro não existe ou não é visível para esta entidade.

Roteamento do Merchant

O objeto perfil de roteamento

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`

Erros

Relacionados

Nesta página

Roteamento do Merchant

O objeto perfil de roteamento

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

Erros

Relacionados

Nesta 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`