API de synchronisation Pharivia

Cette API permet à un logiciel de gestion de pharmacie (caisse, ERP, logiciel maison…)

de synchroniser automatiquement son stock avec Pharivia, afin que les

patients voient des quantités et des prix à jour dans leurs recherches.

• Base URL : https://<votre-domaine>/api/v1
• Format : JSON uniquement (Content-Type: application/json)
• Versionnage : le préfixe /v1 restera stable ; toute évolution non

rétrocompatible sera publiée sous /v2, /v1 continuant de fonctionner

pendant une période de transition annoncée à l'avance.

1. Authentification

Chaque pharmacie génère ses propres clés API depuis son tableau de bord

(Tableau de bord → Synchronisation). Une clé ressemble à :

pca_live_8f3a1c2e9b7d4f60a1c2e9b7d4f60a1c

Elle est affichée une seule fois, au moment de sa création — Pharivia

Africa ne stocke que son empreinte, jamais la valeur en clair. Si elle est

perdue, il faut en générer une nouvelle et révoquer l'ancienne.

Toutes les requêtes doivent inclure l'en-tête :

Authorization: Bearer pca_live_8f3a1c2e9b7d4f60a1c2e9b7d4f60a1c

Une clé invalide, révoquée, ou appartenant à une pharmacie dont le compte

n'est pas encore validé par l'administration renvoie 401 Unauthorized.

Limite de débit

60 requêtes par minute et par clé API. Au-delà, l'API renvoie `429 Too Many

Requests. L'en-tête X-RateLimit-Remaining` indique le nombre de requêtes

restantes dans la fenêtre courante.

2. GET /api/v1/version

Public, sans authentification. À appeler au démarrage de votre intégration

pour vérifier la compatibilité et détecter une éventuelle mise à jour requise.

curl https://votre-domaine/api/v1/version

{
  "versionActuelle": "1.1.0",
  "versionMinimale": "1.0.0",
  "statut": "stable",
  "notesDeVersion": [
    { "version": "1.1.0", "date": "2026-09-07", "changements": ["Ajout du champ `devise`."] },
    { "version": "1.0.0", "date": "2026-08-09", "changements": ["Première version publique."] }
  ]
}

Si versionMinimale dépasse la version que votre intégration a été codée

pour supporter, avertissez votre utilisateur qu'une mise à jour du connecteur

est nécessaire avant de continuer.

3. GET /api/v1/pharmacie

Confirme l'identité de la pharmacie liée à la clé API — utile juste après la

configuration, pour vérifier que la bonne clé a été saisie.

curl https://votre-domaine/api/v1/pharmacie \
  -H "Authorization: Bearer pca_live_..."

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "nom": "Pharmacie du Tokoin",
  "pays": "TOGO",
  "devise": { "code": "XOF", "symbole": "FCFA" },
  "adresse": "Avenue du Général de Gaulle, Tokoin, Lomé",
  "telephone": "+228 90 11 22 33",
  "statutValidation": "VALIDEE"
}

Pharivia couvre plus de 40 pays, chacun avec sa propre devise — devise

indique dans quelle unité les champs prix de /api/v1/stock (ci-dessous)

sont exprimés pour cette pharmacie, sans avoir à maintenir votre propre

table de correspondance pays → devise.

4. GET /api/v1/stock

Renvoie l'état actuel du stock tel que connu par Pharivia

Africa. Utile pour détecter les écarts avant d'envoyer une synchronisation.

Paginé : page (à partir de 1) et limite (1000 par défaut et au maximum). Pour un

stock de plus de 1000 lignes, répétez l'appel en incrémentant page tant que

pagination.aPlusDePages vaut true.

curl "https://votre-domaine/api/v1/stock?page=1&limite=1000" \
  -H "Authorization: Bearer pca_live_..."

{
  "pagination": { "page": 1, "limite": 1000, "total": 2450, "totalPages": 3, "aPlusDePages": true },
  "devise": "XOF",
  "stock": [
    {
      "codeExterne": "DOL500-BT16",
      "medicament": { "nom": "Doliprane 500mg", "molecule": "Paracétamol", "categorie": "Antalgique" },
      "quantite": 42,
      "prix": 1500,
      "statut": "DISPONIBLE",
      "derniereMaj": "2026-08-09T14:32:00.000Z"
    }
  ]
}

5. PUT /api/v1/stock — synchronisation en masse

Point d'entrée principal de l'intégration. Envoie jusqu'à **500 lignes par

appel** ; pour un catalogue plus large, envoyez plusieurs appels successifs.

Identification d'une ligne de stock

Chaque ligne est identifiée par, dans cet ordre de priorité :

1. codeExterne — l'identifiant interne de votre logiciel (référence

produit, code-barres, etc.). Recommandé : stable dans le temps, ne dépend

pas d'un renommage du médicament.

1. nom (repli) — si aucun codeExterne n'est fourni, ou si aucune ligne

existante ne correspond à ce codeExterne pour cette pharmacie,

Pharivia cherche une correspondance par nom du médicament dans son

catalogue, sans tenir compte des majuscules, des accents, des espaces en

trop ni de l'espace entre le dosage et l'unité (« DOLIPRANE 1000 MG » =

« Doliprane 1000mg »). Si aucun médicament de ce nom n'existe encore, il

est créé automatiquement dans le catalogue central à partir de nom,

molecule et categorie.

Requête

curl -X PUT https://votre-domaine/api/v1/stock \
  -H "Authorization: Bearer pca_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "lignes": [
      {
        "codeExterne": "DOL500-BT16",
        "nom": "Doliprane 500mg",
        "molecule": "Paracétamol",
        "categorie": "Antalgique",
        "quantite": 42,
        "prix": 1500
      },
      {
        "nom": "Amoxicilline 500mg",
        "quantite": 0,
        "prix": 2200
      }
    ]
  }'

Le statut de disponibilité (DISPONIBLE / STOCK_FAIBLE / RUPTURE) est

calculé automatiquement à partir de la quantité (0 → rupture, ≤10 →

stock faible, au-delà → disponible) — il n'est pas envoyé par le client.

Réponse

Chaque ligne est traitée indépendamment : une ligne en erreur n'annule pas

les autres.

{
  "synchronisees": 2,
  "erreurs": 0,
  "resultats": [
    { "codeExterne": "DOL500-BT16", "nom": "Doliprane 500mg", "statut": "ok" },
    { "nom": "Amoxicilline 500mg", "statut": "ok" }
  ]
}

6. Codes d'erreur

7. Bonnes pratiques d'intégration

• Appelez GET /api/v1/version au démarrage, pas à chaque synchronisation.
• Privilégiez codeExterne à nom dès que possible : plus robuste face aux

renommages ou aux médicaments homonymes entre catégories.

• Synchronisez par lots raisonnables (quelques dizaines à quelques centaines

de lignes) plutôt que ligne par ligne, pour rester sous la limite de débit.

• Stockez la clé API de façon sécurisée côté client (jamais en clair dans un

fichier de configuration versionné).