Buscar Cupons Por Código
Descrição
Retorna uma lista paginada de cupons cujo código contenha o termo informado. O parâmetro code deve ter no mínimo 2 caracteres. Suporta filtros adicionais por status e período de datas. Retorna 12 registros por página por padrão.
Verbo
GET
URL Base
https://api.soargi.com
Endpoint
/coupons/search?page=1&limit=12&code=SOAR&status=active&start_date=&end_date=
Cabeçalhos
| Parâmetro | Valor |
|---|---|
| Authorization | Bearer Token |
Parâmetros de Consulta
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| code | string | Sim | Código ou parte do código do cupom. Mínimo de 2 caracteres. |
| page | integer | Não | Número da página. Padrão: 1. |
| limit | integer | Não | Quantidade de registros por página. Padrão: 12. |
| status | string | Não | Filtrar por status do cupom. Valores: "active", "expired". |
| start_date | date | Não | Filtrar cupons válidos a partir desta data (formato: YYYY-MM-DD). |
| end_date | date | Não | Filtrar cupons válidos até esta data (formato: YYYY-MM-DD). |
Sucesso - 200
{
"success": true,
"message": "Coupons filtered successfully.",
"page": 1,
"limit": 12,
"total": 5,
"data": [
{
"coupon_id": "2",
"code": "SOAR12",
"discount": "12",
"status": "expired",
"start_date": "2023-01-01",
"end_date": "2024-01-01",
"start_time": "09:00:00",
"end_time": "20:00:00",
"timezone": "GMT-05:00",
"usages": "10",
"enable_users": "1",
"created_at": "2025-05-08 16:18:37",
"updated_at": "2025-05-08 16:18:37",
"list_users": [1,5]
},
{
"coupon_id": "1",
"code": "SOAR123",
"discount": "123",
"status": "active",
"start_date": "2024-10-01",
"end_date": "2025-10-01",
"start_time": "08:00:00",
"end_time": "18:00:00",
"timezone": "GMT-03:00",
"usages": "0",
"enable_users": "0",
"created_at": "2025-05-08 16:18:24",
"updated_at": "2025-05-08 16:18:24",
"list_users": [4,7,8]
}
]
}Erro - 422 (Código inválido)
{
"status": 422,
"error": "Please provide at least 2 characters to search."
}Códigos de Resposta
- 200 - Cupons encontrados com sucesso
- 422 - Código ausente ou inválido
Observações
- É necessário estar autenticado para acessar este endpoint.
- O parâmetro code é obrigatório e deve ter no mínimo 2 caracteres.
- A busca é realizada no campo code.
- A paginação padrão retorna 12 registros por página.
- O campo list_users contém IDs dos usuários autorizados a usar o cupom.
- O campo usages mostra quantas vezes o cupom foi utilizado.
- Todos os filtros (code, status, start_date, end_date) podem ser combinados com a paginação.
- Os resultados são ordenados por data de criação (mais recentes primeiro).
- Datas devem estar no formato YYYY-MM-DD (ex: 2025-10-01).