API v1

Uma entrada para cada avaliação.

A API recebe avaliações de e-commerce, pesquisas, ERPs e automações. Ela valida, normaliza, deduplica e coloca cada registro na fila de análise.

OrigemLoja, ERP ou n8n

→

RateitValidação e deduplicação

→

ResultadoEvidência e análise

Autenticação

Crie uma chave em Dashboard → Integrações → API própria. Ela aparece uma única vez.

Authorization: Bearer rt_live_SUA_CHAVE
Content-Type: application/json

Nunca exponha a chave em JavaScript do navegador, aplicativo público, repositório ou variável NEXT_PUBLIC_. Use um servidor, função ou credencial do n8n.

Enviar avaliações

POSThttps://rateit.site/api/v1/reviews

{
  "reviews": [{
    "externalId": "pedido-1042-review",
    "source": "shopify",
    "rating": 4,
    "comment": "O café é ótimo, mas a embalagem chegou amassada.",
    "reviewerName": "Cliente",
    "reviewerPhone": "+5511999998888",
    "contactConsentAt": "2026-07-15T12:00:00Z",
    "createdAt": "2026-07-15T12:00:00Z",
    "locationName": "Loja online",
    "productId": "CAFE-500",
    "productName": "Café Especial 500g",
    "orderId": "1042"
  }]
}

Campos

Campo	Obrigatório	Descrição
externalId	Sim	ID estável usado para deduplicação.
source	Sim	shopify, vtex, woocommerce, wordpress ou api.
rating	Sim	Inteiro entre 1 e 5.
comment	Sim	Texto com até 12.000 caracteres.
reviewerName	Não	Nome exibido junto da avaliação no painel.
reviewerPhone	Não	Telefone vinculado à avaliação. Informe `contactConsentAt` para aparecer no painel operacional.
contactConsentAt	Não	Data ISO 8601 do consentimento para contato sobre aquela experiência.
marketingConsentAt	Não	Data ISO 8601 do consentimento de marketing, quando houver.
createdAt	Sim	Data ISO 8601.
locationExternalId	Não	ID da unidade ou canal.
productId / orderId	Não	Referências sem dados de pagamento.

Resposta aceita

HTTP 202
{
  "data": {
    "received": 1,
    "imported": 1,
    "duplicates": 0,
    "rejected": 0,
    "blocked": 0,
    "batchId": "..."
  }
}

Erros e limites

Status	Quando acontece
400	JSON ou lote inválido.
401	Chave ausente, expirada ou revogada.
402	Franquia do plano esgotada.
413	Corpo maior que 1 MB.
429	Mais de 120 chamadas por minuto.

Uma chamada aceita no máximo 100 avaliações. Reutilize o mesmo externalId ao repetir uma entrega; duplicatas são ignoradas.

Automação com n8n

Crie uma credencial Header Auth: Authorization = Bearer rt_live_....
Use um gatilho da origem: Webhook, Shopify, WooCommerce, banco ou agendamento.
Mapeie os campos com um nó Set ou Code.
Use HTTP Request com POST, JSON e o endpoint do Rateit.
Ative retry para 429 e erros 5xx; não repita erros 4xx.
Guarde o batchId para rastreabilidade.

Method: POST
URL: https://rateit.site/api/v1/reviews
Authentication: Header Auth
Body: { "reviews": {{ $json.reviews }} }

n8n é excelente para o MVP, sincronizações agendadas e fontes menores. Para alto volume, webhooks assinados e workers próprios são mais previsíveis.

Shopify, VTEX e WooCommerce

WooCommerce: o plugin Rateit 0.4 envia avaliações aprovadas, busca respostas aprovadas na plataforma e as publica como resposta ao comentário original da loja.

Google: a Rateit importa e publica respostas pela API oficial quando a empresa, o OAuth e a cota do projeto estão ativos.

Shopify: não existe uma fonte universal de avaliações. Conecte o app utilizado — Judge.me, Yotpo, Loox, Stamped ou outro — ou transforme seus webhooks no n8n.

VTEX: o destino está pronto, mas o importador precisa de account name, workspace e AppKey/AppToken, além de identificar Reviews & Ratings ou Master Data.

Aprovação e publicação são separadas. A Rateit registra canal, tentativas, confirmação e erro sem esconder uma falha do provedor.