Guide d'integration NSF API v1

Getting Started

1. Creer un compte SociosPhone puis ouvrir la console developpeur.
2. Creer une application sandbox.
3. Generer une cle API sandbox affichee une seule fois.
4. Tester les endpoints publics et webhooks.
5. Demander la validation production pour les APIs partenaires.

Authentification

curl https://www.nsfcm.com/api/v1/explorer/clubs \
  -H "X-API-Key: nsf_test_xxxxx"

Format standard reponse API

// Succes
{
  "success": true,
  "data": {},
  "meta": {}
}

// Erreur
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Description lisible",
    "details": {}
  }
}

Pagination standard

GET /api/v1/explorer/clubs?page=1&limit=20

{
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Rate limiting

• Public: 60 req/min
• Partner: 600 req/min
• Admin: selon role
• Sensitive APIs: strict

Idempotency

Pour paiements, dons, wallet, SSURS et cartes recharge, envoyez toujours un UUID dans l'en-tete suivant.

Idempotency-Key: 6f8b9d7c-2e9d-4d62-b0e8-9cc0f0f7f531

Webhooks signes

Chaque webhook inclut `X-NSF-Signature` et `X-NSF-Timestamp`. Rejetez les timestamps de plus de 5 minutes.

import crypto from "crypto"

function verifyNsfWebhook(secret, timestamp, payload, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${payload}`)
    .digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Table des erreurs