Schnellstart

Kopieren Sie diesen Prompt in Ihren Agenten, um einen Shop einzurichten und Ihre erste Rechnung zu prüfen.

Help me integrate Invoise into my project. Read https://docs.invoise.me/llms.txt, https://docs.invoise.me/openapi.json and https://docs.invoise.me/agents/integration.md.

Use my existing access or help me sign in and create a merchant, shop and API key. If you sign in with a wallet, ask me for my email before creating the merchant. Ask me for the recipient address before creating the shop. Read available networks, tokens, decimals and fees from the API.

Start in Sandbox: create an invoice, get payment_url, connect webhooks with signature verification and deduplication, and check payment through GET. Save Idempotency-Key before sending requests. Finish with the test result and what is needed to accept real payments.

Dies ist der normale Weg, um Invoise in eine Website oder ein Backend zu integrieren: melden Sie sich als Person an, richten Sie den Shop im Dashboard ein, und lassen Sie dann Ihren Server die API mit einem Schlüssel aufrufen.

Sie bauen einen unbeaufsichtigten Agenten ohne Browser und ohne E-Mail? Gehen Sie stattdessen zu Agent-Anmeldung. Diese Seite geht davon aus, dass eine Person die Einrichtung vornimmt.

1. Anmelden und einen Shop erstellen

Öffnen Sie platform.invoise.me und melden Sie sich mit einem E-Mail-Code oder Google an. Bei der ersten Anmeldung erstellen Sie einen Händler; ein neuer Händler hat noch keine Shops, also erstellen Sie einen.

Ein Shop benötigt einen Empfänger — die Wallet, die Ihr Geld erhält — oder zahlt in Ihre Invoise-Wallet. Sie können den Empfänger und den optionalen Delegierten später ändern; bereits erstellte Rechnungen und Adressen behalten diejenigen, mit denen sie erstellt wurden.

Erstellen Sie einen Sandbox-Shop, wenn Sie ohne echte Mittel üben möchten. Siehe Sandbox.

2. Einen API-Schlüssel erstellen

Erstellen Sie im Shop einen Schlüssel mit den Bereichen read und write. Er beginnt mit ivk_ und wird nur einmal angezeigt, speichern Sie ihn also sofort.

Ihr Server sendet ihn bei jeder Anfrage:

Authorization: Bearer ivk_...

Der Schlüssel funktioniert nur für einen Shop und kann nicht auf Ihr Konto oder Ihr Team zugreifen. Siehe API-Schlüssel.

3. Netzwerk und Token auswählen

curl https://platform.invoise.me/api/v1/networks

Entnehmen Sie chain_id, die Token-Adresse und decimals der Antwort. Wählen Sie ein für Ihren Händler aktiviertes Netzwerk und einen einsatzbereiten Token. Verfügbare Assets ändern sich; hinterlegen Sie ihre Liste nicht fest im Code. Siehe Netzwerke und Token.

4. Eine Rechnung ausstellen

Beträge sind ganzzahlige Strings in den kleinsten Einheiten des Tokens. Bei 6 Dezimalstellen sind 10000000 10 Token.

Legen Sie diese Umgebungsvariablen vor der Anfrage fest:

Variable	Wert
`CHAIN_ID`	Die `chain_id` des ausgewählten Netzwerks aus der API.
`TOKEN_ADDRESS`	Die `tokens[].address` des ausgewählten Tokens in diesem Netzwerk.
`AMOUNT`	Rechnungsbetrag in den kleinsten Einheiten, berechnet anhand von `tokens[].decimals`.

curl -X POST https://platform.invoise.me/api/v1/shops/{shop_id}/invoices \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2a8b1f47-6d0c-4a1f-8f0b-4f2c9f3a77d2' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\"}"

Ersetzen Sie {shop_id} durch Ihre Shop-ID. Erzeugen und speichern Sie einen eindeutigen Idempotency-Key für diese Rechnung; der Beispielschlüssel dient nur als Beispiel.

Die Antwort ist 202 Accepted: Speichern Sie ihre id als issuance_id. 202 bedeutet, dass die Erstellung akzeptiert wurde, nicht dass der Kunde bereits bezahlt hat.

Möchten Sie eine wiederverwendbare Aufladeadresse ohne festen Betrag? Rufen Sie stattdessen /deposits auf. Siehe Einzahlungen und Rechnungen.

5. Auf die Adresse warten

curl https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id} \
  -H 'Authorization: Bearer ivk_...'

Fragen Sie ab, bis eine Adresse zurückkommt, und leiten Sie den Zahlenden dann zur payment_url aus dieser Antwort weiter. Das ist die gehostete Zahlungsseite, mit der Adresse, einem QR-Code und bereits eingebautem Live-Status.

6. Prüfen, ob bezahlt wurde

Eine Rechnung ist bezahlt, wenn ihr status funded oder settled ist. funded bedeutet, dass der erforderliche Betrag bestätigt ist; settled bedeutet, dass die Rechnung on-chain abgeschlossen wurde. Lesen Sie den Status über die API und erhalten Sie Änderungsbenachrichtigungen über Webhooks.

Über einen Webhook

Registrieren Sie vor Ihrer ersten Zahlung den Endpunkt Ihres Servers:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-webhook-key>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Ersetzen Sie die URL durch Ihren öffentlichen HTTPS-Endpunkt und speichern Sie secret aus der Antwort.

Überprüfen Sie Invoise-Signature mit diesem Secret und deduplizieren Sie anhand von Invoise-Event-ID. Siehe das Beispiel zur Signaturprüfung.
transfer.confirmed meldet einen bestätigten eingehenden Transfer. Entnehmen Sie data.issuance_id und lesen Sie die Rechnung über das untenstehende GET: ein einzelner Transfer deckt möglicherweise nur einen Teil des Betrags ab.
Wenn status funded oder settled ist und cancelled_at null ist, markieren Sie die Bestellung einmalig als bezahlt. Separat bestätigt payout.confirmed die vollständige Abrechnung unter Berücksichtigung der Auszahlung an den Empfänger.

Über die API

Lesen Sie die Rechnung von Ihrem Backend aus:

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'

Relevante Antwortfelder nach der Zahlung:

{
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "cancelled_at": null
}

Der vollständige Rechnungsbetrag ist bestätigt. Markieren Sie die Bestellung als bezahlt; ein weiteres GET oder ein Webhook darf sie nicht ein zweites Mal gutschreiben.

Bei open warten Sie weiter: die vollständige Zahlung ist noch nicht eingegangen. Sie können alle 3–5 Sekunden abfragen und bei langen Wartezeiten langsamer werden. registering und reconciling bedeuten ebenfalls keinen Erfolg. Wenn cancelled_at gesetzt ist, behandeln Sie die bezahlte, stornierte Bestellung gesondert.

Siehe Rechnungs- und Einzahlungsstatus für alle Zustände und einzahlungsspezifisches Verhalten.

Eine Regel, die Sie sich merken sollten

Das Erstellen einer Rechnung oder Einzahlung erfordert Idempotency-Key. Bewahren Sie den Schlüssel auf: wenn eine Anfrage abläuft und Sie nicht sicher sind, ob sie erfolgreich war, senden Sie dieselbe Anfrage mit demselben Schlüssel erneut. Sie erhalten das ursprüngliche Ergebnis statt einer zweiten Rechnung. Siehe Idempotenz und Fehler.