API Externe - Portail Clients CAM

Vue d'ensemble

L'API Externe du Portail Clients CAM permet aux applications tierces de créer des prospects et des demandes de crédit de manière sécurisée et contrôlée. Cette API REST est conçue pour être intégrée dans des sites web, applications mobiles ou systèmes partenaires.

URL de Base

https://[domaine-api]/api/external/

Authentification

Méthode d'authentification : Clé API

L'API utilise un système d'authentification basé sur des clés API. Chaque client reçoit une clé unique qui doit être incluse dans toutes les requêtes. L'API Key de chaque environnement est disponible dans le keepass.

Méthodes de transmission de la clé API

Option 1 : En-tête HTTP (Recommandée)

X-API-Key: sk_test_1234567890abcdef_site_internet

Option 2 : Paramètre de requête

GET /api/external/health?apikey=sk_test_1234567890abcdef_site_internet

Configuration des clés API

Les clés API sont configurées dans le fichier appsettings.json :

{
  "ExternalApi": {
    "ApiKeys": {
      "site_internet": {
        "Key": "sk_test_1234567890abcdef_site_internet",
        "Name": "Site Internet Public",
        "ClientId": "site_internet_client",
        "ClientName": "Site Internet CAM",
        "IsActive": true,
        "ExpiresAt": null,
        "Permissions": [
          "ExternalApi.ProspectCredit.Create",
          "ExternalApi.ProspectCredit.ViewStatus"
        ]
      }
    }
  }
}

Limitation de taux (Rate Limiting)

L'API applique une limitation de taux pour prévenir les abus et garantir la disponibilité du service.

Limites par défaut

Requêtes maximales : 100 requêtes
Fenêtre de temps : 1 heure
Identification : Par clé API ou adresse IP

En-têtes de réponse

Lorsque la limite est atteinte :

Statut HTTP : 429 Too Many Requests
En-tête : Retry-After: [secondes]

Endpoints disponibles

1. Création de Prospect et Demande de Crédit

Crée un nouveau prospect et une demande de crédit associée dans Salesforce.

Endpoint

POST /api/external/prospect-credit

En-têtes requis

Content-Type: application/json
X-API-Key: [votre-clé-api]

Corps de la requête

{
  "prospect": {
    "nom": "Dupont",
    "prenom": "Jean",
    "rid": "1234567",
    "email": "[email protected]",
    "numeroTelephonePortable": "852950",
    "adresse": {
      "rue": "123 Rue de la Paix",
      "complementAdresse": "Appartement 4B",
      "batiment": "Résidence Les Fleurs",
      "codePostal": "98800",
      "ville": "NOUMEA",
      "pays": "FRANCE"
    }
  },
  "demandeCredit": {
    "description": "Achat véhicule",
    "montantDemande": 25000,
    "montantEcheanceSouhaite": 500,
    "dureeRemboursementMois": 60
  }
}

Validation des données

Champs obligatoires :

prospect.nom (max 100 caractères)
prospect.prenom (max 100 caractères)
prospect.email (format email valide, max 255 caractères)
prospect.numeroTelephonePortable (format téléphone valide, max 20 caractères)
prospect.adresse.rue (max 255 caractères)
prospect.adresse.codePostal (exactement 5 caractères)
prospect.adresse.ville (max 100 caractères)
prospect.adresse.pays (max 100 caractères)
demandeCredit.description (max 1000 caractères)
demandeCredit.montantDemande (> 0)
demandeCredit.montantEcheanceSouhaite (> 0)
demandeCredit.dureeRemboursementMois (entre 1 et 600)

Champs optionnels :

prospect.rid (exactement 7 caractères si fourni)
prospect.adresse.complementAdresse (max 255 caractères)
prospect.adresse.batiment (max 100 caractères)

Réponses

Succès (200 OK)

{
  "success": true,
  "code": 200,
  "message": "Prospect et demande de crédit créés avec succès.",
  "prospectSalesforceId": "0031234567890ABC",
  "opportuniteSalesforceId": "0061234567890DEF",
  "taskSalesforceId": "00T1234567890GHI"
}

Prospect existant (409 Conflict)

{
  "success": false,
  "code": 409,
  "message": "Un prospect correspondant existe déjà dans notre système.",
  "prospectSalesforceId": "0031234567890ABC"
}

Erreur de validation (400 Bad Request)

{
  "success": false,
  "code": 400,
  "message": "Données de requête invalides. Veuillez vérifier tous les champs requis."
}

Erreur Salesforce (502 Bad Gateway)

{
  "success": false,
  "code": 502,
  "message": "Erreur lors de la communication avec Salesforce. Veuillez réessayer plus tard."
}

Erreur interne (500 Internal Server Error)

{
  "success": false,
  "code": 500,
  "message": "Une erreur interne s'est produite. Veuillez contacter le support technique."
}

Comportement fonctionnel

Vérification d'existence : L'API vérifie si un prospect correspondant existe déjà en utilisant :
- Combinaison nom + prénom dans la base de données locale
- Email dans la base de données locale
- Combinaison nom + prénom dans Salesforce
- Email dans Salesforce
Création en cascade : Si aucun prospect n'existe :
- Création du prospect dans Salesforce avec le RecordType "Prospect Personne Physique"
- Création de l'opportunité liée au prospect
- Création d'une tâche de contrôle pour suivi
Mapping d'adresse : Le système tente de mapper automatiquement la ville et le code postal vers un département Salesforce existant.

2. Santé de l'API

Point de terminaison pour vérifier l'état de santé de l'API.

Endpoint

GET /api/external/health

Authentification

Aucune authentification requise.

Réponse (200 OK)

{
  "status": "healthy",
  "timestamp": "2024-01-15T16:20:30.123Z",
  "version": "1.0.0",
  "service": "External Prospect Credit API"
}

Codes de réponse HTTP

Code	Signification	Description
200	OK	Requête traitée avec succès
400	Bad Request	Erreur de validation des données
401	Unauthorized	Clé API invalide ou manquante
409	Conflict	Prospect existant trouvé
429	Too Many Requests	Limite de taux dépassée
500	Internal Server Error	Erreur interne du serveur
502	Bad Gateway	Erreur de communication avec Salesforce

Gestion des erreurs

Stratégie de retry

En cas d'erreur temporaire (codes 5xx), il est recommandé d'implémenter une stratégie de retry avec backoff exponentiel :

async function createProspectWithRetry(data, maxRetries = 3) {
  for (let i = 0; i &lt; maxRetries; i++) {
    try {
      const response = await fetch('/api/external/prospect-credit', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': 'votre-clé-api'
        },
        body: JSON.stringify(data)
      });
      
      if (response.ok || response.status &lt; 500) {
        return await response.json();
      }
      
      // Attendre avant le prochain essai
      await new Promise(resolve =&gt; 
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Logging et traçabilité

Toutes les opérations sont tracées avec les informations suivantes :

Identifiant du client (clé API)
Horodatage de la requête
Données de la requête (sans informations sensibles)
Résultat de l'opération
Identifiants Salesforce générés

Exemples d'intégration

JavaScript/TypeScript

interface ProspectCreditRequest {
  prospect: {
    nom: string;
    prenom: string;
    rid?: string;
    email: string;
    numeroTelephonePortable: string;
    adresse: {
      rue: string;
      complementAdresse?: string;
      batiment?: string;
      codePostal: string;
      ville: string;
      pays: string;
    };
  };
  demandeCredit: {
    description: string;
    montantDemande: number;
    montantEcheanceSouhaite: number;
    dureeRemboursementMois: number;
  };
}

class CamApiClient {
  constructor(private apiKey: string, private baseUrl: string) {}

  async createProspectCredit(data: ProspectCreditRequest) {
    const response = await fetch(`${this.baseUrl}/api/external/prospect-credit`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': this.apiKey
      },
      body: JSON.stringify(data)
    });

    return await response.json();
  }

  async getStatus(numeroReference: string) {
    const response = await fetch(
      `${this.baseUrl}/api/external/prospect-credit/${numeroReference}/status`,
      {
        headers: { 'X-API-Key': this.apiKey }
      }
    );

    return await response.json();
  }
}

cURL

# Création d'un prospect
curl -X POST "https://api.cam.nc/api/external/prospect-credit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_1234567890abcdef_site_internet" \
  -d '{
    "prospect": {
      "nom": "Dupont",
      "prenom": "Jean",
      "email": "[email protected]",
      "numeroTelephonePortable": "+33612345678",
      "adresse": {
        "rue": "123 Rue de la Paix",
        "codePostal": "98800",
        "ville": "Nouméa",
        "pays": "Nouvelle-Calédonie"
      }
    },
    "demandeCredit": {
      "description": "Achat véhicule",
      "montantDemande": 25000,
      "montantEcheanceSouhaite": 500,
      "dureeRemboursementMois": 60
    }
  }'

# Vérification de santé
curl -X GET "https://api.cam.nc/api/external/health"

Sécurité

Bonnes pratiques

Protection de la clé API :
- Ne jamais exposer la clé API côté client
- Stocker la clé dans des variables d'environnement
- Utiliser HTTPS uniquement
Validation côté client :
- Valider les données avant envoi
- Implémenter des contrôles de format
- Gérer les erreurs de manière appropriée
Gestion des timeouts :
- Définir des timeouts appropriés (30-60 secondes)
- Implémenter des indicateurs de chargement
- Informer l'utilisateur en cas de délai

Conformité

RGPD : Les données personnelles sont traitées conformément au RGPD
Traçabilité bancaire : Toutes les opérations sont auditées
Chiffrement : Communications HTTPS obligatoires

Support et monitoring

Logs applicatifs

L'API génère des logs détaillés pour :

Authentification et autorisation
Validation des données
Interactions avec Salesforce
Erreurs et exceptions

Métriques disponibles

Nombre d'appels par clé API
Taux de succès/échec
Latence des réponses
Utilisation de la limitation de taux

Contact support

Pour toute question technique ou problème d'intégration :

Email : [email protected]
Documentation : [URL de la documentation]
Statut du service : [URL du tableau de bord]

Version du document : 1.0
Dernière mise à jour : Janvier 2025
API Version : v1.0

Vue d'ensemble​

URL de Base​

Authentification​

Méthode d'authentification : Clé API​

Méthodes de transmission de la clé API​

Configuration des clés API​

Limitation de taux (Rate Limiting)​

Limites par défaut​

En-têtes de réponse​

Endpoints disponibles​

1. Création de Prospect et Demande de Crédit​

Endpoint​

En-têtes requis​

Corps de la requête​

Validation des données​

Réponses​

Comportement fonctionnel​

2. Santé de l'API​

Endpoint​

Authentification​

Réponse (200 OK)​

Codes de réponse HTTP​

Gestion des erreurs​

Stratégie de retry​

Logging et traçabilité​

Exemples d'intégration​

JavaScript/TypeScript​

cURL​

Sécurité​

Bonnes pratiques​

Conformité​

Support et monitoring​

Logs applicatifs​

Métriques disponibles​

Contact support​

Vue d'ensemble

URL de Base

Authentification

Méthode d'authentification : Clé API

Méthodes de transmission de la clé API

Configuration des clés API

Limitation de taux (Rate Limiting)

Limites par défaut

En-têtes de réponse

Endpoints disponibles

1. Création de Prospect et Demande de Crédit

Endpoint

En-têtes requis

Corps de la requête

Validation des données

Réponses

Comportement fonctionnel

2. Santé de l'API

Endpoint

Authentification

Réponse (200 OK)

Codes de réponse HTTP

Gestion des erreurs

Stratégie de retry

Logging et traçabilité

Exemples d'intégration

JavaScript/TypeScript

cURL

Sécurité

Bonnes pratiques

Conformité

Support et monitoring

Logs applicatifs

Métriques disponibles

Contact support