API de Clientes

Gerenciamento de perfis de clientes no Bnex. Permite criar, consultar, atualizar e buscar clientes por diferentes identificadores.

Escopo necessário: bnex:read (consultas) · bnex:write (criação/atualização)

---

Endpoints

Método	Path	Descrição
GET	/v1/customers	Listar clientes
GET	/v1/customers/{id}	Buscar cliente por ID
POST	/v1/customers	Criar cliente
PUT	/v1/customers/{id}	Atualizar cliente
PATCH	/v1/customers/{id}	Atualização parcial

---

GET /v1/customers

Lista clientes com filtros e paginação.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
cursor	string	Não	Cursor de paginação
limit	integer	Não	Itens por página (padrão: 20, máx: 100)
segment_id	string	Não	Filtrar por segmento do Bnex
created_after	string	Não	Filtrar por data de criação (ISO 8601)
search	string	Não	Busca por nome, e-mail ou CPF

Exemplo de requisição

GET /v1/customers?limit=2&segment_id=seg_churn_risk
Authorization: Bearer <token>

Resposta

{
  "data": [
    {
      "id": "cus_01HXYZ123ABC",
      "external_id": "12345",
      "name": "Ana Souza",
      "email": "ana.souza@email.com",
      "cpf": "***.***.***-12",
      "phone": "+55 11 99999-0001",
      "level": "gold",
      "points_balance": 4820,
      "segments": ["seg_churn_risk", "seg_high_value"],
      "created_at": "2025-03-10T09:00:00-03:00",
      "updated_at": "2026-04-28T14:22:00-03:00"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MX0=",
    "has_more": true,
    "total": 1482
  }
}

---

GET /v1/customers/{id}

Retorna o perfil completo de um cliente.

Exemplo de requisição

GET /v1/customers/cus_01HXYZ123ABC
Authorization: Bearer <token>

Resposta

{
  "id": "cus_01HXYZ123ABC",
  "external_id": "12345",
  "name": "Ana Souza",
  "email": "ana.souza@email.com",
  "cpf": "***.***.***-12",
  "phone": "+55 11 99999-0001",
  "birth_date": "1990-07-15",
  "gender": "F",
  "address": {
    "street": "Rua das Flores, 100",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310-100"
  },
  "level": "gold",
  "points_balance": 4820,
  "lifetime_value": 12480.50,
  "segments": ["seg_churn_risk", "seg_high_value"],
  "consent": {
    "marketing_email": true,
    "marketing_sms": false,
    "updated_at": "2026-01-10T10:00:00-03:00"
  },
  "created_at": "2025-03-10T09:00:00-03:00",
  "updated_at": "2026-04-28T14:22:00-03:00"
}

---

POST /v1/customers

Cria um novo cliente no Bnex.

Body

{
  "external_id": "99999",
  "name": "Carlos Lima",
  "email": "carlos.lima@email.com",
  "cpf": "123.456.789-00",
  "phone": "+55 21 98888-0002",
  "birth_date": "1985-11-20",
  "gender": "M",
  "consent": {
    "marketing_email": true,
    "marketing_sms": true
  }
}

Campos obrigatórios

Campo	Tipo	Descrição
name	string	Nome completo
email	string	E-mail único
cpf	string	CPF com ou sem formatação

Resposta 201 Created

{
  "id": "cus_01JNEW456DEF",
  "external_id": "99999",
  "name": "Carlos Lima",
  "email": "carlos.lima@email.com",
  "created_at": "2026-04-30T10:00:00-03:00"
}

Erros comuns

// 409 — E-mail ou CPF já cadastrado
{
  "error": "duplicate_customer",
  "message": "A customer with this email already exists",
  "field": "email"
}

---

Objeto Customer — Referência completa

Campo	Tipo	Descrição
id	string	ID interno Rock Encantech
external_id	string	ID do sistema de origem (opcional)
name	string	Nome completo
email	string	E-mail
cpf	string	CPF (mascarado nas respostas)
phone	string	Telefone no formato E.164
birth_date	string	Data de nascimento (YYYY-MM-DD)
gender	string	M, F ou NB
level	string	Nível no LL Loyalty: bronze, silver, gold, diamond
points_balance	integer	Saldo atual de pontos
lifetime_value	number	Valor total gasto (R$)
segments	array	IDs dos segmentos Bnex
consent	object	Opt-ins de comunicação
created_at	string	Data de criação (ISO 8601)
updated_at	string	Última atualização (ISO 8601)