Smag Link a été conçu pour les organisations agricoles et les partenaires qui souhaitent connecter leurs solutions digitales avec l'écosystème SMAG.
Smag Link propose un ensemble de référentiels métiers et une plateforme d'API basée sur AgGateway ADAPT, pour intéropérer facilement avec les acteurs majeurs du monde agricole : éditeurs, machinistes, instituts techniques, start-ups, etc.
Les API Smag Link sont en accès privé :
En premier pour accéder aux API, il faut créer un compte développeur sur le portail d'API. Le portail présentera la documentation de toutes les API souscrites par votre organisation. Voir : Comment créer mon compte développeur ?
Pour accéder aux données appartenant à un utilisateur particulier, un token est exigé pour formaliser son consentement. Voir : Comment obtenir un token ?
Pour accéder aux données appartenant exclusivement à SMAG, une APIKEY est exigée pour formaliser l'acquisition de ces données. Voir : Comment obtenir une APIKEY ?
Une fois cet accès obtenu, pour exploiter efficacement les API Smag Link, n'hésitez pas à consulter les sections "Comment les endpoints sont-ils organisés ?", "Comment les données Smag Link sont-elles structurées ?" ainsi que nos Use cases.
Sign up", en renseignant votre adresse e-mail, votre nom et un mot de passe
Nous contacter obligatoirement ensuite à l'adresse mail developers@smag.tech, afin que nous affections à votre compte les droits d'accès aux API souscrites par votre organisation
Dès lors, vous pourrez vous connecter au portail d'API, via le menu "Sign in", et explorer la documentation des différentes API.
Votre compte développeur, une fois vos droits associés par Smag, est relié à une clé de souscription (subscription key) qui devra être transmise lors de chaque appel d'API. Vous pouvez récupérer cette clé via votre Profil du portail API, en cliquant sur "Show" :
Remarque : préférez la clé primaire, mais la clé secondaire fonctionne tout autant, permettant une rotation des clés si nécessaire.
Vous pouvez par ailleurs, en cas de vol ou de suspicion de piratage, régénérer par vous-même votre clé en cliquant sur "regenerate".
Pour accéder par API aux données d'un utilisateur donné, tout logiciel tiers doit au préalable requérir son accord explicite. SMAG, dans son rôle de détenteur des données de l'utilisateur, ne délivrera aucune donnée sans cela.
Cet accord est formalisé sous la forme d'un token JWT (JSON Web token), à transmettre à l'API SMAG pour chaque appel, via le paramètre d'entête (header) SmagAuthorization.
Ce token intègre notamment :
L'application ID qui identifie le logiciel tiers
Le compte Smag de l'utilisateur concerné.
Un token a une durée de validité de 12 heures. Passé ce délai, il est possible de le rafraîchir. Voir : Comment rafraîchir un token ?
Vous devez déclarer votre application auprès de notre équipe par mail à developers@smag.tech. Un application ID vous sera alors attribué.
Si votre application fonctionne sur plusieurs environnements (par exemple : développement, recette, production...) : un application ID doit être demandé pour chaque environnement de votre application.
L'outil de génération de token permet d'obtenir manuellement un token pour un application ID et compte Smag donné. Cet outil est particulièrement utile en phase de développement.
Tout d'abord, le propriétaire du compte Smag doit se connecter :
Après connexion au compte Smag, un token sans application id est automatiquement généré (qui peut être placé dans le presse-papiers en cliquant sur Copier) :
Toutefois ce token a été généré sans application id. Il faut donc maintenant préciser son application et cliquer sur Rafraîchir pour générer un token complet et utilisable pour les appels API.
Si vous développez une application cliente avec possibilité pour l'utilisateur d'interargir avec, vous devez utiliser le mode suivant.
Le processus doit alors suivre les étapes suivantes :
L'application demande à l'API d'authentification Smag Link (Authentication API) une URL vers l'écran de connexion au compte Smag (URL de connexion) avec le endpoint build_url
L'API retourne cette URL de connexion (qui est propre à l'application)
L'application redirige l'utilisateur vers cette URL, ce dernier voit donc apparaître un écran de connexion au compte Smag
L'utilisateur saisit ses identifiants
Après authentification, il est redirigé vers l'URL de callback de votre application (que vous devrez avoir communiqué au préalable à notre équipe : developers@smag.tech), avec transmission du token que l'application pourra utiliser pour ses différents appels des API Smag Link.
flowchart TD; App([Application]) Auth[[Authentication API]] Login([Ecran de connexion compte Smag]) User((Utilisateur)) App -- 1. demande une URL de connexion --> Auth Auth -- 2. retourne l'URL de connexion --> App App -- 3. redirige vers l'URL de connexion --> Login Login o-- 4. saisit ses identifiants --o User Login -- "5. redirige vers l'URL de callback + token" --> App
Pour demander une URL de connexion, il faut appeler le endpoint POST Request a redirection URI for the Smag account Login page de l'API Authentication, documenté sur le portail API comme ci-dessous :
Ce endpoint est de type POST car un objet JSON doit être envoyé en body de l'appel :
{
"AdditionalValues":
{
"application_id" : "******************", // Votre application ID envoyé par Smag
"displayLogin" : 1 // Pour que l'écran s'ouvre sur l'onglet "connexion"
// (Ou 0 pour qu'il s'ouvre sur l'onglet "création de compte")
}
}
Exemple d'appel du endpoint avec curl :
curl -v
-X POST "https://api.smag.tech/authentication-operational/v1/api/authentication/build_url"
-H "Content-Type: application/json-patch+json"
-H "Cache-Control: no-cache"
-H "Ocp-Apim-Subscription-Key: ***********************"
--data-raw "{
\"AdditionalValues\": {
\"application_id\": \"********************\",
\"displayLogin\": 1
}
}"
Remarque : Dans cet appel, comme pour tous les appels d'une API Smag Link, il faut obligatoirement ajouter le
header"Ocp-Apim-Subscription-Key" avec votre clé de souscription fourni par le portail sur l'onglet Profil.
Si vous développez une application de type tâche planifiée/background avec l'impossibilité pour l'utilisateur d'interargir avec, vous devez utiliser ce mode.
Le processus suit les étapes suivantes :
L'application demande à l'API d'authentification Smag Link (Authentication API) un token par login/password
Ce login a été travaillé avec les équipes Smag permettant de réaliser les opérations attendues en respectant différentes contraintes de performances, sécurité, etc.
L'application processus utilise enfin ce token pour réaliser ses appels SmagLink.
Un token a une validité de 12 heures. Passé ce délai, il est possible de le rafraîchir de manière automatique.
Pour cela, il vous faudra récupérer le refresh token contenu dans le token JWT et utiliser le endpoint POST Renew a token after its expiration de l'API Authentication :
Ce endpoint est de type POST car il faut envoyer le JSON suivant en body de l'appel :
{
"applicationId" : "******************", // Votre application ID envoyé par Smag
"refreshToken" : "****************" // Le "refresh token" qui accompagnait le token
}
Exemple d'appel du endpoint avec curl :
curl -v -X POST "https://api.smag.tech/authentication-operational/v1/api/oauth2/refresh_token"
-H "Content-Type: application/json-patch+json"
-H "Cache-Control: no-cache"
-H "Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••"
--data-raw "{
\"applicationId\": \"**************************\",
\"refreshToken\": \"**********************\"
}"
Un nouveau token, valable pour 12 heures, sera renvoyé en réponse par le endpoint.
Ne pas oublier également de fournir comme précédemment le header Ocp-Apim-Subscription-Key.
Remarque : le refresh token a une validité de 30 jours maximum depuis sa dernière utilisation.
Les tokens sont générés selon un algorithme d'encodage RS256 (RSA signature with SHA-256), asymétrique (utilisant un couple clé publique / clé privée).
Dans ce système, le fournisseur d'identité génère une signature inviolable grâce à sa clé privée. Cette signature peut être validée par le destinataire grâce à une clé publique. De ce fait, le token peut être déchiffré via l'outil https://jwt.io.
SMAG a recours à un tiers de confiance pour la fourniture d'identité, qui garantit la sécurité contre les attaques, notamment les attaques par force brute. De ce fait, SMAG n'a jamais connaissance des logins et mots de passe de ses utilisateurs.
Une APIKEY vous est délivrée à la souscription, par votre organisation, d'un contrat d'utilisation de données appartenant à SMAG, dans un cas d'usage défini (notamment : données référentielles).
Cette APIKEY est donc à communiquer dans les appels de endpoints relatifs aux données SMAG inscrites au contrat, au travers du paramètre d'entête X-API-KEY.
Un deuxième paramètre, l'application ID, est à fournir via le paramètre d'entête X-APP-ID. Voir Comment obtenir son application ID ?
Exemple sur l'API CropProtectionProducts :
Smag Link est organisé en domaines fonctionnels. Chaque domaine correspond à une API.
Chaque API est divisée en différents groupes de endpoints appelés tags, ces groupes correspondant principalement à des entités métiers.
Au sein d'un tag, on trouvera le plus souvent :
un endpoint "Get all ...", permettant de récupérer la liste des identifiants et des noms de tous les enregistrements correspondant à l'entité métier demandé
un endpoint "Get a .../{uid}", permettant de récupérer les informations détaillées d'un enregistrement en particulier (défini par son UUID)
Les données Smag Link sont structurées selon un modèle de données fortement inspiré par le standard AgGateway ADAPT, dont nous décrivons ici quelques concepts fondamentaux.
Un compound identifier est la collection des identifiants d'un même enregistrement dans les différents systèmes informatiques (appelés sources) qui se sont échangés pour cet enregistrement.
Chaque système qui reçoit un enregistrement avec un compound identifier, pourra le retransmettre ultérieurement à un autre système après avoir ajouté son propre identifiant à la collection. Grâce à ce principe, tout système destinataire sera en mesure d'interopérer avec l'ensemble des contributeurs antérieurs de cet enregistrement.
La structure d'une entité avec compound identifier est la suivante :
{
"uid" : "596cb84c-43a5...", // L'UUID SMAG de l'entité
"id" : // Le compound identifier
{
"referenceId" : <integer>, // Le numéro de référence au sein du jeu de données de la réponse
// Attention : ce numéro est régénéré à chaque appel
"uniqueId" : // Collection des identifiants dans d'autres sources
[
{ // Identifiant pour une source "XYZ"
"id" : "***********", // L'identifiant à proprement parler
"idType" : "*****", // Le type de l'identifiant : "LongInt", "String", "UUID", "URI"
"source" : "XYZ", // Nom de la source
"sourceType" : "URI" // Type de la source. Peut également être "GLN" (Global Location Number)
},
..., // Autres identifiants pour d'autres sources
{ // Identifiant pour la source "Smag Link"
"id" : "596cb84c-43a5...", // Rappel de l'attribut "uid"
"idType" : "UUID",
"source" : "SmagLink",
"sourceType" : "URI"
}
]
}
}
Les unités de mesure sont une préoccupation dans les transferts de valeurs numériques entre systèmes. En effet, cela sous-entend que ces systèmes aient mis au préalable en correspondance leurs référentiels d'unité (pour pouvoir calculer des conversions).
Pour éviter cette lourdeur, ADAPT accompagne chaque unité des informations nécessaires pour rendre sa conversion possible dans toutes les unités de même dimension (par exemple : unités de poids, de volume, de distance...), à travers une structure unit of measure :
{
"id" : ..., // Compound identifier de l'unité
"code" : "****", // Code de l'unité
"dimension" : "*****" // La dimension de base de l'unité (poids, volume, distance, ...)
"isReferenceForDimension" : <boolean>, // Ou true si l'unité est "l'unité de base" de sa dimension
// (auquel cas le calcul d'une conversion n'est pas requis)
"scale" : <double>, // Facteur multiplicatif de conversion
"offset" : <double> // Facteur additionnel de conversion
}
Une valeur numérique est toujours accompagnée de son unité de mesure, à travers une structure de type numeric value :
{
"value" : <double>, // Valeur numérique
"unitOfMeasure" : <UnitOfMeasure> // Informations sur l'unité de mesure
}
Les informations concernant la façon d'afficher une valeur numérique sont décrites dans une structure numeric representation (dont beaucoup d'attributs sont le plus souvent non renseignés car facultatifs) :
{
"decimalDigits" : <integer>, // Nombre de décimales affichées
"minValue" : <NumericValue>, // Valeur minimum (dans le cas d'une présentation de type "curseur")
"maxValue" : <NumericValue>, // Valeur maximum (dans le cas d'une présentation de type "curseur")
"description" : "*****", // Un texte explicatif pour accompagner la valeur numérique
...
}
Enfin, une structure numeric representation value agrège numeric value et numeric representation, en y ajoutant des informations de présentation relatives à la valeur, telles que la couleur (par exemple : rouge pour les valeurs négatives, et vert pour les positives...)
Pour toute question technique relative à Smag Link, vous pouvez nous contacter à l'adresse mail developers@smag.tech.