Utiliser les SDKs

CowriePay publie trois SDKs officiels. Ils existent pour que vous n’écriviez jamais la recette de signature HMAC à la main, et pour que la référence de l’API se projette une-pour-une sur votre code.

Langage	Package	Installation
Node / TypeScript	@cowriepay/sdk	npm install @cowriepay/sdk
Python	cowriepay	pip install cowriepay
PHP	cowriepay/cowriepay-php	composer require cowriepay/cowriepay-php

Trois propriétés partagées, par conception :

• Zéro dépendance à l’exécution. Chaque SDK n’utilise que la bibliothèque standard de son langage ; rien d’autre n’entre dans votre chaîne d’approvisionnement.
• Côté serveur uniquement. Le secret d’API signe les requêtes : il ne doit jamais atteindre un navigateur ou une application mobile. Il n’existe pas de build client, volontairement.
• Les noms de méthodes sont les operationId de la référence. La page de référence Create a deposit wallet est createWallet ; dans les SDKs, c’est wallets.create sous l’espace de noms de la ressource. Ce que vous lisez est ce que vous appelez, et ces noms sont un contrat stable.

La forme, en Node

import { CowriePay } from '@cowriepay/sdk';

const cowriepay = new CowriePay({
  apiKey: process.env.CPK_KEY,      // cpk_test_... ou cpk_live_...
  apiSecret: process.env.CPK_SECRET,
});

const wallet = await cowriepay.wallets.create(
  { chain: 'TRON', asset: 'USDT_TRON', external_ref: 'order_12345' },
  { idempotencyKey: crypto.randomUUID() },
);

const { data: deposits } = await cowriepay.transactions.listDeposits({ status: 'CONFIRMED' });
const balances = await cowriepay.transactions.balances();

La signature, les horodatages, le hachage du corps et les retentatives sont gérés à l’intérieur ; les clés d’idempotence sont une option de première classe sur les appels mutants. Les README Python et PHP portent le même parcours dans leur propre idiome.

Les erreurs sont typées, et le code voyage

Un appel en échec lève une erreur typée portant le même code que l’API brute (plus le statut HTTP et un identifiant de requête pour le support). Branchez-vous sur le code exactement comme le prescrit le catalogue d’erreurs ; le SDK ajoute des types, jamais un autre contrat.

La vérification de webhooks est incluse

Chaque SDK vérifie les signatures de webhooks sur le corps brut de la requête, et accepte un tableau de secrets pour qu’une rotation de secret (ancien et nouveau en chevauchement) se vérifie proprement :

const event = CowriePay.verifyWebhook({
  payload: rawBody,
  signatureHeader: req.headers['x-cowriepay-signature'],
  timestamp: req.headers['x-cowriepay-timestamp'],
  secrets: [currentSecret, previousSecret].filter(Boolean),
});

Quand le SDK ne couvre pas encore

Chaque SDK expose une échappatoire signée (cowriepay.request({ method, path, body }) en Node) qui signe n’importe quel chemin avec la même recette. Un endpoint tout neuf est utilisable le jour de sa sortie, avant que le SDK ne le rattrape.

Vous préférez Postman ?

Une collection Postman prête à signer est générée depuis le même spec publié :

1. Dans Postman, choisissez Import, puis Link, et collez https://docs.cowriepay.io/cowriepay.postman_collection.json.
2. Sur la collection importée, ouvrez l’onglet Variables et renseignez hmac_key_id et hmac_secret avec une clé API de votre tableau de bord.
3. Envoyez. Un pre-request script au niveau de la collection calcule la signature HMAC à chaque appel, et le préfixe de la clé décide Sandbox ou Live, comme partout ailleurs.

La même collection est aussi consultable sur le Public API Network de Postman ; forkez-la dans votre propre workspace, puis renseignez-y les deux variables. Quelle qu’en soit la provenance, ne mettez jamais votre clé dans un workspace public ou partagé.

Et ensuite

• Authentification : la recette que les SDKs implémentent, si vous intégrez sans eux.
• Référence de l’API : chaque opération que les espaces de noms reflètent.