Clientes

Um Cliente é o registro canônico do comprador para um único Merchant. Ele armazena a identidade do comprador (e-mail, nome, telefone, documento fiscal) e um endereço de cobrança, e ancora as transações, os pedidos e as assinaturas do comprador em um único registro.

Os clientes são únicos por e-mail por Merchant. A criação de um cliente é idempotente por e-mail: se já existir um cliente com o mesmo e-mail para o Merchant, o Tokeflow retorna o registro existente em vez de criar um duplicado. Isso torna a criação de clientes segura para repetir a partir de fluxos de checkout e de servidor para servidor.

O objeto cliente

Autenticação e escopos

Todos os endpoints de clientes exigem uma chave secreta de Merchant (sk_live_mer_…). O Merchant é inferido a partir da chave, então você nunca precisa passar um merchant_id. Use o escopo customers:read para operações de leitura e customers:write para criação/atualização.

Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx

POST/api/v1/customers

Cria um cliente para o Merchant resolvido a partir da chave de API. Idempotente por e-mail: se já existir um cliente com o mesmo e-mail, o registro existente é retornado com HTTP 200; um novo cliente retorna HTTP 201.

Parâmetros do corpo

Objeto billing_address

Requisição

curl -X POST https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1d8c2a-9b07-4f3e-9a1c-7e2b6d0c5a11" \
  -d '{
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "phone": "+5511999990000",
    "document_type": "cpf",
    "document_number": "123.456.789-00",
    "billing_address": {
      "line_1": "Av Paulista, 1000",
      "line_2": "Apto 42",
      "zip_code": "01310-100",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    },
    "metadata": { "source": "checkout_web" }
  }'

Resposta 201 Created

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_9f8e7d6c5b",
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Quando o e-mail já existe, o mesmo corpo é retornado com status 200 OK em vez de 201.

GET/api/v1/customers

Lista os clientes do Merchant, do mais recente para o mais antigo. Suporta um filtro email e paginação.

Parâmetros de consulta

Requisição

curl -X GET "https://api.tokeflow.com/api/v1/customers?page=1&limit=20&email=joao@example.com" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx"

Resposta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "cust_a1b2c3d4e5",
      "merchant_id": "mrc_9f8e7d6c5b",
      "email": "joao@example.com",
      "name": "Joao da Silva",
      "phone": "+5511999990000",
      "document_type": "cpf",
      "metadata": { "source": "checkout_web" },
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET/api/v1/customers/:customerId

Recupera um único cliente pelo ID.

Parâmetros de caminho

Requisição

curl -X GET https://api.tokeflow.com/api/v1/customers/cust_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx"

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_9f8e7d6c5b",
    "email": "joao@example.com",
    "name": "Joao da Silva",
    "phone": "+5511999990000",
    "document_type": "cpf",
    "metadata": { "source": "checkout_web" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Resposta 404 Not Found

{
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Customer with ID \"cust_a1b2c3d4e5\" not found",
    "details": {},
    "request_id": "req_8f3c1a2b4d",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

PATCH/api/v1/customers/:customerId

Atualiza um cliente. Todos os campos do corpo são opcionais; apenas os campos enviados são alterados. Alterar o email para um já usado por outro cliente do Merchant retorna 409 Conflict.

Parâmetros de caminho

Parâmetros do corpo

Requisição

curl -X PATCH https://api.tokeflow.com/api/v1/customers/cust_a1b2c3d4e5 \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Joao P. da Silva",
    "phone": "+5511988887777",
    "metadata": { "source": "checkout_web", "tier": "gold" }
  }'

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3d4e5",
    "merchant_id": "mrc_9f8e7d6c5b",
    "email": "joao@example.com",
    "name": "Joao P. da Silva",
    "phone": "+5511988887777",
    "document_type": "cpf",
    "metadata": { "source": "checkout_web", "tier": "gold" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T13:05:00.000Z"
  },
  "request_id": "req_8f3c1a2b4d",
  "timestamp": "2026-01-15T13:05:00.000Z"
}

Resposta 409 Conflict

Retornado quando o novo email já pertence a outro cliente do Merchant. O ID do cliente conflitante é incluído em details.

{
  "error": {
    "type": "conflict_error",
    "code": "CUSTOMER_EMAIL_EXISTS",
    "message": "A customer with this email already exists for this merchant",
    "details": { "existing_customer_id": "cust_f6e5d4c3b2" },
    "request_id": "req_8f3c1a2b4d",
    "timestamp": "2026-01-15T13:05:00.000Z"
  }
}

DELETE/api/v1/customers/:customerId

Exclui permanentemente um cliente sem histórico. Um cliente com qualquer assinatura, pedido, transação, método de pagamento salvo ou registro em provedor de pagamento é recusado com 409, porque clientes com atividade são mantidos para relatórios e reconciliação. Espere que a recusa seja o resultado comum: isso existe para um cliente criado por engano — um erro de digitação, um duplicado, dados de teste. O e-mail fica disponível para a criação de um novo cliente.

Parâmetros de caminho

Exemplo de requisição

curl -X DELETE https://api.tokeflow.com/api/v1/customers/cust_2f9a71d4 \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 204 No Content

Um corpo vazio é retornado em caso de sucesso.

Erros

Os endpoints de clientes usam o envelope de erro padrão do Tokeflow. Casos comuns:

Relacionados

• Transações — cobrar um cliente.
• Pedidos — agrupar as compras de um cliente.
• Assinaturas — cobrança recorrente para um cliente.
• Autenticação — chaves, escopos e cabeçalhos.