Agenten-Workflow

Dies ist der Einrichtungsweg für einen Agenten mit einer Wallet-Sitzung. Wenn Sie bereits eine Shop-ID und einen API-Schlüssel haben, gehen Sie direkt zu Schritt 4.

Alle unten stehenden JSON-Schreibvorgänge benötigen Content-Type: application/json, Ihr Sitzungs-Bearer-Token und einen gespeicherten, für die Aktion eindeutigen Idempotency-Key.

1. Einen Händler auswählen

Lesen Sie GET /api/v1/me. Wenn user.onboarding_required true ist, fragen Sie zuerst Ihren Menschen nach dessen E-Mail-Adresse und schließen Sie dann die Einrichtung ab:

POST /api/v1/onboarding
Content-Type: application/json

{"name":"My merchant","email":"[email protected]"}

Ein Konto, das sich nur mit einer Wallet angemeldet hat, muss email senden; ohne sie lautet die Antwort 400 email_required. Eine fehlerhafte Adresse gibt invalid_email zurück, eine Wegwerfadresse disposable_email, und eine E-Mail-Adresse, die bereits zu einem anderen Konto gehört, identity_already_linked. Die E-Mail-Adresse wird zu einer Anmeldemethode desselben Kontos. Invoise sendet der Person einen Hinweis: Sie öffnet das Dashboard, meldet sich mit dieser E-Mail-Adresse per Einmalcode an und landet in dem Konto, das Sie erstellt haben.

Dies gibt {"completed":true} zurück, nicht die Händler-ID. Rufen Sie als Nächstes GET /api/v1/merchants auf und speichern Sie die id des gewünschten Händlers.

Ein wiederkehrendes Konto kann zu mehreren Händlern gehören. Wählen Sie ausdrücklich; verwenden Sie nicht stillschweigend den ersten Eintrag. Verwenden Sie POST /merchants nicht für das Onboarding — es gibt forbidden zurück.

2. Einen Shop erstellen

POST /api/v1/merchants/{merchant_id}/shops
Content-Type: application/json

{
  "name": "Agent payments",
  "sandbox": true,
  "recipient": "<your-payout-address>"
}

Speichern Sie die zurückgegebene id als shop_id. Starten Sie zum Testen in der Sandbox; erstellen Sie danach einen separaten Live-Shop mit sandbox: false.

Der optionale EVM-delegate ist eine von Ihnen kontrollierte Abwicklungs-Wallet. Legen Sie ihn nur fest, wenn Sie einen benötigen. Verwenden Sie niemals eine Börsen-Einzahlungsadresse für diese Rolle.

Sie können den Empfänger und den Delegierten später mit PATCH /api/v1/shops/{shop_id} ändern. Bereits erstellte Rechnungen und Adressen behalten diejenigen, mit denen sie erstellt wurden.

Ein Live-Shop kann stattdessen in die Invoise-Wallet des Kontos zahlen: senden Sie "payout_target":"wallet" ohne recipient. Ihr Mensch richtet diese Wallet im Dashboard ein; bis dahin gibt das Erstellen einer Rechnung 400 wallet_not_ready zurück. Solana und Tron benötigen einen eigenen Empfänger; siehe Solana und Tron.

3. Einen Shop-API-Schlüssel ausstellen

Verwenden Sie Ihre Sitzung, um einen Schlüssel zu erstellen mit read und write. Speichern Sie das zurückgegebene ivk_-Token in Ihrem Secret-Store und verwenden Sie es dann für die folgenden Zahlungsaufrufe.

4. Eine Rechnung erstellen

1. Lesen Sie GET /api/v1/networks. Verwenden Sie ein aktiviertes Netzwerk und einen einsatzbereiten Token mit dessen tatsächlicher Adresse und Dezimalstellen.
2. Speichern Sie einen Idempotenzschlüssel mit der Rechnung in Ihrem System, bevor Sie die Anfrage senden.
3. Rufen Sie POST /api/v1/shops/{shop_id}/invoices auf:

Feld	Wert
chain_id	Ausgewählte Netzwerk-ID aus der API; eine Ganzzahl.
token	Ausgewählte Token-Adresse aus der API.
amount	Rechnungsbetrag in den kleinsten Einheiten des Tokens; ein ganzzahliger String.
external_id	Optionaler Verweis auf einen Datensatz in Ihrem System.

Für eine wiederverwendbare Aufladeadresse rufen Sie /deposits ohne amount auf. Damit der Zahlende zwischen mehreren Token oder Netzwerken wählen kann, senden Sie assets anstelle von chain_id und token; siehe Einzahlungen und Rechnungen.

Wiederholen Sie nach einem Timeout dieselbe Anfrage mit demselben Schlüssel. external_id allein verhindert keine Duplikate.

5. Auf die Adresse warten, dann auf die Zahlung

Speichern Sie id aus der 202-Antwort. Fragen Sie ab:

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

Warten Sie auf eine nicht leere address und teilen Sie dann payment_url. Fragen Sie diesen selben Endpunkt weiterhin für status und received ab. Erhalten Sie Änderungsbenachrichtigungen über Webhooks.

Lesen Sie Rechnungs- und Einzahlungsstatus, bevor Sie die Rechnungszahlung erfassen: funded, settled, Stornierung und wiederverwendbare Einzahlungen haben unterschiedliche Bedeutungen. Erfassen Sie jedes Geschäfts-Update einmalig.

Dokumentation ohne Browser lesen

Beginnen Sie bei llms.txt für den Seitenindex und OpenAPI für strukturierte Verträge. Lesewerkzeuge listet Markdown- und Volltextexporte auf.