SDK de Node.js

El SDK @sanghosdk/js es el cliente oficial de Sangho para Node.js 18+. Admite los modos ESM y CommonJS. Es un cliente de servidor: no expone ningún widget de pago para el navegador; en el cliente, basta con redirigir a la URL de checkout devuelta por la API (véase Checkout con redirección).

Instalación

bash

# Avec NPM
npm install @sanghosdk/js
# Avec PNPM
pnpm add @sanghosdk/js
# Avec YARN
yarn add @sanghosdk/js

Módulos disponibles

accountappsaddressespaymentIntentscheckoutSessionstransactionsrefundspaymentLinkscustomerspaymentMethodsproductsinvoicesreceiptssubscriptionswebhookssecuritypartnersterminalsandbox

Node.js y Edge

El SDK está totalmente tipado. Las interfaces se exportan directamente: importe PaymentIntent, Customer, ListResponse, etc. desde @sanghosdk/js sin ninguna configuración adicional.

¿Está clara la instalación?

Inicialización

javascript

import Sangho from '@sanghosdk/js';
// Clé directe (déconseillé en production)
const sangho = new Sangho('sk_prod_xxxxxxxxxxxx');
// Depuis variable d'environnement (recommandé)
const sangho = new Sangho(process.env.SANGHO_SECRET_KEY!);
// Options avancées
const sangho = new Sangho('sk_prod_xxxx', {
  baseURL: 'https://api.sangho.ga/v1/',
  timeout: 30_000,
  maxRetries: 3,
});

Gestión de errores

Todos los errores lanzados por el SDK heredan de SanghoError, que expone type (categoría, p. ej. VALIDATION_ERROR) y code (código de negocio preciso, p. ej. AMOUNT_TOO_SMALL — véase la lista completa). Utilice instanceof para diferenciar los casos de negocio.

Paginación

Los endpoints de listado devuelven un objeto ListResponse<T> con los campos count, next, previous y data. Utilice los parámetros page y page_size para navegar.

Reintento automático

El SDK reintenta automáticamente los errores 429 (rate limit, respetando el retraso Retry-After) y 5xx, así como las caídas de red, con un backoff exponencial. El resto de errores 4xx (400, 401, 403, 404, 409, 422) nunca se reintentan: son problemas de la solicitud que hay que corregir, no incidentes temporales. Configure maxRetries en la inicialización (por defecto: 3).

¿Son suficientes los ejemplos?

Gestión de errores

javascript

import Sangho, { SanghoError } from '@sanghosdk/js';
const sangho = new Sangho(process.env.SANGHO_SECRET_KEY!);
try {
  const intent = await sangho.paymentIntents.create({
    amount: 5000,
    currency: 'XAF',
    payment_method_types: ['mobile_money'],
  });
  console.log(intent.id);
} catch (err) {
  if (err instanceof SanghoError) {
    console.error(err.type);       // Catégorie — 'VALIDATION_ERROR'
    console.error(err.code);       // Code métier précis — 'AMOUNT_TOO_SMALL'
    console.error(err.message);    // Message lisible
    console.error(err.statusCode); // Code HTTP (400, 401, 422…)
  }
}

Paginación

javascript

// Page 1
const page1 = await sangho.transactions.list({
  status: 'completed',
  page: 1,
  page_size: 20,
});
console.log(page1.count); // Total de résultats
console.log(page1.data);  // Tableau de la page courante
// Page suivante
if (page1.next) {
  const page2 = await sangho.transactions.list({
    status: 'completed',
    page: 2,
    page_size: 20,
  });
}