Hasta ahora, un backend que enviaba compras a Provedly usaba una clave por widget, generada en la pestaña Data de ese widget. Eso funciona para un widget. Para un negocio con varios sitios o varios widgets, significaba varios secretos que guardar y rotar. La API de registros ahora también acepta una clave de API de cuenta, la misma clave provedly_ que usan la API REST y el servidor MCP, así que un solo secreto puede cubrir todos los widgets de la cuenta.
Este artículo explica cuándo cambiar, cómo hacerlo y qué no cambia. La referencia completa de campos sigue en la guía de la API de registros.
Qué cambió y qué no
El endpoint es el mismo:
POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget key or account key>
Content-Type: application/json
Los campos son los mismos: name, city, state, country, product_name, price, avatar_url, external_id, occurred_at y visitor. Los valores de external_id duplicados se siguen rechazando por widget, así que los reintentos siguen siendo seguros.
Lo que cambió es la cabecera. Ahora puedes enviar una clave de cuenta con el nivel de acceso Read and write en lugar de la clave propia del widget. Una clave de cuenta de solo lectura se rechaza en este endpoint, porque añadir un registro es una escritura.
Las claves de widget siguen funcionando. Nada se rompe si dejas una integración existente como está.
Cuándo usar cada clave
Conserva la clave del widget cuando la integración solo escribe en un widget y prefieres el alcance reducido. Una clave de widget filtrada solo puede añadir registros a ese widget.
Usa una clave de cuenta cuando un mismo servicio escribe en varios widgets, por ejemplo un servicio de checkout que atiende tres tiendas, cada una con su propio widget. Un solo secreto en el entorno, y el widget se elige con el token de la URL.
Si cambias, crea una clave dedicada para el servicio en Settings, en API keys, y ponle el nombre del servicio: "Checkout service, production". No reutilices la clave que le diste a tu asistente de IA. Tener claves separadas te permite revocar una sin romper la otra.
Un ejemplo práctico
Un servicio que gestiona los pedidos pagados de dos tiendas podría verse así, a grandes rasgos:
const WIDGETS = {
'shop-eu': 'pp_eu_widget_token',
'shop-us': 'pp_us_widget_token',
};
async function sendRecord(order) {
const token = WIDGETS[order.storefront];
const res = await fetch(
`https://provedly.app/api/v1/widgets/${token}/records`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PROVEDLY_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: order.customerFirstName,
city: order.city,
country: order.countryCode,
product_name: order.productName,
price: order.displayPrice,
external_id: order.id,
occurred_at: order.paidAt,
visitor: order.provedlyVisitorId,
}),
},
);
if (res.status === 422) return; // duplicate external_id or invalid data
if (!res.ok) throw new Error(`Provedly ${res.status}`);
}
Llámalo después de confirmar el pago, nunca al crear el pedido. Un registro de un checkout que después falló es una notificación sobre una compra que no ocurrió.
El campo visitor lleva el id de visitante de Provedly del navegador, que es lo que permite que el pedido cuente como pedido asistido por la prueba en tus estadísticas. Sin él, el registro se sigue mostrando y la métrica de atribución simplemente lo deja fuera. Consulta cómo medir los pedidos asistidos por la prueba social.
Cómo aparecen estos registros
Los registros enviados mediante la API conservan la fuente API, sea cual sea la clave que uses. Se muestran en el widget con una etiqueta visible "Imported" y sin la marca de verificado, y la página de verificación pública los cuenta en "Site owner's backend (API)".
Si tus pedidos pasan por Stripe, Shopify o WooCommerce, la conexión por webhook firmado es la mejor vía: esos registros llegan verificados sin código de tu parte. La API de registros es para todo lo que esas conexiones no cubren. Por qué tu asistente no puede verificar una compra explica por qué una llamada a la API, esté autenticada como esté, no puede producir un registro verificado.
Comprobarlo desde tu asistente
Tu asistente de IA ve la misma cuenta a través del servidor MCP, con una clave aparte. Después de desplegar el cambio, puedes preguntar:
Lista mis widgets y dame las estadísticas del último día.
y comparar la respuesta con tu propio registro de pedidos. El recetario de prompts tiene más ejemplos. Si primero quieres probar la integración a mano, el asistente puede llamar a add_record para un único pedido real, que es una forma rápida de ver exactamente cómo se muestra un registro.
Preguntas frecuentes
¿Una clave de cuenta me permite publicar en un widget de otra cuenta?
No. Una clave de cuenta solo funciona con los widgets de su propia cuenta. Un token de otra cuenta se rechaza.
¿Debería rotar ahora mis claves de widget?
Solo si te pasas a una clave de cuenta. Cuando el servicio use la nueva clave, rota la antigua clave del widget en su pestaña Data para que deje de funcionar.
¿Hay un endpoint masivo para el historial?
No. Para pedidos anteriores, usa la importación CSV en la pestaña Data del widget, descrita en importar pedidos anteriores desde CSV. La API es para el flujo en vivo.
La API de registros y las claves de cuenta están disponibles en el plan Free: crea una cuenta.