API BackendEndpoints
Lojas e Promoções
Gestão de lojas e endpoints de carregamento de promoções para administradores
Lojas e Promoções
GET /api/stores
Listar todas as lojas com promoções disponíveis.
| Método | Caminho | Autenticação | Nível |
|---|---|---|---|
| GET | /api/stores | Nenhuma | Free |
Resposta 200 OK
[
{
"id": "uuid",
"name": "Continente",
"logo_url": "https://...",
"last_updated": "2024-01-20T12:00:00Z",
"promotion_count": 142
}
]GET /api/stores/:id/promotions
Listar as promoções atuais de uma loja.
| Método | Caminho | Autenticação | Nível |
|---|---|---|---|
| GET | /api/stores/:id/promotions | Nenhuma | Free |
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
q | string | Pesquisar por nome de produto |
limit | integer | Máximo de resultados (padrão: 50) |
offset | integer | Deslocamento de paginação |
Resposta 200 OK
{
"store_name": "Continente",
"items": [
{
"id": "uuid",
"product": "Frango do Campo",
"brand": "Casa Matias",
"original_price": 4.99,
"discounted_price": 3.49,
"unit": "kg",
"valid_until": "2024-01-28"
}
],
"total": 142
}POST /api/admin/stores
Criar uma nova loja. Apenas para administradores.
| Método | Caminho | Autenticação | Nível |
|---|---|---|---|
| POST | /api/admin/stores | JWT Bearer (admin) | Admin |
Corpo do pedido
{
"name": "Aldi",
"logo_url": "https://..."
}Resposta 201 Created
Devolve o objeto de loja criado.
POST /api/admin/stores/:id/promotions/upload
Carregar um folheto promocional PDF semanal para processamento. Apenas para administradores.
| Método | Caminho | Autenticação | Nível |
|---|---|---|---|
| POST | /api/admin/stores/:id/promotions/upload | JWT Bearer (admin) | Admin |
Pedido
Dados de formulário multipart com um campo file contendo o PDF.
curl -X POST http://localhost:8080/api/admin/stores/uuid/promotions/upload \
-H "Authorization: Bearer <admin_token>" \
-F "file=@promo_week_04.pdf"Resposta 202 Accepted
{
"job_id": "uuid",
"status": "pending",
"message": "PDF processing started in background"
}GET /api/admin/stores/:id/jobs
Verificar o estado de um trabalho de processamento de PDF. Apenas para administradores.
| Método | Caminho | Autenticação | Nível |
|---|---|---|---|
| GET | /api/admin/stores/:id/jobs | JWT Bearer (admin) | Admin |
Resposta 200 OK
{
"jobs": [
{
"id": "uuid",
"status": "completed",
"pages_processed": 12,
"candidates_extracted": 87,
"created_at": "2024-01-20T14:00:00Z",
"completed_at": "2024-01-20T14:03:22Z"
}
]
}Valores de status: pending | processing | completed | failed
As promoções extraídas são colocadas em espera como candidatos. Um administrador deve promovê-las explicitamente para produção usando o endpoint de promoção antes de aparecerem aos utilizadores.