Como Usar Sua Chave de API do Workspace

Sua chave de API do workspace fornece acesso programático aos seus depoimentos — leia-os, aprove-os, crie-os a partir de fontes externas ou sincronize-os com seu próprio produto. Este é o ponto de integração para desenvolvedores que querem ir além dos widgets de incorporação integrados.

Gerando Sua Chave de API

Passo 1: Abra o painel de administração do seu workspace

Faça login no SocialProof.Reviews e navegue até seu workspace. Clique na guia Configurações ou Integrações na barra lateral esquerda.

Passo 2: Gere a chave

Clique em Gerar Chave de API. Sua chave completa será exibida uma única vez — copie-a imediatamente e armazene-a em um local seguro, como um gerenciador de senhas ou cofre de segredos.

Após sair da página, apenas os primeiros 10 caracteres da chave são exibidos. Se você perder a chave, deve regenerá-la — a chave antiga é invalidada.

Passo 3: Armazene-a com segurança

Nunca coloque sua chave de API em:

JavaScript do lado do cliente (ficará visível no navegador)
Um repositório público do GitHub
Um canal ou documento compartilhado do Slack

Sempre armazene-a em:

Variáveis de ambiente no seu servidor (process.env.SPR_API_KEY)
Um gerenciador de segredos (AWS Secrets Manager, HashiCorp Vault, Doppler)
Firebase Secret Manager para Cloud Functions

Autenticação

Inclua sua chave de API em cada requisição como um token Bearer no cabeçalho Authorization:

Authorization: Bearer SUA_CHAVE_DE_API

Todas as requisições de API devem ser feitas via HTTPS. Requisições HTTP são rejeitadas.

URL Base

https://api.socialproof.reviews/v1

Todos os endpoints são automaticamente escopados para seu workspace com base na chave de API.

Endpoints Principais

Listar depoimentos

Recupere todos os depoimentos no seu workspace:

GET /testimonials
Authorization: Bearer SUA_CHAVE_DE_API

Parâmetros de consulta opcionais:

Parâmetro	Tipo	Descrição
`approved`	boolean	Filtrar por status de aprovação
`rating`	number	Filtrar por classificação mínima (1–5)
`limit`	number	Número de resultados (padrão 20, máx 100)
`offset`	number	Deslocamento de paginação

Resposta de exemplo:

{
  "data": [
    {
      "id": "t_abc123",
      "reviewer": {
        "name": "Sarah Chen",
        "email": "[email protected]",
        "jobTitle": "Product Manager",
        "company": "TechCorp"
      },
      "rating": 5,
      "review": "Ferramenta incrível. Incorporamos o mural na nossa página inicial e vimos um aumento de 23% nas solicitações de demo.",
      "approved": true,
      "submittedAt": "2026-03-10T14:22:00Z",
      "photos": [],
      "videoUrl": null
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Obter um único depoimento

GET /testimonials/:id
Authorization: Bearer SUA_CHAVE_DE_API

Aprovar um depoimento

PATCH /testimonials/:id
Authorization: Bearer SUA_CHAVE_DE_API
Content-Type: application/json

{
  "approved": true
}

Criar um depoimento

Importe um depoimento de uma fonte externa (importação de CSV, migração de plataforma legada ou uma pesquisa concluída):

POST /testimonials
Authorization: Bearer SUA_CHAVE_DE_API
Content-Type: application/json

{
  "reviewer": {
    "name": "Marcus Webb",
    "email": "[email protected]",
    "jobTitle": "CEO",
    "company": "Acme Corp"
  },
  "rating": 5,
  "review": "Substituímos nosso antigo widget de avaliações em um dia. A configuração foi perfeita.",
  "approved": false,
  "source": "import"
}

Excluir um depoimento

DELETE /testimonials/:id
Authorization: Bearer SUA_CHAVE_DE_API

Retorna 204 No Content em caso de sucesso.

Exemplos de Código

Node.js (fetch)

const SPR_API_KEY = process.env.SPR_API_KEY;

async function getApprovedTestimonials() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&limit=10',
    {
      headers: {
        'Authorization': `Bearer ${SPR_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );
  const data = await res.json();
  return data.data;
}

Python (requests)

import os
import requests

api_key = os.environ['SPR_API_KEY']
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(
    'https://api.socialproof.reviews/v1/testimonials',
    headers=headers,
    params={'approved': 'true', 'rating': 5}
)
testimonials = response.json()['data']

cURL

curl -X GET \
  "https://api.socialproof.reviews/v1/testimonials?approved=true" \
  -H "Authorization: Bearer SUA_CHAVE_DE_API"

Padrões de Integração Comuns

Puxar depoimentos para o seu próprio site

Se você precisa de depoimentos renderizados em um design totalmente personalizado que não corresponde aos widgets de incorporação, busque-os da API e os renderize você mesmo:

// Exemplo server-side do Next.js
export async function getStaticProps() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&rating=5',
    { headers: { Authorization: `Bearer ${process.env.SPR_API_KEY}` } }
  );
  const { data } = await res.json();
  return { props: { testimonials: data }, revalidate: 3600 };
}

Auto-aprovar depoimentos de alta classificação via webhook + API

Combine seu gatilho de webhook com a API para criar um fluxo de aprovação totalmente automatizado:

Webhook dispara quando um depoimento é enviado
Seu servidor recebe o payload
Se rating === 5, chame PATCH /testimonials/:id com { "approved": true }
O depoimento aparece no seu Mural de Amor instantaneamente

Sincronizar com seu CRM

Após um depoimento ser enviado, use a API para puxar o registro completo e enviá-lo ao seu CRM como uma nota de cliente ou atividade:

// Acionado pelo seu manipulador de webhook
async function syncToCRM(testimonialId) {
  const testimonial = await fetchTestimonial(testimonialId);
  await crm.createNote({
    contactEmail: testimonial.reviewer.email,
    note: `Deixou um depoimento de ${testimonial.rating} estrelas: "${testimonial.review}"`,
    date: testimonial.submittedAt,
  });
}

Limites de Taxa

Plano	Requisições por minuto	Requisições por dia
Starter	30	1.000
Pro	120	10.000
Agency	300	50.000

Requisições que excedem o limite de taxa recebem uma resposta 429 Too Many Requests. Implemente backoff exponencial na sua integração.

Referência de Erros

Status	Significado
`200`	Sucesso
`201`	Criado
`204`	Excluído
`400`	Requisição inválida — verifique o corpo da requisição
`401`	Chave de API inválida ou ausente
`403`	A chave não tem permissão para esta ação
`404`	Depoimento não encontrado
`429`	Limite de taxa excedido
`500`	Erro do servidor — tente novamente