API WiseDyn
Guide d’intégration pour lire et écrire des fiches, envoyer des photos et télécharger des documents PDF.
Accès et conventions
Utilisez le service de données pour synchroniser des fiches depuis votre serveur. Pour gérer les médias, ouvrez une session applicative autorisée pour la société concernée. Le devis PDF du deviseur dispose de son propre service de téléchargement.
| Opération | Accès | Réponse |
|---|---|---|
| Lire des fiches | GET · jeton serveur | Tableau JSON |
| Créer ou modifier des fiches | POST · jeton serveur | Compteurs en texte |
| Envoyer une photo ou lire un PDF joint | POST · session applicative | Objet JSON |
| Télécharger le devis du deviseur | GET · jeton serveur | Fichier PDF |
Les exemples utilisent atelier.example.invalid, une société fictive de numéro 900001 et des références inventées. Les chemins sont illustratifs. Remplacez-les par les adresses de votre intégration. Les noms des champs, les formats et les réponses reprennent le contrat WiseDyn.
Préparer le client Python
Les extraits suivants utilisent Python 3 et la bibliothèque requests. Le jeton reste sur votre serveur. Pour les médias, chargez la session obtenue lors de la connexion du compte applicatif habilité. Le fichier de cookies ci-dessous est au format Netscape.
import base64
import os
import uuid
from http.cookiejar import MozillaCookieJar
from pathlib import Path
from urllib.parse import quote
import requests
BASE = "https://atelier.example.invalid"
FICHES = BASE + "/exemple/fiches"
PHOTO = BASE + "/exemple/photo-contact"
MEDIAS = BASE + "/exemple/media-produit"
DEVIS = BASE + "/exemple/devis-pdf"
SOCIETE = 900001
produit_id = 42017
contact_id = 42018
serveur = requests.Session()
serveur.headers["Authorization"] = "Bearer " + os.environ["JETON_INTEGRATION"]
application = requests.Session()
application.cookies = MozillaCookieJar(os.environ["SESSION_APPLICATION"])
application.cookies.load(ignore_discard=True)
def formulaire(url, champs):
reponse = application.post(url, data=champs, timeout=60)
reponse.raise_for_status()
resultat = reponse.json()
if not resultat.get("ok"):
raise ValueError(resultat.get("erreur", "Opération refusée"))
return resultatLire et filtrer les fiches
Indiquez la table, les champs à retourner entre parenthèses et le filtre après le tiret. Gardez la société dans le filtre. Un Id numérique identifie une fiche dans sa société. Le Code renvoyé par la lecture sert à la mise à jour.
expression = f"Répertoire(Id,Code,Nom,Ville)-Société={SOCIETE}&Nom='Atelier Silex Démo'"
url = FICHES + "/" + quote(expression, safe="")
reponse = serveur.get(url, timeout=30)
reponse.raise_for_status()
fiches = reponse.json()[
{"Id":42018, "Code":"DEMO-C-018", "Nom":"Atelier Silex Démo", "Ville":"Ville-Exemple"}
]Une recherche sans résultat renvoie un tableau vide. Plusieurs correspondances donnent plusieurs objets. Pour attendre une seule fiche, vérifiez le nombre de résultats avant de réutiliser son code.
Les filtres acceptent notamment =, !=, <, <=, > et >=. Combinez les conditions avec & (et), | (ou) et des parenthèses. Entourez les valeurs textuelles de guillemets et encodez l’expression dans le chemin de l’URL. Utilisez le format AAAA-MM-JJ pour une date.
Créer et modifier des fiches
Envoyez un tableau JSON en POST, même pour une seule fiche. Chaque objet contient Table, Société, Codes et les valeurs à enregistrer. Pour créer une fiche, donnez à Codes la valeur ajout. Pour la modifier, reprenez le code obtenu à la lecture.
creation = [{"Table": "Répertoire", "Société": SOCIETE, "Codes": "ajout",
"Nom": "Atelier Silex Démo", "Ville": "Ville-Exemple",
"T-eMail": "achats@atelier.example.invalid"}]
reponse = serveur.post(FICHES, json=creation, timeout=30)
reponse.raise_for_status()
print(reponse.text.strip()) # 0-1 pour une créationRelire puis mettre à jour
La réponse de création contient un compteur. Relisez la fiche avec un critère unique propre à votre intégration pour obtenir son code. Pour un contact existant, transmettez uniquement les champs à changer.
[
{"Table":"Répertoire", "Société":900001, "Codes":"DEMO-C-018", "Ville":"Port-Exemple"}
]Le résultat 1-0 signifie une modification et zéro création. Pour attribuer la même valeur à plusieurs fiches, séparez leurs codes par des virgules dans Codes. Pour leur attribuer des valeurs différentes, envoyez un objet par fiche.
Corbeille et reprise d’un lot
Pour mettre une fiche à la corbeille, Codes identifie sa référence actuelle et Code contient cette référence préfixée de x. Vérifiez d’abord la société et la fiche ciblées. Un lot peut être partiellement appliqué. En cas d’erreur ou de réponse perdue, relisez les fiches avant de reprendre les seules opérations manquantes, en particulier les créations.
Envoyer des photos
Photo ou logo d’un contact
Envoyez un formulaire avec la société, l’identifiant numérique de la fiche Répertoire, l’action, le format et le contenu encodé en Base64. Le fichier peut être un JPEG ou un PNG de 8 Mio maximum avant encodage. Le PNG est converti en JPEG sur fond blanc. La photo est destinée à être publiée sur le site de la société.
photo = formulaire(PHOTO, {
"societe": SOCIETE, "id": contact_id, "action": "envoyer", "format": "png",
"donnees": base64.b64encode(Path("portrait-demo.png").read_bytes()).decode("ascii")
})
adresse_photo = photo["photo"]La réponse contient ok et photo, l’adresse de l’image. Un nouvel envoi remplace la photo. Pour la retirer, envoyez action=supprimer avec les mêmes societe et id.
Photos et notices d’un produit
Pour un produit, utilisez le service de médias. Le client Mac dépose les JPEG, PNG et PDF par blocs de 700 000 octets. Gardez le même identifiant de transfert, le même produit et le même nom de fichier jusqu’au dernier bloc. Le champ jeton de ce formulaire identifie le transfert. L’authentification est assurée par la session applicative.
fichier = Path("lampe-silex-demo.jpg")
contenu = fichier.read_bytes()
if not contenu:
raise ValueError("Fichier vide")
transfert = str(uuid.uuid4())
for debut in range(0, len(contenu), 700_000):
bloc = contenu[debut:debut + 700_000]
dernier = debut + len(bloc) == len(contenu)
resultat = formulaire(MEDIAS, {
"societe": SOCIETE, "id": produit_id, "action": "morceau",
"nom": fichier.name, "jeton": transfert, "fin": "1" if dernier else "0",
"data": base64.b64encode(bloc).decode("ascii"),
"commentaire": "Vue de face du modèle de démonstration"
})
if not resultat.get("medias"):
raise ValueError("Vérifier la liste des médias sur le produit")Choisissez un nom de fichier distinct et un suffixe autorisé pour votre société. Envoyez les blocs dans l’ordre. Si la réponse à un bloc est perdue, vérifiez les médias du produit avant de reprendre le dépôt avec un nouvel identifiant. Une notice PDF se dépose par le même mécanisme.
Télécharger des documents
PDF joint à une fiche produit
Reprenez le nom de la notice figurant dans les médias du produit. L’action de consultation renvoie le PDF dans le champ Base64 data, avec son type et sa taille d’origine en octets. Pour une image, cette même action fournit un aperçu susceptible d’être redimensionné.
notice = formulaire(MEDIAS, {"societe": SOCIETE, "id": produit_id,
"action": "image", "nom": "notice-silex-demo.pdf"})
if notice.get("type") != "pdf":
raise ValueError("Un PDF était attendu")
contenu = base64.b64decode(notice["data"], validate=True)
if len(contenu) != notice["taille"]:
raise ValueError("Document incomplet")
Path("notice-demo.pdf").write_bytes(contenu)Devis généré par le deviseur
Le service du deviseur prépare le PDF avec le modèle macOS de la société émettrice. Cette opération concerne les devis de l’intégration configurée. Fournissez le code du devis et enregistrez directement le corps binaire de la réponse.
code = "DEMO-DEV-042"
reponse = serveur.get(DEVIS + "/" + quote(code, safe=""), timeout=60)
reponse.raise_for_status()
if reponse.headers.get("Content-Type", "").split(";")[0] != "application/pdf":
raise ValueError("Le service n’a pas renvoyé de PDF")
Path("devis-demo.pdf").write_bytes(reponse.content)Réponses et erreurs
| Résultat | Interprétation et suite à donner |
|---|---|
Lecture · [] | Aucune correspondance. Vérifiez la société et le filtre. |
Écriture · 2-1 | Deux fiches modifiées, une créée. Relisez les fiches dont vous avez besoin. |
| HTTP 400 | Contrôlez le filtre, les noms de champs ou le tableau JSON. En écriture, examinez aussi les compteurs retournés. |
| HTTP 403 | Vérifiez le jeton de l’intégration auprès de votre interlocuteur. |
Médias · ok: false | Lisez le champ erreur, même avec un HTTP 200. Vérifiez la session, les droits, la fiche, le nom et le format du fichier. |
| PDF · HTTP 404 ou 503 | Pour un 404, vérifiez la référence et la société émettrice. Pour un 503, réessayez le téléchargement ou faites vérifier le modèle. |
Pour obtenir les adresses de votre intégration ou préciser les documents à échanger, contactez NOMA.