SDK serveur — API/SDK avancé

Utilisez le mode API/SDK avancé pour un Checkout personnalisé, une facturation non Stripe, une attribution personnalisée avant le Checkout, des remises, essais ou parcours d’intégration personnalisés, ou des événements non financiers. Si Stripe est votre source de paiement et qu’un Payment Link compatible convient à votre parcours, utilisez plutôt Stripe automatique.

@affihq/sdk fonctionne avec Node.js 20 ou une version ultérieure et ne dépend d’aucun framework. AffiHQ le fournit sous forme d’archive compilée à conserver dans votre circuit privé de dépendances.

Installer le SDK

Installez l’archive fournie par AffiHQ depuis le dossier de votre projet :

pnpm add ./affihq-sdk-0.1.0.tgz

Créer le client

import { createAffiHQ } from '@affihq/sdk/server'

const affihq = createAffiHQ({
  apiKey: process.env.AFFIHQ_API_KEY!,
  fingerprintKey: process.env.AFFIHQ_FINGERPRINT_KEY!,
  baseUrl: process.env.AFFIHQ_BASE_URL,
  timeoutMs: 1500,
})

Les clés API produit et d’empreinte doivent rester dans le gestionnaire de secrets du serveur pour les requêtes API/SDK avancées. N’utilisez jamais l’une ou l’autre dans du code navigateur. Stripe automatique ne nécessite ni ces clés ni ce SDK ; AffiHQ gère ses livraisons Stripe connectées. L’URL par défaut est https://affihq.com et le délai maximal par défaut est de 2 500 ms.

Calculer l’empreinte du client

const customerFingerprint = affihq.customers.fingerprint(customerEmail)

Le SDK normalise l’email et calcule localement un HMAC-SHA-256 propre au produit. Envoyez l’empreinte, jamais l’adresse email dans une requête, une boîte d’envoi, une exception ou un log.

Traiter les résultats typés

const result = await affihq.attributions.create(input)

if (result.status === 'accepted') {
  // Continuez avec result.data.
} else if (result.status === 'retryable_error') {
  // Gardez le message d’origine dans la boîte d’envoi API/SDK avancée pour le retenter.
} else {
  // Conservez result.error.code pour examen sans journaliser les données.
}

Les délais dépassés, erreurs réseau, réponses 429 et réponses 5xx peuvent être retentés. Les rejets métier stables renvoient invalid. Une mauvaise configuration locale lève une erreur avant l’envoi.

Clients disponibles

• integration.get() vérifie les identifiants et capacités ;
• references.validate(input) prévisualise une référence ;
• attributions.create(input) verrouille la première attribution admissible ;
• attributions.discount(publicId, billingCycle) lit la remise figée ;
• billingEvents.send(input) transmet les données financières vérifiées ;
• delivery.* crée et vide les messages de la boîte d’envoi API/SDK avancée.