Bisher nutzte ein Backend, das Käufe an Provedly sendete, einen Schlüssel pro Widget, erzeugt im Data-Tab des jeweiligen Widgets. Für ein Widget funktioniert das. Für ein Unternehmen mit mehreren Websites oder mehreren Widgets bedeutete es mehrere Secrets, die gespeichert und rotiert werden müssen. Die Records-API akzeptiert jetzt auch einen Account-API-Schlüssel, denselben provedly_-Schlüssel, den die REST-API und der MCP-Server verwenden. Ein Secret kann also jedes Widget im Konto abdecken.
Dieser Beitrag erklärt, wann sich der Umstieg lohnt, wie er geht und was gleich bleibt. Die vollständige Feldreferenz steht weiterhin im Leitfaden zur Records-API.
Was sich geändert hat und was nicht
Der Endpoint ist derselbe:
POST https://provedly.app/api/v1/widgets/{token}/records
Authorization: Bearer <widget key or account key>
Content-Type: application/json
Die Felder sind dieselben: name, city, state, country, product_name, price, avatar_url, external_id, occurred_at und visitor. Doppelte external_id-Werte werden weiterhin pro Widget abgelehnt, Wiederholungen bleiben also sicher.
Geändert hat sich der Header. Du kannst jetzt statt des widgeteigenen Schlüssels einen Account-Schlüssel mit der Zugriffsstufe Read and write senden. Ein Account-Schlüssel mit reinem Lesezugriff wird an diesem Endpoint abgelehnt, weil das Hinzufügen eines Eintrags ein Schreibvorgang ist.
Widget-Schlüssel funktionieren weiter. Nichts geht kaputt, wenn du eine bestehende Integration so lässt, wie sie ist.
Wann welcher Schlüssel
Behalte den Widget-Schlüssel, wenn die Integration immer nur in ein Widget schreibt und dir der enge Geltungsbereich gefällt. Ein geleakter Widget-Schlüssel kann nur Einträge zu diesem einen Widget hinzufügen.
Nimm einen Account-Schlüssel, wenn ein Dienst in mehrere Widgets schreibt, zum Beispiel ein Checkout-Service für drei Storefronts mit jeweils eigenem Widget. Ein Secret in der Umgebung, das Widget wird über den Token in der URL gewählt.
Wenn du umsteigst, erstelle unter Settings, im Bereich API keys, einen eigenen Schlüssel für den Dienst und benenne ihn nach dem Dienst: „Checkout service, production“. Verwende nicht den Schlüssel wieder, den du deinem KI-Assistenten gegeben hast. Mit getrennten Schlüsseln kannst du einen widerrufen, ohne den anderen kaputtzumachen.
Ein durchgerechnetes Beispiel
Ein Dienst, der bezahlte Bestellungen für zwei Storefronts verarbeitet, könnte im Groben so aussehen:
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}`);
}
Ruf ihn auf, nachdem die Zahlung bestätigt ist, niemals beim Anlegen der Bestellung. Ein Eintrag für einen Checkout, der später fehlschlägt, ist eine Benachrichtigung über einen Kauf, der nie stattgefunden hat.
Das Feld visitor überträgt die Provedly-Besucher-ID aus dem Browser. Erst dadurch zählt die Bestellung in deinen Statistiken zu den durch Proof unterstützten Bestellungen. Ohne sie wird der Eintrag trotzdem angezeigt, die Attributionskennzahl lässt ihn einfach weg. Siehe durch Proof unterstützte Bestellungen messen.
Wie diese Einträge erscheinen
Über die API gesendete Einträge behalten die Quelle API, egal welchen Schlüssel du verwendest. Sie erscheinen im Widget mit einem sichtbaren „Imported“-Label und ohne die Kennzeichnung „Verifiziert“, und die öffentliche Verifizierungsseite zählt sie unter „Site owner's backend (API)“.
Laufen deine Bestellungen über Stripe, Shopify oder WooCommerce, ist die signierte Webhook-Verbindung der bessere Weg: Diese Einträge kommen verifiziert an, ganz ohne Code auf deiner Seite. Die Records-API ist für alles, was diese Verbindungen nicht abdecken. Warum dein Assistent keinen Kauf verifizieren kann erklärt, warum ein API-Aufruf, egal wie er authentifiziert ist, keinen verifizierten Eintrag erzeugen kann.
Mit deinem Assistenten nachprüfen
Dasselbe Konto ist über den MCP-Server auch für deinen KI-Assistenten sichtbar, mit einem eigenen Schlüssel. Nach dem Deployment der Änderung kannst du fragen:
Liste meine Widgets auf und zeig mir die Statistiken für den letzten Tag.
und die Antwort mit deinem eigenen Bestellprotokoll vergleichen. Im Prompt-Kochbuch findest du weitere Beispiele. Willst du die Integration zuerst von Hand testen, kann der Assistent add_record für eine einzelne echte Bestellung aufrufen. So siehst du schnell, wie ein Eintrag genau dargestellt wird.
Häufige Fragen
Kann ich mit einem Account-Schlüssel in ein Widget eines anderen Kontos schreiben?
Nein. Ein Account-Schlüssel funktioniert nur für Widgets, die zu seinem eigenen Konto gehören. Ein Token aus einem anderen Konto wird abgelehnt.
Sollte ich meine Widget-Schlüssel jetzt rotieren?
Nur wenn du auf einen Account-Schlüssel umsteigst. Sobald der Dienst den neuen Schlüssel nutzt, rotiere den alten Widget-Schlüssel im Data-Tab des Widgets, damit er nicht mehr funktioniert.
Gibt es einen Bulk-Endpoint für die Historie?
Nein. Für vergangene Bestellungen nutze den CSV-Import im Data-Tab des Widgets, beschrieben in vergangene Bestellungen per CSV importieren. Die API ist für den laufenden Strom.
Die Records-API und Account-Schlüssel gibt es im Free-Plan: Konto erstellen.