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.
- 1Créez votre espace et installez le logiciel sur un poste de l’officine : il lit Winpharma, LGPI ou Leo sans rien y écrire.
- 2Acceptez l’accord de partage dans l’onglet « Partage des données » (formule gratuite), ou prenez la formule Pro.
- 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
https://api.pharwiz.com/api/v1/donnees-ia/mcphttps://api.pharwiz.com/api/v1/donnees-ia/v1MCP (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.GETetDELETEreçoivent405: 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-Versiond’une version inconnue reçoit400.
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 droitoutils(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.
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
- 1Dans les réglages de Claude, ouvrez les connecteurs et ajoutez un connecteur personnalisé. Selon votre abonnement, cette possibilité peut ne pas être ouverte.
- 2Nommez-le Officidata et collez l’adresse du serveur MCP :
https://api.pharwiz.com/api/v1/donnees-ia/mcp. - 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.
- 4Dans une conversation, activez le connecteur, puis posez votre question ou décrivez l’outil que vous voulez.
ChatGPT
- 1Dans les réglages de ChatGPT, ouvrez la partie consacrée aux connecteurs. Selon votre abonnement, il peut falloir activer le mode développeur.
- 2Créez un connecteur avec l’adresse du serveur MCP :
https://api.pharwiz.com/api/v1/donnees-ia/mcp, authentification OAuth. - 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
claude mcp add --transport http officidata \
https://api.pharwiz.com/api/v1/donnees-ia/mcp \
--header "Authorization: Bearer odk_live_VOTRE_CLE"Cursor
{
"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.
- 1L’assistant appelle le serveur MCP sans jeton ; le serveur répond
401avec l’en-têteWWW-Authenticate, qui donne l’adresse de ses métadonnées. - 2L’assistant s’enregistre de lui-même (enregistrement dynamique), puis ouvre une page de connexion à votre compte.
- 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ément | Valeur |
|---|---|
| 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ées | donnees: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 |
| Flux | Code d’autorisation avec PKCE (S256 obligatoire), application publique sans secret ; resource, s’il est donné, doit être l’adresse du serveur MCP |
| Durées | Demande d’autorisation valable dix minutes ; code valable cinq minutes, une seule fois |
| Jetons | Accè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 |
| Erreurs | Au 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.
| Fonction | Ce qu’elle fait |
|---|---|
guide_donnees | Le guide des données : tables, colonnes, pièges à connaître, et la couverture de votre officine. À lire en premier. |
mon_officine | Votre 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. |
achats | Les 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. |
ventes | Les ventes, les plus récentes d’abord : par période, produit ou code CIP, par pages. Mêmes paramètres que la route /ventes. |
stock | Les 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_mensuels | Mois 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_sql | Une 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_generiqueur | Formule 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_outils | Le 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_outils | Les 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_outil | Dé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èsdu. 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, puispage=3. La réponse donnepage_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èsdu. 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 deaupar 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,ventesetstock, 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éeoutils: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
- 1Il lit le guide d’écriture : la fonction
guide_outilspar le connecteur, ouGET /outils/guidepar l’API. - 2Il écrit la page, en déclarant dans
fluxles données qu’elle lira. - 3Il la dépose avec la fonction
deployer_outil, ouPOST /outils. Avec leslugd’un outil qu’il a déjà déposé, il en dépose une nouvelle version. - 4Il vous rend le lien
url_ouvrirde la réponse, qui ouvre l’outil dans votre espace, après connexion.
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>"
}'{
"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.
| Adresse | Ce qu’elle rend |
|---|---|
/achats | Une commande par élément, avec ses lignes : période depuis et jusqua (au format AAAA-MM-JJ), pages limit (200 au plus) et offset. |
/ventes | Une vente par élément (souvent une journée de caisse), avec ses lignes, mêmes paramètres. |
/stock | Sans paramètre, la dernière photo du stock, un produit par élément ; date, depuis, limit et offset pour une autre photo. |
/achats/agregats | Des 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/agregats | Les mêmes totaux pour les ventes (par=mois, par=produit ou par=categorie). |
/stockage | Les 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.
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
nomde 80 caractères au plus, unedescriptionde 500 au plus. - Un
slugde 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
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
{
"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_lignesettronque:tronquevauttruequand d’autres lignes existent au-delà de la limite.page,limiteetpage_suivante(routes en pages seulement) :page_suivantevautnullà la dernière page.couverture: jusqu’à quelle date vont les données lues (dernierpour les achats et les ventes,date_photopour le stock,dernier_moispour 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./moiet/guidedonnent 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
_ttcdu stock.
{
"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.
| Vue | Une ligne = |
|---|---|
ana_officine_achats | une ligne d’achat |
ana_officine_ventes | une ligne de vente |
ana_officine_stock | un produit d’une photo du stock |
ana_officine_stock_actuel | un produit de la dernière photo du stock |
ana_officine_kpis_mensuels | un mois |
ana_officine_kpis_journaliers | un 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.
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 1curl -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 HTTP | Code | Ce qu’il veut dire |
|---|---|---|
401 | cle_invalide | Clé absente, inconnue, retirée ou expirée, ou jeton d’accès expiré (à renouveler). |
402 | application_non_souscrite | L’officine n’a pas, ou plus, accès à l’application. |
402 | reserve_pro | La route demande la formule Pro. |
402 | mes_apps_inaccessible | Outils : l’espace où ils tournent n’est pas ouvert pour l’officine. |
403 | partage_requis | Formule gratuite sans accord de partage accepté. |
403 | droit_outils_requis | Outils : la clé ou l’autorisation n’a pas le droit outils ; le message dit comment l’obtenir. |
409 | espace_demonstration | Outils : un espace de démonstration ne reçoit aucun outil. |
409 | trop_d_outils | Outils : l’espace de l’officine compte déjà vingt outils ou apps. |
409 | slug_reserve | Outils : ce slug désigne un outil qui ne se remplace pas ; choisissez-en un autre. |
409 | slug_pris | Outils : ce slug désigne un outil que l’API ou le connecteur n’a pas déposé ; il ne se remplace pas d’ici. |
409 | depot_concurrent | Outils : un dépôt du même outil vient d’avoir lieu ; réessayez dans un instant. |
413 | corps_trop_volumineux | Outils : le corps du dépôt est trop volumineux. |
422 | parametre_invalide | Un paramètre est mal formé : date, code CIP, limite, page, texte trop long, champ inconnu ; champ le nomme. |
422 | requete_invalide | La requête SQL est refusée par les contrôles ; le message dit pourquoi. |
422 | html_trop_volumineux, html_invalide | Outils : la page dépasse 1 Mo, ou n’est pas un document HTML complet. |
429 | quota_atteint | Le quota du jour est atteint ; la réponse donne limite et reinitialisation. |
429 | trop_rapide | Trop d’appels en une minute ; attendez la durée donnée par l’en-tête Retry-After. |
429 | trop_de_depots | Outils : trop de dépôts aujourd’hui avec cette clé. |
503 | indisponible | Le service est momentanément indisponible ; réessayez. |
| Quota | Gratuit | Pro |
|---|---|---|
| Appels par jour, pour l’officine | 300 | 5 000 |
| Appels par minute, pour une clé | 60 | 120 |
| Appels par minute, pour l’officine, toutes clés confondues | 120 | 300 |
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
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"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.