> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cliente

> Endpoints para consulta de informações do cliente e seu saldo de pontos

Os endpoints de cliente permitem consultar informações do usuário autenticado, incluindo saldo de pontos, histórico de transações e pontos a expirar.

## Status de Autenticação dos Endpoints

| Endpoint                                  | Status      |
| ----------------------------------------- | ----------- |
| `GET /pub/widget/customer/points`         | Autenticado |
| `GET /pub/widget/customer/info`           | Autenticado |
| `GET /pub/widget/customer/history`        | Autenticado |
| `POST /pub/widget/customer/setbirthday`   | Autenticado |
| `GET /pub/widget/customer/expiringpoints` | Autenticado |

***

## Consultar Saldo de Pontos

Retorna o saldo de pontos do cliente autenticado.

### Requisição

`GET /pub/widget/customer/points`

**Headers**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

### Exemplo

```bash theme={null}
curl -X GET "https://api.bonifiq.com.br/pub/widget/customer/points" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"
```

### Resposta

<ResponseField name="HasError" type="boolean">
  Indica se houve erro na requisição.
</ResponseField>

<ResponseField name="Item" type="object">
  <Expandable title="Propriedades">
    <ResponseField name="PointsBalance" type="integer">
      Saldo atual de pontos do cliente.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "HasError": false,
  "Message": null,
  "Item": {
    "PointsBalance": 1500
  }
}
```

***

## Consultar Informações do Cliente

Retorna informações detalhadas do cliente autenticado, incluindo saldo, tier atual e status de afiliado.

### Requisição

`GET /pub/widget/customer/info`

**Headers**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

### Exemplo

```bash theme={null}
curl -X GET "https://api.bonifiq.com.br/pub/widget/customer/info" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"
```

### Resposta

<ResponseField name="HasError" type="boolean">
  Indica se houve erro na requisição.
</ResponseField>

<ResponseField name="Item" type="object">
  <Expandable title="Propriedades">
    <ResponseField name="PointsBalance" type="integer">
      Saldo atual de pontos do cliente.
    </ResponseField>

    <ResponseField name="PointsText" type="string">
      Texto formatado do saldo de pontos (ex: "1.500 pontos").
    </ResponseField>

    <ResponseField name="Name" type="string">
      Nome do cliente.
    </ResponseField>

    <ResponseField name="CurrentTier" type="object">
      Informações do tier/nível atual do cliente (se houver programa de tiers).
    </ResponseField>

    <ResponseField name="IsAffiliate" type="boolean">
      Indica se o cliente é um afiliado.
    </ResponseField>

    <ResponseField name="LastPointUpdateDate" type="string">
      Data da última atualização de pontos (formato ISO 8601).
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "HasError": false,
  "Message": null,
  "Item": {
    "PointsBalance": 1500,
    "PointsText": "1.500 pontos",
    "Name": "João Silva",
    "CurrentTier": {
      "Id": 1,
      "Name": "Gold",
      "Color": "#FFD700"
    },
    "IsAffiliate": false,
    "LastPointUpdateDate": "2025-02-01T10:30:00Z"
  }
}
```

***

## Consultar Histórico de Pontos

Retorna o histórico de transações de pontos do cliente com paginação.

### Requisição

`GET /pub/widget/customer/history`

**Headers**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Query Parameters**

<ParamField query="page" type="integer" required>
  Número da página (começa em 0 ou 1).
</ParamField>

### Exemplo

```bash theme={null}
curl -X GET "https://api.bonifiq.com.br/pub/widget/customer/history?page=1" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"
```

### Resposta

<ResponseField name="HasError" type="boolean">
  Indica se houve erro na requisição.
</ResponseField>

<ResponseField name="Item" type="object">
  <Expandable title="Propriedades">
    <ResponseField name="Items" type="array">
      Lista de transações de pontos.

      <Expandable title="Item da lista">
        <ResponseField name="Id" type="integer">
          Identificador único da transação.
        </ResponseField>

        <ResponseField name="Type" type="integer">
          Tipo da transação.
        </ResponseField>

        <ResponseField name="Title" type="string">
          Título/descrição da transação.
        </ResponseField>

        <ResponseField name="Points" type="integer">
          Quantidade de pontos (positivo para crédito, negativo para débito).
        </ResponseField>

        <ResponseField name="Value" type="number">
          Valor monetário associado (se aplicável).
        </ResponseField>

        <ResponseField name="Date" type="string">
          Data da transação.
        </ResponseField>

        <ResponseField name="OrderState" type="integer">
          Estado do pedido associado (se aplicável).
        </ResponseField>

        <ResponseField name="CancelledDate" type="string">
          Data de cancelamento (se aplicável).
        </ResponseField>

        <ResponseField name="OriginalId" type="string">
          ID original do pedido na plataforma de e-commerce.
        </ResponseField>

        <ResponseField name="CouponCode" type="string">
          Código do cupom gerado (se aplicável).
        </ResponseField>

        <ResponseField name="HasCouponCode" type="boolean">
          Indica se há cupom associado.
        </ResponseField>

        <ResponseField name="CustomIcon" type="string">
          Ícone customizado para exibição.
        </ResponseField>

        <ResponseField name="IsCanceled" type="boolean">
          Indica se a transação foi cancelada.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="TotalPages" type="integer">
      Total de páginas disponíveis.
    </ResponseField>

    <ResponseField name="TotalItems" type="integer">
      Total de itens.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "HasError": false,
  "Message": null,
  "Item": {
    "Items": [
      {
        "Id": 12345,
        "Type": 1,
        "Title": "Compra #ABC123",
        "Points": 150,
        "Value": 150.00,
        "Date": "2025-02-01T10:30:00Z",
        "OrderState": 2,
        "CancelledDate": null,
        "OriginalId": "ABC123",
        "CouponCode": null,
        "HasCouponCode": false,
        "CustomIcon": null,
        "IsCanceled": false
      },
      {
        "Id": 12344,
        "Type": 2,
        "Title": "Resgate de recompensa",
        "Points": -100,
        "Value": null,
        "Date": "2025-01-28T14:20:00Z",
        "OrderState": null,
        "CancelledDate": null,
        "OriginalId": null,
        "CouponCode": "DESCONTO10",
        "HasCouponCode": true,
        "CustomIcon": null,
        "IsCanceled": false
      }
    ],
    "TotalPages": 5,
    "TotalItems": 47
  }
}
```

***

## Definir Data de Aniversário

Permite ao cliente definir ou atualizar sua data de aniversário para receber benefícios especiais.

### Requisição

`POST /pub/widget/customer/setbirthday`

**Headers**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Query Parameters**

<ParamField query="birthday" type="string" required>
  Data de aniversário no formato `dd/MM` ou `yyyy-MM-dd`.
</ParamField>

### Exemplo

```bash theme={null}
curl -X POST "https://api.bonifiq.com.br/pub/widget/customer/setbirthday?birthday=15/03" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"
```

### Resposta

```json theme={null}
{
  "HasError": false,
  "Message": "Aniversário atualizado com sucesso",
  "Item": null
}
```

<Warning>
  A data de aniversário geralmente só pode ser definida uma vez. Verifique as regras do programa de fidelidade.
</Warning>

***

## Consultar Pontos a Expirar

Retorna a lista de pontos que estão próximos de expirar.

### Requisição

`GET /pub/widget/customer/expiringpoints`

**Headers**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

### Exemplo

```bash theme={null}
curl -X GET "https://api.bonifiq.com.br/pub/widget/customer/expiringpoints" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"
```

### Resposta

<ResponseField name="HasError" type="boolean">
  Indica se houve erro na requisição.
</ResponseField>

<ResponseField name="Item" type="array">
  Lista de lotes de pontos a expirar.

  <Expandable title="Item da lista">
    <ResponseField name="Id" type="integer">
      Identificador do lote de pontos.
    </ResponseField>

    <ResponseField name="Value" type="integer">
      Quantidade de pontos que irão expirar.
    </ResponseField>

    <ResponseField name="Date" type="string">
      Data de expiração.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "Id": 1001,
      "Value": 200,
      "Date": "2025-03-15"
    },
    {
      "Id": 1002,
      "Value": 150,
      "Date": "2025-04-01"
    }
  ]
}
```

<Note>
  Use esta informação para alertar o cliente sobre pontos prestes a expirar e incentivá-lo a utilizá-los.
</Note>