Comprendre les bases de la documentation API

Nous allons expliquer ici comment notre documentation est structurée, quelles informations elle contient et comment les rechercher.

Des articles dédiés sont disponibles sur ce site pour l’envoi de données via l’API, l’accompagnement de votre projet ou la connexion de vos systèmes aux nôtres.

La Documentation API - Vue d'Ensemble

Commençons par une vue d’ensemble :

La documentation API complète est disponible ici.

Vous y trouverez tout ce qui est lié à l’API, avec des informations classées par type de projet (l’offre que vous avez choisie avec Fairly Made) puis par routes (POST et GET).

Cette documentation est destinée aux niveaux intermédiaire à expert. Vous pouvez y retrouver des explications techniques détaillées pour chaque route et leur contenu.

Routes POST

Par exemple, prenons la documentation pour le projet STANDARD :

Il existe quatre routes POST pour créer un produit. Les données doivent être envoyées dans un ordre précis (différent de l'ordre alphabétique indiqué dans l'aperçu) :

• SUPPLIER,
• PACKAGING (optionnel),
• PRODUCT
• et COMPONENT.

Champs requis

Chaque route vous précisera les champs requis pour créer chaque objet. Ceux-ci doivent être remplis sinon vous recevrez un message d’erreur et l’objet ne sera pas créé.

Exemple de Payload

A droite, dans l'encart noir se trouvent les exemples de requêtes, pour vous montrer à quoi devrait ressembler un payload pour cette route.

Prenons cette même route, le POST Create Component du type de projet STANDARD :

C’est un exemple visuel des paramètres indiqués à gauche avec des données aléatoires que vous pouvez copier et coller pour tester l’API.

Jeu de Test POST - Create Component

{
"projectType": "STANDARD",
"componentRef": "Semelle Intérieure Cuir Y34",
"supplierComponentCode": "Soletta in pelle Y34",
"productCollectionRef": "SS26",
"productRef": "BottesMagnifiquesSS26",
"productColorCode": "NERO",
"type": "LEATHER",
"category": "INSOLES",
"composition": [
{
"material": "BOVINE LEATHER",
"percentage": 100
}
],
"componentWeight": 100,
"certifications": [
{
"date_start": "2024-02-04",
"type": "ICEC - LEATHER FROM ITALY - UNI EN 16484",
"date_end": "2024-12-04"
}
],
"importationBatch": "StandardPostV1Clotilde",
"supplierRef": "Tannerie Grandes Peaux"
}

Comme expliqué dans l'article précédent, l'environnement Sandbox est conçu pour tester l'envoi de données à Fairly Made. Des messages d'erreur apparaîtront si des champs requis sont manquants ou si les données sont incorrectes. Notre approche repose sur l'apprentissage par la pratique.

Routes GET

Plus bas, nous avons les routes GET, pour interroger l’API afin de retourner les données que vous souhaitez.

Comme pour les autres routes, vous obtiendrez toutes les informations nécessaires dans la documentation. Par exemple ici le GET Study Details, avec les informations requises toujours en rouge, et à droite l’exemple de payload approprié :

Réponses de l'API 

Voici les réponses les plus courantes expliquées :

• 400 : Réponse d'Erreur
  • 400 : Mauvaise requête, par exemple, composant déjà lié
  • 403 : Interdit, par exemple, token incorrect utilisé
  • 404 : Point de terminaison inexistant, par exemple, v2/supplierssss
• 200 : Réponse de Validation
  • 201 : Validation
• 500 : Erreur du serveur

Pour une meilleure compréhension des erreurs possibles, veuillez vous référer à cet article.