Vai al contenuto principale
Il SDK TypeScript fornisce un accesso conveniente al server all’API REST di Dodo Payments per applicazioni TypeScript e JavaScript. Presenta definizioni di tipo complete, gestione degli errori, ritentativi, timeout e auto-paginazione per un’elaborazione dei pagamenti senza soluzione di continuità.

​
Installazione

Installa il SDK utilizzando il tuo gestore di pacchetti preferito: 
npm install dodopayments

​
Inizio Veloce

Inizializza il client con la tua chiave API e inizia a elaborare i pagamenti: 
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
  environment: 'test_mode', // defaults to 'live_mode'
});

const checkoutSessionResponse = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'product_id', quantity: 1 }],
});

console.log(checkoutSessionResponse.session_id);
Conserva sempre le tue chiavi API in modo sicuro utilizzando variabili di ambiente. Non commetterle mai nel controllo di versione o esporle nel codice lato client.

​
Caratteristiche Principali

TypeScript First

Supporto completo per TypeScript con definizioni di tipo complete per tutti gli endpoint API

Auto-Paginazione

Paginazione automatica per le risposte delle liste rende il lavoro con grandi set di dati senza sforzo

Gestione degli Errori

Tipi di errore integrati con messaggi dettagliati per diversi scenari di errore

Ritenti Intelligenti

Ritentativi automatici configurabili con backoff esponenziale per errori transitori

​
Configurazione

​
Variabili di Ambiente

Imposta variabili di ambiente per una configurazione sicura:
.env
DODO_PAYMENTS_API_KEY=your_api_key_here

​
Configurazione del Timeout

Configura i timeout delle richieste globalmente o per richiesta: 
// Configure default timeout for all requests (default is 1 minute)
const client = new DodoPayments({
  timeout: 20 * 1000, // 20 seconds
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 0 }] },
  { timeout: 5 * 1000 }
);

​
Configurazione dei Ritenti

Configura il comportamento dei ritentativi automatici: 
// Configure default for all requests (default is 2 retries)
const client = new DodoPayments({
  maxRetries: 0, // disable retries
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 0 }] },
  { maxRetries: 5 }
);
Il SDK ritenta automaticamente le richieste che falliscono a causa di errori di rete o problemi del server (risposte 5xx) con backoff esponenziale.

​
Operazioni Comuni

​
Crea una Sessione di Checkout

Genera una sessione di checkout per raccogliere informazioni di pagamento: 
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_123',
      quantity: 1
    }
  ],
  return_url: 'https://yourdomain.com/return'
});

console.log('Redirect to:', session.url);

​
Gestisci i Clienti

Crea e recupera informazioni sui clienti: 
// Create a customer
const customer = await client.customers.create({
  email: '[email protected]',
  name: 'John Doe',
  metadata: {
    user_id: '12345'
  }
});

// Retrieve customer
const retrieved = await client.customers.retrieve('cus_123');
console.log(`Customer: ${retrieved.name} (${retrieved.email})`);

​
Gestisci Abbonamenti

Crea e gestisci abbonamenti ricorrenti: 
// Create a subscription
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_456',
  price_id: 'price_789'
});

// Retrieve subscription usage history
const usageHistory = await client.subscriptions.retrieveUsageHistory('sub_123', {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-03-31T23:59:59Z'
});

​
Fatturazione Basata sull’Uso

​
Ingestione di Eventi di Utilizzo

Monitora eventi personalizzati per la fatturazione basata sull’uso: 
await client.usageEvents.ingest({
  events: [
    {
      event_id: 'api_call_12345',
      customer_id: 'cus_abc123',
      event_name: 'api_request',
      timestamp: '2024-01-15T10:30:00Z',
      metadata: {
        endpoint: '/api/v1/users',
        method: 'GET',
        tokens_used: '150'
      }
    }
  ]
});
Gli eventi devono avere valori unici event_id per l’idempotenza. ID duplicati all’interno della stessa richiesta vengono rifiutati e richieste successive con ID esistenti vengono ignorate.

​
Recupera Eventi di Utilizzo

Recupera informazioni dettagliate sugli eventi di utilizzo: 
// Get a specific event
const event = await client.usageEvents.retrieve('api_call_12345');

// List events with filtering
const events = await client.usageEvents.list({
  customer_id: 'cus_abc123',
  event_name: 'api_request',
  start: '2024-01-14T10:30:00Z',
  end: '2024-01-15T10:30:00Z'
});

​
Configurazione del Proxy

Configura le impostazioni del proxy per diversi runtime:

​
Node.js (utilizzando undici)

import DodoPayments from 'dodopayments';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new DodoPayments({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

​
Bun

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

​
Deno

import DodoPayments from 'npm:dodopayments';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
  fetchOptions: {
    client: httpClient,
  },
});

​
Logging

Controlla la verbosità dei log utilizzando variabili di ambiente o opzioni del client: 
// Via client option
const client = new DodoPayments({
  logLevel: 'debug', // Show all log messages
});

# Via environment variable
export DODO_PAYMENTS_LOG=debug
Livelli di log disponibili:
  • 'debug' - Mostra messaggi di debug, info, avvisi ed errori
  • 'info' - Mostra messaggi informativi, avvisi ed errori
  • 'warn' - Mostra avvisi ed errori (predefinito)
  • 'error' - Mostra solo errori
  • 'off' - Disabilita tutti i log
A livello di debug, tutte le richieste e risposte HTTP vengono registrate, inclusi intestazioni e corpi. Alcune intestazioni di autenticazione vengono oscurate, ma i dati sensibili nei corpi potrebbero essere ancora visibili.

​
Migrazione dal SDK Node.js

Se stai aggiornando dal SDK Node.js legacy, il SDK TypeScript offre una maggiore sicurezza dei tipi e funzionalità migliorate:

Visualizza la Guida alla Migrazione

Scopri come migrare dal SDK Node.js al SDK TypeScript

​
Risorse

Repository GitHub

Visualizza il codice sorgente e contribuisci

Riferimento API

Documentazione API completa

Comunità Discord

Ottieni aiuto e connettiti con gli sviluppatori

Segnala Problemi

Segnala bug o richiedi funzionalità

​
Supporto

Hai bisogno di aiuto con il SDK TypeScript?

​
Contribuire

Accogliamo con favore i contributi! Controlla le linee guida per i contributi per iniziare.