Cupons

Endpoints para gestão de cupons de desconto e benefícios.

Listar Cupons

GET /api/coupons

Retorna uma lista paginada de cupons com opções de filtro. Os resultados são limitados a um máximo de 100 cupons por requisição. Funciona com integrações de franquia e empresa.

Casos de uso:

• Consultar cupons emitidos
• Gerar relatórios de utilização
• Monitorar cupons vencendo

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
date_start	string	Sim	Data de início para filtrar por data de criação (YYYY-MM-DD)
date_end	string	Sim	Data de fim para filtrar por data de criação (YYYY-MM-DD)
date_of_use_start	string	Não	Data de início para filtrar por data de uso (YYYY-MM-DD)
date_of_use_end	string	Não	Data de fim para filtrar por data de uso (YYYY-MM-DD)
expiration_date_start	string	Não	Data de início para filtrar por data de expiração (YYYY-MM-DD)
expiration_date_end	string	Não	Data de fim para filtrar por data de expiração (YYYY-MM-DD)
coupon_status	string	Não	Status do cupom: Utilizado, Não Utilizado, Vencido, Vencendo
limit	integer	Sim	Número de cupons por requisição (máximo 100)
offset	integer	Sim	Número de cupons a pular (mínimo 1)
search	string	Não	Termo de busca por código ou informação do cliente
order_column	string	Sim	Coluna para ordenação (ex: created_at)
order_type	string	Sim	Direção da ordenação: ASC ou DESC
module	string	Sim	Contexto do módulo: premiado ou falae

Exemplo de Requisição

curl -X GET "https://api-b2s.experienciab2s.com/api/coupons?date_start=2024-01-01&date_end=2024-12-31&limit=10&offset=1&order_column=created_at&order_type=DESC&module=falae" \
     -H "Authorization: Bearer SEU_TOKEN"

Resposta de Sucesso (200)

{
  "limit": 10,
  "offset": 1,
  "total": 45,
  "coupons": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "code": "WELCOME2024",
      "status": true,
      "date_of_use": "2024-03-15",
      "expiration_date": "2024-12-31",
      "created_at": "2024-01-15T10:30:00.000Z",
      "bonus": {
        "id": "bonus-uuid",
        "name": "5% Cashback",
        "type": "answer"
      },
      "client": {
        "id": "client-uuid",
        "name": "João Silva",
        "email": "joao@example.com",
        "phone": "(11) 99999-9999"
      }
    }
  ]
}

Tipos de Bônus Disponíveis

Tipo	Descrição
answer	Resposta de pesquisa
birthday	Aniversário
default	Padrão
create	Criação
fidelityProgram	Programa de fidelidade
prizeDraw	Sorteio
marketing	Marketing
roulette	Roleta
winning_registration_roulette	Registro vencedor de roleta
infinity	Infinito

---

Buscar Cupons por Cliente

GET /api/coupons/clients/{company_id}

Retorna uma lista de cupons vinculados a um cliente específico, utilizando telefone, e-mail ou CPF como critério de busca. É necessário informar o company_id no caminho da requisição.

Casos de uso:

• Consultar cupons de um cliente no atendimento
• Verificar benefícios disponíveis
• Validar cupom antes do resgate

Parâmetros de Caminho

Parâmetro	Tipo	Obrigatório	Descrição
company_id	string	Sim	ID da empresa

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
phone	string	Não*	Telefone no formato internacional E.164 (ex: 551199999999)
email	string	Não*	Endereço de e-mail do cliente
cpf	string	Não*	CPF do cliente no formato 000.000.000-00

Nota: Pelo menos um parâmetro de busca (phone, email ou cpf) deve ser fornecido.

Exemplo de Requisição

curl -X GET "https://api-b2s.experienciab2s.com/api/coupons/clients/103a525c-0ce3-4182-a504-aad595425233?email=cliente@exemplo.com" \
     -H "Authorization: Bearer SEU_TOKEN"

Resposta de Sucesso (200)

[
  {
    "id": "103a525c-0ce3-4182-a504-aad595425233",
    "status": true,
    "expiration_date": "2024-12-31",
    "date_of_use": "2024-05-10",
    "created_at": "2024-01-01T12:00:00.000Z",
    "code": "ABCDEF123",
    "bonus": {
      "name": "5% Cashback"
    }
  },
  {
    "id": "303a525c-0ce3-4182-a504-aad595425233",
    "status": false,
    "expiration_date": "2024-11-30",
    "date_of_use": null,
    "created_at": "2024-02-15",
    "code": "XYZ789",
    "bonus": {
      "name": "10% Cashback"
    }
  }
]

Estrutura da Resposta

Campo	Tipo	Descrição
id	string	ID único do cupom
code	string	Código do cupom
status	boolean	true = utilizado, false = não utilizado
expiration_date	string	Data de expiração
date_of_use	string	Data de utilização (null se não usado)
created_at	string	Data de criação
bonus.name	string	Nome do benefício

Códigos de Resposta

Código	Descrição
200	Cupons encontrados
400	Parâmetros inválidos
401	Token ausente ou inválido
404	Cliente não encontrado

---

Marcar Cupom como Utilizado

PATCH /api/coupons/status/{id}

Atualiza o status de um cupom, marcando-o como utilizado. O sistema valida se o cupom existe, se não foi utilizado anteriormente e se não está expirado (data de expiração deve ser maior que 3 horas do horário atual).

Validações automáticas:

• Se o cupom existe
• Se não foi utilizado anteriormente
• Se todavia está dentro da validade (ao menos 3 horas antes da expiração)

Parâmetros de Caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	ID único do cupom a ser atualizado

Exemplo de Requisição

curl -X PATCH "https://api-b2s.experienciab2s.com/api/coupons/status/abc123-cupom-id" \
     -H "Authorization: Bearer SEU_TOKEN"

Resposta de Sucesso (204)

O status do cupom foi atualizado com sucesso. Nenhum conteúdo é retornado na resposta.

Respostas de Erro (400)

{
  "status": "error",
  "message": "Coupon already used"
}

{
  "status": "error",
  "message": "Coupon expired"
}

Códigos de Resposta

Código	Descrição
204	Cupom atualizado com sucesso
400	Cupom já utilizado ou expirado
401	Token ausente ou inválido
404	Cupom não encontrado