Skip to main content

Ce document fournit une documentation détaillée pour les points de terminaison de l'API gérés par CourrierManagerController.

1. Introduction

Cette API a vocation d'être consommé par les différentes applications du CAM qui ont besoin de s'interfacer avec le gestionnaire de courrier.

  • Objectif : Fournir un contrat clair pour les intégrations.
  • Audience : Développeurs front-end, partenaires techniques.
  • Version : v1

2. Informations Générales

  • Base URL : https://[URL_DE_BASE_DE_VOTRE_API]/ (à remplacer par l'URL de votre environnement)
  • Protocoles : HTTPS
  • Format : JSON
  • Authentification : Bearer Token (JWT)
  • Rate Limiting : 1000 requêtes / heure / IP

3. Applications consommant déjà cette API

  • Eckert
  • Scoring
  • AddInWord
  • Relevés de comptes

4. Authentification

Voir détail d'implémentation en bas de page [Mise en place sécurité]

L'API utilise le standard OAuth 2.0 avec des JSON Web Tokens (JWT) pour sécuriser les points de terminaison. Toutes les requêtes doivent inclure un Bearer Token dans l'en-tête Authorization.

Obtention du Token TODO​

Pour obtenir un token, vous devez envoyer une requête POST à un point de terminaison d'authentification (par exemple, /connect/token) avec vos informations d'identification (client_id, client_secret, grant_type).

Utilisation du Token TODO​

Une fois le token obtenu, vous devez l'inclure dans chaque requête API comme suit :

Endpoints

1. Attacher un fichier à un courrier​

Attache un fichier à un courrier existant. Cette opération utilise une requête multipart/form-data pour gérer le téléversement du fichier ainsi que les métadonnées associées.

  • Méthode : POST
  • Route : API/CourrierManager/AttachFileToCourrierAsync
  • Type de contenu : multipart/form-data

Parties de la requête​

Nom du champTypeDescriptionRequis
NumeroCourrierstringLe numéro de chrono unique identifiant le courrier.Oui
filefileLe contenu binaire du fichier à attacher.Oui

Réponses​

  • 200 OK

    • Description : Le fichier a été reçu et attaché avec succès au courrier.
    • Contenu : string
    • Exemple : "File received and attached to Courrier."

  • 412 Precondition Failed

    • Description : Les données fournies sont invalides. Cela se produit si le numéro de courrier, le nom du fichier ou le contenu du fichier est manquant.
    • Contenu : application/json
    • Exemple : 
      {
        "ErrorCode": "500",
        "Message": "Invalid data, Courrier Number not found."
      }

  • 422 Unprocessable Entity

    • Description : Le courrier spécifié par NumeroCourrier n'existe pas dans le système.
    • Contenu : application/json
    • Exemple : 
      {
        "ErrorCode": "500",
        "Message": "Invalid data, Courrier Number not found."
      }

  • 500 Internal Server Error

    • Description : Une erreur inattendue s'est produite sur le serveur lors du traitement de la requête.
    • Contenu : application/json
    • Exemple : 
      {
        "ErrorCode": "500",
        "Message": "Echec de l'upload du rattachement du fichier à un courrier : \r\n{détails de l'exception}."
      }

2. Créer un nouveau courrier​

Crée un nouveau courrier avec les propriétés fournies. Un fichier peut être attaché optionnellement lors de la création.

  • Méthode : POST
  • Route : API/CourrierManager/CreateCourrierAsync
  • Type de contenu : application/json

Corps de la requête (CourrierDto)​

PropriétéTypeDescriptionRequis
StatutstringLe statut du courrier (ex: 'A' pour Arrivé, 'D' pour Départ).Oui
CodeObjetstringLe code identifiant l'objet du courrier.Oui
CodeModeTransmissionstringLe code identifiant le mode de transmission.Oui
NomCorrespondantstringLe nom du correspondant.Non
DossierConcernestringLe numéro du dossier concerné.Non
TiersarrayUne liste d'entités "Tiers" associées.Non
FileNamestringLe nom du fichier à attacher. Requis si FileBytes est fourni.Non
FileBytesbyte[]Le contenu binaire du fichier encodé en Base64.Non
GenerationGuidguidL'identifiant unique pour une génération de courriers en masse.Non
GenerationSourcestringLa source de la génération.Non

Réponses​

  • 200 OK

    • Description : Le courrier a été créé avec succès.

  • 500 Internal Server Error

    • Description : Une erreur est survenue. Le corps de la réponse contient des détails sur l'erreur.
    • Exemples de messages :
      • "Le statut '{courrierProperties.Statut}' n'est pas correct."
      • "{resultCourrier.ErrorMessage}" (si la création en base de données échoue)
      • { "File": ["Le fichier '{referenceGuid}' n'a pas pu être uploadé..."] } (si le téléversement du fichier échoue)

3. Obtenir le nombre d'impayés par tiers​

Récupère le nombre total d'impayés pour chaque tiers sur une période donnée en mois.

  • Méthode : GET
  • Route : API/CourrierManager/GetNombreImpayesPeriodeParTiersAsync

Paramètres de la requête​

NomDansTypeDescriptionRequis
periodeEnMoisQueryintLa période en mois pour laquelle calculer les impayés.Oui

Réponses​

  • 200 OK
    • Description : Retourne un dictionnaire contenant l'identifiant du tiers et le nombre d'impayés.
    • Contenu : application/json
    • Exemple : 
      {
        "101": 5,
        "102": 2
      }

4. Obtenir la date de dernière activité par tiers​

Récupère la date de la dernière activité (basée sur la date d'arrivée du courrier) pour chaque tiers.

  • Méthode : GET
  • Route : API/CourrierManager/GetDateDerniereActiviteByNumeroTiersAsync

Réponses​

  • 200 OK
    • Description : Retourne une liste d'objets avec le numéro du tiers et la date de sa dernière activité.
    • Contenu : application/json
    • Exemple : 
      [
        {
          "NumeroTiers": 12345,
          "DateDerniereActivite": "2025-06-26T14:30:00Z"
        },
        {
          "NumeroTiers": 67890,
          "DateDerniereActivite": "2025-05-10T11:00:00Z"
        }
      ]

5. Obtenir tous les objets courriers en lien avec le portail sociétaire​

Récupère la liste de toutes les entités ObjetCourrier disponibles dans le système qui sont associé au portail sociétaire. • Méthode : GET • Route : API/CourrierManager/GetAllObjetCourrierPortailSocietaireAsync

Réponses​

  • 200 OK
    • Description : Retourne une liste de tous les objets courriers en lien avec le portail sociétaire.
    • Contenu : application/json
    • Exemple : 
      [
        {
          "typeObjet": "ENRAPP",
          "description": "Rappel",
          "isDepart": true,
          "isArrivee": false,
          // ... autres propriétés de l'objet courrier
        },
        {
          "typeObjet": "ENRIMP",
          "description": "Impayé",
          "isDepart": true,
          "isArrivee": false,
          // ... autres propriétés de l'objet courrier
        }
      ]

Mise en place sécurité

Pour une application consommatrice hébergée sur le tenant du CAM Azure Portal​

1. Enregistrer chaque application cliente dans Azure AD​

Même si les applications ne sont pas hébergées sur Azure, elles doivent avoir une "identité" dans votre Azure AD.

  1. Allez sur le Portail Azure > Azure Active Directory > Inscriptions d’applications.
  2. Cliquez sur Nouvelle inscription pour chaque application cliente (AddinWord, PortailSociétaire, etc.).
  3. Donnez-lui un nom clair (ex: "Client App - PortailSociétaire").
  4. Laissez les autres options par défaut et cliquez sur Inscrire.
  5. Une fois l'application inscrite, notez son ID d'application (client). C'est son identifiant unique.
  6. Allez dans la section Certificats et secrets, créez un nouveau secret client, et copiez immédiatement sa valeur. C'est le mot de passe de l'application. Chaque application cliente aura maintenant son propre couple ClientID + ClientSecret.

2. Exposer une permission d'API dans votre application principale​

L'API Kelios.CAM.Courrier.App doit définir les permissions que d'autres applications peuvent lui demander.

  1. Dans Azure AD, trouvez l'inscription de votre application API.
  2. Allez dans la section Exposer une API.
  3. Cliquez sur Ajouter une étendue (scope) si vous ne l'avez pas déjà fait pour définir un URI d'ID d'application (ex: api://<votre-client-id>).
  4. Cliquez sur Ajouter un rôle d'application. • Nom d'affichage : API.Access (ou un nom plus descriptif). • Types de membres autorisés : Applications. C'est le point crucial. • Valeur : API.Access. C'est le nom de la permission qui apparaîtra dans le jeton. • Description : "Permet à une application d'accéder à l'API Courrier."
  5. Cliquez sur Appliquer.

3. Donner la permission aux applications clientes​

Maintenant, vous devez lier les deux. Vous devez autoriser chaque application cliente à utiliser la permission que vous venez de créer.

  1. Retournez à l'inscription de l'application cliente (ex: "Client App - AddinWord").
  2. Allez dans Autorisations de l'API > Ajouter une autorisation.
  3. Sélectionnez l'onglet Mes API et choisissez votre application API (Kelios.CAM.Courrier.App).
  4. Sélectionnez Autorisations de l'application. La permission API.Access que vous avez créée à l'étape 2 devrait apparaître. Cochez-la.
  5. Cliquez sur Ajouter des autorisations.
  6. Étape très importante : Un administrateur doit cliquer sur le bouton "Accorder le consentement de l'administrateur pour [Votre Tenant]". Cela finalise l'octroi de la permission.

4. Mettre à jour les applications clientes pour obtenir le jeton​

Chaque application cliente doit maintenant être modifiée pour utiliser son ClientID et son ClientSecret afin de demander un jeton à Azure AD avant d'appeler votre API. La meilleure façon de le faire en .NET est d'utiliser la bibliothèque Microsoft.Identity.Client (MSAL). Voici un exemple conceptuel de ce que le code côté client pourrait faire :

// Les informations d'identification de l'application cliente
var clientId = "ID_CLIENT_DE_L_APP_SCORING";
var clientSecret = "SECRET_CLIENT_DE_L_APP_SCORING";
var tenantId = "VOTRE_ID_DE_TENANT_AZURE_AD";
var apiScope = "api://ID_CLIENT_DE_VOTRE_API/.default"; // Le scope pour le flux client credentials

// Créer une instance d'application confidentielle
var app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithAuthority(new Uri($"https://login.microsoftonline.com/{tenantId}"))
    .Build();

// Demander le jeton
AuthenticationResult result = await app.AcquireTokenForClient(new[] { apiScope })
    .ExecuteAsync();

// 'result.AccessToken' contient maintenant le jeton JWT
string accessToken = result.AccessToken;

// Utiliser le jeton pour appeler votre API
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

var response = await httpClient.GetAsync("https://.../API/CourrierManager/GetDateDerniereActiviteByNumeroTiersAsync");

Pour une application consommatrice non hébergée sur le tenant du CAM Azure Portal​

Pour être autorisé à consommer l'api, exploiter le client secrets de l'application Courrier présent dans Azure Portal (et Keepass pour un accès après création)

1. Prérequis​

  • Accès au portail Azure du CAM
  • Droits de lecture sur l’application CAM-Courrier-App-QUAL
  • Accès au client secret (via Azure Portal ou Keepass)

2. Récupération du client secret​

image.png

  1. Connectez-vous à Azure Portal.
  2. Naviguez vers Azure Active Directory > App registrations.
  3. Recherchez et sélectionnez l’application CAM-Courrier-App-QUAL.
  4. Allez dans Certificates & secrets.
  5. Si un secret existe, copiez sa valeur (attention, elle n’est visible qu’à la création).
  6. Si besoin, créez un nouveau secret :
    • Cliquez sur New client secret.
    • Donnez une description et une durée de validité.
    • Cliquez sur Add puis copiez la valeur générée.
  7. Stockez ce secret dans Keepass pour un accès sécurisé ultérieur.

3. Utilisation du client secret pour obtenir un token​

Pour consommer l’API, vous devez obtenir un token OAuth2 via le flux client credentials :

  • Tenant ID : [ID du tenant CAM]
  • Client ID : [ID de l’application CAM-Courrier-App-QUAL]
  • Client Secret : [Secret récupéré]
  • Scope : [Scope de l’API à consommer]

Exemple de requête POST (disponible dans le postman de courrier) : https://kelios.sharepoint.com/:u:/s/PROJ-CAM-SI/EQFEJZDl92hLmHzAezMqM6oBO2_UJzHYQ1k8NLvJ8UBbkA?e=Jvv086 image.png

4. Appel de l’API​

  • Utilisez le token reçu dans l’en-tête Authorization: Bearer &lt;token&gt; pour vos requêtes API.

Annexes

TODO