# Agenten-Workflow

Von der Wallet-Anmeldung bis zur bezahlten Rechnung, der vollständige Weg für einen automatisierten Agenten.

Source: https://docs.invoise.me/de/agents/integration/

Dies ist der Einrichtungsweg für einen Agenten mit einer [Wallet-Sitzung](https://docs.invoise.me/de/agents/sign-in/). 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:

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

{"name":"My merchant","email":"owner@example.com"}
```

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

```http
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](https://docs.invoise.me/de/payments/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](https://docs.invoise.me/de/payments/solana-and-tron/).

## 3. Einen Shop-API-Schlüssel ausstellen

Verwenden Sie Ihre Sitzung, um [einen Schlüssel zu erstellen](https://docs.invoise.me/de/integration/api-keys/) 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](https://docs.invoise.me/de/payments/deposits-and-invoices/#mehrere-token-oder-netzwerke-anbieten).

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:

```bash
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](https://docs.invoise.me/de/integration/webhooks/).

Lesen Sie [Rechnungs- und Einzahlungsstatus](https://docs.invoise.me/de/payments/status/), 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](https://docs.invoise.me/llms.txt) für den Seitenindex und [OpenAPI](https://docs.invoise.me/openapi.json) für strukturierte Verträge. [Lesewerkzeuge](https://docs.invoise.me/de/agents/reading/) listet Markdown- und Volltextexporte auf.