Aller au contenu
Officidata Officidata

Documentation

Documentation de l’API, du connecteur et des outils d’Officidata

Tout ce qu’il faut pour brancher un assistant IA, un tableur ou un script sur les achats, les ventes et le stock de votre officine, et pour faire créer des outils par votre assistant : les deux adresses, l’authentification, les fonctions du connecteur, les routes de l’API, la création d’un outil, le format des réponses, les codes d’erreur et les quotas.

Avant de commencer

Trois gestes, faits une fois, depuis votre espace.

  1. 1Créez votre espace et installez le logiciel sur un poste de l’officine : il lit Winpharma, LGPI ou Leo sans rien y écrire.
  2. 2Acceptez l’accord de partage dans l’onglet « Partage des données » (formule gratuite), ou prenez la formule Pro.
  3. 3Créez une clé dans l’onglet « Clés d’API », en cochant « Autoriser cette clé à créer des outils » si votre assistant doit en créer, ou suivez l’onglet « Brancher mon IA » pour Claude et ChatGPT.

Une seule officine par clé

Le serveur déduit l’officine de la clé ou de l’autorisation, jamais d’un paramètre de la demande : un outil ne peut pas lire les données d’une autre officine.

Les deux adresses

Serveur MCP (connecteur) : Claude, ChatGPT, Claude Code, CursorTexte
https://api.pharwiz.com/api/v1/donnees-ia/mcp
API : vos scripts, vos tableurs, vos tableaux de bordTexte
https://api.pharwiz.com/api/v1/donnees-ia/v1

MCP (Model Context Protocol) est le standard ouvert par lequel les assistants IA appellent des outils extérieurs. Le serveur MCP d’Officidata répond en JSON-RPC 2.0, en Streamable HTTP : requêtes POST, réponses application/json. Les versions de protocole 2025-06-18, 2025-03-26 et 2024-11-05 sont acceptées : initialize retient celle de l’assistant si elle est dans la liste, sinon 2025-06-18.

  • Un message par requête : un lot (tableau de messages) est refusé, code -32600.
  • Une notification reçoit 202, sans corps. GET et DELETE reçoivent 405 : le serveur n’ouvre pas de flux.
  • Sans état de session : chaque requête porte sa clé ou son jeton, vérifié à chaque fois.
  • Un message fait 64 Kio au plus, 4 Mio avec une clé ou une autorisation qui a le droit outils (le temps de déposer une page).
  • Un en-tête MCP-Protocol-Version d’une version inconnue reçoit 400.

S’authentifier

Chaque appel porte l’en-tête Authorization: Bearer <clé>. La clé est soit une clé d’API créée dans votre espace (elle commence par odk_live_), soit un jeton d’accès obtenu par OAuth (il commence par odk_oauth_), que Claude et ChatGPT demandent eux-mêmes. Une clé absente ou refusée reçoit 401 avec le code cle_invalide et l’en-tête WWW-Authenticate.

  • Une clé n’est montrée qu’une fois, à sa création : copiez-la aussitôt. Nous n’en gardons qu’une empreinte, qui ne permet pas de la retrouver.
  • Dix clés actives au plus par officine, chacune nommée (de 1 à 64 caractères) : un usage, une clé. Les applications autorisées par OAuth ont leur propre plafond, vingt par officine.
  • Une clé porte le droit lecture, toujours, et le droit outils (créer et mettre à jour des outils) seulement si vous avez coché « Autoriser cette clé à créer des outils » à sa création.
  • Seul le titulaire, ou un administrateur de l’espace de l’officine, crée et retire les clés.
  • Une clé cesse de fonctionner dès qu’elle est retirée, que l’officine n’a plus accès à l’application, ou que la personne qui l’a créée n’administre plus l’officine.
Vérifier une cléTerminal
curl -sS https://api.pharwiz.com/api/v1/donnees-ia/v1/moi \
  -H "Authorization: Bearer odk_live_VOTRE_CLE"

Gardez la clé pour vous

Ne collez jamais une clé dans un document partagé, un e-mail ou un dépôt de code : qui la détient lit les données de l’officine jusqu’à ce que vous la retiriez.

Brancher votre assistant

Claude et ChatGPT passent par une autorisation (OAuth) ; Claude Code, Cursor et vos scripts, par une clé.

Claude

  1. 1Dans les réglages de Claude, ouvrez les connecteurs et ajoutez un connecteur personnalisé. Selon votre abonnement, cette possibilité peut ne pas être ouverte.
  2. 2Nommez-le Officidata et collez l’adresse du serveur MCP : https://api.pharwiz.com/api/v1/donnees-ia/mcp.
  3. 3Connectez-vous à votre compte, choisissez l’officine et autorisez la lecture. Si Claude demande aussi la création d’outils, l’écran d’autorisation le montre avec une case « Autoriser aussi la création d’outils », cochée puisque Claude la demande : décochez-la pour n’autoriser que la lecture.
  4. 4Dans une conversation, activez le connecteur, puis posez votre question ou décrivez l’outil que vous voulez.

ChatGPT

  1. 1Dans les réglages de ChatGPT, ouvrez la partie consacrée aux connecteurs. Selon votre abonnement, il peut falloir activer le mode développeur.
  2. 2Créez un connecteur avec l’adresse du serveur MCP : https://api.pharwiz.com/api/v1/donnees-ia/mcp, authentification OAuth.
  3. 3Connectez-vous à votre compte, choisissez l’officine et autorisez la lecture. Si ChatGPT demande aussi la création d’outils, la même case vous laisse l’accorder ou non.

Claude Code

Ajouter le serveur MCPTerminal
claude mcp add --transport http officidata \
  https://api.pharwiz.com/api/v1/donnees-ia/mcp \
  --header "Authorization: Bearer odk_live_VOTRE_CLE"

Cursor

Fichier ~/.cursor/mcp.jsonJSON
{
  "mcpServers": {
    "officidata": {
      "url": "https://api.pharwiz.com/api/v1/donnees-ia/mcp",
      "headers": { "Authorization": "Bearer odk_live_VOTRE_CLE" }
    }
  }
}

Toute autre application compatible MCP se branche de la même façon : l’adresse du serveur, et l’en-tête Authorization avec une clé.

OAuth pour Claude et ChatGPT

Claude et ChatGPT n’acceptent pas une clé collée : ils passent par OAuth 2.1, et trouvent seuls les adresses à partir de celle du serveur MCP.

  1. 1L’assistant appelle le serveur MCP sans jeton ; le serveur répond 401 avec l’en-tête WWW-Authenticate, qui donne l’adresse de ses métadonnées.
  2. 2L’assistant s’enregistre de lui-même (enregistrement dynamique), puis ouvre une page de connexion à votre compte.
  3. 3Vous choisissez l’officine et vous autorisez la lecture. Si l’application demande aussi la création d’outils, l’écran le dit avec une case « Autoriser aussi la création d’outils », cochée puisque l’application la demande : décochée, seule la lecture est accordée, et le jeton rend la portée réellement accordée dans scope. L’application apparaît alors parmi les applications autorisées de votre espace, d’où vous la retirez quand vous voulez.
ÉlémentValeur
Métadonnées de la ressource (RFC 9728)https://api.pharwiz.com/.well-known/oauth-protected-resource/api/v1/donnees-ia/mcp
Serveur d’autorisation (émetteur)https://api.pharwiz.com/api/v1/donnees-ia/oauth
Métadonnées du serveur d’autorisation (RFC 8414)https://api.pharwiz.com/.well-known/oauth-authorization-server/api/v1/donnees-ia/oauth, ou https://api.pharwiz.com/api/v1/donnees-ia/oauth/.well-known/oauth-authorization-server
Points d’accès/register, /authorize, /token, /revoke, sous l’émetteur
Enregistrement (RFC 7591)redirect_uris : de 1 à 10 adresses en https, ou une adresse locale du poste, sans fragment, 500 caractères au plus ; client_name : 100 caractères au plus. Vingt enregistrements par heure et par adresse IP.
Portéesdonnees:lecture (lire les données, toujours comprise) ; outils:ecriture (créer et mettre à jour des outils dans votre espace), si l’application la demande dans scope et que vous l’accordez
FluxCode d’autorisation avec PKCE (S256 obligatoire), application publique sans secret ; resource, s’il est donné, doit être l’adresse du serveur MCP
DuréesDemande d’autorisation valable dix minutes ; code valable cinq minutes, une seule fois
JetonsAccès valable une heure (expires_in) ; renouvellement valable 90 jours, remplacé à chaque usage : un renouvellement déjà utilisé, présenté une seconde fois, retire l’autorisation
ErreursAu format RFC 6749 : {"error": …, "error_description": …}. La révocation (/revoke, RFC 7009) répond toujours 200.

Toujours avec le chemin

Les métadonnées d’Officidata ne sont servies qu’avec leur chemin. Les adresses /.well-known/oauth-protected-resource et /.well-known/oauth-authorization-server nues, à la racine de api.pharwiz.com, ne décrivent pas Officidata : partez de l’en-tête WWW-Authenticate du serveur MCP, ou des adresses ci-dessus.

Les fonctions du connecteur (outils MCP)

Dans le vocabulaire MCP, les fonctions qu’un assistant peut appeler s’appellent des « outils ». Elles servent à lire vos données, et, avec le droit outils, à créer les vôtres.

FonctionCe qu’elle fait
guide_donneesLe guide des données : tables, colonnes, pièges à connaître, et la couverture de votre officine. À lire en premier.
mon_officineVotre officine, votre formule, le quota du jour, l’accord de partage et la couverture des données, comme /moi. Ne compte pas dans le quota.
achatsLes lignes d’achat, les plus récentes d’abord : par période, produit, grossiste ou code CIP, par pages. Mêmes paramètres que la route /achats.
ventesLes ventes, les plus récentes d’abord : par période, produit ou code CIP, par pages. Mêmes paramètres que la route /ventes.
stockLes produits de la dernière photo du stock, de la plus grande valeur à la plus petite. Mêmes paramètres que la route /stock.
indicateurs_mensuelsMois par mois : le nombre de commandes, les achats, le nombre de jours de vente et le chiffre d’affaires hors taxes. Paramètres du et au.
requete_sqlUne requête SELECT en lecture seule sur les vues de votre officine. Deux paramètres obligatoires : sql, et objet, ce que la requête compte, en une phrase (repris dans la réponse).
achats_par_generiqueurFormule Pro : vos achats de génériques regroupés par génériqueur, avec le montant brut, le montant commandé et la remise obtenue. Paramètres du et au, depuis le 1er janvier par défaut. En formule gratuite, la fonction répond qu’elle fait partie de la formule Pro.
guide_outilsLe guide d’écriture d’un outil : l’environnement où il tourne, les flux qu’il peut lire, la charte, la sécurité et les états attendus. À lire avant d’écrire un outil ; ne demande pas le droit outils.
lister_outilsLes outils déjà déposés par ce connecteur dans l’espace de votre officine, avec le lien pour ouvrir chacun. Demande le droit outils.
deployer_outilDépose un outil dans votre espace : nom, html et flux, obligatoires, et facultativement description et slug. Le slug d’un outil déjà déposé par ce connecteur en dépose une nouvelle version ; sans slug, un nouvel outil est créé et rien n’est remplacé. Rend url_ouvrir. Demande le droit outils.

Chaque résultat arrive en texte (JSON, dans content) et en contenu structuré (structuredContent). Une erreur métier, comme un quota atteint, une formule Pro requise, un paramètre mal formé ou un droit outils absent, revient comme un résultat isError: true : son texte est un message en français que l’assistant lit et vous explique, et son contenu structuré porte le code (erreur) et ce message.

Les routes de l’API

Toutes les routes sont relatives à https://api.pharwiz.com/api/v1/donnees-ia/v1 et répondent en JSON.

GET/moi

Votre officine (nom, ville), la formule (gratuit ou pro), le quota du jour (jour, utilises, limite), l’accord de partage (accepte, depuis, requis), la couverture des achats, des ventes, du stock et des indicateurs, et la clé utilisée (nom, prefixe, origine).

Ne compte pas dans le quota.

GET/guide

Le guide des données en markdown (guide) : chaque vue, chaque colonne, les pièges à connaître ; et la couverture de votre officine (couverture).

GET/achats

Les lignes d’achat, de la plus récente à la plus ancienne. Chaque ligne porte notamment la date de commande, le numéro de facture, le grossiste et son type, le code CIP, le produit, la quantité, le prix unitaire, la remise, le prix net, les montants commandé et reçu hors taxes, le taux de TVA, la péremption et le lot.

du
Date de début, au format AAAA-MM-JJ.
au
Date de fin, au format AAAA-MM-JJ, après du.
produit
Une partie du nom du produit, 80 caractères au plus, sans distinction de majuscules.
fournisseur
Une partie du nom du grossiste ou du génériqueur qui a livré, 80 caractères au plus.
cip13
Le code CIP à 13 chiffres exactement.
limite
Le nombre de lignes par page : 100 par défaut, de 1 à 500.
page
Le numéro de page, de 1 (par défaut) à 1 000 : page=2, puis page=3. La réponse donne page_suivante.

GET/ventes

Les ventes, de la plus récente à la plus ancienne. Selon le logiciel de gestion, une vente est souvent une journée de caisse, pas un ticket.

du
Date de début, au format AAAA-MM-JJ.
au
Date de fin, au format AAAA-MM-JJ, après du.
produit
Une partie du nom du produit, 80 caractères au plus.
cip13
Le code CIP à 13 chiffres exactement.
limite
Le nombre de lignes par page : 100 par défaut, de 1 à 500.
page
Le numéro de page, de 1 (par défaut) à 1 000.

GET/stock

Les produits de la dernière photo du stock, de la plus grande valeur à la plus petite, en valeur hors taxes et toutes taxes. Un produit absent de la photo n’est pas forcément à zéro.

produit
Une partie du nom du produit, 80 caractères au plus.
cip13
Le code CIP à 13 chiffres exactement.
limite
Le nombre de lignes par page : 100 par défaut, de 1 à 500.
page
Le numéro de page, de 1 (par défaut) à 1 000.

GET/indicateurs

Les indicateurs mensuels, du mois le plus récent au plus ancien : nombre de commandes, achats hors taxes, nombre de jours de vente (nb_tickets) et chiffre d’affaires hors taxes.

du
Date de début, au format AAAA-MM-JJ : le mois de cette date est compris en entier.
au
Date de fin, au format AAAA-MM-JJ.

POST/requete

Une requête SELECT (ou WITH … SELECT) en lecture seule sur les vues de votre officine. Corps JSON : {"sql": "SELECT …", "objet": "…"}, sql de 4 000 caractères au plus, objet facultatif (ce que la requête compte, repris dans detail_du_calcul).

Réponse : 200 lignes au plus ; au-delà, tronque vaut true et avertissement le dit. Une requête refusée par les contrôles reçoit 422 avec le code requete_invalide et la raison.

GET/achats/par-generiqueur

Formule Pro : vos achats de génériques regroupés par génériqueur, du plus gros au plus petit. Colonnes generiqueur, brut_ht (prix catalogue), commande_ht (prix net facturé), remise_eur, remise_pct, part_pct et nb_lignes, plus la période lue (periode).

du
Date de début, au format AAAA-MM-JJ : le 1er janvier de l’année de au par défaut.
au
Date de fin, au format AAAA-MM-JJ : aujourd’hui par défaut.

En formule gratuite : 402 avec le code reserve_pro.

GET/outils

Les outils déjà créés dans l’espace de votre officine : {"outils": […], "nb_outils", "maximum"}. Pour chaque outil : id, slug, nom, version, statut (actif ou desactive), flux, mis_a_jour_le et url_ouvrir (vide pour un outil désactivé).

Demande une clé avec le droit outils.

GET/outils/guide

Le guide d’écriture d’un outil (guide, en markdown) : l’environnement, les flux, la charte, la sécurité et les états attendus. Le même guide que la fonction guide_outils, avec les flux possibles (flux_possibles) et les plafonds (limites).

Ne demande ni le droit outils ni l’accord de partage ; compte dans le quota.

POST/outils

Dépose un outil dans votre espace. Corps JSON, sans autre champ que ceux-ci ; le slug d’un outil déjà déposé par l’API ou le connecteur en dépose une nouvelle version. Demande une clé avec le droit outils.

nom
Obligatoire : le nom de l’outil, tel qu’il s’affiche dans votre espace, 80 caractères au plus.
html
Obligatoire : la page complète, en un seul fichier (document HTML avec sa balise <html>, CSS et JavaScript dans le même document). 1 Mo au plus.
flux
Obligatoire : la liste des flux que l’outil lira, parmi achats, ventes et stock, par exemple ["achats", "stock"]. Il ne pourra lire que ceux-là.
description
Facultatif : ce que fait l’outil, en une phrase, 500 caractères au plus.
slug
Facultatif : l’identifiant de l’outil, de 2 à 48 caractères, en lettres minuscules, chiffres et tirets simples ; tiré du nom s’il est absent (un slug libre : un nouvel outil, jamais un remplacement). Celui d’un outil déjà déposé par l’API ou le connecteur dépose une nouvelle version ; celui d’un outil ajouté autrement est refusé (409 slug_pris).

Réponse : 201 à la création, 200 pour une nouvelle version : {"id", "slug", "nom", "version", "cree", "flux", "url_ouvrir", "message"}. url_ouvrir ouvre l’outil dans votre espace, après connexion ; il n’existe pas de lien sans connexion.

Les filtres sont relus par le serveur

Une date doit être au format AAAA-MM-JJ, un code CIP faire 13 chiffres, un texte 80 caractères au plus. La requête est construite par le serveur à partir de ces valeurs, puis passe par les mêmes contrôles qu’une requête SQL écrite à la main.

Créer un outil

Un outil est une petite application d’une seule page, écrite par votre assistant IA et déposée dans votre espace, où elle lit vos données sur place.

Vous décrivez l’outil avec vos mots ; votre assistant lit le guide d’écriture, écrit la page (HTML, CSS et JavaScript dans un seul fichier), la dépose dans votre espace et vous rend le lien pour l’ouvrir. L’outil tourne ensuite chez Pharwiz, sur vos données, isolé : il ne peut appeler que l’API, et ce qu’il affiche ne repasse pas par votre assistant. Il est partagé avec l’équipe de l’officine. Comme pour tout logiciel que vous installez, relisez ce que votre assistant dépose.

Ce qu’il faut

  • Une clé avec le droit outils (case « Autoriser cette clé à créer des outils », jamais cochée d’office), ou une autorisation OAuth avec la portée outils:ecriture, acceptée sur l’écran d’autorisation.
  • Une officine qui a accès à l’application, et à l’espace où tournent les outils, compris dans l’application ; en formule gratuite, l’accord de partage accepté, comme pour la lecture.
  • Une clé créée, ou une application autorisée, par le titulaire ou un administrateur de l’espace qui l’est toujours.
  • Pas un espace de démonstration : aucun outil ne s’y dépose.

Comment votre assistant s’y prend

  1. 1Il lit le guide d’écriture : la fonction guide_outils par le connecteur, ou GET /outils/guide par l’API.
  2. 2Il écrit la page, en déclarant dans flux les données qu’elle lira.
  3. 3Il la dépose avec la fonction deployer_outil, ou POST /outils. Avec le slug d’un outil qu’il a déjà déposé, il en dépose une nouvelle version.
  4. 4Il vous rend le lien url_ouvrir de la réponse, qui ouvre l’outil dans votre espace, après connexion.
Déposer un outil par l’APITerminal
curl -sS -X POST https://api.pharwiz.com/api/v1/donnees-ia/v1/outils \
  -H "Authorization: Bearer odk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Produits qui dorment",
    "flux": ["stock", "ventes"],
    "slug": "produits-qui-dorment",
    "html": "<!doctype html><html lang=\"fr\">…</html>"
  }'
La réponseJSON
{
  "id": "…",
  "slug": "produits-qui-dorment",
  "nom": "Produits qui dorment",
  "version": 1,
  "cree": true,
  "flux": ["stock", "ventes"],
  "url_ouvrir": "…",
  "message": "…"
}

Ce que l’outil peut appeler, une fois déposé

À l’ouverture, l’outil reçoit dans son adresse un jeton de session, le paramètre st, valable 30 minutes. Il le présente dans l’en-tête Authorization: Bearer <st> et le renouvelle avant son terme par POST /api/v1/data/v1/session/rafraichir, dont la réponse donne le nouveau jeton (token) ; la chaîne de renouvellements s’arrête au bout de douze heures. Ses adresses sont relatives : il appelle l’API qui le sert, et rien d’autre.

Ses appels ne sont pas les routes de l’API décrites plus haut : ce sont celles de l’espace, toutes sous /api/v1/data/v1, en lecture (GET) sauf le stockage.

AdresseCe qu’elle rend
/achatsUne commande par élément, avec ses lignes : période depuis et jusqua (au format AAAA-MM-JJ), pages limit (200 au plus) et offset.
/ventesUne vente par élément (souvent une journée de caisse), avec ses lignes, mêmes paramètres.
/stockSans paramètre, la dernière photo du stock, un produit par élément ; date, depuis, limit et offset pour une autre photo.
/achats/agregatsDes totaux d’achats regroupés (par=mois, par=produit, ou par grossiste : la valeur est dans le guide d’écriture), pour un historique long sans tout parcourir ; depuis et jusqua.
/ventes/agregatsLes mêmes totaux pour les ventes (par=mois, par=produit ou par=categorie).
/stockageLes collections du stockage propre à l’outil, et leur taille.
/stockage/{collection}Le stockage propre à l’outil, ses réglages et ses listes, partagés par l’équipe : lu (GET), remplacé (PUT) ou effacé (DELETE). Une collection absente se lit avec payload à null.

Une liste répond {"flux", "items", "limit", "offset", "count"} : pour tout lire, l’outil boucle tant que count vaut limit. L’outil ne lit que les flux déclarés dans flux. La liste complète des champs est dans le guide d’écriture.

Dans la page de l’outilJavaScript
const st = new URLSearchParams(location.search).get('st')
const r = await fetch('/api/v1/data/v1/stock?limit=200', {
  headers: { Authorization: 'Bearer ' + st },
})
const { items } = await r.json()

Ce que l’outil ne peut pas faire

  • Appeler une autre adresse que l’API : la règle connect-src 'self' posée sur sa page fait bloquer par le navigateur tout autre envoi.
  • Lire un flux qu’il n’a pas déclaré, ou les données d’une autre officine.
  • Garder un accès durable : sa session dure 30 minutes, ne se renouvelle que pendant que l’outil est ouvert, et jamais au-delà de douze heures.
  • Écrire dans vos données ou dans votre logiciel de gestion : il n’écrit que dans son propre stockage.

Plafonds

  • Vingt outils par officine, et 1 Mo par page.
  • Un nom de 80 caractères au plus, une description de 500 au plus.
  • Un slug de 2 à 48 caractères : lettres minuscules, chiffres et tirets simples.
  • Chaque dépôt, nouvelle version comprise, compte dans le quota du jour ; 200 dépôts au plus par jour et par clé.
  • Un outil lit ses flux dans la limite de 5 000 appels par jour, et garde 1 Mo de stockage en 20 collections au plus.

Pas de lien sans connexion

url_ouvrir ouvre l’outil dans votre espace, après connexion : il n’existe pas de lien qui l’ouvre sans. Un outil déposé par l’API ou le connecteur ne s’ouvre que tant que l’officine a accès à l’application et, en formule gratuite, que l’accord de partage est en vigueur.

Un exemple de message à donner à Claude

À coller dans une conversation où le connecteur est activéTexte
Avec le connecteur Officidata, crée-moi un outil « Produits qui dorment » :
la liste des produits en stock qui ne se sont pas vendus depuis 90 jours,
avec leur quantité et leur valeur au prix d’achat hors taxes,
de la plus grosse valeur à la plus petite, et la valeur totale en haut.
Lis d’abord guide_outils, puis dépose l’outil avec deployer_outil
et donne-moi le lien pour l’ouvrir.

Le format des réponses

Une réponse de /ventesJSON
{
  "colonnes": ["date_vente", "numero_ticket", "cip13", "produit", "categorie", "quantite",
               "prix_unitaire_ht", "remise_pct", "montant_ht", "chiffre_affaires_ht", "taux_tva"],
  "lignes": [["2026-10-28", "20261028", "3400930000000", "PARACETAMOL 1000MG CPR B/8",
              "ordonnance", 24, 1.32, 0, 31.68, 31.68, 2.1]],
  "nb_lignes": 1,
  "tronque": true,
  "couverture": { "ventes": { "dernier": "2026-10-31" } },
  "avertissement": null,
  "page": 1,
  "limite": 1,
  "page_suivante": 2
}
  • colonnes : les noms des colonnes, dans l’ordre des valeurs de chaque ligne.
  • lignes : une ligne par élément, les nombres en nombres JSON, le code CIP en texte.
  • nb_lignes et tronque : tronque vaut true quand d’autres lignes existent au-delà de la limite.
  • page, limite et page_suivante (routes en pages seulement) : page_suivante vaut null à la dernière page.
  • couverture : jusqu’à quelle date vont les données lues (dernier pour les achats et les ventes, date_photo pour le stock, dernier_mois pour les indicateurs). Une période après la dernière date remontée n’est pas un zéro : ces données ne sont pas encore arrivées. /moi et /guide donnent la couverture complète, avec les premières dates et les nombres de lignes.
  • avertissement : ce qu’il faut savoir avant de conclure, quand il y a lieu.
  • Tous les montants sont hors taxes, sauf les colonnes _ttc du stock.
Une erreurJSON
{
  "detail": {
    "code": "partage_requis",
    "message": "La formule gratuite demande d'accepter l'accord de partage de statistiques anonymes (écran « Partage des données » de l'application)."
  }
}

Une erreur de l’API répond toujours {"detail": {"code", "message", …}} : code est stable, à tester dans vos scripts ; message est en français, prêt à afficher. Certains codes ajoutent un champ : champ pour un paramètre mal formé, limite et reinitialisation pour un quota atteint, retry_after pour une rafale.

Requêtes SQL

La route /requete et la fonction requete_sql acceptent une seule requête de lecture sur les vues de votre officine.

VueUne ligne =
ana_officine_achatsune ligne d’achat
ana_officine_ventesune ligne de vente
ana_officine_stockun produit d’une photo du stock
ana_officine_stock_actuelun produit de la dernière photo du stock
ana_officine_kpis_mensuelsun mois
ana_officine_kpis_journaliersun jour

Le détail de chaque colonne est servi par /guide et par la fonction guide_donnees. Une requête fait 4 000 caractères au plus, s’exécute en 10 secondes au plus et rend 200 lignes au plus : agrégez plutôt que de lister.

  • La requête est relue avant d’être exécutée : seules les vues de votre officine et des fonctions connues sont acceptées.
  • Elle s’exécute dans une transaction en lecture seule.
  • Elle s’exécute sous un rôle qui ne voit que les vues de votre officine.
  • Un contrôle après exécution écarte tout résultat qui ne serait pas celui de votre officine.
Achats hors taxes par mois depuis janvierSQL
SELECT date_trunc('month', date_commande) AS mois,
       sum(montant_ht) AS achats_ht
FROM ana_officine_achats
WHERE date_commande >= '2026-01-01'
GROUP BY 1
ORDER BY 1
Envoyer une requêteTerminal
curl -sS -X POST https://api.pharwiz.com/api/v1/donnees-ia/v1/requete \
  -H "Authorization: Bearer odk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT count(*) AS lignes, min(date_commande) AS premier, max(date_commande) AS dernier FROM ana_officine_achats"}'

Codes d’erreur et quotas

Statut HTTPCodeCe qu’il veut dire
401cle_invalideClé absente, inconnue, retirée ou expirée, ou jeton d’accès expiré (à renouveler).
402application_non_souscriteL’officine n’a pas, ou plus, accès à l’application.
402reserve_proLa route demande la formule Pro.
402mes_apps_inaccessibleOutils : l’espace où ils tournent n’est pas ouvert pour l’officine.
403partage_requisFormule gratuite sans accord de partage accepté.
403droit_outils_requisOutils : la clé ou l’autorisation n’a pas le droit outils ; le message dit comment l’obtenir.
409espace_demonstrationOutils : un espace de démonstration ne reçoit aucun outil.
409trop_d_outilsOutils : l’espace de l’officine compte déjà vingt outils ou apps.
409slug_reserveOutils : ce slug désigne un outil qui ne se remplace pas ; choisissez-en un autre.
409slug_prisOutils : ce slug désigne un outil que l’API ou le connecteur n’a pas déposé ; il ne se remplace pas d’ici.
409depot_concurrentOutils : un dépôt du même outil vient d’avoir lieu ; réessayez dans un instant.
413corps_trop_volumineuxOutils : le corps du dépôt est trop volumineux.
422parametre_invalideUn paramètre est mal formé : date, code CIP, limite, page, texte trop long, champ inconnu ; champ le nomme.
422requete_invalideLa requête SQL est refusée par les contrôles ; le message dit pourquoi.
422html_trop_volumineux, html_invalideOutils : la page dépasse 1 Mo, ou n’est pas un document HTML complet.
429quota_atteintLe quota du jour est atteint ; la réponse donne limite et reinitialisation.
429trop_rapideTrop d’appels en une minute ; attendez la durée donnée par l’en-tête Retry-After.
429trop_de_depotsOutils : trop de dépôts aujourd’hui avec cette clé.
503indisponibleLe service est momentanément indisponible ; réessayez.
QuotaGratuitPro
Appels par jour, pour l’officine3005 000
Appels par minute, pour une clé60120
Appels par minute, pour l’officine, toutes clés confondues120300

Le jour est le jour civil, à l’heure de Paris. initialize, tools/list, ping, /moi et mon_officine ne comptent pas dans le quota ; tout autre appel compte, guides compris, sauf s’il est refusé avant la lecture (paramètre mal formé, accord de partage manquant, formule Pro requise, rafale dépassée). Une requête SQL refusée par les contrôles compte. Sur le connecteur, un quota atteint ou une rafale dépassée pendant un appel de fonction revient comme un résultat isError: true.

Exemples

Les achats d’octobre d’un produitTerminal
curl -sS "https://api.pharwiz.com/api/v1/donnees-ia/v1/achats?du=2026-10-01&au=2026-10-31&produit=paracetamol&limite=50" \
  -H "Authorization: Bearer odk_live_VOTRE_CLE"
Les indicateurs mensuels en PythonPython
import requests

API = "https://api.pharwiz.com/api/v1/donnees-ia/v1"
ENTETES = {"Authorization": "Bearer odk_live_VOTRE_CLE"}

r = requests.get(f"{API}/indicateurs", headers=ENTETES,
                 params={"du": "2026-01-01", "au": "2026-10-31"}, timeout=30)
r.raise_for_status()
donnees = r.json()
for ligne in donnees["lignes"]:
    print(dict(zip(donnees["colonnes"], ligne)))
print("Couverture :", donnees["couverture"])

Sécurité et confidentialité

  • Vos données en lecture seule : aucune route n’écrit dans vos données ni dans votre logiciel de gestion. La seule écriture possible est le dépôt d’un outil dans votre espace, avec une clé ou une autorisation qui en a le droit.
  • Un outil déposé tourne isolé dans votre espace et ne peut appeler que l’API : le navigateur bloque ses appels vers tout autre serveur. Relisez ce que votre assistant dépose, comme tout logiciel que vous installez.
  • Aucune donnée de patient : seulement des achats, des ventes et du stock.
  • L’officine est déduite de la clé, jamais de la demande.
  • Chaque appel est inscrit dans un journal que vous consultez depuis votre espace.
  • Une clé ou une application autorisée se retire d’un clic ; l’accès s’arrête aussitôt.

Ce qu’un assistant IA reçoit pour vous répondre est ensuite traité par son éditeur, selon les conditions de votre compte chez lui.

Créer votre espace Officidata

Votre assistant IA répond sur les achats, les ventes et le stock de votre officine, et crée les outils qu’il vous manque.