Clientes

Visão Geral

Clientes são criados automaticamente quando um pedido é realizado. A API permite consultar informações, histórico de compras e estatísticas dos seus clientes.

Clientes são identificados pelo email. Não possuem um ID próprio — se um mesmo email realizar múltiplas compras, todas são associadas ao mesmo cliente.

Endpoints

Método	Endpoint	Descrição
`GET`	`/api/sdk/customers`	Listar clientes
`GET`	`/api/sdk/customers/:email`	Buscar cliente por email

Listar Clientes

GET /api/sdk/customers

Retorna uma lista agregada de clientes, calculada a partir dos pedidos da loja.

Parâmetros de Query

Parâmetro	Tipo	Descrição
`page`	`number`	Página (padrão: 1)
`limit`	`number`	Itens por página (1-100, padrão: 50)
`email`	`string`	Filtrar por email (busca parcial)
`search`	`string`	Busca por email, nome ou telefone
`minOrders`	`number`	Mínimo de pedidos
`minSpent`	`number`	Gasto mínimo total
`hasPhone`	`string`	`true` para filtrar clientes com telefone
`dateFrom`	`string`	Data inicial (ISO 8601)
`dateTo`	`string`	Data final (ISO 8601)
`sortBy`	`string`	`createdAt`, `totalSpent`, `totalOrders`, `email`
`sortOrder`	`string`	`asc` ou `desc` (padrão: `desc`)

Exemplo

curl -X GET "https://api.plasmacheckout.com/api/sdk/customers?limit=20&search=joao" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

const response = await fetch(
  'https://api.plasmacheckout.com/api/sdk/customers?limit=20&search=joao',
  {
    headers: {
      'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
      'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    }
  }
);

const result = await response.json();
console.log(result.data);        // array de clientes
console.log(result.pagination);  // { page, limit, total, totalPages, hasMore }

import requests

response = requests.get(
    'https://api.plasmacheckout.com/api/sdk/customers',
    headers={
        'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
        'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    },
    params={'limit': 20, 'search': 'joao'}
)

data = response.json()
print(data['data'])
print(data['pagination'])

Resposta

{
  "data": [
    {
      "email": "joao@email.com",
      "name": "João Silva",
      "phone": "+5511999999999",
      "stats": {
        "totalOrders": 5,
        "paidOrders": 4,
        "totalSpent": 87400,
        "totalPaid": 69920,
        "averageOrderValue": 17480
      },
      "firstOrderAt": "2024-06-15T10:30:00Z",
      "lastOrderAt": "2025-01-10T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasMore": false
  },
  "filters": {
    "available": {
      "sortBy": ["createdAt", "totalSpent", "totalOrders", "email"],
      "sortOrder": ["asc", "desc"]
    },
    "applied": {
      "search": "joao",
      "sortBy": "createdAt",
      "sortOrder": "desc"
    }
  }
}

Filtros Avançados

# Clientes VIP: mais de 3 pedidos e mais de R$ 500 gastos
curl -X GET "https://api.plasmacheckout.com/api/sdk/customers?minOrders=3&minSpent=50000&sortBy=totalSpent&sortOrder=desc" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

Buscar Cliente por Email

GET /api/sdk/customers/:email

Retorna dados completos do cliente, incluindo estatísticas detalhadas e histórico de pedidos.

Parâmetros de Query

Parâmetro	Tipo	Descrição
`includeOrders`	`string`	`true` (padrão) ou `false` — incluir lista de pedidos
`ordersLimit`	`number`	Máximo de pedidos retornados (1-100, padrão: 20)
`ordersStatus`	`string`	Filtrar pedidos: `pending`, `processing`, `completed`, `cancelled`
`ordersPaymentStatus`	`string`	`pending`, `paid`, `failed`, `refunded`, `partially_refunded`
`ordersFulfillmentStatus`	`string`	`unfulfilled`, `partial`, `fulfilled`

O email na URL deve ser URL-encoded. Ex: joao%40email.com para joao@email.com.

Exemplo

curl -X GET "https://api.plasmacheckout.com/api/sdk/customers/joao%40email.com?ordersLimit=5" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

const email = encodeURIComponent('joao@email.com');

const response = await fetch(
  `https://api.plasmacheckout.com/api/sdk/customers/${email}?ordersLimit=5`,
  {
    headers: {
      'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
      'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx'
    }
  }
);

const { data } = await response.json();
console.log(data.email);     // "joao@email.com"
console.log(data.stats);     // estatísticas completas
console.log(data.orders);    // últimos pedidos

Resposta

{
  "data": {
    "email": "joao@email.com",
    "name": "João Silva",
    "phone": "+5511999999999",
    "addresses": {
      "shipping": {
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "01234-567"
      },
      "billing": null
    },
    "stats": {
      "totalOrders": 5,
      "paidOrders": 4,
      "cancelledOrders": 1,
      "refundedOrders": 0,
      "fulfilledOrders": 3,
      "partiallyFulfilledOrders": 0,
      "totalSpent": 87400,
      "totalPaid": 69920,
      "averageOrderValue": 17480,
      "preferredCurrency": "BRL"
    },
    "firstOrderAt": "2024-06-15T10:30:00Z",
    "lastOrderAt": "2025-01-10T14:20:00Z",
    "orders": [
      {
        "id": "cm5order789xyz",
        "orderNumber": "PLS-2025-X1Y2Z3",
        "status": "completed",
        "paymentStatus": "paid",
        "fulfillmentStatus": "fulfilled",
        "total": 17480,
        "currency": "BRL",
        "itemCount": 2,
        "createdAt": "2025-01-10T14:20:00Z"
      }
    ],
    "ordersPagination": {
      "returned": 5,
      "total": 5,
      "hasMore": false
    }
  },
  "filters": {
    "applied": {
      "includeOrders": true,
      "ordersLimit": 5
    }
  }
}

Filtrando Pedidos do Cliente

# Apenas pedidos pagos e enviados
curl -X GET "https://api.plasmacheckout.com/api/sdk/customers/joao%40email.com?ordersPaymentStatus=paid&ordersFulfillmentStatus=fulfilled" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

# Sem incluir pedidos (apenas dados + stats)
curl -X GET "https://api.plasmacheckout.com/api/sdk/customers/joao%40email.com?includeOrders=false" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx"

Códigos de Erro

Código HTTP	Código	Descrição
`400`	`INVALID_EMAIL`	Formato de email inválido
`400`	`INVALID_STATUS`	Filtro de status inválido
`400`	`INVALID_PAYMENT_STATUS`	Filtro de pagamento inválido
`400`	`INVALID_FULFILLMENT_STATUS`	Filtro de fulfillment inválido
`404`	`NOT_FOUND`	Nenhum pedido encontrado para este email

Exemplo de Erro

{
  "error": "Customer not found",
  "code": "NOT_FOUND"
}

Formatação de Valores

Todos os valores monetários são retornados em centavos (inteiros).

// Exemplo de formatação
const totalSpent = 87400; // centavos

const formatted = new Intl.NumberFormat('pt-BR', {
  style: 'currency',
  currency: 'BRL'
}).format(totalSpent / 100);

console.log(formatted); // R$ 874,00

Segmentação de Clientes

Use os filtros da listagem para criar segmentos personalizados:

lib/customer-segments.js

async function getVipCustomers() {
  // Clientes com mais de 5 pedidos e R$ 1.000+ gastos
  const response = await fetch(
    'https://api.plasmacheckout.com/api/sdk/customers?minOrders=5&minSpent=100000&sortBy=totalSpent&sortOrder=desc',
    {
      headers: {
        'X-PLASMA-Public-Key': process.env.PLASMA_PUBLIC_KEY,
        'X-PLASMA-Secret-Key': process.env.PLASMA_SECRET_KEY
      }
    }
  );

  const { data } = await response.json();
  return data;
}

Proteção de Dados

LGPD: Certifique-se de estar em conformidade com a Lei Geral de Proteção de Dados ao acessar informações de clientes.

Armazene apenas dados necessários
Implemente políticas de retenção
Respeite solicitações de exclusão
Mantenha logs de acesso

On this page