Recursos

API REST pública do WareRushAI (só de leitura)

Consulte os seus produtos, inventário, encomendas, dados em falta e erros de marketplaces a partir do Zapier, Make, n8n ou do seu próprio código com uma chave de API. Especificação OpenAPI 3.1 incluída.

Revised:

1. O que é

A API REST do WareRushAI permite que outros programas leiam os dados de uma empresa: produtos, inventário por localização, encomendas, produtos com dados em falta e erros de listagem em marketplaces. Nesta versão é apenas de leitura e assenta nos mesmos serviços e verificações de permissões que a aplicação web e o conector MCP. O endereço base é https://app.warerushai.com/api/v1. A API está a ser disponibilizada gradualmente: até ser ativada para a plataforma, todas as chamadas devolvem 404 e não é possível criar chaves.

2. Criar uma chave de API

Um proprietário ou administrador abre as Definições, depois Integrações e Chaves de API, dá um nome à chave, escolhe as permissões (catalog.read, inventory.read, orders.read, account.read), uma validade e um limite por minuto, e cria-a. A chave completa começa por wra_live_ e é mostrada apenas uma vez. O WareRushAI armazena apenas uma hash unidirecional e os primeiros caracteres, pelo que uma chave perdida não pode ser recuperada: crie uma nova. Pode revogar uma chave a qualquer momento ou renová-la (rotação): a nova chave é apresentada uma vez e a antiga continua a funcionar durante 24 horas.

3. Autenticar

Envie a chave no cabeçalho Authorization: Authorization: Bearer wra_live_... através de HTTPS. Nunca coloque a chave no endereço web; qualquer pedido que o faça é rejeitado com key_in_url. Exemplo: curl -H "Authorization: Bearer $WRA_KEY" "https://app.warerushai.com/api/v1/products?limit=20". Os tokens de acesso OAuth 2.1 do conector MCP também são aceites, com as permissões aprovadas pelo utilizador.

4. Endpoints

GET /me (a chave, os seus limites e a utilização de hoje), GET /products (pesquisa e listagem, com query, limit, cursor), GET /products/{id}, GET /locations, GET /inventory (linhas de inventário, paginadas), GET /inventory/summary, GET /orders (com updated_since, status, source, limit, cursor), GET /missing-data e GET /marketplace-errors (com channel). Cada endpoint requer a permissão correspondente: catalog.read para produtos, dados em falta e erros de marketplaces, inventory.read para localizações e inventário, orders.read para encomendas. Apenas o método GET é suportado; outros métodos devolvem 405.

5. Paginação e polling

As listas devolvem data, next_cursor e has_more, com um máximo de 50 itens por página (limit de 1 a 50, predefinição 20). Envie o next_cursor como cursor para obter a página seguinte. Para gatilhos de polling no Zapier, Make e n8n, chame GET /orders?updated_since=2026-11-15T08:00:00Z e guarde a data/hora da última consulta bem-sucedida: receberá as encomendas criadas ou alteradas desde então, as mais recentes primeiro.

6. Limites e erros

Cada chave tem um limite por minuto (predefinição 60, no máximo 600) e um limite diário opcional. Cada empresa tem também um limite diário de acordo com o plano: por predefinição 1 000 chamadas no Starter, 10 000 no Business e 100 000 no Pro. Quando um limite é atingido, a API responde com 429 e um cabeçalho Retry-After. Os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining, X-Daily-Limit e X-Daily-Remaining mostram o saldo restante. Os erros têm sempre a estrutura {"error":{"code","message","request_id"}}; mencione o request_id ao contactar o suporte. Códigos comuns: invalid_api_key (401), insufficient_scope (403), not_found (404), invalid_parameter (400), rate_limited e daily_quota_exceeded (429).

7. Especificação OpenAPI

A especificação legível por máquina OpenAPI 3.1 está disponível em https://app.warerushai.com/api/v1/openapi.json e não necessita de chave. Importe-a para o Postman, Zapier, Make, n8n ou para um assistente de IA para obter todos os endpoints, parâmetros e formatos de resposta. As atualizações são efetuadas sem quebrar os campos existentes; a versão é /api/v1.

8. Segurança

As chaves pertencem a apenas uma empresa e são verificadas a cada chamada; uma chave nunca consegue ler dados de outra empresa e deixa de funcionar se o administrador que a criou sair da empresa. As chaves nunca surgem em registos ou mensagens de erro, e o registo de chamadas mostra apenas o caminho, o estado e a data/hora. Dados financeiros, como preços de compra, não são expostos por esta API.