Sessões e configuração do Customer Portal

O Customer Portal permite que um cliente gerencie suas próprias assinaturas e métodos de pagamento sem precisar entrar em contato com o suporte. Uma sessão começa com um magic link: o cliente solicita um link por e-mail e, então, a etapa de verificação troca o token enviado por e-mail por um cookie de sessão. Estes endpoints cobrem esse handshake, a sessão atual, o payload de bootstrap que a interface carrega primeiro, e a configuração do portal.

Todo o restante do portal — assinaturas, métodos de pagamento, conta — funciona sobre o cookie estabelecido aqui. O portal é white-label, portanto seu branding e as ações permitidas vêm da configuração do portal do Merchant.

A sessão do portal

Retornado pelos endpoints de listagem e consulta desta página.

Endpoints

GET/api/v1/merchants/:merchant_id/portal-config

Branding e comportamento do portal self-service que os seus clientes usam para gerenciar as assinaturas deles. Retorna os padrões quando ainda não houver nada configurado.

Parâmetros de caminho

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/portal-config \
  -H "Cookie: tf_portal_session=…"

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/merchants/:merchant_id/portal-config

Faz upsert da configuração — a primeira chamada a cria, chamadas posteriores substituem os campos enviados.

Parâmetros de caminho

Campos da requisição

Exemplo de requisição

curl -X PUT https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/portal-config \
  -H "Cookie: tf_portal_session=…" \
  -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"
}

POST/api/v1/portal/auth/email-change/confirm

Confirma uma alteração de e-mail por meio do token enviado por e-mail.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/email-change/confirm \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

POST/api/v1/portal/auth/logout

Limpa o cookie de sessão do portal.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/logout \
  -H "Cookie: tf_portal_session=…"

GET/api/v1/portal/auth/me

Obtém a conta da sessão atual do portal.

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/portal/auth/me \
  -H "Cookie: tf_portal_session=…"

Exemplo de resposta — 200

{
  "id": "cpa_123",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "email": "customer@example.com",
  "expires_in": 1800
}

POST/api/v1/portal/auth/request-link

Solicita um e-mail de magic link do portal.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/request-link \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "merchant_id": "mrc_123",
    "email": "customer@example.com"
  }'

POST/api/v1/portal/auth/verify

Verifica um token de magic link; define o cookie de sessão.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/verify \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

Exemplo de resposta — 200

{
  "id": "cpa_123",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "email": "customer@example.com",
  "expires_in": 1800
}

GET/api/v1/portal/bootstrap

Resolve o branding e as flags do Merchant para o portal.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/portal/bootstrap \
  -H "Cookie: tf_portal_session=…" \
  --data-urlencode "merchant_id=mrc_123" \
  --data-urlencode "organization_id=org_123" \
  --data-urlencode "merchant=acme-store"

Exemplo de resposta — 200

{
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "merchant_slug": "acme-store",
  "merchant_name": "Acme Store",
  "branding": {
    "site_title": "Acme Store",
    "favicon": "string",
    "logo_light_mode": "string",
    "logo_dark_mode": "string",
    "theme_primary_color": "#1A73E8",
    "theme_secondary_color": "#0B5394",
    "custom_url": "https://acme.example.com",
    "show_name_with_logo": false
  },
  "config": {
    "allow_cancellation": true,
    "allow_plan_change": true,
    "allow_payment_method_change": true,
    "cancellation_survey": false,
    "custom_cancellation_message": "Operation completed successfully"
  }
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

Relacionados

• Assinaturas do portal
• Métodos de pagamento do portal
• Configuração do portal do Merchant