Cómo usar tu clave API del espacio de trabajo

Tu clave API del espacio de trabajo te da acceso programático a tus testimonios: léelos, apruébalos, créalos desde fuentes externas o sincronízalos con tu propio producto. Este es el punto de integración para desarrolladores que quieren ir más allá de los widgets de inserción integrados.

Generación de tu clave API

Paso 1: Abre el panel de administración de tu espacio de trabajo

Inicia sesión en SocialProof.Reviews y navega a tu espacio de trabajo. Haz clic en la pestaña Configuración o Integraciones en la barra lateral izquierda.

Paso 2: Genera la clave

Haz clic en Generar clave API. Tu clave completa se mostrará una sola vez — cópiala de inmediato y guárdala en un lugar seguro, como un gestor de contraseñas o una bóveda de secretos.

Después de salir de la página, solo se muestran los primeros 10 caracteres de la clave. Si pierdes la clave, deberás regenerarla — la clave anterior quedará invalidada.

Paso 3: Guárdala de forma segura

Nunca incluyas tu clave API en:

JavaScript del lado del cliente (será visible en el navegador)
Un repositorio público de GitHub
Un canal o documento compartido de Slack

Guárdala siempre en:

Variables de entorno en tu servidor (process.env.SPR_API_KEY)
Un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, Doppler)
Firebase Secret Manager para Cloud Functions

Autenticación

Incluye tu clave API en cada solicitud como token Bearer en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Todas las solicitudes a la API deben realizarse mediante HTTPS. Las solicitudes HTTP son rechazadas.

URL base

https://api.socialproof.reviews/v1

Todos los endpoints están asociados automáticamente a tu espacio de trabajo según la clave API.

Endpoints principales

Listar testimonios

Recupera todos los testimonios de tu espacio de trabajo:

GET /testimonials
Authorization: Bearer YOUR_API_KEY

Parámetros de consulta opcionales:

Parámetro	Tipo	Descripción
`approved`	boolean	Filtra por estado de aprobación
`rating`	number	Filtra por calificación mínima (1–5)
`limit`	number	Número de resultados (por defecto 20, máximo 100)
`offset`	number	Desplazamiento para paginación

Ejemplo de respuesta:

{
  "data": [
    {
      "id": "t_abc123",
      "reviewer": {
        "name": "Sarah Chen",
        "email": "[email protected]",
        "jobTitle": "Product Manager",
        "company": "TechCorp"
      },
      "rating": 5,
      "review": "Incredible tool. We embedded the wall on our homepage and saw a 23% lift in demo requests.",
      "approved": true,
      "submittedAt": "2026-03-10T14:22:00Z",
      "photos": [],
      "videoUrl": null
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Obtener un testimonio individual

GET /testimonials/:id
Authorization: Bearer YOUR_API_KEY

Aprobar un testimonio

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

{
  "approved": true
}

Crear un testimonio

Importa un testimonio desde una fuente externa (importación CSV, migración desde una plataforma anterior o una encuesta completada):

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

{
  "reviewer": {
    "name": "Marcus Webb",
    "email": "[email protected]",
    "jobTitle": "CEO",
    "company": "Acme Corp"
  },
  "rating": 5,
  "review": "We replaced our old review widget within a day. The setup was seamless.",
  "approved": false,
  "source": "import"
}

Eliminar un testimonio

DELETE /testimonials/:id
Authorization: Bearer YOUR_API_KEY

Devuelve 204 No Content en caso de éxito.

Ejemplos 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 YOUR_API_KEY"

Patrones de integración habituales

Incorporar testimonios en tu propio sitio web

Si necesitas que los testimonios se rendericen con un diseño completamente personalizado que no coincide con los widgets de inserción, obténlos desde la API y renderízalos tú mismo:

// Ejemplo de servidor con 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 };
}

Aprobar automáticamente testimonios con alta calificación mediante webhook + API

Combina tu disparador de webhook con la API para crear un flujo de aprobación completamente automatizado:

El webhook se activa cuando se envía un testimonio
Tu servidor recibe el payload
Si rating === 5, llama a PATCH /testimonials/:id con { "approved": true }
El testimonio aparece de inmediato en tu Muro de Amor

Sincronizar con tu CRM

Después de que se envíe un testimonio, usa la API para obtener el registro completo y enviarlo a tu CRM como nota de cliente o actividad:

// Activado por tu manejador de webhook
async function syncToCRM(testimonialId) {
  const testimonial = await fetchTestimonial(testimonialId);
  await crm.createNote({
    contactEmail: testimonial.reviewer.email,
    note: `Left a ${testimonial.rating}-star testimonial: "${testimonial.review}"`,
    date: testimonial.submittedAt,
  });
}

Límites de frecuencia

Plan	Solicitudes por minuto	Solicitudes por día
Starter	30	1,000
Pro	120	10,000
Agency	300	50,000

Las solicitudes que superan el límite de frecuencia reciben una respuesta 429 Too Many Requests. Implementa retroceso exponencial en tu integración.

Referencia de errores

Estado	Significado
`200`	Éxito
`201`	Creado
`204`	Eliminado
`400`	Solicitud incorrecta — revisa el cuerpo de la solicitud
`401`	Clave API inválida o ausente
`403`	La clave no tiene permiso para esta acción
`404`	Testimonio no encontrado
`429`	Límite de frecuencia superado
`500`	Error del servidor — inténtalo de nuevo