Intégration Service Provider

Ce guide décrit le parcours d'intégration de l'API Service Provider. Pour le détail de chaque endpoint, consultez la spécification OpenAPI.

Prérequis

• Un compte entreprise Service Provider
• Des identifiants Partner API (clé API et ID de clé API)
• L'accès aux endpoints Service Provider de la Partner API

Authentification

Tous les endpoints nécessitent les en-têtes suivants :

X-API-KEY: your_api_key_here
X-API-KEY-ID: your_api_key_id_here

Workflow d'intégration

Flux d'intégration complet

Étapes d'intégration

POST /partner_api/service_providers/business_onboarding

{
  "owner": {
    "phone": "+22507012345",
    "firstName": "Jean",
    "lastName": "Dupont",
    "sex": "M"
  },
  "business": {
    "name": "Magasin de Jean",
    "category": "retail",
    "categoryActivity": "home_appliances",
    "city": "abidjan",
    "municipality": "cocody"
  }
}

{
  "business": {
    "id": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "name": "Magasin de Jean",
    "reference": "BIZ-2024-001"
  },
  "serviceProviderMemberId": "29f81706-03a6-492f-92ee-5f0b2e9b18e7"
}

POST /partner_api/service_providers/business_link_requests

{
  "phone": "+22507012345"
}

[
  {
    "id": "c1e15642-cdb5-404a-b028-26a51c94059b",
    "status": "pending",
    "merchantBusinessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "merchantBusinessName": "Magasin de Jean",
    "serviceProviderBusinessId": "a0b1c2d3-e4f5-6789-abcd-ef0123456789",
    "serviceProviderBusinessName": "Ma Marketplace",
    "ownerPhone": "+22507012345",
    "expiresAt": "2026-08-30T12:00:00.000Z",
    "createdAt": "2026-08-23T12:00:00.000Z"
  }
]

POST /partner_api/service_providers/business_api_keys

{
  "merchantBusinessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "name": "Clé API de production"
}

{
  "id": "a3c81f3d-ee04-4ec5-8bd2-cd8af5dabcfc",
  "name": "Clé API de production",
  "businessId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "key": "jeko_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
}

Gestion des erreurs courantes

Numéro de téléphone déjà utilisé (409 phone_already_in_use)

L'onboarding est create-only. Ce téléphone a déjà un compte Jèko. Enchaînez avec POST /partner_api/service_providers/business_link_requests (voir Rattacher un marchand déjà inscrit).

Utilisateur introuvable (404 user_not_found)

La demande de rattachement n'a trouvé aucun utilisateur. Créez le marchand avec business_onboarding.

Aucune entreprise possédée (409 no_owned_business)

L'utilisateur existe mais n'est Owner d'aucune entreprise. Un cashier ou un director d'une entreprise d'un tiers n'est pas ciblé.

Déjà rattaché (409 already_linked)

Un membre service_provider existe déjà entre vous et ce marchand. Le champ extras de la réponse est le merchantBusinessId : créez les clés API sans nouvelle demande.

Accès refusé (403)

Vous ne pouvez créer des clés API que pour les marchands que vous avez intégrés. Vérifiez que le merchantBusinessId correspond à un marchand que vous avez intégré.

Erreurs de validation (422)

Vérifiez que les valeurs de category, city, municipality correspondent aux données retournées par les endpoints de référence.

Limitation de débit (Rate Limiting)

Pour garantir la stabilité et la disponibilité de l'API, Jèko applique des limites de débit au niveau applicatif.

Limites appliquées

Comportement en cas de dépassement

1. Blocage temporaire : Votre entreprise sera bloquée pendant 10 à 15 minutes
2. Réponse HTTP 429 : Toutes les requêtes pendant le blocage recevront une réponse 429 Too Many Requests

Exemple de réponse 429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after some time."
}

Gestion du rate limiting avec backoff exponentiel

async function makeRequestWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const waitTime = Math.pow(2, attempt) * 1000;
      console.log(`Rate limited. Attente de ${waitTime}ms avant nouvelle tentative...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Nombre maximum de tentatives dépassé');
}

Bonnes pratiques

1. Sécurité des clés API : Stockez les clés API brutes dans un coffre-fort sécurisé dès leur création
2. Validation : Utilisez toujours les endpoints de référence pour valider les valeurs avant l'intégration
3. Gestion d'erreurs : Renvoyez des messages compréhensibles par le marchand
4. Limitation de débit : Implémentez le backoff exponentiel pour gérer les erreurs 429

Exemples de code

async function onboardMerchant(merchantData) {
  const response = await fetch('https://api.jeko.africa/partner_api/service_providers/business_onboarding', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.SERVICE_PROVIDER_API_KEY,
      'X-API-KEY-ID': process.env.SERVICE_PROVIDER_API_KEY_ID,
    },
    body: JSON.stringify(merchantData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Échec de l'intégration : ${JSON.stringify(error)}`);
  }

  return await response.json();
}

async function createApiKey(merchantBusinessId, keyName) {
  const response = await fetch('https://api.jeko.africa/partner_api/service_providers/business_api_keys', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': process.env.SERVICE_PROVIDER_API_KEY,
      'X-API-KEY-ID': process.env.SERVICE_PROVIDER_API_KEY_ID,
    },
    body: JSON.stringify({ merchantBusinessId, name: keyName }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Échec de la création de la clé API : ${JSON.stringify(error)}`);
  }

  const result = await response.json();
  
  // IMPORTANT : Sauvegarder la clé brute de manière sécurisée
  await saveApiKeySecurely(merchantBusinessId, result.key, result.id);
  
  return result;
}

Et ensuite

Le marchand est intégré et dispose de ses clés. À partir de là, il utilise la Partner API comme n'importe quel partenaire Jèko :

• Paiements : encaisser en boutique, en ligne ou en application
• Transferts : envoyer des fonds vers Mobile Money ou compte bancaire
• Webhooks : recevoir les notifications de transaction

Les clés que vous lui avez créées s'authentifient exactement de la même façon, avec les en-têtes X-API-KEY et X-API-KEY-ID.