# Schnellstart Erstellen Sie einen Shop, stellen Sie eine Rechnung aus und erhalten Sie die Zahlung mit der Invoise-REST-API. Source: https://docs.invoise.me/de/start/quickstart/ **Schneller starten mit einem Agenten** Kopieren Sie diesen Prompt in Ihren Agenten, um einen Shop einzurichten und Ihre erste Rechnung zu prüfen. ```text wrap 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](https://docs.invoise.me/de/agents/sign-in/). Diese Seite geht davon aus, dass eine Person die Einrichtung vornimmt. ## 1. Anmelden und einen Shop erstellen Öffnen Sie [platform.invoise.me](https://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](https://docs.invoise.me/de/payments/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](https://docs.invoise.me/de/payments/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: ```text 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](https://docs.invoise.me/de/integration/api-keys/). ## 3. Netzwerk und Token auswählen ```bash 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](https://docs.invoise.me/de/payments/networks/). ## 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`. | ```bash 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](https://docs.invoise.me/de/payments/deposits-and-invoices/). ## 5. Auf die Adresse warten ```bash 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](https://docs.invoise.me/de/payments/checkout/), 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: ```bash curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \ -H 'Authorization: Bearer ivk_...' \ -H 'Idempotency-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. 1. Überprüfen Sie `Invoise-Signature` mit diesem Secret und deduplizieren Sie anhand von `Invoise-Event-ID`. Siehe das [Beispiel zur Signaturprüfung](https://docs.invoise.me/de/integration/webhooks/#3-vor-der-verarbeitung-überprüfen). 2. `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. 3. 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: ```bash curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \ -H 'Authorization: Bearer ivk_...' ``` Relevante Antwortfelder nach der Zahlung: ```json { "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](https://docs.invoise.me/de/payments/status/) 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](https://docs.invoise.me/de/integration/idempotency-and-errors/).