Cuenta del Customer Portal
Permite que un cliente vea y actualice su propio perfil, y consulte su historial de facturación y pedidos en el portal.
Estos endpoints permiten que un cliente autenticado gestione su cuenta: leer y actualizar su perfil, confirmar un cambio de correo electrónico y consultar su historial de facturación y pedidos.
Todo está limitado al cliente propietario de la sesión. Los cambios sensibles, como una actualización de correo electrónico, pasan por un paso de confirmación para comprobar que el cliente controla la nueva dirección.
Estos endpoints dan soporte al Customer Portal — la superficie de autoservicio que usan tus clientes finales, bajo tu marca. Se autentican mediante una cookie de sesión del portal, establecida a través del flujo de magic-link (solicitar un enlace y luego verificar el token), y no mediante una clave de API. Consulta Sesiones y configuración del portal.
El objeto de perfil
Devuelto por los endpoints de listado y consulta de esta página.
| Field | Type | Description |
|---|---|---|
id | string | — |
name | string | null | — |
email | string | — |
phone | string | null | — |
document_type | string | null | — |
document_number | string | null | Enmascarado — solo se muestran los últimos dígitos. |
merchant_name | string | null | — |
created_at | string | (ISO 8601 UTC). |
Endpoints
GET/api/v1/portal/orders
Auth: Customer Portal session (cookie establecida por el flujo de magic-link).
Lista el historial de facturación.
Parámetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
page | number | No | Predeterminado 1, mín. 1. |
limit | number | No | Predeterminado 20, mín. 1, máx. 100. |
date_from | string | No | Fecha ISO — pedidos en o después de |
date_to | string | No | Fecha ISO — pedidos en o antes de |
Ejemplo de solicitud
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"Ejemplo de respuesta — 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 establecida por el flujo de magic-link).
Obtiene el detalle de un pedido (factura).
Parámetros de ruta
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Sí | — |
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/portal/orders/obj_1a2b3c4d \
-H "Cookie: tf_portal_session=…"Ejemplo de respuesta — 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 establecida por el flujo de magic-link).
Obtiene el perfil del cliente.
Ejemplo de solicitud
curl https://api.tokeflow.com/api/v1/portal/profile \
-H "Cookie: tf_portal_session=…"Ejemplo de respuesta — 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 establecida por el flujo de magic-link).
Actualiza nombre / teléfono / documento.
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | — |
phone | string | No | — |
document_type | string | No | Uno de cpf, cnpj, passport, tax_id. |
document_number | string | No | — |
Ejemplo de solicitud
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"
}'Ejemplo de respuesta — 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 establecida por el flujo de magic-link).
Solicita un cambio de correo electrónico (envía una confirmación).
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
new_email | string | Sí | — |
Ejemplo de solicitud
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"
}'Errores
Los errores usan el sobre estándar. Los casos más comunes aquí:
| HTTP | Significado |
|---|---|
400 | Parámetros inválidos o un estado que no permite esta operación. |
401 | Token de sesión del Dashboard ausente, expirado o inválido. |
403 | Autenticado, pero el usuario con sesión iniciada no tiene acceso a esta entidad. |
404 | El registro no existe o no es visible para esta entidad. |