Autenticação e a primeira requisição
A URL base da API é https://api.weprofit.com/v1/dev. Crie um token de acesso pessoal no card Tokens de API da página Desenvolvedor. Envie-o no cabeçalho Authorization como um token Bearer. Guarde o token no ambiente do seu servidor, nunca no JavaScript da loja nem em um repositório público.
O token segue as permissões de loja do usuário a quem ele pertence. Os membros da equipe precisam de acesso de desenvolvedor e da permissão de análises ou de eventos correspondente. Tokens revogados ou expirados são rejeitados.
curl https://api.weprofit.com/v1/dev/stores \
-H "Authorization: Bearer $WEPROFIT_API_TOKEN"Escolha uma loja na resposta
Use um ID retornado pelo endpoint de lojas nas requisições seguintes. Os valores abaixo são ilustrativos e não contêm dados de clientes.
{
"items": [{
"id": "STORE_ID",
"name": "Example store",
"platform": "shopify",
"currency": "USD",
"timezone": "America/New_York",
"role": "owner"
}]
}Endpoints de relatórios
Todos os caminhos abaixo são relativos à base da API e exigem autenticação bearer. Substitua :storeId pelo ID de uma loja ativa acessível. A tabela cobre as leituras de relatórios. A API REST também permite atualizar gastos com anúncios e gerenciar assinaturas de webhooks; ela não é uma API somente leitura.
| Método e caminho | Finalidade | Parâmetros de consulta opcionais |
|---|---|---|
| GET /me | Identidade do usuário e metadados não secretos do token | Nenhum |
| GET /stores | Lojas ativas acessíveis e os IDs delas | Nenhum |
| GET /stores/:storeId/summary | Resumo de visitantes, sessões, compras, receita, cobertura e lucro | from, to |
| GET /stores/:storeId/orders | Pedidos, atribuição e status de envio por rede | from, to, limit, cursor e filtros de pedidos |
| GET /stores/:storeId/events | Eventos normalizados, origem, canal, estado do consentimento e valor | from, to, limit, cursor e filtros de eventos |
| GET /stores/:storeId/profit | Receita, reembolsos, custos de produtos, taxas, frete, gastos e lucro líquido | from, to |
| GET /stores/:storeId/profit/timeseries | Série diária de lucro e custos | from, to |
| GET /stores/:storeId/profit/ad-spend | Gastos por dia, rede e campanha | month, no formato YYYY-MM |
Datas, filtros e paginação
Informe from e to como datas UTC inclusivas no formato YYYY-MM-DD. Se forem omitidas, o período padrão do relatório é hoje e os seis dias anteriores. Defina as duas datas explicitamente para ter comparações reproduzíveis. Já o endpoint ad-spend usa month e, por padrão, o mês UTC atual.
As listas de pedidos e eventos retornam 50 linhas por padrão e aceitam até 200. Os resultados vêm dos mais recentes para os mais antigos. Passe o nextCursor retornado sem alterações para buscar outra página. Os dados podem mudar durante a paginação, então ela não oferece um retrato fixo dos dados.
- Os filtros de pedidos incluem order_id, status, financial_status, tracked, link_method, link_confidence, channel, currency, min_total, max_total e sent_to.
- Os filtros de eventos incluem event_name, event_id, source, channel, country, url_contains, consent_state, currency, min_value e max_value.
- As duas listas aceitam visitor_id e session_id. Os filtros de eventos também aceitam checkout_token e cart_token.
curl "https://api.weprofit.com/v1/dev/stores/STORE_ID/profit?from=2026-09-01&to=2026-09-07" \
-H "Authorization: Bearer $WEPROFIT_API_TOKEN"Leia várias lojas em uma única requisição
GET /summary, /orders, /events, /profit e /profit/timeseries aceitam um parâmetro de consulta stores obrigatório com até 50 IDs de loja separados por vírgula. Informe as mesmas opções de data e de filtro da requisição equivalente para uma única loja.
As respostas em lote trazem os resultados (results), com entradas independentes de sucesso ou de erro para cada loja. Uma loja com acesso negado não invalida as outras. Nos sucessos de resumo, pedidos e eventos, o payload fica em data; nos sucessos de lucro, os campos de lucro aparecem ao lado de storeId e ok. O resultado de pedidos ou de eventos de cada loja tem o próprio nextCursor.
Interprete corretamente os campos de lucro
Os relatórios de lucro usam custos registrados e estimados. Pedidos cancelados ficam fora do cálculo do lucro e são informados separadamente. A margem é null quando a receita líquida é zero.
O timeseries retorna os dias com atividade de pedidos ou de gasto com anúncios, não um calendário preenchido com zeros. O netProfit dele inclui os reembolsos, embora cada item da série não exponha um campo de reembolsos separado. Use o endpoint de lucro agregado quando precisar do total explícito de reembolsos.
Limites de requisições e erros comuns
Os limites atuais são 240 requisições por minuto e 20.000 requisições por dia por token. Ao atingir o limite, reduza a frequência das requisições e use um número limitado de novas tentativas. Não repita requisições com credenciais ou permissões inválidas sem corrigir a causa.
| Status HTTP | Significado | Próxima ação |
|---|---|---|
| 400 validation_error | Datas, filtros ou outros parâmetros de consulta inválidos | Corrija os parâmetros da requisição. |
| 401 unauthorized | Token ausente, revogado ou expirado | Use um token ativo e o cabeçalho Bearer. |
| 402 plan_required | A loja não tem o plano de cobrança necessário | Revise a cobrança da loja e qualquer restrição por excesso do limite. |
| 403 forbidden | Permissão insuficiente | Peça ao proprietário da loja para revisar o acesso do usuário do token. |
| 404 store_not_found | Loja indisponível para esta requisição | Use um ID ativo e acessível retornado por GET /stores. |
| 429 rate_limited | Limite de requisições do token atingido | Aguarde e reduza o volume de requisições. |