Sessao
Entrar
Novo acesso
Criar conta
Operacao diaria
Empresa
Painel
Guia tecnico para orders e produto.
Consulta os endpoints, payloads e exemplos necessarios para integrar a recolha de reviews no ecommerce ou website.
Developer Guide
Integrar reviews de encomenda e produto
Esta página resume o fluxo técnico para autenticar a loja, criar convites de review, recolher respostas públicas e consultar reviews de serviço ou catálogo de produto. Para integrações server-to-server, usa preferencialmente a API key da empresa.
Credenciais
API key da integração
Sem API key configurada.
Gera uma API key própria para chamadas server-to-server.
A key completa so e mostrada na rotacao. Depois disso, o dashboard guarda apenas o prefixo e o hash.
Headers
Como autenticar pedidos
X-API-Key: fd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAuthorization: ApiKey fd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxMantemos `Authorization: Bearer ...` para uso humano e dashboard, mas API key e o modo recomendado para integrações de backend.
Fluxo
Passos de integração
Autenticar a loja
Gera uma API key no dashboard e usa-a nos pedidos server-to-server. O login com `Bearer` fica como fallback operacional.
Criar o convite
Chama `POST /api/review-invites` com o `collection_mode` certo e contexto da encomenda.
Enviar o cliente para a landing
Usa o `public_url` devolvido ou consome `GET /ri/{token}` em JSON para um frontend próprio.
Receber a review
A submissão entra em `pending` e fica disponível para moderação e consulta no catálogo.
Collection Modes
Quando usar cada modo
Modo
`order`
Para recolher apenas a experiência de serviço / encomenda.
- `rating` global obrigatório
- `products` opcional
- Ideal para entrega, apoio e experiência geral
Modo
`product`
Para recolher review de um ou vários produtos da mesma encomenda.
- Sem necessidade de `rating` global
- Pelo menos 1 produto tem de ser avaliado
- `gtin`, `sku` e `name` sempre obrigatórios
Modo
`order_and_products`
Para recolher serviço + produto na mesma página pública.
- Combina bloco de encomenda e bloco de produto
- Melhor opção para ecommerce clássico
- Permite análise editorial separada no dashboard
Auth
1. Obter API key
GET /api/auth/api-key
Cookie: fd_company_token=...
POST /api/auth/api-key
Cookie: fd_company_token=...
Recomendado
Usa `POST /api/auth/api-key` no dashboard para gerar ou rodar a key da loja.
Depois disso autentica os pedidos com `X-API-Key` ou `Authorization: ApiKey ...`.
curl -X POST https://app.exemplo.pt/api/review-invites \
-H "Content-Type: application/json" \
-H "X-API-Key: fd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{ ... }'Invites
2. Criar convite para encomenda e produto
POST /api/review-invites
{
"customer_name": "Ana Silva",
"customer_email": "[email protected]",
"external_order_id": "100045",
"order_number": "#100045",
"collection_mode": "order_and_products",
"delay_hours": 72,
"order": {
"store_name": "Loja Exemplo",
"order_reference": "#100045",
"placed_at": "2026-03-12 10:30:00",
"delivered_at": "2026-03-14 15:00:00",
"total_amount": "89.90",
"currency": "EUR"
},
"products": [
{
"gtin": "5601234567890",
"sku": "SKU-RED-42",
"name": "Tenis Runner Vermelhos",
"quantity": 1
},
{
"gtin": "5601234567891",
"sku": "SKU-BLUE-41",
"name": "Tenis Runner Azuis",
"quantity": 2
}
]
}
Regras críticas
`external_order_id + customer_email` é único por empresa.
Em `product` e `order_and_products`, `products` não pode vir vazio.
Cada produto deve trazer sempre `gtin` ou `ean`, `sku` e `name`.
Landing
3. Ler o convite em JSON
Se o frontend for teu, pede `Accept: application/json` em `GET /ri/{token}`.
GET /ri/INVITE_TOKEN
Accept: application/json{
"data": {
"accepts_submissions": true,
"requested_locale": "pt-PT",
"invite": {
"collection_mode": "order_and_products",
"order": {
"store_name": "Loja Exemplo",
"order_reference": "#100045"
},
"products": [
{
"gtin": "5601234567890",
"sku": "SKU-RED-42",
"name": "Tenis Runner Vermelhos"
}
]
}
}
}Submit
4. Submeter a review
POST /ri/INVITE_TOKEN
{
"rating": 5,
"comment": "Boa experiencia global.",
"delivery_rating": 5,
"service_rating": 4,
"highlights": "Rapidez e comunicacao.",
"improvements": "A embalagem podia vir melhor protegida.",
"author_name": "Ana Silva",
"author_email": "[email protected]",
"locale": "pt-PT",
"browser_locale": "pt-PT",
"website": "",
"product_reviews": [
{
"rating": 5,
"comment": "Muito confortaveis."
},
{
"rating": 3,
"comment": "Bom, mas o tamanho e pequeno."
}
]
}
Importante para produto
`product_reviews[*]` é alinhado por índice com `invite.products[*]`.
Em `collection_mode=product`, o `rating` global pode ser omitido se existir pelo menos um produto avaliado.
O campo `website` é honeypot e deve ficar vazio.
Consulta
5. Ler reviews de serviço e catálogo
GET /api/reviews?type=service&status=published
Usa esta rota para fila editorial, pesquisa por encomenda, loja e análise de serviço.
GET /api/reviews?type=product
Usa esta rota se precisares da fila raw de reviews classificadas como produto.
GET /api/reviews/catalog?q=SKU-RED-42
Agrega por `gtin + sku + name` e devolve `reviews_total`, `rating_avg` e reviews recentes por artigo.
Campos
Mapeamento recomendado
Identificador único da encomenda no ecommerce.
Número apresentado ao cliente e à equipa.
Valor final mostrado na página pública.
Podes enviar `ean`, mas o backend normaliza para `gtin`.
Obrigatório para catálogo e pesquisa interna.
Obrigatório para contexto de recolha e consulta.
Checklist
Antes de desenvolver
Garantir um `review_link` ativo
Sem isso, a API não cria convites automaticamente.
Enviar `external_order_id`
Evita duplicados por encomenda/email.
Enviar `gtin`, `sku` e `name`
São os campos mínimos para backend de produto e catálogo.
Alinhar `product_reviews` por índice
O índice do array é a chave de associação aos produtos do convite.