---
title: "Detalhe do cliente"
description: "GET /v1/customers/{customerId} — detalhe de um cliente do estabelecimento."
method: "GET"
path: "/v1/customers/{customerId}"
url: "https://developer.beefood.com.br/docs/clientes/detalhe"
group: "Clientes"
scope: "customers:read"
lang: "pt"
---
# Detalhe do cliente

`GET /v1/customers/{customerId}`

- Produção: `https://api.beefood.app/v1/customers/{customerId}`
- Sandbox: `https://api-sandbox.beefood.app/v1/customers/{customerId}`

Retorna o detalhe de um cliente.

## Autenticação

Envie o access token no header `Authorization: Bearer <accessToken>`. Escopo necessário: `customers:read`. Limite: 300 requisições a cada 3 minutos.


## Parâmetros de path

- `customerId` *integer* **obrigatório** — ID do cliente. Exemplo: `123456`.





## Exemplos de requisição

### cURL

```bash
curl -X GET "https://api.beefood.app/v1/customers/{customerId}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


## Exemplos de resposta

### 200 OK

```json
{
  "customerId": "123456",
  "customerName": "Mariana Souza",
  "tradeName": "Mariana Souza",
  "personType": "individual",
  "documentNumber": "12345678900",
  "email": "contato@exemplo.com",
  "phone": {
    "number": "11999990000",
    "extension": "+55"
  },
  "observations": "teste",
  "active": true,
  "balance": {
    "cashback": [
      {
        "merchantId": 39202,
        "merchantName": "Restaurante Exemplo",
        "cashback": 0.8,
        "cashbackActive": true
      }
    ],
    "rewardPoints": [
      {
        "merchantId": 39202,
        "merchantName": "Restaurante Exemplo",
        "rewardPoints": 120,
        "rewardPointsActive": true
      }
    ],
    "storeCredit": -0.5
  },
  "addresses": [
    {
      "addressId": 11707136,
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "city": "Sorocaba",
      "state": "SP",
      "postalCode": "18040370",
      "latitude": -23.5015,
      "longitude": -47.4526
    },
    {
      "addressId": 11723846,
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "city": "Sorocaba",
      "state": "SP",
      "latitude": -23.5015,
      "longitude": -47.4526
    }
  ]
}
```


## Campos da resposta

- `customerId` *string* — ID do cliente.

- `customerName` *string* — Nome completo / razão social.

- `documentNumber` *string* — CPF ou CNPJ.

- `phone` *object* — Telefone.

- `birthDate` *string* — Data de nascimento.

- `tradeName` *string* — Nome fantasia.

- `personType` *string* — Pessoa física ou jurídica.
  - *Valores:* `individual`, `company`

- `email` *string* — E-mail.

- `observations` *string* — Observações internas sobre o cliente.

- `active` *boolean* — Indica se o cliente está ativo.

- `indicators` *object* — Indicadores de consumo do cliente.

- `balance.cashback` *array* — Saldos de cashback por cardápio.

- `balance.rewardPoints` *array* — Saldos de pontos por cardápio.

- `balance.storeCredit` *number* — Crédito de restaurante disponível.

- `addresses[]` *array* — Endereços cadastrados do cliente.

- `phone.number` *string* — Número do telefone. Exemplo: `"11999990000"`.

- `phone.extension` *string* — DDI (ex.: +55). Exemplo: `"+55"`.

- `indicators.ordersCount` *number* — Quantidade de pedidos. Exemplo: `12`.

- `indicators.averageTicket` *number* — Ticket médio. Exemplo: `48.5`.

- `indicators.averageRating` *number* — Nota média. Exemplo: `4.7`.

- `indicators.firstOrderDate` *string* — Data do primeiro pedido. Exemplo: `"2024-01-15"`.

- `indicators.origin` *string* — Origem do cliente. Exemplo: `"DIGITAL_MENU"`.
  - *Valores:* `DIGITAL_MENU`, `DIGITAL_MENU_DELIVERY`, `DIGITAL_MENU_LOCAL`, `DELIVERY`, `TABLE`, `OTHER`

- `balance` *object* — Saldos do cliente: cashback e pontos por cardápio e crédito de restaurante.

- `balance.cashback.merchantId` *number* — ID do cardápio. Exemplo: `39202`.

- `balance.cashback.merchantName` *string* — Nome do cardápio. Exemplo: `"Restaurante Exemplo"`.

- `balance.cashback.cashback` *number* — Saldo de cashback. Exemplo: `0.8`.

- `balance.cashback.cashbackActive` *boolean* — Indica se o cashback está ativo. Exemplo: `true`.

- `balance.rewardPoints.merchantId` *number* — ID do cardápio. Exemplo: `39202`.

- `balance.rewardPoints.merchantName` *string* — Nome do cardápio. Exemplo: `"Restaurante Exemplo"`.

- `balance.rewardPoints.rewardPoints` *number* — Saldo de pontos. Exemplo: `120`.

- `balance.rewardPoints.rewardPointsActive` *boolean* — Indica se o programa de pontos está ativo. Exemplo: `true`.

- `addresses[].addressId` *string* — ID do endereço. Exemplo: `445566`.

- `addresses[].street` *string* — Rua.

- `addresses[].number` *string* — Número.

- `addresses[].complement` *string* — Complemento.

- `addresses[].neighborhood` *string* — Bairro.

- `addresses[].city` *string* — Cidade.

- `addresses[].state` *string* — UF.

- `addresses[].postalCode` *string* — CEP, só dígitos.

- `addresses[].latitude` *number* — Latitude.

- `addresses[].longitude` *number* — Longitude.



## Erros

| Status | Mensagem |
| --- | --- |
| 400 | 'id' must be a positive integer |
| 401 | Authentication token is missing |
| 401 | Invalid or expired access token |
| 403 | This credential does not include the customers:read scope |
| 404 | Customer ID 123 not found |
| 500 | Database error when trying to … |


## Vocabulários usados neste endpoint

## Clientes · personType

| Valor | Significado | Uso |
| --- | --- | --- |
| `individual` | Pessoa física | Lista e detalhe de clientes |
| `company` | Pessoa jurídica | Lista e detalhe de clientes |

## Clientes · origin

| Valor | Significado | Uso |
| --- | --- | --- |
| `DIGITAL_MENU` | Cardápio digital | Clientes |
| `DIGITAL_MENU_DELIVERY` | Cardápio digital delivery | Clientes |
| `DIGITAL_MENU_LOCAL` | Cardápio digital presencial | Clientes |
| `DELIVERY` | Delivery | Clientes |
| `TABLE` | Mesa / comanda | Clientes |
| `OTHER` | Outro | Clientes |