Ir para o conteúdo

Identificar Cliente

Confirma se o cliente existe na base do varejista e retorna dados cadastrais, classificação e código de preço diferenciado. É a primeira operação do fluxo de PDV, chamada ao informar o CPF/CNPJ no início da compra.

Item Valor
URL POST /api/v1/tenants/{tenantId}/customers/identify
Método POST
Autenticação Basic Auth
Content-Type application/json

Request

{
  "sessionId": "abc-123",
  "protocol": "ROCK",
  "customer": {
    "id": "100.980.750-12",
    "type": "CPF",
    "phone": "11987654321"
  },
  "store": {
    "id": "001",
    "posId": "PDV-01",
    "employeeId": "OP-042"
  }
}

Campos

Campo Tipo Obrigatório Descrição
sessionId string Sim Identificador único da sessão do PDV
protocol string Não Protocolo (usar ROCK)
customer object Sim Dados do cliente
customer.id string (máx 18) Sim CPF ou CNPJ (com ou sem formatação)
customer.type string (máx 10) Sim CPF ou CNPJ
customer.phone string Não Telefone do cliente
store object Não Dados da loja
store.id string Não Identificador da loja
store.posId string Não Identificador do PDV
store.employeeId string Não Identificador do operador

Response 200 OK

Cliente identificado:

{
  "sessionId": "abc-123",
  "customer": {
    "id": "10098075012",
    "type": "CPF",
    "externalCode": "EXT-001",
    "firstName": "João",
    "lastName": "Silva",
    "phone": "11987654321",
    "email": "joao@email.com",
    "status": "COMPLETE",
    "classification": { "code": 1, "description": "Gold" },
    "hasCredit": true
  },
  "priceCode": 2
}

Campos do response

Campo Tipo Descrição
sessionId string Ecoado do request
customer.id string CPF/CNPJ sanitizado (apenas dígitos/alfanumérico)
customer.type string CPF ou CNPJ
customer.externalCode string Código externo do cliente no varejista
customer.firstName / customer.lastName string Nome do cliente
customer.phone / customer.email string Contatos do cliente
customer.status string PRE_REGISTER, INCOMPLETE, COMPLETE ou NOT_FOUND
customer.classification object Classificação do cliente (code + description). Só aparece se houver classificação vinculada
customer.hasCredit boolean Indica crédito pré-aprovado. Pode ser omitido quando a feature está desabilitada
priceCode integer Código de preço diferenciado. 0 quando não há campanha/elegibilidade aplicável

Campos nulos são omitidos

Campos com valor null não aparecem no JSON de resposta. Trate a ausência do campo como valor não informado.

Cliente não encontrado retorna 200, não 404

Quando o cliente não existe (e o pré-registro está desabilitado), a resposta é 200 OK com customer.status = "NOT_FOUND". Não trate esse caso como erro HTTP.

Status codes

HTTP Cenário
200 Cliente identificado (ou não encontrado, com status = NOT_FOUND)
400 Erro de validação (campos obrigatórios, formato, documento inválido, tenantId não-UUID)
401 Credenciais inválidas
404 Tenant não encontrado ou inativo
500 Erro interno inesperado

Detalhes do formato de erro em Tratamento de Erros.

Exemplo — curl

curl -X POST "https://<BASE_URL>/api/v1/tenants/<TENANT_ID>/customers/identify" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "sessionId": "abc-123", "protocol": "ROCK", "customer": { "id": "10098075012", "type": "CPF" } }'

Referências