# Allgemeine Informationen

> Technische Spezifikation für die Integration der Kryptowährungs-Zahlungsabwicklung und -Auszahlungen mit 2328.io.

Willkommen zur Dokumentation der 2328.io API. Diese Referenz beschreibt, wie Sie die Verarbeitung von Kryptowährungszahlungen und Auszahlungen in Ihre Anwendung integrieren.

## Erste Schritte

So starten Sie mit der Integration:

1. Erstellen Sie ein Händlerkonto und ein Projekt auf [2328.io](https://2328.io)
2. Beziehen Sie Ihre **Projekt-UUID** und Ihren **API-Schlüssel** aus den Projekteinstellungen
3. Erzeugen Sie einen separaten **Payout-API-Schlüssel**, falls Sie Auszahlungen nutzen möchten
4. Lesen Sie den Abschnitt [Authentifizierung](/docs/authentication), um zu erfahren, wie Anfragen signiert werden
5. Führen Sie Ihren ersten Aufruf [Zahlung erstellen](/docs/payments) aus

## Basis-URL

Alle Produktiv-API-Anfragen verwenden die folgende Basis-URL:

```
https://api.2328.io/api
```

> **WARNING:** Alle Anfragen müssen über **HTTPS** erfolgen. Anfragen ohne HTTPS werden blockiert.

## Was Sie tun können

Mit der 2328.io API können Sie:

- **Krypto-Zahlungen akzeptieren** — Zahlungssitzungen erstellen und Kunden zu einem gehosteten Checkout oder einer Telegram MiniApp weiterleiten
- **Mittel auszahlen** — programmatisch Auszahlungen von Ihrem Händlerguthaben an eine beliebige Blockchain-Adresse senden
- **Guthaben prüfen** — sehen Sie die Händlerguthaben pro Währung, USD-Äquivalente und durch AML gesperrte Beträge
- **Statische Wallets verwenden** — permanente Einzahlungsadressen erzeugen, die an einen Benutzer oder eine Bestellung gebunden sind
- **Wechselkurse abrufen** — Kurse in Echtzeit für Fiat- und Krypto-Paare ermitteln
- **Webhooks empfangen** — sofort benachrichtigt werden, wenn sich der Status einer Zahlung ändert
## Ratenbegrenzung

Die API erlaubt bis zu **10 Anfragen pro Sekunde pro Projekt**. Anfragen, die das Limit überschreiten, erhalten eine HTTP-`429 Too Many Requests`-Antwort — warten Sie ab und versuchen Sie es erneut.

## Wählen Sie das richtige Integrationsmuster

| Anforderung | Empfohlenes Muster | Warum |
|-------------|---------------------|-----|
| Lassen Sie den Kunden wählen, wie er bezahlen möchte | Hosted checkout | Erstellen Sie eine Zahlung und leiten Sie weiter zu `result.url`; 2328.io zeigt derzeit verfügbare Richtungen an. |
| Halten Sie den Kunden in Ihrem eigenen Checkout | Direktadresse **H2H** invoice | Senden Sie `to_currency` und `network` beim Erstellen der Zahlung; geben Sie die zurückgegebenen `address`, `payer_amount` und `qr` aus. |
| Belasten Sie genau `25 USDT` oder `0.001 BTC` | In Kryptowährung nominierte invoice | Legen Sie die Kryptowährung in `currency` und den genauen Dezimalbetrag in `amount` ab. |
| Geben Sie jedem Benutzer eine wiederverwendbare Einzahlungsadresse | Static wallet | Die Adresse ist permanent und kann viele unabhängige Einzahlungen empfangen. |
| Normalisieren Sie eingehende Vermögenswerte in eine Bilanzwährung | Auto-convert | Konfigurieren Sie Projektregeln im Dashboard und verwenden Sie das `convert`-Ergebnis, wenn die Konvertierung abgeschlossen ist. |
| Tauschen Sie ein bestehendes merchant-Guthaben | Manual convert | Vorschau mit `/v1/convert/price`, dann ausführen mit `/v1/convert`. |
| Senden Sie Gelder an eine Blockchain-Adresse | Auszahlung | Verwenden Sie den separaten Payout-API-Schlüssel, berechnen Sie zuerst und gleichen Sie anschließend den Auszahlungsstatus ab. |

> **INFO:** Hosted checkout und H2H sind zwei Darstellungen derselben Payment-API. H2H erstellt keine schwächere oder unsignierte Zahlung: Das backend erstellt weiterhin das invoice, 2328.io besitzt weiterhin die Adresse und den Status und signierte webhooks bleiben für settlement autoritativ.

## Integrationsinvarianten

Diese Regeln gelten für jede production-Integration:

- **Nur Backend** — halten Sie API-Schlüssel aus Browsern, mobilen Anwendungen, Protokollen, Analysen und Support-Screenshots heraus.
- **Dezimalstrings** — senden und speichern Sie Geld als Strings. Runden Sie niemals Kryptowährungen oder Wechselkurse mit binärer Fließkommaarithmetik.
- **Unveränderliche idempotency-Schlüssel** — erzeugen Sie `order_id` vor der ersten Anfrage und speichern Sie die vollständige Anfrage damit. Ein retry mit demselben `order_id` kann das ursprüngliche Objekt zurückgeben, anstatt geänderte Felder anzuwenden.
- **Webhook-zuerst settlement** — Weiterleitungen, Client-Polling, von Benutzern bereitgestellte Transaktions-Hashes und HTTP-Timeouts sind kein Zahlungsnachweis.
- **Überprüfen, duplizieren, dann ändern** — überprüfen Sie das HMAC, beanspruchen Sie einen idempotency-Datensatz atomar, aktualisieren Sie die Bestellung/den Saldo einmal und geben Sie schnell HTTP 200 zurück.
- **Reconciliation** — fragen Sie regelmäßig den Zahlungs-, Static-Wallet- und Auszahlungsstatus ab, damit ein verlorenes webhook keinen dauerhaften Konflikt hinterlassen kann.
- **Dynamische Verfügbarkeit** — validieren Sie Währungs-/Netzwerk-Paare mit `/v1/directions`; ein unterstützter Vermögenswert kann trotzdem vorübergehend in einer Einzahlungs- oder Auszahlung Richtung deaktiviert sein.
- **Explizite Statusrichtlinie** — entscheiden Sie, wie Ihr Produkt Teilzahlungen, Überzahlungen, Ablauf, AML-Sperre, Conversion fallback und mehrdeutige Upstream-Timeouts behandelt, bevor es live geht.

## Empfohlene zu speichernde Daten

Für Zahlungen speichern Sie mindestens `uuid`, `order_id`, den ursprünglichen Anforderungstext, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, den neuesten `payment_status`, `txid`, `payment_amount`, `merchant_amount`, den optionalen `convert`-Block und die verifizierten Rohdaten webhook payload.

Für static wallets halten Sie die Wallet `uuid`, Adresse, Währung, Netzwerk, Kunden-/Kontoreferenz, Status und Callback-URL getrennt von Einzahlungsaufzeichnungen. Jede Einzahlung benötigt ihre eigene Transaktion `uuid`, `txid`, Status, erhaltenen Betrag, merchant Betrag und Konversionsergebnis.