Developers

Zlecenia i idempotencja

Utworzenie zlecenia blokuje kurs i przypisuje adres depozytowy. To jedyne miejsce, gdzie błąd integracji przesuwa pieniądze: idempotentność nie jest tam wygodą.

Opublikowany kontrakt, jeszcze nieotwarty

Te endpointy nie są obecnie udostępniane. Są udokumentowane, abyś mógł zbudować integrację z wyprzedzeniem; ich kształt jest ustalony, a każda zmiana przełamująca kompatybilność przejdzie przez nową wersję i wpis w changelogu.

POST/api/v1/ordersPublished contract, not open

Utwórz zlecenie

Blokuje kurs i zwraca dedykowany adres depozytowy. Zlecenie zawiera zestawienie jako zablokowane: jest odtwarzalne, co pozwala odtworzyć dokładną zastosowaną cenę nawet miesiące później. Nagłówek Idempotency-Key jest wymagany.

Uwierzytelnianie: Authorization: Bearer … Zobacz uwierzytelnianie

Parametry

Parametry
Pole	Typ	Opis
`quoteId`wymagane	string	Identyfikator zaakceptowanej wyceny.
`beneficiary`wymagane	object	Pola narzucone przez schemat kanału. Nazwa musi odpowiadać zweryfikowanej tożsamości: brak wypłat na rzecz osób trzecich.
`networkId`wymagane	string	Sieć, na którą zostanie wysłany depozyt. Określa zwracany adres, a w niektórych sieciach obowiązkowe memo.

Żądaniebash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

Odpowiedź — opublikowany kontraktjson

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

Memo jest null w większości sieci i obowiązkowe w XRP, Stellar i TON. Pominięcie go tam powoduje utratę środków: traktuj pole jako wymagane, gdy tylko nie jest null.

Możliwe błędy: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Pełny katalog

GET/api/v1/orders/{reference}Published contract, not open

Odczytaj zlecenie

Bieżący stan i historia przejść z znacznikami czasu. Historia jest źródłem prawdy: jest tylko do dopisywania, nigdy nie jest przepisywana, i to ona odpowiada na pytanie „dlaczego moje zlecenie przeszło do tego stanu w tym czasie”.

Uwierzytelnianie: Authorization: Bearer … Zobacz uwierzytelnianie

Żądaniebash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Odpowiedź — opublikowany kontraktjson

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Możliwe błędy: unauthorized, not_found. Pełny katalog

Idempotentność

Żądanie utworzenia, które przekroczy limit czasu w sieci, nie informuje, czy zlecenie zostało utworzone. Bez klucza idempotentności masz tylko dwie złe opcje: ponowić i ryzykować dwa zlecenia lub nie ponowić i ryzykować żadne.

Nagłówekhttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Jeden klucz na intencję

Klucz identyfikuje intencję „utwórz to zlecenie”, nie żądanie HTTP. Unikalny identyfikator po Twojej stronie: identyfikator koszyka, UUID wygenerowany przed wywołaniem, nigdy licznik.

Powtórzenie zwraca oryginalną odpowiedź

Powtórzenie tego samego klucza z tym samym ciałem zwraca odpowiedź pierwszego żądania, z tym samym statusem HTTP. To czyni ponowienie bezpiecznym, także po przekroczeniu limitu czasu.

Ten sam klucz, inne ciało: konflikt

Odpowiedź jest jawnym konfliktem. Jeśli treść się zmienia, klucz musi się zmienić: w przeciwnym razie nikt nie może stwierdzić, które z dwóch zleceń należy powtórzyć.

Przechowywanie przez 24 godziny

Po tym czasie klucz jest zapominany, a powtórzenie utworzyłoby nowe zlecenie. Ponów w oknie lub sprawdź stan za pomocą endpointu odczytu.

Memo, w sieciach, które go wymagają

W sieciach XRP, Stellar i TON adres depozytowy nie wystarczy: dodatkowy identyfikator wskazuje ostatecznego odbiorcę. To najkosztowniejsza przyczyna incydentów w integracji off-ramp.

Depozyt bez memo to depozyt utracony

Pole memo ma wartość null w większości sieci i nie jest null w tych, które go wymagają. Traktuj je jako obowiązkowe, gdy tylko nie jest null, i wyświetlaj z taką samą wagą jak adres. Depozyt bez memo na współdzielonym adresie wymaga ręcznego odzyskania, co nie zawsze się udaje.

Stany zlecenia

Poniższe stany to te, które może zaobserwować Twoja integracja. Przejścia są opatrzone znacznikiem czasu i dołączane, nigdy nie przepisywane: historia odpowiada na pytanie „dlaczego moje zlecenie przeszło do tego stanu w tym czasie”.

Stany zlecenia
Stan	Co oznacza
`QUOTE_LOCKED`	Kurs jest zamrożony. Zlecenie oczekuje na dane beneficjenta lub weryfikację tożsamości.
`AWAITING_DEPOSIT`	Adres depozytowy jest przypisany i okno depozytowe jest otwarte. To jedyny moment na wysłanie środków.
`DEPOSIT_DETECTED`	Transakcja przychodząca jest widoczna w sieci, ale jeszcze niepotwierdzona. Uspokój użytkownika, niczego nie dostarczaj.
`CONFIRMING`	Potwierdzenia się kumulują. Wymagana liczba zależy od sieci, nie od kwoty.
`DEPOSIT_CONFIRMED`	Depozyt jest zabezpieczony. Od tego momentu oceniane są zasady zgodności i ponownej wyceny.
`UNDERPAID`	Otrzymana kwota jest niższa od oczekiwanej poza tolerancją. Trzy możliwości: doładowanie, kontynuacja z otrzymaną kwotą lub zwrot środków.
`OVERPAID`	Otrzymana kwota przekracza oczekiwaną. Kwota początkowa pozostaje po zablokowanym kursie, nadwyżka jest obsługiwana osobno.
`PAYOUT_QUEUED`	Przelew jest w kolejce. Kolejka gwarantuje, że wypłata zostanie wysłana raz, nawet jeśli kilka procesów uruchomi się równolegle.
`PAYOUT_SENT`	Przelew został wysłany kanałem płatności. Wysłanie nie oznacza otrzymania: ostateczne opóźnienie zależy od banku beneficjenta.
`COMPLETED`	Rozliczenie potwierdzone przez kanał płatności. Stan końcowy.
`PAYOUT_FAILED`	Kanał płatności odrzucił lub zwrócił przelew. Brak automatycznych ponowień: przyczyna prawie zawsze leży w szczegółach.
`REFUNDED`	Środki zwrócone na adres źródłowy, pomniejszone o opłaty sieciowe. Stan końcowy.