Configuração do portal do Merchant
Configure o Customer Portal de um Merchant — o branding e as ações self-service que os clientes têm permissão para realizar.
Estes endpoints controlam como o Customer Portal aparece e se comporta para este Merchant: o branding que os clientes veem e quais ações self-service eles podem realizar, como alterar um plano ou atualizar um cartão.
O portal funciona sob a sua marca, portanto sua configuração pertence ao Merchant, e não à Tokeflow. As alterações entram em vigor na próxima sessão do cliente no portal.
Estes endpoints alimentam a Tokeflow Dashboard UI. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, e não de uma chave de API sk_/pk_. As requisições também carregam o cabeçalho x-merchant-id, identificando o Merchant no contexto, e o usuário autenticado deve ser um membro com acesso a ele.
O objeto de configuração do portal
Retornado pelos endpoints de listagem e consulta desta página.
| Field | Type | Description |
|---|---|---|
merchant_id | string | — |
allow_cancellation | boolean | — |
allow_plan_change | boolean | — |
allow_payment_method_change | boolean | — |
cancellation_survey | boolean | — |
custom_cancellation_message | string | null | — |
Endpoints
GET/api/v1/merchant/portal-config
Auth: Sessão do Dashboard (JWT bearer). É necessário ser membro do Merchant.
Obtém a configuração do portal do cliente.
Exemplo de requisição
curl https://api.tokeflow.com/api/v1/merchant/portal-config \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9"Exemplo de resposta — 200
{
"merchant_id": "mrc_123",
"allow_cancellation": true,
"allow_plan_change": true,
"allow_payment_method_change": true,
"cancellation_survey": true,
"custom_cancellation_message": "Operation completed successfully"
}PUT/api/v1/merchant/portal-config
Auth: Sessão do Dashboard (JWT bearer). É necessário ser membro do Merchant.
Atualiza a configuração do portal do cliente.
Campos da requisição
| Field | Type | Required | Description |
|---|---|---|---|
allow_cancellation | boolean | Não | Permite que os clientes cancelem pelo portal. |
allow_plan_change | boolean | Não | Permite que os clientes alterem o plano pelo portal. |
allow_payment_method_change | boolean | Não | Permite que os clientes adicionem um cartão durante o dunning. |
cancellation_survey | boolean | Não | Exibe uma pesquisa de cancelamento. |
custom_cancellation_message | string | Não | Markdown exibido na tela de cancelamento. |
Exemplo de requisição
curl -X PUT https://api.tokeflow.com/api/v1/merchant/portal-config \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-merchant-id: mrc_8a3f12d9" \
-H "Content-Type: application/json" \
-d '{
"allow_cancellation": true,
"allow_plan_change": true,
"allow_payment_method_change": true,
"cancellation_survey": true,
"custom_cancellation_message": "Operation completed successfully"
}'Exemplo de resposta — 200
{
"merchant_id": "mrc_123",
"allow_cancellation": true,
"allow_plan_change": true,
"allow_payment_method_change": true,
"cancellation_survey": true,
"custom_cancellation_message": "Operation completed successfully"
}Erros
Os erros usam o envelope padrão. Os casos mais comuns aqui:
| HTTP | Meaning |
|---|---|
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 logado não tem acesso a esta entidade. |
404 | O registro não existe ou não está visível para esta entidade. |