Cómo usar la Records API con compras de tu propio backend

Si tus compras no pasan por Stripe Checkout, Shopify ni WooCommerce, la Records API es la forma de hacerlas llegar a Provedly. Un POST de servidor a servidor por pedido, autenticado con una clave bearer propia de cada widget, y la compra aparece como notificación dentro de la ventana de antigüedad. Los registros creados así llevan una etiqueta "Imported" visible y nunca la marca "Verified"; en este artículo explicamos esa regla además de cómo funciona todo.

El endpoint

POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget api key>
Content-Type: application/json

La clave se genera por widget en la pestaña Data y puede rotarse ahí mismo. Trátala como cualquier secreto: variable de entorno en el servidor, nunca en código del lado del cliente. El endpoint es solo de servidor a servidor; las llamadas desde un navegador quedan a la vista de cualquiera con devtools, y una clave filtrada permite a un desconocido publicar registros en tu widget.

Campos

Envía lo que tengas. Un registro con solo name es válido y se mostrará con el producto por defecto del widget y sin ubicación.

Un ejemplo mínimo

curl -X POST https://provedly.app/api/v1/widgets/pp_your_token/records \
  -H "Authorization: Bearer $PROVEDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "city": "Berlin",
    "country": "DE",
    "product_name": "Pro Plan",
    "price": "€49",
    "external_id": "order_123",
    "occurred_at": "2026-08-12T14:03:00Z"
  }'

Respuestas:

201 Created
{ "id": 812, "hash": "9c1e0b7a…", "verified": false, "occurred_at": "2026-08-12T14:03:00+00:00" }

401 Unauthorized   wrong or missing bearer key
422 Unprocessable  validation errors, including a duplicate external_id

Fíjate en el "verified": false de la respuesta correcta. No es un error y no hay ningún indicador para cambiarlo.

Cuándo llamarla

Llama después de que se confirme el pago, no cuando se crea el pedido. Un registro de un checkout abandonado o fallido es una notificación falsa, justo lo que el sistema está diseñado para evitar. En la mayoría de los backends, eso significa el manejador del callback de éxito de tu proveedor de pagos o el job que marca un pedido como pagado.

Envía siempre external_id. Los callbacks de pago se reintentan, las colas vuelven a entregar y los despliegues reinician workers a mitad de un job. Con external_id igual al ID de tu pedido, el segundo intento devuelve 422 y puedes tratarlo como un éxito. Sin él, tarde o temprano mostrarás la misma compra dos veces.

Pon en occurred_at la hora real del pago en lugar de dejar el valor por defecto. Si una cola se atasca veinte minutos, la notificación sigue diciendo lo correcto y el registro cae en su lugar en la página de verificación.

Atribución

La métrica de pedidos asistidos por la prueba social del panel cuenta a los compradores que vieron una notificación antes de comprar, emparejados por ID de visitante dentro de una ventana de 30 días. Con los registros de la API, eso solo funciona si envías el ID.

En el cliente, en el punto en que el visitante empieza el checkout:

const visitor = window.Provedly?.visitorId();
// include it in your checkout form or API call

En el servidor, pásalo como visitor en el registro. Si tu checkout está en un dominio distinto al del widget, lleva el ID en la URL o en tu sesión. Provedly nunca estima la atribución, así que un ID que falta produce una métrica vacía, no una equivocada. Consulta Cómo medir los pedidos asistidos por la prueba social.

Por qué los registros de la API nunca son "Verified"

Provedly puede verificar un webhook de Stripe, Shopify o WooCommerce porque el proveedor firma el contenido con un secreto y Provedly comprueba la firma. Un POST desde tu servidor lleva una clave bearer, que demuestra que quien llama tiene la clave, no que se haya producido un pago. Un comerciante podría crear cien registros con un bucle. Provedly no puede distinguirlo desde fuera, así que los registros de la API nunca reciben la marca Verified. Se muestran en el widget con una etiqueta "Imported" que ningún ajuste, plan ni petición a soporte puede quitar, y la página de verificación pública los muestra bajo "Site owner's backend (API)".

Es una decisión deliberada, y es la razón principal por la que existe Provedly. La mayoría de las herramientas de notificaciones, a octubre de 2026 y según sus propios listados, aceptan entradas de compra arbitrarias y las presentan igual que las reales. Un visitante no tiene forma de saberlo. Con Provedly, solo los pedidos firmados muestran la marca Verified, y la página de verificación lista todas las fuentes. Si quieres la marca Verified, haz pasar los pagos por un proveedor con webhook firmado, como se explica en Webhooks de Stripe para compras verificadas.

Relleno histórico

Para el historial, no recorras con la API los pedidos del año pasado. Usa en su lugar la importación por CSV de la pestaña Data: gestiona los duplicados por nombre y ciudad dentro de una hora, asigna occurred_at a cada fila y guarda sin mostrarlas las filas que quedan fuera de la ventana de antigüedad. La API es para el flujo en vivo. Consulta Cómo importar pedidos pasados desde un CSV.

Preguntas frecuentes

¿Hay un límite de peticiones?

Si publicas un registro por pedido a medida que se producen, no llegarás a ningún límite. Para historial masivo, usa la importación por CSV.

¿Puedo actualizar o borrar un registro después de publicarlo?

Los registros se pueden eliminar desde el panel. No hay endpoint de actualización; publica un registro corregido con un nuevo external_id y borra el anterior.

¿Puedo enviar un precio en una moneda que el widget no conoce?

Sí. price es texto libre de hasta 30 caracteres y se muestra tal como lo envías. Dale formato por tu parte, incluido el símbolo de la moneda.

La API y los webhooks verificados están incluidos en el plan Free: lee la referencia completa o crea un widget.