Introduction
L'API GelatoConnect vous permet d'intégrer de manière programmatique vos systèmes à GelatoConnect pour soumettre des commandes, suivre leur statut et gérer les détails d'expédition. Ce guide vous aidera à comprendre comment commencer avec l'API et mettre en œuvre votre première intégration.
Prérequis
Avant de commencer à utiliser l'API GelatoConnect, vous devez avoir :
Votre clé API et votre secret (fournis lors de la configuration d'un connecteur pour votre client)
Compréhension de base des API REST et des méthodes HTTP
Connaissance du format de données JSON
Un environnement de développement qui peut effectuer des requêtes HTTP
Les bases de l'API
L'API de gestion des commandes GelatoConnect est structurée selon les principes REST et utilise les méthodes HTTP standard pour interagir avec les ressources. Toutes les requêtes API doivent utiliser HTTPS, et toutes les réponses sont renvoyées au format JSON, y compris les messages d'erreur.
URL de base
L'URL de base pour l'API GelatoConnect est :
https://api.partner-connect.io/api/{partner-prefix}/
Votre préfixe partenaire spécifique vous sera fourni lors de l'intégration.
Authentification
Toutes les requêtes API doivent inclure vos identifiants d’authentification dans l’en-tête. Pour vous authentifier :
Ajoutez l'en-tête
X-API-KEYà votre requêteIndiquez votre clé et votre secret au format
clé:secret.
Exemple :
X-API-KEY : votre-api-key:votre-api-secret
Faire votre première demande API
Découvrons ensemble comment envoyer une demande API simple pour passer une commande.
1. Préparez les informations de votre commande
Créez un objet JSON avec les détails de la commande. Voici un exemple simple :
{
"orderReferenceId": "your-order-ref-123",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"country": "US",
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Main St",
"city": "New York",
"postCode": "10001",
"state": "NY",
"email": "[email protected]",
"phone": "1234567890"
},
"items": [
{
"itemReferenceId": "item-123",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"files": [
{
"type": "default",
"url": "https://example.com/path/to/printfile.pdf"
}
]
}
]
}
2. Soumettre la commande
Effectuez une requête POST vers le point de terminaison de soumission de commande :
POST https://api.partner-connect.io/api/{partner-prefix}/order
Ajoutez votre en-tête d’authentification ainsi que les données de commande au format JSON dans le corps de la requête.
3. Traiter la réponse
Si tout se passe bien, vous recevrez une réponse comme celle-ci :
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "your-order-ref-123",
"createdAt": "2025-04-12T10:23:28+00:00"
}
Le champ id contient l'identifiant de commande GelatoConnect, que vous devriez conserver pour référence ultérieure.
Opérations courantes de l’API
Une fois que vous maîtrisez la soumission de commandes de base, vous pouvez explorer d'autres opérations de l'API :
Obtenir les détails de la commande
Récupérez les informations concernant une commande existante :
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Annuler une commande
Annuler une commande qui n'a pas été expédiée :
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancel
Rechercher des commandes
Trouvez des commandes selon des critères spécifiques :
POST https://api.partner-connect.io/api/{partner-prefix}/search
Mettre à jour l'expédition
Modifier les informations de livraison pour une commande :
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}
Mise en place de produits personnalisés
Au lieu d'utiliser les UIDs de produit, vous pouvez opter pour les produits client, une solution plus facile à comprendre :
{
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
}
}
Cela nécessite de configurer les Produits Personnalisés dans GelatoConnect avant de les utiliser dans les appels API.
Tester votre intégration
Avant de mettre en service votre intégration, testez-la minutieusement en utilisant ces approches :
Testez avec des commandes d’essai : Créez des commandes test avec de petites quantités, puis vérifiez qu’elles s’affichent correctement dans GelatoConnect.
Vérifier les mises à jour de statut des commandes : Suivez les commandes tout au long de leur cycle de vie pour vous assurer que votre système reçoit et traite correctement les changements de statut.
Gestion des erreurs : Créez intentionnellement des commandes invalides pour tester votre logique de gestion des erreurs.
Test de bout en bout : Complétez l'ensemble du processus de commande, de la soumission à la livraison, avec un petit ensemble de commandes test.
Bonnes pratiques
Pour assurer une intégration optimale avec l'API GelatoConnect :
Identifiants de commande : Conservez toujours l'identifiant de commande GelatoConnect renvoyé dans la réponse de création de commande.
Mettre en œuvre la gestion des erreurs : Ajoutez une gestion robuste des erreurs pour gérer les réponses inattendues ou les temps d'arrêt de l'API.
Utilisez l'idempotence : Générez des identifiants de référence de commande uniques pour éviter les doublons de commandes.
Mettre en œuvre une temporisation exponentielle : Lorsque vous recevez des erreurs de limitation de débit (429), utilisez des temps d'attente croissants entre les nouvelles tentatives.
Surveiller l'utilisation de l'API : Suivez votre utilisation de l'API pour éviter d'atteindre les limites de taux.
Résoudre les problèmes courants
Erreurs d’authentification
Si vous recevez une erreur 401 Non autorisé, vérifiez que :
Votre clé API et votre code secret sont corrects
Le format est
clé:secretdans l’en-tête X-API-KEYVous utilisez HTTPS, pas HTTP
Erreurs de demande non valides
Si vous recevez une erreur 400 Bad Request :
Vérifiez le message d’erreur pour savoir quels champs posent problème.
Vérifiez que tous les champs obligatoires sont inclus
Vérifiez que le format JSON est correct.
Erreurs de limitation de débit
Si vous recevez une erreur 429 Trop de requêtes :
Mettez en place une stratégie d’attente progressive pour espacer les demandes.
Pensez à regrouper les demandes lorsque c'est possible
Vérifiez votre intégration pour éviter les appels répétés inutiles
Étape suivante
Maintenant que vous comprenez les bases de l'API GelatoConnect, vous êtes également prêt à consulter la documentation complète de l'API pour des informations détaillées sur les points de terminaison 🔗 [Order Intake - GCW] Order Management API Documentation