Clientes da Organization
Navegue pelos clientes de todos os Merchants da Organization a partir do Dashboard.
Esses endpoints dão à Organization uma visão consolidada dos clientes em todos os seus Merchants: pesquisar, listar e abrir um registro para ver os detalhes.
Os clientes nunca cruzam os limites de um Merchant — a mesma pessoa em dois Merchants é dois registros — portanto, esta visão agrega em vez de mesclar. Use-a para responder a perguntas em nível de toda a Organization; gerencie um cliente na própria tela de clientes do Merchant.
Esses endpoints alimentam a interface do Tokeflow Dashboard no nível da Organization. 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-organization-id, e o usuário autenticado deve ser membro dessa Organization.
Endpoints
GET/api/v1/org/customers
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Lista os clientes da Organization.
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. |
merchant_id | string | Não | Filtra por ID do Merchant |
search | string | Não | Busca por nome, e-mail ou ID do cliente |
start_date | string | Não | Data de início (ISO 8601) |
end_date | string | Não | Data de término (ISO 8601) |
Exemplo de solicitação
curl -G https://api.tokeflow.com/api/v1/org/customers \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "merchant_id=mrc_8a3f12d9" \
--data-urlencode "search=string"GET/api/v1/org/customers/:id
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Obtém um cliente por ID.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Exemplo de solicitação
curl https://api.tokeflow.com/api/v1/org/customers/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3"PATCH/api/v1/org/customers/:id
Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.
Atualiza um cliente.
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | — |
Campos da solicitação
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Não | — |
email | 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 solicitação
curl -X PATCH https://api.tokeflow.com/api/v1/org/customers/obj_1a2b3c4d \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
-H "x-organization-id: org_4b21e7c3" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Store",
"email": "jane@example.com",
"phone": "+5511987654321",
"document_type": "cpf",
"document_number": "12345678909"
}'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. |