Poupa Tchê

Autenticação

Todas as rotas requerem um token de API gerado em Gerenciar conta. Envie em uma das formas abaixo:

Authorization: Bearer SEU_TOKEN_AQUI

ou

GET /api/v1/me?api_token=SEU_TOKEN_AQUI

Limite: 60 requisições/minuto. Excedido, retorna HTTP 429 com header Retry-After.

URL base

https://www.poupatche.com.br/api/v1

Todas as respostas são JSON com a estrutura: { "success": bool, "data": ..., "message": "...", "errors": {} }

Endpoints

Método	Rota	Descrição
GET	/me	Dados do usuário autenticado
GET	/robos	Lista todos os robôs
POST	/robos	Cria um novo robô
GET	/robos/{id}	Detalhes de um robô
PUT	/robos/{id}	Atualiza um robô
DELETE	/robos/{id}	Exclui um robô
GET	/robos/{id}/reports	Últimos 50 eventos do robô
GET	/reports	Relatório de eventos com paginação, ordenação e filtros
Webhook
GET	/webhook	Consulta a URL de webhook configurada
POST	/webhook	Define ou atualiza a URL de webhook
DELETE	/webhook	Remove a URL de webhook

Parâmetros — GET /reports

Parâmetro	Tipo	Padrão	Descrição
`page`	int	`1`	Página atual
`per_page`	int	`20`	Itens por página (máx. `100`)
`sort`	string	`created_at`	Coluna de ordenação: `created_at`, `type`, `action`, `description`
`direction`	string	`desc`	`asc` ou `desc`
`search`	string	—	Texto livre em `description`
`type`	string	—	Tipo do evento: `user_action`, `system`, `api`
`action`	string	—	Ação específica: ex. `robot_created`, `search_run`, `api_request`
`date_from`	date	—	Data inicial (formato `YYYY-MM-DD`)
`date_to`	date	—	Data final (formato `YYYY-MM-DD`)
`robot_id`	int	—	Filtra eventos associados a um robô específico

Campos aceitos — POST e PUT /robos

Campo	Tipo	Obrigatório	Descrição
`description`	string	POST	Nome do produto. Use `cod:GTIN` para código de barras.
`max_price`	number	POST	Preço máximo de alerta (ex: `29.90`)
`hours`	array<int>	POST	Horários de busca, 0–23 (ex: `[8, 12, 18]`)
`cities`	array<object>	POST	Cidades onde buscar. Cada item pode ser: `{"name":"Porto Alegre"}` — busca pela cidade `{"name":"Casa","lat":-30.02,"lng":-51.22}` — busca por GPS
`state`	boolean	não	Ativo (`true`) ou inativo (`false`). Padrão: `true`.

Exemplos com curl

Listar robôs

curl -H "Authorization: Bearer SEU_TOKEN" \ https://www.poupatche.com.br/api/v1/robos

Criar robô — cidade por nome

curl -X POST \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "Arroz 5kg", "max_price": 29.90, "hours": [8, 18], "cities": [{"name": "Porto Alegre"}] }' \ https://www.poupatche.com.br/api/v1/robos

Criar robô — cidade por coordenadas GPS (lat/lng)

curl -X POST \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "Leite integral", "max_price": 5.99, "hours": [9, 21], "cities": [ {"name": "Minha localização", "lat": -30.0277, "lng": -51.2287} ] }' \ https://www.poupatche.com.br/api/v1/robos

Com lat/lng, o sistema busca estabelecimentos próximos à localização GPS informada. Sem essas coordenadas, busca pela cidade pelo nome. Você pode misturar ambos na mesma lista de cities.

Criar robô — múltiplas cidades (nome e GPS)

curl -X POST \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "Feijão 1kg", "max_price": 8.50, "hours": [7, 12, 19], "cities": [ {"name": "São Paulo"}, {"name": "Escritório", "lat": -23.5614, "lng": -46.6560}, {"name": "Casa", "lat": -23.5489, "lng": -46.6388} ] }' \ https://www.poupatche.com.br/api/v1/robos

Ativar/desativar robô

curl -X PUT \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"state": false}' \ https://www.poupatche.com.br/api/v1/robos/ID_DO_ROBO

Eventos de um robô específico (últimos 50)

curl -H "Authorization: Bearer SEU_TOKEN" \ https://www.poupatche.com.br/api/v1/robos/ID_DO_ROBO/reports

Relatório de eventos — listagem geral (paginado)

curl -H "Authorization: Bearer SEU_TOKEN" \ "https://www.poupatche.com.br/api/v1/reports?per_page=20&sort=created_at&direction=desc"

Relatório — filtrar por tipo, ação e período

curl -H "Authorization: Bearer SEU_TOKEN" \ "https://www.poupatche.com.br/api/v1/reports?type=api&action=api_request&date_from=2026-06-01&date_to=2026-06-30&per_page=50"

A resposta inclui o objeto pagination com total, per_page, current_page, last_page, from e to.

Webhooks — notificação automática

Configure uma URL de webhook pela API ou em Gerenciar conta → Token de API. Quando um robô encontrar um preço dentro do limite, o sistema dispara um POST automático para essa URL.

Consultar webhook atual

curl -H "Authorization: Bearer SEU_TOKEN" \ https://www.poupatche.com.br/api/v1/webhook

Configurar webhook

curl -X POST \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"webhook_url": "https://meusite.com/webhook/poupatche"}' \ https://www.poupatche.com.br/api/v1/webhook

Retorna {"success": true, "data": {"webhook_url": "https://..."}, ...}. Se uma URL já existia, é substituída.

Remover webhook

curl -X DELETE \ -H "Authorization: Bearer SEU_TOKEN" \ https://www.poupatche.com.br/api/v1/webhook

Campo aceito — POST /webhook

Campo	Tipo	Obrigatório	Descrição
`webhook_url`	string	sim	URL válida com esquema `http` ou `https`. Máximo 500 caracteres.

Método

POST sua URL

Content-Type

application/json

Timeout

10 segundos

Payload enviado

{ "event": "price_found", "timestamp": "2026-06-27T08:00:00-03:00", "user": "seu@email.com", "results": [ { "robot_description": "Arroz 5kg", "city": "Porto Alegre", "max_price": 29.90, "items_found": 3, "items": [ { "product": "Arroz Parboilizado 5kg", "price": 24.99, "store": "Supermercado Exemplo", "neighborhood": "Centro", "lat": -30.0277, "lng": -51.2287 } ] } ] }

Campos do payload

Campo	Tipo	Descrição
`event`	string	Sempre `"price_found"`
`timestamp`	string	Data/hora do disparo em formato ISO 8601
`user`	string	E-mail do usuário dono do robô
`results`	array	Um item por robô/cidade com resultado no ciclo
`results[].robot_description`	string	Descrição do produto monitorado
`results[].city`	string	Nome da cidade pesquisada
`results[].max_price`	number	Preço máximo configurado no robô
`results[].items_found`	int	Quantidade de itens abaixo do limite
`results[].items[]`	array	Cada item encontrado no ciclo
`results[].items[].product`	string	Descrição do produto na nota fiscal
`results[].items[].price`	number	Preço encontrado (R$)
`results[].items[].store`	string	Nome fantasia ou razão social do estabelecimento
`results[].items[].neighborhood`	string	Bairro do estabelecimento
`results[].items[].lat`	number	Latitude do estabelecimento
`results[].items[].lng`	number	Longitude do estabelecimento

O webhook é disparado uma vez por ciclo de execução (não por item). Se vários robôs gerarem resultado no mesmo horário, todos chegam num único payload dentro do array results. Erros de entrega são registrados nos logs do sistema e não causam nova tentativa.

Estrutura de resposta

{ "success": true, "data": { ... }, "message": "Robô criado com sucesso.", "errors": {} }

Em caso de erro, success é false e errors contém os detalhes de validação. Códigos HTTP: 200, 201, 401, 404, 422, 429.

Resposta de listagem paginada (GET /reports)

{ "success": true, "data": { "items": [ { "id": 123, "type": "api", "action": "api_request", "description": "GET /api/v1/robos", "data": { ... }, "ip_address": "200.x.x.x", "created_at": "2026-06-24T15:30:00.000000Z" } ], "pagination": { "total": 87, "per_page": 20, "current_page": 1, "last_page": 5, "from": 1, "to": 20 }, "sort": "created_at", "direction": "desc" }, "message": "", "errors": {} }

API REST — PoupaTchê