# Informazioni Generali

> Specifica tecnica per l'integrazione dell'elaborazione dei pagamenti in criptovaluta e dei prelievi con 2328.io.

Benvenuto nella documentazione dell'API di 2328.io. Questo riferimento descrive come integrare l'elaborazione dei pagamenti in criptovaluta e i prelievi nella tua applicazione.

## Per iniziare

Per avviare l'integrazione:

1. Crea un account merchant e un progetto su [2328.io](https://2328.io)
2. Ottieni il tuo **project UUID** e l'**API key** dalle impostazioni del progetto
3. Genera una **Payout API key** separata se intendi utilizzare i prelievi
4. Leggi la sezione [Authentication](/docs/authentication) per scoprire come firmare le richieste
5. Effettua la tua prima chiamata [Create Payment](/docs/payments)

## URL di base

Tutte le richieste API in produzione utilizzano il seguente URL di base:

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

> **WARNING:** Tutte le richieste devono essere effettuate tramite **HTTPS**. Le richieste senza HTTPS vengono bloccate.

## Cosa puoi fare

Con l'API di 2328.io puoi:

- **Accettare pagamenti in criptovaluta** — creare sessioni di pagamento e reindirizzare i clienti a un checkout ospitato o a una Telegram MiniApp
- **Prelevare fondi** — inviare prelievi in modo programmatico dal saldo merchant a qualsiasi indirizzo blockchain
- **Controllare i saldi** — visualizza i saldi degli account merchant per valuta, gli equivalenti in USD e gli importi bloccati per AML
- **Utilizzare wallet statici** — generare indirizzi di deposito permanenti associati a un utente o a un ordine
- **Recuperare i tassi di cambio** — ottenere tassi in tempo reale per coppie fiat e crypto
- **Ricevere webhook** — essere notificato istantaneamente al cambio di stato di un pagamento
## Limiti di frequenza

L'API consente fino a **10 richieste al secondo per progetto**. Le richieste oltre il limite ricevono una risposta HTTP `429 Too Many Requests` — applica un backoff e riprova.

## Scegli il giusto modello di integrazione

| Requisito | Modello consigliato | Perché |
|-------------|---------------------|-----|
| Lascia che il cliente scelga come pagare | Checkout ospitato | Crea un pagamento e reindirizza a `result.url`; 2328.io presenta le direzioni attualmente disponibili. |
| Mantieni il cliente all'interno del tuo checkout | Fattura con indirizzo diretto **H2H** | Invia `to_currency` e `network` quando crei il pagamento; visualizza `address`, `payer_amount` e `qr` restituiti. |
| Addebita esattamente `25 USDT` o `0.001 BTC` | Fattura denominata in criptovaluta | Metti la criptovaluta in `currency` e l'importo decimale esatto in `amount`. |
| Fornisci a ogni utente un indirizzo di deposito riutilizzabile | Portafoglio statico | L'indirizzo è permanente e può ricevere molti depositi indipendenti. |
| Normalizza gli asset in arrivo in un'unica valuta di saldo | Auto-conversione | Configura le regole del progetto nella dashboard e usa il risultato di `convert` quando la conversione è completata. |
| Scambia un saldo commerciale esistente | Conversione manuale | Anteprima con `/v1/convert/price`, poi esegui con `/v1/convert`. |
| Invia fondi a un indirizzo blockchain | Pagamento | Usa la chiave API Payout separata, calcola prima e riconcilia lo stato del pagamento. |

> **INFO:** Il checkout ospitato e H2H sono due presentazioni della stessa API di pagamento. H2H non crea un pagamento più debole o non firmato: il backend crea comunque la fattura, 2328.io possiede ancora l'indirizzo e lo stato, e i webhook firmati rimangono autorevoli per la regolazione.

## Invarianti di integrazione

Queste regole si applicano a ogni integrazione di produzione:

- **Backend only** — tieni le chiavi API fuori dai browser, dalle applicazioni mobili, dai log, dall'analisi e dagli screenshot di supporto.
- **Decimal strings** — invia e conserva denaro come stringhe. Non arrotondare mai criptovalute o tassi di cambio con l'aritmetica a virgola mobile binaria.
- **Immutable idempotency keys** — genera `order_id` prima della prima richiesta e conserva la richiesta completa con esso. Un tentativo di nuovo con lo stesso `order_id` può restituire l'oggetto originale invece di applicare campi modificati.
- **Webhook-first settlement** — reindirizzamenti, polling del client, hash di transazioni forniti dagli utenti e timeout HTTP non sono prova di pagamento.
- **Verify, deduplicate, then mutate** — verifica l'HMAC, richiedi in modo atomico un record di idempotenza, aggiorna l'ordine/saldo una sola volta e restituisci rapidamente HTTP 200.
- **Reconciliation** — interroga periodicamente lo stato di pagamento, portafoglio statico e pagamento in modo che un webhook perso non possa lasciare disaccordi permanenti.
- **Dynamic availability** — convalidare le coppie valuta/rete con `/v1/directions`; un asset supportato può comunque avere temporaneamente disabilitato un senso di deposito o prelievo.
- **Explicit status policy** — decidere come il tuo prodotto gestisce pagamento parziale, pagamento in eccesso, scadenza, blocco AML, conversione di fallback e timeout ambigui a monte prima del lancio.

## Dati consigliati da conservare

Per i pagamenti, memorizzare almeno `uuid`, `order_id`, il corpo della richiesta originale, `amount`, `currency`, `payer_currency`, `payer_amount`, `network`, `address`, `expires_at`, l'ultimo `payment_status`, `txid`, `payment_amount`, `merchant_amount`, il blocco opzionale `convert` e il payload webhook verificato grezzo.

Per i portafogli statici, tieni il portafoglio `uuid`, l'indirizzo, la valuta, la rete, il riferimento cliente/contabile, lo stato e l'URL di callback separati dai record dei depositi. Ogni deposito necessita del proprio `uuid`, `txid`, stato, importo ricevuto, importo del commerciante e risultato della conversione.