Envoyez catalogue, historique de ventes et bons de réduction par API
L’API d’Ultineo E-commerce reçoit votre catalogue, votre historique de ventes et vos bons de réduction par lots, puis relit chaque enregistrement un à la fois. Cette page les parcourt ressource par ressource : ce qu’un programme envoie, ce qu’il relit et la taille d’un lot.
Ce qu’un programme peut faire avec ces ressources
- Envoyer le catalogue
Votre catalogue existe souvent déjà ailleurs, dans un ERP, un fichier fournisseur ou une ancienne boutique. Les points d’accès du catalogue permettent à vos outils de l’envoyer à votre boutique par lots : caractéristiques, catégories, groupes de produits, produits et avis clients.
- Rapatrier l’historique des ventes
Un outil de migration ou de synchronisation rapatrie votre historique de ventes dans votre boutique, des clients et des commandes jusqu’aux remboursements, aux retours et aux demandes d’assistance, en conservant les dates d’origine. Chaque enregistrement est reconnu par son external_id, si bien que le renvoyer le met à jour au lieu de créer un doublon.
- Reprendre les bons de réduction
Importez vos bons de réduction en cours et les codes que vous avez déjà envoyés, afin qu’ils continuent de fonctionner dans votre boutique. Relisez ensuite chaque bon de réduction avec tous ses codes, y compris le nombre de fois où chaque code a été utilisé.
Les ressources, une par une
Chaque ressource a un seul chemin : un POST reçoit un lot d’éléments, et un GET relit un enregistrement, désigné par sa clé ou par son identifiant dans votre boutique. Un GET exige le droit :read de la ressource et un POST son droit :write.
- Caractéristiques
Envoyez jusqu’à 25 caractéristiques par lot, comme une capacité ou une couleur, chacune pouvant porter une liste fermée de 400 valeurs au plus. Relisez-en une par son nom ou son identifiant ; les caractéristiques partagées par le service sont renvoyées avec shared à true et ne peuvent pas être modifiées.
- Catégories et groupes de produits
Envoyez jusqu’à 50 catégories par lot, imbriquées via parent en envoyant les parents avant leurs enfants, et jusqu’à 50 groupes de produits, chacun avec 20 axes au plus parmi lesquels l’acheteur choisit sur la fiche produit. Catégories et groupes sont reconnus par leur nom et se relisent par nom ou par identifiant.
- Produits
Envoyez jusqu’à 40 produits par lot, chacun reconnu par son SKU, avec ses niveaux d’état, ses caractéristiques et des photos déjà présentes dans vos médias, car l’API ne téléverse pas de fichiers. La lecture par SKU ou par identifiant renvoie les champs propres au produit, sans ses niveaux d’état, ses caractéristiques ni ses photos.
- Avis clients
Envoyez jusqu’à 250 avis clients par lot, issus de l’historique de votre ancienne boutique, chacun rattaché à un client déjà importé et, le cas échéant, à la commande dont il provient. Relisez-en un par son external_id ou son identifiant ; un avis client retiré est tout de même renvoyé, avec le statut deleted.
- Clients
Envoyez jusqu’à 200 clients par lot, chacun étant un acheteur de votre boutique avec une adresse de facturation et une adresse de livraison ; importez-les en premier, car tous les autres enregistrements de l’historique des ventes y font référence. La lecture ne renvoie jamais le mot de passe lui-même : has_password indique s’il en existe un.
- Commandes et paiements
Envoyez jusqu’à 100 commandes par lot, chacune avec toutes ses lignes dans un seul élément ; les totaux sont enregistrés tels que vous les envoyez, jamais recalculés, et le rapport vous signale un écart dans amount_check. Envoyez jusqu’à 300 paiements par lot, chacun réglant une commande déjà importée, et relisez une commande ou un paiement par son external_id ou son identifiant.
- Expéditions, réclamations transporteur et colis refusés
Envoyez jusqu’à 500 expéditions par lot, chacune étant un colis envoyé pour une commande déjà importée, avec son transporteur et son numéro de suivi, puis jusqu’à 500 réclamations transporteur et 500 colis refusés, rattachés à une expédition déjà importée. Une expédition relue porte un statut qui suit ses dates : delivered, shipped ou pending.
- Remboursements, retours, cagnotte client et demandes d’assistance
Envoyez par lot jusqu’à 400 remboursements, 300 retours, 500 mouvements de cagnotte de fidélité ou 25 demandes d’assistance, chacun sur son propre chemin ; une demande d’assistance s’envoie avec son fil de messages. Chaque enregistrement se relit par son external_id ou son identifiant dans votre boutique, et une demande d’assistance revient avec son fil par ordre chronologique.
- Bons de réduction
Envoyez jusqu’à 50 bons de réduction et 500 codes par requête : un pourcentage ou un montant fixe déduit du panier, avec un montant minimum et une période de validité facultatifs, et les codes que vos clients saisissent lors du paiement. Relisez un bon de réduction avec tous ses codes et leur nombre d’utilisations ; la lecture exige le droit promotion:read et l’import promotion:write, bien que le chemin soit /v1/voucher/import.
Un import et sa relecture
Le premier exemple importe une expédition d’une commande déjà importée ; le second est la réponse obtenue quand cette expédition est relue par son external_id. Le second est coupé là où une ligne ne contient que trois points.
Requête d’import
curl https://api.ultineo.com/v1/shipment/import \
-H "Authorization: Bearer sk-project-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"external_id": "SHP-20931",
"order_external_id": "ORD-10458",
"carrier_name": "Colissimo",
"tracking_number": "6A23456789012",
"recipient_name": "Claire Martin",
"shipped_at": 1781334000,
"delivered_at": 1781431200
}
]
}' L’expédition est reconnue par son external_id et désigne sa commande par order_external_id ; ses dates sont des horodatages Unix en secondes.
Réponse de relecture
{
"code": 200,
"title": "OK",
"response": {
"id": "ship_9c1e5a7f02d34b86e0a3",
"object": "shipment",
"external_id": "SHP-20931",
"status": "delivered",
"order": "ordr_5e0a8c2f71d94b36e1c8",
"carrier_name": "Colissimo",
"tracking_number": "6A23456789012",
...
"shipped_at": 1781334000,
"delivered_at": 1781431200,
"created_at": 1781334000,
"updated_at": 1791745200
}
} La réponse porte l’identifiant de l’expédition dans votre boutique, ship_…, et le statut delivered, puisque delivered_at est renseigné.
Les points à surveiller
- Une liste enfant est complète
Lorsqu’un élément porte une liste enfant, comme les values d’une caractéristique, les axes d’un groupe ou les grades et les media d’un produit, cette liste constitue l’ensemble complet et les entrées que vous avez omises sont désactivées. Omettez la liste pour conserver l’ensemble enregistré tel quel.
- Deux pages à ouvrir
Si votre boutique n’a jamais ouvert sa page Réclamations ou sa page Colis refusés, l’import des réclamations transporteur ou des colis refusés répond 422. Ouvrez cette page une fois dans votre espace de travail, puis rejouez le lot.
- Un code fait refuser son bon
Un code invalide entraîne le refus de tout son bon de réduction, et un code déjà utilisé par un autre code de la boutique le fait refuser avec le code 409. Corrigez le code ou choisissez-en un autre, puis renvoyez le bon de réduction.
Les articles derrière cette page
Cette page reprend les articles suivants du centre d’aide. Ils détaillent chaque champ, chaque valeur et chaque réponse.
Les pages produit à lire ensuite
- Accès API
Reliez vos systèmes avec des accès adaptés à la boutique
- Produits
Fiches produits, images et catégories
- Commandes
Articles, paiements et expéditions liés
- Codes promo
Codes, validité et limites d’utilisation
- Import et export
Modifiez le catalogue en masse avec un résultat lisible
Poursuivre dans cette rubrique
- API E-commerce
Créer un accès API et échanger les données de votre boutique
- Colis, adresses et transporteurs
L’API d’Ultineo Logistics : suivre des colis, tenir un carnet d’adresses à jour et lire le catalogue des transporteurs.
- API Ultineo Reasoning
Lancez vos raisonnements depuis vos logiciels.
- API de projet Ultineo SaaS
Examinez le périmètre API d’un projet éligible et distinguez les routes prévues des endpoints déjà construits.
Importez une ressource et vous savez les importer toutes
La documentation de référence donne pour chaque ressource ses champs, sa limite par lot et ses exemples.
Questions
Non. Une caractéristique, une catégorie et un groupe de produits sont reconnus par leur nom : un nom modifié est lu comme un nouvel enregistrement, pas comme un renommage. Un produit est reconnu par son SKU, et un avis client ou un enregistrement de l’historique des ventes par son external_id.
Aucun point d’accès de ces ressources ne supprime d’enregistrement : la suppression se fait dans votre espace de travail. Un enregistrement retiré dans votre espace de travail conserve son statut : un import ne le rétablit jamais, et un message d’information le signale. Pour un avis client ou un retour, envoyer le statut deleted retire un enregistrement déjà importé.
Oui. Le created_at que vous envoyez est conservé comme date d’origine de l’enregistrement et n’est jamais modifié par un import ultérieur. Les dates sont des horodatages Unix en secondes ; si vous omettez created_at, la plupart des ressources utilisent la date connue la plus proche, comme la date de la commande.
Seuls les bons de réduction en pourcentage et à montant fixe sont importés. La livraison gratuite, les cadeaux, le ciblage par produit ou par segment et l’historique de chaque utilisation d’un code sont gérés dans votre espace de travail et ne sont pas disponibles via l’API. L’API ne supprime pas non plus de bon de réduction ni de code.