Developers

Ordini e idempotenza

La creazione di un ordine blocca il tasso e assegna un indirizzo di deposito. È il punto in cui un errore di integrazione sposta denaro: l'idempotenza non è una comodità lì.

Contratto pubblicato, non ancora aperto

Questi endpoint non sono esposti oggi. Sono documentati così puoi costruire la tua integrazione in anticipo; la loro forma è definita, e qualsiasi modifica sostanziale passerà attraverso una nuova versione e una voce nel changelog.

POST/api/v1/ordersPublished contract, not open

Crea un ordine

Blocca il tasso e restituisce un indirizzo di deposito dedicato. L'ordine riporta la ripartizione come bloccata: è riproducibile, il che ti permette di ricostruire il prezzo esatto applicato anche mesi dopo. L'header Idempotency-Key è obbligatorio.

Autenticazione: Authorization: Bearer … Vedi autenticazione

Parametri

Parametri
Campo	Tipo	Descrizione
`quoteId`obbligatorio	string	Identificatore della preventiva accettata.
`beneficiary`obbligatorio	object	Campi imposti dallo schema del canale. Il nome deve corrispondere all'identità verificata: niente pagamenti a terzi.
`networkId`obbligatorio	string	Rete su cui verrà inviato il deposito. Determina l'indirizzo restituito e, su alcune reti, il memo obbligatorio.

Richiestabash

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"
    }
  }'

Risposta — contratto pubblicatojson

{
  "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" }
}

Il memo è null sulla maggior parte delle reti ed è obbligatorio su XRP, Stellar e TON. Tralasciarlo lì fa perdere i fondi: tratta il campo come obbligatorio appena è non-null.

Possibili errori: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Catalogo completo

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

Leggi un ordine

Stato attuale e cronologia delle transizioni con timestamp. La cronologia è la fonte di verità: è append-only, mai riscritta, ed è ciò che risponde a "perché il mio ordine è passato a quello stato in quel momento".

Autenticazione: Authorization: Bearer … Vedi autenticazione

Richiestabash

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

Risposta — contratto pubblicatojson

{
  "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" }
  ]
}

Possibili errori: unauthorized, not_found. Catalogo completo

Idempotenza

Una richiesta di creazione che va in timeout sulla rete non ti dice se l'ordine è stato creato. Senza una chiave di idempotenza hai solo due opzioni sbagliate: riprovare e rischiare due ordini, o non riprovare e rischiare nessuno.

Intestazionehttp

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

Una chiave per intenzione

La chiave identifica l'intenzione "crea quell'ordine", non la richiesta HTTP. Un id unico dalla tua parte: un id del carrello, un UUID generato prima della chiamata, mai un contatore.

Una ripetizione restituisce la risposta originale

Ripetere la stessa chiave con lo stesso corpo restituisce la risposta della prima richiesta, con lo stesso stato HTTP. Questo è ciò che rende sicuro un nuovo tentativo, anche dopo un timeout.

Stessa chiave, corpo diverso: conflitto

La risposta è un conflitto esplicito. Se il contenuto cambia, la chiave deve cambiare: altrimenti nessuno può dire quale dei due ordini ripetere.

Conservazione per 24 ore

Dopo quel periodo la chiave viene dimenticata e una ripetizione creerebbe un nuovo ordine. Riprova entro la finestra, o controlla lo stato con l'endpoint di lettura.

Il memo, sulle reti che lo richiedono

Su XRP, Stellar e TON l'indirizzo di deposito non basta: un identificatore extra designa il destinatario finale. È la causa di incidente più costosa in un'integrazione di off-ramp.

Un deposito senza il suo memo è un deposito perso

Il campo memo è null sulla maggior parte delle reti e non null su quelle che lo richiedono. Trattalo come obbligatorio appena è non null, e visualizzalo con lo stesso peso dell'indirizzo. Un deposito che arriva senza memo su un indirizzo condiviso richiede un recupero manuale, che non sempre riesce.

Stati dell'ordine

Gli stati seguenti sono quelli che la tua integrazione può osservare. Le transizioni sono timestampate e aggiunte, mai riscritte: la cronologia risponde a "perché il mio ordine è passato a quello stato in quel momento".

Stati dell'ordine
Stato	Cosa significa
`QUOTE_LOCKED`	Il tasso è congelato. L'ordine attende i dettagli del beneficiario o la verifica dell'identità.
`AWAITING_DEPOSIT`	L'indirizzo di deposito è assegnato e la finestra di deposito è attiva. È l'unico momento per inviare fondi.
`DEPOSIT_DETECTED`	Una transazione in arrivo è vista sulla rete, non ancora confermata. Rassicura l'utente, non consegnare nulla.
`CONFIRMING`	Le conferme si stanno accumulando. Il numero richiesto dipende dalla rete, non dall'importo.
`DEPOSIT_CONFIRMED`	Il deposito è assicurato. Le regole di conformità e riquotazione sono valutate da qui.
`UNDERPAID`	L'importo ricevuto è inferiore al previsto oltre la tolleranza. Tre esiti: integra, continua con l'importo ricevuto, o sii rimborsato.
`OVERPAID`	L'importo ricevuto supera quanto previsto. L'importo iniziale rimane al tasso bloccato, l'eccedenza viene gestita separatamente.
`PAYOUT_QUEUED`	Il trasferimento è in coda. La coda garantisce che un pagamento venga inviato una sola volta, anche se più worker scattano in parallelo.
`PAYOUT_SENT`	Il trasferimento è partito sul circuito. Inviato non significa ricevuto: il ritardo finale dipende dalla banca del beneficiario.
`COMPLETED`	Il regolamento è confermato dal circuito. Stato terminale.
`PAYOUT_FAILED`	Il circuito ha rifiutato o restituito il trasferimento. Nessun nuovo tentativo automatico: la causa è quasi sempre nei dettagli.
`REFUNDED`	I fondi sono stati restituiti all'indirizzo di origine, al netto delle commissioni di rete. Stato terminale.