Die Records API für Käufe aus deinem eigenen Backend nutzen

Wenn deine Käufe nicht über Stripe Checkout, Shopify oder WooCommerce laufen, kommen sie über die Records API zu Provedly. Ein Server-zu-Server-POST pro Bestellung, authentifiziert mit einem Bearer-Key pro Widget, und der Kauf erscheint innerhalb des Rückblickzeitraums als Benachrichtigung. Auf diesem Weg erstellte Datensätze tragen ein sichtbares Label „Imported“ und nie das Kennzeichen „Verified“, und dieser Beitrag erklärt diese Regel ebenso wie die Mechanik.

Der Endpunkt

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

Der Key wird pro Widget im Tab Data erzeugt und kann dort rotiert werden. Behandle ihn wie jedes Secret: Umgebungsvariable auf dem Server, nie im clientseitigen Code. Der Endpunkt ist nur für Server-zu-Server-Aufrufe gedacht; Aufrufe aus einem Browser sind für jeden mit Devtools sichtbar, und ein geleakter Key erlaubt Fremden, Datensätze in dein Widget zu posten.

Felder

Sende, was du hast. Ein Datensatz nur mit name ist gültig und wird mit dem Standardprodukt des Widgets und ohne Ort angezeigt.

Ein minimales Beispiel

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"
  }'

Antworten:

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

Beachte "verified": false in der Erfolgsantwort. Das ist kein Bug, und es gibt kein Flag, um es umzuschalten.

Wann du sie aufrufst

Ruf sie auf, nachdem die Zahlung bestätigt ist, nicht wenn die Bestellung angelegt wird. Ein Datensatz für einen abgebrochenen oder fehlgeschlagenen Checkout ist eine falsche Benachrichtigung, und genau das soll das System verhindern. In den meisten Backends heißt das: im Handler für den Erfolgs-Callback deines Zahlungsanbieters oder in dem Job, der eine Bestellung als bezahlt markiert.

Sende immer external_id. Zahlungs-Callbacks werden wiederholt, Queues liefern erneut aus, und Deploys starten Worker mitten im Job neu. Wenn external_id auf deine Bestell-ID gesetzt ist, liefert der zweite Versuch 422, und du kannst das als Erfolg behandeln. Ohne sie zeigst du irgendwann denselben Kauf zweimal.

Setz occurred_at auf den tatsächlichen Zahlungszeitpunkt, statt den Standard greifen zu lassen. Wenn sich eine Queue zwanzig Minuten lang staut, sagt der Toast trotzdem das Richtige, und der Datensatz landet auf der Verifizierungsseite an der richtigen Stelle.

Zuordnung

Die Kennzahl proof-unterstützter Bestellungen im Dashboard zählt Käufer, die vor dem Kauf eine Benachrichtigung gesehen haben, zugeordnet über die Besucher-ID innerhalb eines 30-Tage-Fensters. Bei API-Datensätzen funktioniert das nur, wenn du die ID mitsendest.

Auf dem Client, an der Stelle, an der der Besucher den Checkout beginnt:

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

Auf dem Server gibst du sie als visitor im Datensatz weiter. Wenn dein Checkout auf einer anderen Domain liegt als das Widget, trag die ID per URL oder in deiner Session hinüber. Provedly schätzt nie eine Zuordnung, eine fehlende ID führt also zu einer leeren Kennzahl statt zu einer falschen. Siehe Proof-unterstützte Bestellungen messen.

Warum API-Datensätze nie „Verified“ sind

Provedly kann einen Webhook von Stripe, Shopify oder WooCommerce verifizieren, weil der Anbieter die Nutzlast mit einem Secret signiert und Provedly die Signatur prüft. Ein POST von deinem Server trägt einen Bearer-Key, und der beweist, dass der Aufrufer den Key besitzt, nicht dass eine Zahlung stattgefunden hat. Ein Händler könnte hundert Datensätze in einer Schleife per Script erzeugen. Provedly kann den Unterschied von außen nicht erkennen, also bekommen API-Datensätze nie das Verifizierungszeichen. Sie erscheinen im Widget mit einem Label „Imported“, das keine Einstellung, kein Plan und keine Support-Anfrage entfernen kann, und die öffentliche Verifizierungsseite führt sie unter „Site owner's backend (API)“ auf.

Das ist eine bewusste Entscheidung, und sie ist der Hauptgrund, warum es Provedly gibt. Die meisten Benachrichtigungstools akzeptieren, Stand Oktober 2026 und laut ihren Angeboten, beliebige Kaufeinträge und zeigen sie genauso an wie echte. Ein Besucher hat keine Möglichkeit, das zu erkennen. Bei Provedly tragen nur signierte Bestellungen das Verifizierungszeichen, und die Verifizierungsseite listet jede Quelle auf. Wenn du das Verifizierungszeichen willst, leite Zahlungen über einen Anbieter mit signiertem Webhook, wie in Stripe-Webhooks für verifizierte Käufe beschrieben.

Nachträglich befüllen

Für die Historie solltest du die API nicht in einer Schleife über die Bestellungen des letzten Jahres laufen lassen. Nutze stattdessen den CSV-Import im Tab Data; er erkennt Duplikate über Name und Stadt innerhalb einer Stunde, setzt occurred_at pro Zeile und speichert Zeilen außerhalb des Rückblickzeitraums, ohne sie anzuzeigen. Die API ist für den laufenden Strom gedacht. Siehe Frühere Bestellungen per CSV importieren.

Häufige Fragen

Gibt es ein Rate Limit?

Poste einen Datensatz pro Bestellung, wenn sie passiert, und du erreichst kein Limit. Für umfangreiche Historie nutze den CSV-Import.

Kann ich einen Datensatz nach dem Posten ändern oder löschen?

Datensätze lassen sich im Dashboard entfernen. Einen Update-Endpunkt gibt es nicht; poste einen korrigierten Datensatz mit neuer external_id und lösche den alten.

Kann ich einen Preis in einer Währung übergeben, die das Widget nicht kennt?

Ja. price ist Freitext mit bis zu 30 Zeichen und wird so angezeigt, wie du ihn sendest. Formatiere ihn auf deiner Seite, einschließlich Währungssymbol.

Die API und verifizierte Webhooks sind im Free-Plan enthalten: vollständige Referenz lesen oder ein Widget anlegen.