Eu administro a Prisma Reviews, uma pequena API que retorna avaliações de clientes de 84 plataformas em um único formato JSON. Este post não é sobre o produto. É sobre três problemas de engenharia que consumiram a maior parte do nosso tempo: projetar um schema que acomode fontes com formatos muito diferentes, manter os IDs estáveis para que a mesma avaliação nunca apareça duas vezes e testar o contrato para que uma mudança a montante não quebre silenciosamente os clientes a jusante.
Uma coisa primeiro, porque isso molda todo o resto: nem toda fonte de avaliações é uma API. Das nossas 84 fontes, 59 têm uma API oficial. As outras 25 não têm, e em vez disso lemos suas páginas ou feeds públicos.
Nem toda fonte é uma API
Cada plataforma na nossa configuração tem três propriedades: como uma empresa a conecta, se podemos publicar uma resposta e como as novas avaliações chegam até nós. Ao classificar as 84 fontes pela forma como as lemos, obtemos quatro grupos:
| Grupo | Fontes | Exemplos |
|---|---|---|
| API oficial, credenciais da própria empresa ou OAuth | 50 | Google Business Profile (acesso pendente), App Store, Google Play, Trustpilot (acesso pendente), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, gerenciadores de propriedades como Hostaway e Guesty |
| API pública oficial, sem credenciais da empresa | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| Sem API: página ou feed público | 3 | Shopify App Store (página HTML de avaliações), WordPress.org (feed RSS de avaliações), Apple Podcasts (feed público de avaliações) |
| Sem API: provedor de dados pago | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |

Os grupos diferem de formas que acabam vazando para o design da API:
- Autenticação. O primeiro grupo exige um fluxo OAuth ou uma chave que a empresa cola. Os outros três exigem apenas a URL pública de um anúncio/listagem.
- Respostas. Apenas 25 das 84 fontes permitem que terceiros publiquem respostas, e duas delas, Google Business Profile e Trustpilot, ainda aguardam a aprovação do nosso acesso pela plataforma. Ter uma API não é suficiente: o endpoint de respostas da Atlassian agora responde
410 API_DEPRECATED, e a API de respostas da Microsoft Store está quebrada do lado da Microsoft, então ambas são somente leitura. - Custo e frequência. As APIs oficiais não nos custam nada por chamada, então as verificamos com frequência. A leitura por meio de um provedor de dados é cobrada por avaliação, e alguns provedores cobram por execução tudo o que houver de novo, por isso essas fontes são verificadas uma vez por dia.
- Por que não há API. A API de parceiros da Expedia com suporte a respostas é aberta apenas a channel managers completos, e ela nos recusou. A do Airbnb é apenas por convite. A Shopify não tem API de avaliações; os desenvolvedores de apps respondem pelo próprio painel deles.
Algumas plataformas aparecem duas vezes. As avaliações do Airbnb e do Booking.com podem vir de uma página pública (somente leitura) ou por meio da API oficial de um gerenciador de propriedades, que permite respostas. É por isso que existe um dos campos abaixo.
Um schema para todas
Cada avaliação, de todas as fontes, tem os mesmos 14 campos, e todos estão sempre presentes. Quando uma plataforma não nos fornece algo, o campo é null, nunca ausente. Uma chave ausente e um null significam a mesma coisa para uma pessoa, mas não para um cliente com tipagem, e "sempre presente" é fácil de testar.
{
"id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
"platform": "google",
"location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
"rating": 4,
"title": null,
"text": "Great flat white, a bit slow at lunchtime.",
"author": "Marta G.",
"language": "en",
"url": null,
"source": null,
"created_at": "2026-10-19T12:41:07.000Z",
"updated_at": "2026-10-19T12:41:07.000Z",
"deleted_at": null,
"reply": null
}rating é um inteiro de 1 a 5, ou null. O Booking.com usa notas de 0 a 10, então dividimos por dois, arredondamos e limitamos ao intervalo 1–5. O Steam não tem estrelas, apenas "recomendado" ou "não recomendado", que mapeamos para 5 e 1. Algumas fontes permitem uma avaliação sem nota alguma, e nesse caso o campo é null. Nunca escrevemos um 0: parece uma nota real e puxa as médias para baixo.
text e title podem ser null. Avaliações apenas com nota são comuns nas lojas de apps, e apenas algumas plataformas têm títulos. Não inventamos um a partir da primeira frase.
url tem um significado específico nas plataformas somente leitura. Quando não podemos publicar uma resposta, url é o local onde a empresa pode respondê-la manualmente. Se um cliente tenta responder mesmo assim, o erro carrega a mesma URL.
source existe por causa dos agregadores. A Viator retorna avaliações escritas na Viator e no Tripadvisor. Um gerenciador de propriedades retorna avaliações do Airbnb, Booking.com e Vrbo por meio de uma única conexão. platform indica por qual conexão a avaliação chegou; source indica em qual site ela foi escrita.
created_at e updated_at são separados porque as pessoas editam avaliações. Uma avaliação de uma estrela editada que passa a ser de quatro estrelas deve ser uma atualização, não uma nova linha.
reply é um objeto com um status, não uma string. O status é published, queued, failed ou unknown. O último precisa de explicação. Às vezes, a requisição à plataforma é enviada e nenhuma resposta volta, e não há como ler a resposta de volta na plataforma. Repetir a tentativa poderia publicar a mesma resposta duas vezes, em nome da empresa. Então paramos, marcamos como unknown e orientamos o cliente a verificar a plataforma antes de publicar de novo. Um status que diz "não sabemos" é mais útil do que um palpite.

Os limites de tamanho das respostas são verificados por plataforma antes de uma resposta entrar na fila: 4.096 bytes no Google Business Profile, 350 caracteres no Google Play, 80 no eBay. Um emoji é um caractere, mas quatro bytes, por isso contamos pontos de código para limites de caracteres e bytes para limites de bytes.
IDs estáveis e desduplicação
Duplicatas são o bug que os clientes percebem primeiro. Nossa regra é simples: cada conector deve retornar o ID próprio da plataforma para cada avaliação, e o banco de dados tem um índice único em (location_id, external_id). Uma segunda sincronização da mesma avaliação é uma atualização, nunca uma inserção. As locations funcionam da mesma forma, com um índice único em (connection_id, external_id).
A parte difícil é que "o ID próprio da plataforma" nem sempre existe:
- As avaliações do Etsy não têm ID próprio. Cada avaliação pertence a exatamente uma transação, então o ID da transação é o ID da avaliação.
- O WordPress.org não fornece ID de avaliação no feed. Cada avaliação é um tópico de fórum, então usamos o slug do tópico.
- A página da Shopify App Store carrega um ID de conteúdo da avaliação em seu HTML. Confiamos nele, sabendo que um redesenho da página poderia alterá-lo.
- O Google Play tem IDs reais, mas sua API retorna apenas avaliações criadas ou editadas nos últimos sete dias. O histórico armazenado é nosso, e não podemos relê-lo.
Os clientes nunca veem IDs de plataformas como chaves primárias. Eles recebem nossos próprios IDs com um prefixo de tipo e um corpo ordenado por tempo (rev_01KJ…, loc_01KJ…, req_01KJ…). O prefixo torna um ID fora do lugar óbvio nos logs, e a ordenação ajuda na paginação: o cursor codifica o timestamp e o ID do último item, então o limite de uma página permanece fixo enquanto novas avaliações chegam.
Reconexão. Uma empresa desconecta uma conta e a conecta novamente uma semana depois. Criar novas locations duplicaria todas as avaliações. Em vez disso, uma location desconectada há menos de 30 dias com o mesmo ID externo é reativada: mesmos IDs, nenhuma avaliação duplicada.
Exclusões. Uma avaliação removida da plataforma simplesmente deixa de aparecer. Nada avisa você. Para 60 das 84 fontes podemos ler o histórico completo, então o relmos periodicamente (a cada 25 dias no Google Business Profile, cujos termos não nos permitem manter conteúdo não confirmado por mais de 30; semanalmente para a maioria das outras) e marcamos com deleted_at as avaliações que a plataforma não retorna mais, além de um webhook review.deleted. A proteção essencial: se uma leitura parou antes do fim, por causa de um timeout ou de um limite de páginas, não marcamos nada. Tratar "não vi" como "sumiu" apagaria avaliações reais. O Google Play fica de fora por causa da sua janela de sete dias.
Testes de contrato contra a especificação OpenAPI
O contrato é um documento OpenAPI 3.1 com 18 paths, 30 schemas e 9 eventos de webhook. Dois tipos de teste o mantêm honesto.
O primeiro é barato e roda a cada commit: os enums da especificação devem corresponder exatamente ao código. Os IDs de plataforma na especificação devem ser iguais à lista na configuração de plataformas, e os eventos de webhook na especificação devem ser iguais aos tipos de evento que o código pode emitir. Os clientes gerados rejeitam valores de enum que não conhecem, então uma plataforma adicionada ao código mas não à especificação quebraria esses clientes na primeira sincronização.
O segundo é um modo de teste. As chaves de API vêm em dois tipos, pk_live_… e pk_test_…, contra o mesmo servidor. Uma chave de teste direciona todas as plataformas para um conector de teste: locations e avaliações de exemplo determinísticas com a forma das reais (um café no Google, um app na App Store, um hotel no Booking.com), respostas que são aceitas mas nunca publicadas em lugar nenhum e, nas plataformas somente leitura, uma url em cada avaliação, porque a documentação promete uma. Qualquer pessoa pode executar todo o contrato, incluindo os paths de escrita, sem tocar em uma conta real.
Os exemplos abaixo são os que estão na especificação, com URLs substituídas por example.com. Uma requisição de listagem:
GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…retorna a avaliação mostrada anteriormente dentro de data, além de um next_cursor. Uma resposta para uma plataforma que suporta respostas é aceita com 202, e a avaliação volta com sua resposta na fila (outros campos omitidos):
POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply
Authorization: Bearer pk_test_…
Content-Type: application/json
{ "text": "Thanks Marta! We have added a second barista at lunch." }{
"id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
"platform": "google",
"reply": {
"text": "Thanks Marta! We have added a second barista at lunch.",
"created_at": null,
"status": "queued",
"error": null
}
}Os casos interessantes são as falhas. Todo erro tem a mesma forma (type, code, message, retryable, request_id, docs_url), e alguns códigos adicionam campos em que o cliente pode agir. Responder a uma avaliação do Yelp retorna 422:
{
"error": {
"type": "invalid_request_error",
"code": "reply_not_supported",
"message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid",
"retryable": false,
"request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N",
"docs_url": "https://example.com/docs/errors#reply_not_supported",
"platform": "yelp",
"url": "https://example.com/biz/example-cafe-madrid"
}
}Uma resposta acima do limite da plataforma também retorna 422, com code: "reply_too_long", platform: "google_play" e max_length: 350. Os clientes devem ramificar com base em code, nunca em message: a mensagem é para pessoas e pode mudar.
A mesma forma vale no tráfego real. Esta é uma resposta real de produção para uma requisição sem chave (cabeçalhos encurtados, URL da documentação substituída):
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S
{"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}}O request_id do corpo corresponde ao cabeçalho Request-Id. Para cada operação, verificamos o código de status, que o corpo valida contra seu schema (todos os 14 campos de avaliação presentes, tipos anuláveis onde declarados), a forma de erro em toda resposta não-2xx e os cabeçalhos Request-Id e de rate limit em caso de sucesso.
Execute as mesmas verificações com a Apidog CLI
As mesmas verificações funcionam em qualquer API que forneça um arquivo OpenAPI. A Apidog CLI importa a especificação, e um agente de código como o Claude Code escreve e executa os casos de teste. Configure uma vez:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Depois, dê ao agente um único prompt:
Import ./openapi.json into Apidog project <projectId>. Create test cases for the
list reviews and reply endpoints that assert the status code, that the body
validates against its schema with all 14 review fields present, and that the
Request-Id header is set. Add a case that replies to a Yelp review and expects
422 with code reply_not_supported. Run them against the test environment and
summarize any failures.O agente importa a especificação, lê o schema dos casos de teste, valida seu payload, cria o caso e o executa:
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit
O reporter junit escreve um arquivo que seu CI consegue ler, então a mesma execução pode servir de portão para todo pull request. O guia de CI/CD da Apidog CLI cobre a configuração do pipeline.
Lições
Modele "tem uma API" e "pode responder" como propriedades separadas. Atlassian e Microsoft mostram que uma API pode existir e ainda assim não aceitar respostas. Um único flag para ambos prometeria respostas que não podemos entregar.
Planeje o estado de resposta unknown antes de a primeira resposta sair. Um estado que admite incerteza custa um valor de enum; uma resposta pública duplicada custa a confiança de um cliente.
Não confie que um ID de plataforma existe ou permanece estável. Registre, por conector, de onde vem o ID e o que poderia alterá-lo.
Teste a especificação contra o código, não apenas o código contra a especificação. O teste de enum tem cerca de dez linhas, e protege a falha que mais machuca os clientes gerados.
