Sviluppatori

Documentazione

Tutto ciò che serve per integrare Toreador nella Sua applicazione.

REST API Riferimento completo dell'API HTTP: endpoint, autenticazione, errori, paginazione. Vedere il riferimento TypeScript SDK L'SDK ufficiale @toreador/sdk per Node.js, Deno e runtime edge. Leggere la guida Webhooks Notifiche HTTPS firmate HMAC-SHA256 quando le Sue sessioni cambiano stato. Leggere la guida Plugin WordPress Installi il plugin, colleghi il Suo sito e incassi in crypto con WooCommerce e i Suoi moduli. Leggere la guida Domande frequenti Custodia, pagamenti, wallet, piani e verifica: le risposte, per tema. Leggere le risposte
Indice

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

Terminal
npm install @toreador/sdk

Guida rapida

TypeScript
import Toreador from "@toreador/sdk";

// Initialize the client
const client = new Toreador({ apiKey: "tor_live_your_key_here" });

// Generate a Bitcoin QR code
const qr = await client.qrcode.generate({
  token: "BTC",
  chainId: "bitcoin",
  amount: "0.001",
  recipientAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
});

console.log(qr.qrCodeURL); // data:image/png;base64,...

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

TypeScript
import Toreador from "@toreador/sdk";

const client = new Toreador({ apiKey: "tor_live_your_key_here" });

// Create a USDC payment session on Ethereum
const session = await client.sessions.create({
  token: "USDC",
  chainId: "ethereum",
  amount: "100",
  recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
});

console.log(session.url);       // Payment page URL
console.log(session.expiresIn); // Seconds until expiry

// Check status later
const status = await client.sessions.getStatus(session.sessionId);
console.log(status.status); // 'pending' | 'completed' | ...

Gestione degli errori

TypeScript
import { Toreador, ToreadorError } from "@toreador/sdk";

try {
  await client.qrcode.generate({ /* ... */ });
} catch (err) {
  if (err instanceof ToreadorError) {
    console.error(err.message); // "Missing required fields: ..."
    console.error(err.status);  // 400
    console.error(err.body);    // Full error response
  }
}

Opzioni del costruttore

OptionTypeObbligatorioDescription
apiKeystringSìLa Sua chiave API (tor_live_… o tor_test_…)
baseURLstringNoURL di base dell'API. Predefinito: https://toreador.io/api/v1/public
fetchfunctionNoImplementazione 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

EventAttivazione
session.createdQuando /create-session riesce
session.submittedIl pagatore ha trasmesso la transazione
session.confirmingPrima conferma sulla blockchain
session.completedNumero di conferme richiesto raggiunto
session.expiredScadenza di 15 minuti superata
session.failedTransazione non riuscita sulla blockchain
checkout.createdQuando /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

HeaderValore
Toreador-Signaturet=1761123121,v1=0xabc...
Toreador-Event-Idevt_xxx — idempotenza lato destinatario
Toreador-Event-Typesession.completed
Toreador-Delivery-Idwhd_xxx
Toreador-Attemptnumero del tentativo (1, 2, 3, ...)

Esempio: Express + SDK ufficiale

TypeScript
import { webhooks, WebhookSignatureError } from "@toreador/sdk";
import express from "express";

const app = express();

// Raw body, not parsed JSON: the signature covers the exact bytes
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await webhooks.constructEvent(
      req.body.toString("utf8"),
      req.headers["toreador-signature"] as string,
      process.env.TOREADOR_WEBHOOK_SECRET!
    );

    if (event.type === "session.completed") {
      // fulfill order, update DB, send receipt, etc.
    }

    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
    throw err;
  }
});

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

Rispettiamo la Sua privacy

Utilizziamo cookie analitici per migliorare il nostro servizio. Questi cookie vengono attivati solo con il Suo consenso. I cookie essenziali (autenticazione, lingua ecc.) sono sempre attivi.