Conta do Customer Portal
Permita que um cliente visualize e atualize o próprio perfil, e veja seu histórico de cobranças e pedidos no portal.
Esses endpoints permitem que um cliente autenticado gerencie sua conta: ler e atualizar o perfil, confirmar uma alteração de e-mail e navegar pelo histórico de cobranças e pedidos.
Tudo é restrito ao cliente proprietário da sessão. Alterações sensíveis, como uma atualização de e-mail, passam por uma etapa de confirmação para comprovar que o cliente controla o novo endereço.
Esses endpoints alimentam o Customer Portal — a superfície de autoatendimento que seus clientes finais usam, sob a sua marca. Eles são autenticados por um cookie de sessão do portal, estabelecido pelo fluxo de magic-link (solicitar um link e, em seguida, verificar o token), e não por uma chave de API. Consulte Sessões e configuração do portal.
O objeto de perfil
Retornado pelos endpoints de listagem e consulta desta página.
| Field | Type | Description |
|---|---|---|
id | string | — |
name | string | null | — |
email | string | — |
phone | string | null | — |
document_type | string | null | — |
document_number | string | null | Mascarado — apenas os últimos dígitos são exibidos. |
merchant_name | string | null | — |
created_at | string | (ISO 8601 UTC). |
Endpoints
GET/api/v1/portal/orders
Auth: Customer Portal session (cookie definido pelo fluxo de magic-link).
Lista o histórico de cobranças.
Parâmetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | Não | Padrão 1, mín. 1. |
limit | number | Não | Padrão 20, mín. 1, máx. 100. |
date_from | string | Não | Data ISO — pedidos em ou após |
date_to | string | Não | Data ISO — pedidos em ou antes |
Exemplo de requisição
curl -G https://api.tokeflow.com/api/v1/portal/orders \
-H "Cookie: tf_portal_session=…" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "date_from=string" \
--data-urlencode "date_to=string"Exemplo de resposta — 200
{
"data": [
{
"id": "ord_123",
"order_type": "renewal",
"total_amount": 4990,
"currency": "BRL",
"status": "authorized",
"description": "Premium Monthly \u2014 Renewal",
"created_at": "2026-01-15T12:30:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20
}GET/api/v1/portal/orders/:id
Auth: Customer Portal session (cookie definido pelo fluxo de magic-link).
Obtém o detalhe de um pedido (fatura).
Parâmetros de caminho
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sim | — |
Exemplo de requisição
curl https://api.tokeflow.com/api/v1/portal/orders/obj_1a2b3c4d \
-H "Cookie: tf_portal_session=…"Exemplo de resposta — 200
{
"id": "ord_123",
"order_type": "renewal",
"total_amount": 4990,
"currency": "BRL",
"status": "authorized",
"description": "Premium Monthly \u2014 Renewal",
"created_at": "2026-01-15T12:30:00.000Z",
"items": [
{
"product_name": "Premium Plan",
"offer_name": "Premium Monthly",
"quantity": 1,
"unit_amount": 4990,
"total_amount": 4990,
"installments": 1
}
],
"payment_method": "visa \u2022\u2022\u2022\u2022 4242"
}GET/api/v1/portal/profile
Auth: Customer Portal session (cookie definido pelo fluxo de magic-link).
Obtém o perfil do cliente.
Exemplo de requisição
curl https://api.tokeflow.com/api/v1/portal/profile \
-H "Cookie: tf_portal_session=…"Exemplo de resposta — 200
{
"id": "cust_123",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+5511999990000",
"document_type": "cpf",
"document_number": "\u2022\u2022\u2022\u2022\u2022\u2022\u202289",
"merchant_name": "Acme Store",
"created_at": "2026-01-15T12:30:00.000Z"
}PUT/api/v1/portal/profile
Auth: Customer Portal session (cookie definido pelo fluxo de magic-link).
Atualiza nome / telefone / documento.
Campos da requisição
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Não | — |
phone | string | Não | — |
document_type | string | Não | Um dos valores cpf, cnpj, passport, tax_id. |
document_number | string | Não | — |
Exemplo de requisição
curl -X PUT https://api.tokeflow.com/api/v1/portal/profile \
-H "Cookie: tf_portal_session=…" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"phone": "+55 11 99999-0000",
"document_type": "cpf",
"document_number": "12345678909"
}'Exemplo de resposta — 200
{
"id": "cust_123",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+5511999990000",
"document_type": "cpf",
"document_number": "\u2022\u2022\u2022\u2022\u2022\u2022\u202289",
"merchant_name": "Acme Store",
"created_at": "2026-01-15T12:30:00.000Z"
}POST/api/v1/portal/profile/email-change
Auth: Customer Portal session (cookie definido pelo fluxo de magic-link).
Solicita uma alteração de e-mail (envia uma confirmação).
Campos da requisição
| Field | Type | Required | Description |
|---|---|---|---|
new_email | string | Sim | — |
Exemplo de requisição
curl -X POST https://api.tokeflow.com/api/v1/portal/profile/email-change \
-H "Cookie: tf_portal_session=…" \
-H "Content-Type: application/json" \
-d '{
"new_email": "new@example.com"
}'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 conectado não tem acesso a esta entidade. |
404 | O registro não existe ou não está visível para esta entidade. |