Lorsque vous passez des commandes à GelatoConnect via l’API, vous avez deux possibilités pour indiquer les produits : utiliser les UID de produit ou les produits client. Ce guide vous présente ces deux méthodes, leurs avantages, ainsi que les situations dans lesquelles chacune est la plus adaptée.
Approche UID produit
La méthode UID de produit consiste à utiliser des identifiants uniques de produit (UID) pour désigner les produits dans vos commandes.
Comment ça fonctionne
Lorsque vous utilisez les Product UIDs, vous ajoutez le paramètre productUid à votre article de commande :
{
"itemReferenceId": "ITEM-001",
"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/files/printfile.pdf"
}
]
}
Structure de l'UID du produit
Un UID de produit est une chaîne structurée qui encode les caractéristiques d’un produit. Par exemple, dans flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor :
flat_product: Type de produitpf_a4: Format de papier (taille A4)pt_200-gsm-uncoated: Type de papier (papier non couché 200 g/m²)cl_4-0: Configuration de couleur (processus quadrichromique sur le recto, 0 couleur sur le verso)ct_none: Découpe (aucune)prt_none: Effets d'impression spéciaux (aucun)sft_none: Finitions de surface (aucune)set_none: Effets spéciaux (aucun)hor: Orientation (horizontale)
Approche des produits pour les clients
L’approche Produits client consiste à créer des définitions de produits Personnalisé dans GelatoConnect, puis à les référencer par nom et variante dans vos commandes.
Comment ça fonctionne
Tout d'abord, vous configurez les Produits Clients dans GelatoConnect, en définissant les noms des produits et leurs options de variantes. Ensuite, lors de la passation de commandes, vous faites référence à ces produits en utilisant les paramètres productName et productVariant :
{
"itemReferenceId": "ITEM-001",
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
},
"quantity": 100,
"files": [
{
"type": "front",
"url": "https://example.com/files/front.pdf"
},
{
"type": "back",
"url": "https://example.com/files/back.pdf"
}
]
}
Mise en place des produits clients
Avant d'utiliser les produits clients dans vos commandes API, vous devez les configurer dans GelatoConnect :
Allez dans la section Produits de GelatoConnect
Créez des produits Personnalisé avec des noms précis et des options de variantes
Associez ces produits clients aux spécifications de produits de Gelato
Quand utiliser chaque approche
Utiliser les UID de produit quand :
Vous venez tout juste de commencer avec GelatoConnect
Vous disposez d'un petit nombre de produits fixes
Vous souhaitez mettre en place rapidement, sans configuration supplémentaire.
Vous créez un prototype ou une version test
Utilisez les produits client lorsque :
Vous avez un vaste catalogue des produits
Vous souhaitez des références produit plus intuitives dans votre code
Les noms de vos produits diffèrent des conventions de dénomination de Gelato
Les configurations des produits peuvent évoluer avec le temps
Exemples d’implémentation
Exemple d’UID de produit
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "ORDER-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": "123-456-7890"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"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/files/printfile.pdf"
}
]
}
]
}'
Exemple de produits client
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "ORDER-124",
"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": "123-456-7890"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"productName": "Flyer",
"productVariant": {
"Size": "A4",
"Paper": "Uncoated 200gsm",
"Printing": "Full Color One Side"
},
"quantity": 100,
"files": [
{
"type": "default",
"url": "https://example.com/files/flyer.pdf"
}
]
}
]
}'
Bonnes pratiques
Quelle que soit l'approche que vous choisissez, suivez ces bonnes pratiques :
Cohérence : Gardez la même méthode du début à la fin
Documentation : Gardez une documentation claire de vos correspondances de produits
Validation : Vérifiez les identifiants des produits avant de passer vos commandes
Test : Testez minutieusement avec des commandes d'essai avant de mettre en service
Gestion des erreurs : Mettez en place une gestion fiable des erreurs pour les produits non valides
Changer de méthode
Si vous commencez avec des UID de produits et que vous souhaitez ensuite passer à des produits personnalisés :
Configurez vos Produits Clients dans GelatoConnect
Associez-les aux identifiants uniques de produit (UID) que vous utilisez
Mettez à jour votre implémentation de l’API pour utiliser productName et productVariant
Testez minutieusement avant de déployer en production
La transition inverse est également possible, mais elle est plus rare.
Conclusion
Les deux approches ont leurs avantages, et le choix dépend de vos besoins et contraintes spécifiques. Les UIDs de produit offrent une solution simple et un accès direct au catalogue de Gelato, tandis que les produits client apportent une meilleure lisibilité, plus de flexibilité, et une gestion centralisée.
Pour la plupart des mises en œuvre à long terme, les produits client offrent des avantages en matière de maintenance et de clarté. Cependant, pour des mises en œuvre rapides ou des besoins spécifiques, les identifiants uniques de produit peuvent être préférés.
Pour plus d'informations sur la configuration des Produits Clients dans GelatoConnect, consultez le guide Création de Produits Clients.