Cliente

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Exemplo

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

boolean

Indica se houve erro na requisição.

object

Show Propriedades

integer

Saldo atual de pontos do cliente.

{
  "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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Exemplo

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

boolean

Indica se houve erro na requisição.

object

Show Propriedades

integer

Saldo atual de pontos do cliente.

string

Texto formatado do saldo de pontos (ex: “1.500 pontos”).

string

Nome do cliente.

object

Informações do tier/nível atual do cliente (se houver programa de tiers).

boolean

Indica se o cliente é um afiliado.

string

Data da última atualização de pontos (formato ISO 8601).

{
  "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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Query Parameters

integer

required

Número da página (começa em 0 ou 1).

Exemplo

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

boolean

Indica se houve erro na requisição.

object

Show Propriedades

array

Lista de transações de pontos.

Show Item da lista

integer

Identificador único da transação.

integer

Tipo da transação.

string

Título/descrição da transação.

integer

Quantidade de pontos (positivo para crédito, negativo para débito).

number

Valor monetário associado (se aplicável).

string

Data da transação.

integer

Estado do pedido associado (se aplicável).

string

Data de cancelamento (se aplicável).

string

ID original do pedido na plataforma de e-commerce.

string

Código do cupom gerado (se aplicável).

boolean

Indica se há cupom associado.

string

Ícone customizado para exibição.

boolean

Indica se a transação foi cancelada.

integer

Total de páginas disponíveis.

integer

Total de itens.

{
  "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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Query Parameters

string

required

Data de aniversário no formato dd/MM ou yyyy-MM-dd.

Exemplo

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

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

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

Consultar Pontos a Expirar

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

Requisição

GET /pub/widget/customer/expiringpoints Headers

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Exemplo

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

boolean

Indica se houve erro na requisição.

array

Lista de lotes de pontos a expirar.

Show Item da lista

integer

Identificador do lote de pontos.

integer

Quantidade de pontos que irão expirar.

string

Data de expiração.

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

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

Introdução

Autenticação

Recompensas

Gamificação

Outros

Cliente

Status de Autenticação dos Endpoints

Consultar Saldo de Pontos

Requisição

Exemplo

Resposta

Consultar Informações do Cliente

Requisição

Exemplo

Resposta

Consultar Histórico de Pontos

Requisição

Exemplo

Resposta

Definir Data de Aniversário

Requisição

Exemplo

Resposta

Consultar Pontos a Expirar

Requisição

Exemplo

Resposta

​Status de Autenticação dos Endpoints

​Consultar Saldo de Pontos

​Requisição

​Exemplo

​Resposta

​Consultar Informações do Cliente

​Requisição

​Exemplo

​Resposta

​Consultar Histórico de Pontos

​Requisição

​Exemplo

​Resposta

​Definir Data de Aniversário

​Requisição

​Exemplo

​Resposta

​Consultar Pontos a Expirar

​Requisição

​Exemplo

​Resposta

Status de Autenticação dos Endpoints

Consultar Saldo de Pontos

Requisição

Exemplo

Resposta

Consultar Informações do Cliente

Requisição

Exemplo

Resposta

Consultar Histórico de Pontos

Requisição

Exemplo

Resposta

Definir Data de Aniversário

Requisição

Exemplo

Resposta

Consultar Pontos a Expirar

Requisição

Exemplo

Resposta