El servidor MCP se lleva la atención, pero debajo hay una API REST normal, y todo lo que puede hacer el asistente también lo puede hacer un script. Este artículo recorre los endpoints en el orden en que probablemente los necesites, con un comando curl para cada uno. Si prefieres hablar con ella a través de Claude, empieza por el artículo del lanzamiento.
URL base y autenticación
Base URL: https://provedly.app/api/v1
Header: Authorization: Bearer provedly_…
La clave es una clave de API de cuenta, creada en Settings, en API keys. Empieza por provedly_, se muestra una sola vez y se puede revocar en cualquier momento. Elige Read only para scripts que solo generan informes, y Read and write para cualquier cosa que cambie el estado. La diferencia se explica en elegir una clave de API.
Para los ejemplos, guarda la clave en una variable de entorno para que no quede en el historial de tu shell:
export PROVEDLY_KEY="provedly_your_key_here"
Las claves van en servidores y en tu propia terminal. Nunca incluyas una en el JavaScript del navegador.
Leer tu cuenta
Empieza por el endpoint de la cuenta. Devuelve tu plan, sus límites y el uso actual, que es el contexto de todo lo demás.
curl https://provedly.app/api/v1/account \
-H "Authorization: Bearer $PROVEDLY_KEY"
Después, lo que hay en la cuenta:
curl https://provedly.app/api/v1/sites -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/widgets -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/bars -H "Authorization: Bearer $PROVEDLY_KEY"
Los elementos individuales están en /widgets/{id} y /bars/{id}. Puedes referirte a widgets, barras y sitios por su id, que es un UUID, o por su token, el que tengas a mano. Un script que ya tiene el token de un widget de tu fragmento de instalación no necesita buscar antes el UUID.
Estadísticas
curl "https://provedly.app/api/v1/stats?days=30" \
-H "Authorization: Bearer $PROVEDLY_KEY"
La respuesta incluye impresiones, clics, pedidos verificados y pedidos asistidos por la prueba con sus ingresos, para el número de días que pidas. "Asistido por la prueba" significa que el comprador vio una notificación antes de comprar, emparejado por visitante dentro de una ventana de 30 días, la misma definición que usa el panel y que se explica en cómo medir los pedidos asistidos por la prueba social. Cambia days a 7 para un informe semanal.
Cambiar widgets y barras
Todo lo de esta sección necesita una clave de lectura y escritura. Pausar o reactivar un widget es un PATCH:
curl -X PATCH https://provedly.app/api/v1/widgets/WIDGET_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'
Envía "active" para reactivarlo. Al reactivar es donde aparecen los límites del plan: si el plan permite un número fijo de widgets activos y ya estás en él, la solicitud se rechaza indicando el motivo en lugar de pasarse en silencio. Una clave de solo lectura se rechaza en cualquier escritura, sea cual sea el cuerpo.
Crear una barra es un POST a /bars. Guarda el cuerpo en un archivo para que sea fácil de revisar:
curl -X POST https://provedly.app/api/v1/bars \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d @winter-launch.json
Una barra nueva creada mediante la API empieza en pausa. Es deliberado: nadie la ve hasta que la has revisado, y un error de tipeo en un script no puede poner una barra a medio escribir frente a los visitantes. Publicarla es una segunda llamada:
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "active"}'
La activación respeta el límite de barras de tu plan igual que la reactivación de widgets.
El mismo endpoint PATCH edita el nombre, el mensaje y la fecha de fin de una barra, y la pausa o la reactiva. Para las fechas de fin, ends_at acepta una hora local como "2026-12-01 09:00", que se interpreta en la zona horaria de la propia barra, o una marca de tiempo ISO 8601 completa:
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"ends_at": "2026-12-01 09:00"}'
La forma local suele ser la que quieres para un lanzamiento, porque "9 a. m." significa las 9 a. m. donde está configurada la barra, no donde se ejecute tu servidor. Más sobre fechas en programar cuentas regresivas de lanzamiento.
Añadir registros
La API de registros, POST /widgets/{token}/records, no cambia de forma y ahora también acepta una clave de cuenta, así que una sola clave puede alimentar todos los widgets de la cuenta en lugar de mantener una clave de widget distinta para cada uno. Los campos y las reglas de idempotencia están en la referencia de la API de registros, y la versión con clave de cuenta se explica paso a paso en enviar registros con una clave de cuenta.
Los registros creados así conservan la fuente API y se muestran en el widget con una etiqueta visible "Imported", sin la marca de verificado. La API no tiene ningún campo que marque un registro como verificado, y ningún nivel de clave lo añade. Solo los webhooks firmados de Stripe, Shopify y WooCommerce producen registros verificados.
Interpretar los rechazos
La mayoría de los fallos caen en unos pocos grupos:
| Situación | Qué obtienes |
|---|---|
| Clave ausente, incorrecta o revocada | Un error de autenticación |
| Clave de solo lectura en un endpoint de escritura | Un rechazo que dice que la clave es de solo lectura |
| El cambio superaría un límite del plan | Un rechazo que nombra el límite |
| Campo no válido, como una fecha incorrecta | Un error de validación para ese campo |
Los scripts deberían tratar los rechazos por límite del plan como información para una persona, no como algo que reintentar.
Preguntas frecuentes
¿La API es lo mismo que usa el servidor MCP?
Las herramientas MCP cubren las mismas acciones con las mismas reglas: mismas claves, mismos límites de plan y la misma negativa a verificar registros. Usa lo que mejor encaje con la tarea.
¿Puedo crear una barra que se publique de inmediato?
No en una sola llamada. Las barras creadas mediante la API empiezan en pausa y las activas con una segunda solicitud. Es una línea más en un script, y evita sorpresas.
¿Qué planes incluyen la API?
Todos, incluido Free. Los límites del plan sobre widgets, barras e impresiones se aplican como siempre.
Mira lo que permite cada plan en la página de precios.