Reliez votre boutique à vos autres systèmes
L'API E-commerce permet à vos propres outils de remplir votre boutique et de la relire.
Quelle API est disponible
- API E-commerce
Une API JSON sur HTTPS pour la boutique que vous tenez avec Ultineo E-commerce. Un script de migration, une synchronisation avec votre ERP ou un flux fournisseur envoie des éléments par lots, et relit n'importe quel élément pour vérifier ce qui a été enregistré.
- API de projet Ultineo SaaS
Une option d'un projet Ultineo SaaS, qui n'accompagne pas chaque application. Sa disponibilité et son prix figurent dans l'offre du projet, et elle expose les opérations convenues pour ce projet.
Ce que couvre l'API
Chaque sujet ci-dessous est un article de la documentation de référence.
- Votre premier appel
L'URL de base, la clé Bearer et ses droits, un exemple curl complet et le contrat d'import par lots commun à tous les points d'accès.
- Codes d'erreur
L'enveloppe d'erreur, chaque statut HTTP renvoyé par l'API avec la conduite à tenir, et la façon dont les refus au sein d'un lot d'import sont signalés.
- Catalogue
Importez et relisez vos caractéristiques, catégories, groupes de produits, produits et avis clients, par lots et sans ressaisie.
- Commandes & logistique
Importez votre historique de ventes avec ses dates d'origine, puis relisez chaque enregistrement : clients, commandes, paiements, expéditions, réclamations transporteur, colis refusés, remboursements, retours, mouvements de cagnotte et demandes d'assistance.
- Bons de réduction
Importez vos bons de réduction et leurs codes par lots, puis relisez un bon de réduction avec tous ses codes et leur nombre d'utilisations.
- Colis, adresses et transporteurs
Suivez des colis depuis vos propres logiciels, tenez votre carnet d'adresses à jour et lisez le catalogue des transporteurs.
Comment fonctionne l'accès
Une clé est créée dans l'espace de travail par un administrateur du projet : ouvrez le projet, puis l'onglet « Accès API », et cliquez sur « Créer une clé API ».
La valeur complète de la clé est affichée une seule fois, à sa création, et ne peut plus l'être ensuite. Copiez-la à ce moment-là. Si vous la perdez, supprimez la clé et créez-en une autre.
Une clé appartient à une seule boutique. Chaque lecture et chaque écriture est limitée à cette boutique.
À la création de la clé, vous choisissez « Accès complet » ou « Accès restreint ». Une clé restreinte est limitée, ressource par ressource, à la lecture, ou à la lecture et à l'écriture.
Vous choisissez aussi son expiration : « 30 jours », « 90 jours », « 365 jours » ou « N'expire jamais ». L'accès et l'expiration se choisissent une seule fois. Pour les modifier, créez une nouvelle clé et supprimez l'ancienne.
Une clé suppose une boutique ouverte : elle se crée dans le projet de la boutique, et une clé dont la boutique n'est plus active est refusée.
L'adresse https://api.ultineo.com/health ne demande aucune clé : appelez-la pour vérifier que l'API est joignable.
Une connexion type : un ERP
Votre catalogue existe souvent déjà ailleurs, dans un ERP par exemple. Les éléments font référence les uns aux autres : la documentation de référence recommande d'importer d'abord ceux dont les autres dépendent.
1. Importez le catalogue : les caractéristiques, puis les catégories, puis les groupes de produits, puis les produits, puis les avis.
2. Importez l'historique des ventes : les clients, puis les commandes, puis les paiements et les expéditions, puis les remboursements, les retours, les réclamations transporteur, les colis refusés, les mouvements de cagnotte et les demandes d'assistance.
3. Importez les bons de réduction, une fois importés les clients auxquels leurs codes sont réservés.
Envoyer un élément déjà présent dans votre boutique le met à jour ou le signale comme inchangé. Il n'est jamais créé deux fois : vous pouvez donc rejouer un import interrompu depuis le début.
Chacune de ces ressources se relit un élément à la fois : il n'y a ni liste ni recherche.
Avant de développer
- Adresse et contrôle de disponibilité
Toutes les requêtes sont envoyées à https://api.ultineo.com/v1/ et seul HTTPS est servi. L'adresse https://api.ultineo.com/health ne demande aucune clé et vous permet de vérifier que l'API est joignable.
- Enveloppe de réponse et codes d'erreur
Chaque point d'accès répond avec les trois mêmes clés, en cas de succès comme en cas d'échec : code, title et response. Lisez d'abord le code de statut HTTP, puis response, et basez votre logique sur le code de statut.
- Limites et essais
Lorsque trop de requêtes arrivent en peu de temps, l'appel est refusé et l'en-tête Retry-After indique le nombre de secondes à attendre. Pour tester un import, envoyez-le en mode essai, avec dry_run à true : vous obtenez le rapport complet de ce qui serait créé, mis à jour, laissé inchangé ou refusé, et rien n'est écrit.
Rester informé
Ouvrez votre boutique, puis connectez-la
Une clé se crée dans une boutique ouverte. Les comptes sont ouverts après étude : envoyez votre demande, et notre équipe vous répond par e-mail.
Questions de développeurs
Un administrateur du projet de votre boutique la crée dans l'espace de travail, dans l'onglet « Accès API ». Sa valeur complète est affichée une seule fois : copiez-la dès sa création. Il vous faut d'abord une boutique ouverte, et les comptes sont ouverts après étude.
Oui, pour les imports. Envoyez le lot en mode essai, avec dry_run à true : vous obtenez le rapport complet de ce qui serait créé, mis à jour, laissé inchangé ou refusé, et rien n'est écrit. Vérifiez le champ dry_run de la réponse avant de vous fier à un rapport.
Le catalogue, l'historique des ventes, les bons de réduction, ainsi que les colis, les adresses et les transporteurs. L'article « Votre premier appel » liste chaque ressource avec ses droits. Ne supposez pas que chaque écran de l'espace de travail possède un point d'accès équivalent.
Un appel en échec utilise la même enveloppe qu'un appel réussi : lisez le code de statut HTTP, puis le message dans response. Dans un import, chaque élément est vérifié séparément : un élément qui échoue à un contrôle est signalé comme refusé avec ce qu'il faut corriger, et les autres éléments du lot poursuivent leur traitement.
Oui. Chaque ressource a sa propre limite par lot, indiquée dans son article de référence, et le corps d'une requête a une taille maximale. Lorsque trop de requêtes arrivent en peu de temps, l'appel est refusé et l'en-tête Retry-After indique le nombre de secondes à attendre. Renvoyer le même lot ne crée jamais de doublon.
Non. L'API fournit des éléments de connexion, pas un connecteur installé automatiquement. Votre équipe technique ou votre prestataire construit et teste l'échange avec les points d'accès documentés.
Une API de projet est une option d'un projet Ultineo SaaS. Sa disponibilité et son prix figurent dans l'offre du projet, et une application peut fonctionner sans elle. Sa documentation de référence est celle du projet pour lequel elle est activée.
Dans le centre d'aide E-commerce, à la rubrique consacrée à l'API E-commerce. Elle est publique, rédigée en anglais et en français, et se lit sans compte.