Referencia API

Introducción

La API de Reviewlee es una API RESTful que te permite gestionar programáticamente todos los aspectos de tu infraestructura de reseñas. Todos los endpoints están versionados bajo /api/v1/ y devuelven respuestas JSON.

• Endpoints RESTful con cuerpos de solicitud/respuesta JSON
• Autenticación con clave API con alcances granulares (lectura, escritura, admin)
• Endpoints de lista paginados con formato meta consistente
• Soporte de webhooks para notificaciones de eventos en tiempo real

URL base

Todas las solicitudes API deben realizarse a la siguiente URL base. Todos los endpoints requieren el prefijo /api/v1/.

La API está versionada mediante la ruta URL. La versión actual es v1. Anunciaremos la descontinuación de versiones anteriores con anticipación.

Autenticación

Autentica las solicitudes API usando autenticación Bearer con tu clave API de organización. Las claves comienzan con rk_ y están asociadas a una sola organización.

curl -X GET https://api.reviewlee.com/api/v1/reviews \
  -H "Authorization: Bearer rk_your_api_key_here"

Límites de velocidad

Las solicitudes API tienen límites de velocidad por clave API. Las cabeceras de límite se incluyen en cada respuesta para ayudarte a controlar el uso.

Paginación

Todos los endpoints de lista soportan paginación mediante los parámetros page y limit. Las respuestas incluyen un objeto meta con el total y la información de página.

// Paginated response format
{
  "data": [...],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

// Query parameters
GET /api/v1/reviews?page=2&limit=10

Reseñas

Las reseñas son el recurso principal. Lista, consulta, modera y envía reseñas. Las reseñas no se pueden eliminar — solo ocultar mediante moderación con registro de auditoría.

Ejemplo de respuesta

{
  "id": "cm...",
  "rating": 5,
  "title": "Excellent service",
  "content": "Great experience with the product!",
  "reviewer_name": "Jane Doe",
  "reviewer_email": "[email protected]",
  "verification_status": "verified",
  "is_hidden": false,
  "created_at": "2026-01-15T12:00:00Z",
  "form_id": "cm..."
}

Formularios de reseñas

Los formularios definen cómo se recopilan las reseñas. Configura modos de verificación, campos personalizados y enlaces públicos de envío.

Organizaciones

Gestiona la configuración de la organización, miembros del equipo e invitaciones. Todos los datos están asociados a la organización de tu clave API.

Exportaciones

Exporta datos de reseñas como CSV o JSON. Las exportaciones se ejecutan de forma asíncrona — crea un trabajo y luego descárgalo cuando esté listo.

// Create an export job
POST /api/v1/organizations/:orgId/exports
{
  "format": "csv",   // "csv" or "json"
  "filters": {
    "startDate": "2026-01-01",
    "endDate": "2026-02-01"
  }
}

Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu organización. Los payloads de webhooks están firmados con HMAC-SHA256 para verificación.

// Webhook payload example
{
  "event": "review.created",
  "timestamp": "2026-02-15T10:30:00Z",
  "data": {
    "id": "cm...",
    "rating": 5,
    "content": "Amazing product!",
    "reviewer_name": "John Smith"
  }
}

// Verify HMAC signature
const signature = request.headers["x-webhook-signature"];
const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(JSON.stringify(body))
  .digest("hex");

Widget embebido

Incrusta tus reseñas en cualquier sitio web con un widget JavaScript ligero. Soporta diseños de lista, cuadrícula y carrusel con temas claro y oscuro.

<!-- Embed reviews on any website -->
<div id="reviewlee-widget" data-slug="your-business-slug"></div>
<script src="https://www.reviewlee.com/embed.js"></script>

Perfiles públicos

Los perfiles de empresa públicos son páginas indexadas por SEO que muestran reseñas con calificaciones agregadas. Gestiona la configuración del perfil y accede a datos públicos.

Claves API

Crea, lista, rota y revoca claves API para tu organización. Las claves tienen alcances de lectura, escritura o admin.

Verificación

Verifica reseñas usando múltiples métodos. Cada formulario puede configurarse con un modo de verificación específico.

Solicitudes de reseñas

Automatiza la recopilación de reseñas enviando solicitudes por email a clientes. Soporte para envíos individuales y masivos con seguimiento de entrega.

Manejo de errores

La API usa códigos HTTP convencionales. Los códigos 2xx indican éxito, 4xx errores del cliente y 5xx errores del servidor.

// Error response format
{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "error": "Unauthorized"
}