TypeScript SDK
L'SDK ufficiale @toreador/sdk fornisce un'interfaccia TypeScript tipizzata per l'API Toreador. Compatibile con Node.js 18+, Deno e i browser moderni.
Installation
Guida rapida
Metodi disponibili
client.checkouts.create(params)
Crea una richiesta di pagamento in USD o EUR: il pagatore sceglie la stablecoin e la rete sulla pagina ospitata. La risorsa canonica per un'integrazione.
Restituisce: { checkoutId, url, allowedRails, expiresAt, ... }
client.payments.retrieve(id)
Oggetto di pagamento unificato per id di checkout (co_…) o id di sessione: stato, hash della transazione, sequenza degli eventi.
Restituisce: { id, status, token, chain, amount, txHash, timeline, ... }
client.qrcode.generate(params)
Genera un codice QR per i token nativi (BTC, ETH, SOL, POL) o per i token SPL di Solana.
Restituisce: { success, type, qrData, qrCodeURL, token, chain, amount, recipientAddress }
client.qrcode.history()
Elenca le Sue ultime 50 generazioni di codici QR.
Restituisce: { data: PaymentRecord[], has_more, next_cursor }
client.sessions.create(params)
Crea una sessione di pagamento per i token EVM non nativi (USDC, USDT, EURC).
Restituisce: { sessionId, url, expiresIn, ... }
client.sessions.list()
Elenca le Sue ultime 50 sessioni di pagamento.
Restituisce: { data: SessionRecord[], has_more, next_cursor }
client.sessions.getStatus(sessionId)
Verifica lo stato di una sessione di pagamento.
Restituisce: { status: 'pending' | 'submitted' | 'confirming' | 'completed' | 'expired' | 'failed', ... }
client.account.establishments()
Elenca i punti vendita della Sua organizzazione. I pagamenti riportano il loro punto vendita, chiunque del team li abbia creati.
Restituisce: { data: Establishment[] }
client.payments.export(options)
Esporta i pagamenti confermati in JSON o CSV, oppure come file di importazione delle transazioni bancarie di un software di contabilità (quickbooks, xero, odoo, pennylane).
Restituisce: { count, truncated, data: ExportRecord[] } | string
Esempio: sessione di pagamento USDC
Gestione degli errori
Opzioni del costruttore
| Option | Type | Obbligatorio | Description |
|---|---|---|---|
apiKey | string | Sì | La Sua chiave API (tor_live_… o tor_test_…) |
baseURL | string | No | URL di base dell'API. Predefinito: https://toreador.io/api/v1/public |
fetch | function | No | Implementazione fetch personalizzata. Predefinito: globalThis.fetch |
Webhooks
Riceva eventi firmati HMAC-SHA256 in tempo reale quando le Sue sessioni cambiano stato. Configuri gli endpoint dalla Sua dashboard.
Eventi emessi
| Event | Attivazione |
|---|---|
session.created | Quando /create-session riesce |
session.submitted | Il pagatore ha trasmesso la transazione |
session.confirming | Prima conferma sulla blockchain |
session.completed | Numero di conferme richiesto raggiunto |
session.expired | Scadenza di 15 minuti superata |
session.failed | Transazione non riuscita sulla blockchain |
checkout.created | Quando /checkout riesce |
Verifica della firma
Ogni consegna include un'intestazione Toreador-Signature: t=<unix>,v1=<hex>. La firma è un HMAC-SHA256 calcolato su <timestamp>.<rawBody> con il segreto del Suo endpoint. Verifichi sempre la firma prima di elaborare l'evento.
Intestazioni inviate
| Header | Valore |
|---|---|
Toreador-Signature | t=1761123121,v1=0xabc... |
Toreador-Event-Id | evt_xxx — idempotenza lato destinatario |
Toreador-Event-Type | session.completed |
Toreador-Delivery-Id | whd_xxx |
Toreador-Attempt | numero del tentativo (1, 2, 3, ...) |
Esempio: Express + SDK ufficiale
Politica dei nuovi tentativi
Se il Suo endpoint restituisce un codice diverso da 2xx o non risponde entro 10 secondi, Toreador ritenta con backoff esponenziale: 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h (9 tentativi in totale in circa 4 giorni), poi lo stato failed. Un endpoint viene disattivato automaticamente dopo 50 errori consecutivi.
Le consegne possono essere ritentate manualmente dalla dashboard. Idempotenza lato destinatario: utilizzi l'intestazione Toreador-Event-Id per rilevare i duplicati.
Pronto per iniziare?
Crei un account gratuito per ottenere la Sua chiave API — una chiave di test per la sandbox, una chiave di produzione per la mainnet — e inizi a integrare Toreador.
Vedere i prezzi