# Informacje ogólne

> Specyfikacja techniczna integracji przetwarzania płatności kryptowalutowych i wypłat z 2328.io.

Witamy w dokumentacji API 2328.io. Niniejsza dokumentacja referencyjna opisuje, jak zintegrować przetwarzanie płatności kryptowalutowych oraz wypłat z Państwa aplikacją.

## Pierwsze kroki

Aby rozpocząć integrację:

1. Załóż konto sprzedawcy oraz projekt na [2328.io](https://2328.io)
2. Pobierz **project UUID** oraz **API key** z ustawień projektu
3. Wygeneruj osobny **Payout API key**, jeśli planujesz korzystać z wypłat
4. Zapoznaj się z sekcją [Authentication](/docs/authentication), aby dowiedzieć się, jak podpisywać żądania
5. Wykonaj swoje pierwsze wywołanie [Create Payment](/docs/payments)

## Bazowy URL

Wszystkie produkcyjne żądania API korzystają z następującego bazowego URL:

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

> **WARNING:** Wszystkie żądania muszą być wykonywane przez **HTTPS**. Żądania bez HTTPS są blokowane.

## Co możesz robić

Za pomocą API 2328.io możesz:

- **Akceptować płatności kryptowalutowe** — twórz sesje płatności i przekierowuj klientów do hostowanego checkoutu lub Telegram MiniApp
- **Wypłacać środki** — programowo wysyłaj wypłaty z salda sprzedawcy na dowolny adres blockchain
- **Sprawdzanie sald** — zobacz salda kont merchanta dla każdej waluty, ekwiwalenty w USD i kwoty zablokowane przez AML
- **Korzystać ze statycznych portfeli** — generuj trwałe adresy depozytowe powiązane z użytkownikiem lub zamówieniem
- **Pobierać kursy walutowe** — uzyskuj kursy w czasie rzeczywistym dla par fiat i kryptowalut
- **Otrzymywać webhooki** — natychmiast otrzymuj powiadomienia o zmianie statusu płatności
## Limity zapytań

API pozwala na maksymalnie **10 żądań na sekundę na projekt**. Żądania przekraczające limit otrzymują odpowiedź HTTP `429 Too Many Requests` — zastosuj wycofanie i spróbuj ponownie.

## Wybierz odpowiedni wzorzec integracji

| Wymaganie | Zalecany wzorzec | Dlaczego |
|-------------|---------------------|-----|
| Pozwól klientowi wybrać, jak zapłacić | Hostowana kasa | Utwórz płatność i przekieruj do `result.url`; 2328.io prezentuje obecnie dostępne kierunki. |
| Pozwól klientowi pozostać w Twojej własnej kasie | Faktura z bezpośrednim adresem **H2H** | Wyślij `to_currency` i `network` podczas tworzenia płatności; wyświetl otrzymane `address`, `payer_amount` i `qr`. |
| Pobierz dokładnie `25 USDT` lub `0.001 BTC` | Faktura denominowana w kryptowalutach | Umieść kryptowalutę w `currency` i dokładną kwotę dziesiętną w `amount`. |
| Nadaj każdemu użytkownikowi wielokrotnego użytku adres depozytowy | Statyczny portfel | Adres jest stały i może odbierać wiele niezależnych depozytów. |
| Normalizuj przychodzące aktywa do jednej waluty bilansowej | Automatyczne przekonwertowanie | Skonfiguruj zasady projektu w panelu sterowania i wykorzystaj wynik `convert` po zakończeniu konwersji. |
| Wymień istniejący bilans sprzedawcy | Konwersja ręczna | Podgląd z `/v1/convert/price`, następnie wykonaj z `/v1/convert` |
| Wyślij środki na adres blockchain | Wypłata | Użyj osobnego klucza API do wypłat, najpierw dokonaj obliczeń, a następnie uzgodnij status wypłaty. |

> **INFO:** Hosted checkout i H2H to dwie formy prezentacji tego samego API płatności. H2H nie tworzy słabszej ani niepodpisanej płatności: backend nadal tworzy fakturę, 2328.io nadal posiada adres i status, a podpisane webhooki pozostają wiążące dla rozliczenia.

## Nienaruszalne właściwości integracji

Te zasady dotyczą każdej integracji produkcyjnej:

- **Backend only** — trzymaj klucze API z dala od przeglądarek, aplikacji mobilnych, logów, analiz i zrzutów ekranu wsparcia.
- **Decimal strings** — wysyłaj i przechowuj pieniądze jako ciągi znaków. Nigdy nie zaokrąglaj kryptowalut ani kursów wymiany przy użyciu binarnej arytmetyki zmiennoprzecinkowej.
- **Immutable idempotency keys** — wygeneruj `order_id` przed pierwszym żądaniem i zachowaj pełne żądanie z nim. Ponowna próba z tym samym `order_id` może zwrócić oryginalny obiekt zamiast stosować zmienione pola.
- **Webhook-first settlement** — przekierowania, odpytywanie przez klienta, hashe transakcji dostarczone przez użytkowników i limity czasu HTTP nie są dowodem płatności.
- **Verify, deduplicate, then mutate** — zweryfikuj HMAC, atomowo zgłoś rekord idempotencji, zaktualizuj zamówienie/saldo raz i szybko zwróć HTTP 200.
- **Reconciliation** — okresowo sprawdzaj status płatności, portfela statycznego i wypłat, aby utracony webhook nie powodował trwałych niezgodności.
- **Dynamic availability** — waliduj pary waluta/sieć za pomocą `/v1/directions`; obsługiwany aktyw nadal może mieć tymczasowo wyłączony jeden kierunek wpłaty lub wypłaty.
- **Explicit status policy** — zdecyduj, jak Twój produkt obsługuje częściową płatność, nadpłatę, wygaśnięcie, blokadę AML, awaryjną konwersję i niejednoznaczne przekroczenia czasu w górnym strumieniu przed uruchomieniem.

## Zalecane dane do przechowywania

Dla płatności przechowuj co najmniej `uuid`, `order_id`, oryginalną treść żądania, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, najnowsze `payment_status`, `txid`, `payment_amount`, `merchant_amount`, opcjonalny blok `convert` oraz surowy zweryfikowany ładunek webhooka.

Dla portfeli statycznych, przechowuj portfel `uuid`, adres, walutę, sieć, referencję klienta/konta, status i adres URL wywołania zwrotnego oddzielnie od zapisów wpłat. Każda wpłata wymaga własnej transakcji `uuid`, `txid`, statusu, otrzymanej kwoty, kwoty dla sprzedawcy i wyniku konwersji.