Ce guide propose des instructions pratiques et des exemples pour utiliser les points de terminaison de l’API Order de GelatoConnect. Nous verrons comment passer des commandes, les annuler, mettre à jour les informations de livraison, consulter les détails d’une commande et rechercher des commandes via l’API.

Prérequis

Avant de commencer à utiliser ces points de terminaison, assurez-vous d’avoir :

Votre clé API et votre secret (fournis lors de la configuration d’un connecteur pour votre client)
L'URL de base pour vos points de terminaison API
Compréhension de base pour effectuer des requêtes HTTP avec curl ou votre outil préféré

Valider la commande

Le point de terminaison « Submit Order » vous permet de créer une nouvelle commande dans GelatoConnect.

Point de terminaison : POST /{submitOrderUrl}

Exemple de demande

# Basic order submission
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": "YOUR-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 réponse

{
  "id": "32884a3e-bd09-42be-8225-c5cea7d24611",
  "orderReferenceId": "YOUR-ORDER-123",
  "createdAt": "2025-04-13T10:23:28+00:00"
}

Utiliser des produits Personnalisé

Au lieu de spécifier un productUid, vous pouvez utiliser des produits personnalisés avec productName et productVariant :

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": "YOUR-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": "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"
        }
      ]
    }
  ]
}'

Commandes internationales

Pour les commandes internationales, indiquez les prix de vente au détail pour les déclarations douanières :

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": "INTL-ORDER-456",
  "orderType": "order",
  "currency": "EUR",
  "retailCurrency": "GBP",
  "retailShippingPriceInclVat": 6.99,
  "shippingAddress": {
    "country": "DE",
    "firstName": "Hans",
    "lastName": "Schmidt",
    "addressLine1": "Unter den Linden 10",
    "city": "Berlin",
    "postCode": "10117",
    "email": "[email protected]",
    "phone": "+49123456789"
  },
  "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,
      "retailPriceInclVat": 19.99,
      "files": [
        {
          "type": "default",
          "url": "https://example.com/files/printfile.pdf"
        }
      ]
    }
  ]
}'

Problèmes courants

Champs obligatoires manquants : Assurez-vous que tous les champs obligatoires sont inclus dans votre demande.
URLs de fichier non valides : Assurez-vous que vos URLs de fichier sont accessibles publiquement.
UID de produit inconnu : Vérifiez que le UID du produit existe ou utilisez des produits client.
Référence de commande en double : Utilisez des identifiants de référence uniques pour chaque commande.

Annuler la commande

Le point de terminaison Annuler la commande vous permet d'arrêter le processus de production et d'expédition pour une commande qui n'a pas encore été expédiée.

Point de terminaison : POST /{orderCancelUrl}/{orderId}/cancel

Exemple de demande

# Cancel using Gelato Order ID
curl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \
--header 'X-API-KEY: your-key:your-secret'

# Cancel using your Order Reference ID
curl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \
--header 'X-API-KEY: your-key:your-secret'

Exemple de réponse

{
  "code": 200,
  "message": "OK"
}

Problèmes courants

Commande déjà expédiée : Une commande qui a déjà été envoyée ne peut plus être annulée.
Commande introuvable : Vérifiez que l'ID de commande ou l'ID de référence est correct.
Problèmes d’authentification : Vérifiez que votre clé API et votre secret sont corrects.

Mettre à jour l'expédition

Le point de terminaison Mettre à jour l'expédition vous permet de modifier la méthode d'expédition ou de mettre à jour l'adresse de livraison pour une commande qui n'a pas encore été expédiée.

Point de terminaison : POST /{updateShipmentURL}/{orderId}

Exemple de demande

# Update shipping details
curl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "shipmentMethodUid": "fed_ex_2_day",
  "shippingAddress": {
    "country": "US",
    "firstName": "Jane",
    "lastName": "Smith",
    "addressLine1": "456 Park Ave",
    "city": "New York",
    "postCode": "10022",
    "state": "NY",
    "email": "[email protected]",
    "phone": "987-654-3210"
  }
}'

# Update only shipping method
curl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "shipmentMethodUid": "fed_ex_2_day"
}'

Exemple de réponse

{
  "shippingAddress": {
    "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1",
    "orderId": "32884a3e-bd09-42be-8225-c5cea7d24611",
    "country": "US",
    "firstName": "Jane",
    "lastName": "Smith",
    "addressLine1": "456 Park Ave",
    "city": "New York",
    "postCode": "10022",
    "state": "NY",
    "email": "[email protected]",
    "phone": "987-654-3210"
  },
  "shipment": {
    "shipmentMethodUid": "fed_ex_2_day",
    "shipmentMethodName": "FedEx 2Day",
    "fulfillmentCountry": "US",
    "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa",
    "packageCount": 1,
    "initialMinDeliveryDate": "2025-04-15",
    "initialMaxDeliveryDate": "2025-04-15",
    "serviceType": "normal"
  }
}

Problèmes courants

Commande déjà expédiée : Les informations d’expédition ne peuvent plus être modifiées une fois la commande envoyée.
Champs obligatoires manquants : Assurez-vous que tous les champs obligatoires sont inclus dans l'adresse de livraison.
Méthode d'expédition non valide : Vérifiez que l'[nt]UID[/nt] de la méthode d'expédition est valide.
Commande introuvable : Vérifiez que l’ID de commande ou la référence est correcte.

Obtenir la commande

Le point de terminaison Get Order vous permet d’obtenir des informations détaillées sur une commande existante.

Point de terminaison : POST /{getOrderURL}/{orderId}

Exemple de demande

# Get order using Gelato Order ID
curl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \
--header 'X-API-KEY: your-key:your-secret'

# Get order using your Order Reference ID
curl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \
--header 'X-API-KEY: your-key:your-secret'

Exemple de réponse

La réponse contient des informations détaillées sur la commande, notamment :

Détails de la commande (ID, référence, statut, horodatages)
Adresse de livraison
Articles commandés
Informations d'expédition
Informations financières

En raison de la longueur de la réponse, veuillez consulter la documentation de l'API pour la structure complète de la réponse.

Utilisation des données de réponse

La réponse à la demande de commande vous donne des informations précieuses que vous pouvez utiliser pour :

Afficher le statut de la commande : Montrez aux clients l'état actuel de leurs commandes.
Suivre les expéditions : Récupérez les informations de suivi pour suivre vos envois.
Vérifier les détails de la commande : Confirmez que les détails de la commande sont corrects.
Analyser l'historique des commandes : Créez des rapports et des analyses basés sur les données de commandes.

Problèmes courants

Commande introuvable : Vérifiez que l'ID de commande ou l'ID de référence est correct.
Problèmes d'authentification : Assurez-vous que votre clé API et votre code secret sont corrects.

Rechercher des commandes

Le point de terminaison Rechercher des commandes vous permet de récupérer une liste de commandes selon des critères spécifiques.

Point de terminaison : POST /{searchOrdersURL}

Exemple de demande

# Search by fulfillment status
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "fulfillmentStatus": ["shipped", "delivered"]
}'

# Search by date range
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "startDate": "2025-01-01T00:00:00+00:00",
  "endDate": "2025-04-13T23:59:59+00:00"
}'

# Search by order reference ID
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "orderReferenceId": "YOUR-ORDER-123"
}'

# Search with pagination
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "fulfillmentStatus": ["created", "printed"],
  "limit": 50,
  "offset": 0
}'

Exemple de réponse

{
  "orders": [
    {
      "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1",
      "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366",
      "orderReferenceId": "YOUR-ORDER-123",
      "fulfillmentStatus": "shipped",
      "financialStatus": "paid",
      "currency": "USD",
      "totalInclVat": "33.45",
      "orderType": "order",
      "channel": "api",
      "firstName": "John",
      "lastName": "Doe",
      "country": "US",
      "itemsCount": 1,
      "createdAt": "2025-04-10T11:05:09+00:00",
      "updatedAt": "2025-04-10T14:05:10+00:00",
      "orderedAt": "2025-04-10T11:05:07+00:00",
      "customerReferenceId": "CUST-456"
    },
    // More orders...
  ]
}

Pagination

Le point de terminaison Rechercher des commandes prend en charge la pagination pour gérer les grands ensembles de résultats :

# First page (50 items)
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "fulfillmentStatus": ["shipped"],
  "limit": 50,
  "offset": 0
}'

# Second page (next 50 items)
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
  "fulfillmentStatus": ["shipped"],
  "limit": 50,
  "offset": 50
}'

Situations courantes de recherche

Commandes par statut :

{ "fulfillmentStatus": ["created", "printed"] }

Commandes par période :

{
  "startDate": "2025-04-01T00:00:00+00:00",
  "endDate": "2025-04-13T23:59:59+00:00"
}

Commandes par pays :
```
{ "countries": ["US", "CA"] }
```

Combinaison des critères :

{
  "fulfillmentStatus": ["shipped"],
  "countries": ["US"],
  "startDate": "2025-04-01T00:00:00+00:00"
}

Problèmes courants

Aucun résultat : Vérifiez que vos critères de recherche ne sont pas trop restrictifs.
Trop de résultats : Utilisez la pagination ou ajoutez des filtres pour affiner votre recherche.
Format invalide : Veuillez utiliser le format de date ISO 8601 (AAAA-MM-JJTHH:MM:SS+00:00).

Liaison des modèles aux points de terminaison API

Lors de la soumission de commandes via l'API, vous aurez souvent besoin de transformer les données entre votre format et celui de GelatoConnect. Les modèles gèrent cette transformation, mais vous devez explicitement lier votre modèle au point de terminaison de l'API pour qu'il soit appliqué.

Comment associer un modèle à un point de soumission de commande :

Accédez à votre liste de connecteurs et cliquez sur le lien hypertexte Modifier à côté du point de terminaison de soumission de commande.
Sur la page de configuration de l’endpoint, trouvez la section Modèle d’endpoint
Sélectionnez votre modèle de soumission de commande dans le menu déroulant
Cliquez sur le bouton Définir l'endpoint en haut à droite de la page
Cliquez sur Enregistrer les modifications en haut à droite pour appliquer votre configuration

Après avoir terminé ces étapes, toutes les commandes envoyées à ce point de terminaison utiliseront votre modèle pour transformer les données avant traitement. Cela garantit que le format de votre système est bien converti dans le format attendu par GelatoConnect.

Sans cette configuration, votre modèle ne sera pas appliqué même s'il existe et est correctement conçu, ce qui peut entraîner des échecs de validation de commande si votre format de données ne correspond pas exactement aux exigences de GelatoConnect.

Meilleures pratiques d'intégration

Lorsque vous intégrez les points de terminaison de l'API de commande, tenez compte de ces bonnes pratiques :

1. Identifiants de commande du magasin

Conservez toujours à la fois votre identifiant de référence de commande et l’identifiant de commande Gelato fourni dans la réponse. Cela vous permettra de suivre et de retrouver facilement vos commandes dans les deux systèmes.

2. Gérer les erreurs avec élégance

Mettez en place une gestion des erreurs adaptée pour chaque appel d’API. Analysez le message d’erreur de la réponse afin de fournir un retour utile aux utilisateurs, puis prévoyez des solutions de reprise appropriées.

Pour des conseils sur la mise en place d'une gestion des erreurs efficace, consultez la section « Bonnes pratiques de gestion des erreurs » dans la documentation de l'API de gestion des commandes.

3. Mettre en place l'idempotence

Générez des références de commande uniques pour chaque commande et utilisez le paramètre preventDuplicate afin de garantir qu’en cas de problème réseau, une commande ne soit pas envoyée deux fois.

4. Utiliser les notifications Webhook

Au lieu d'interroger régulièrement les mises à jour de statut des commandes, configurez des notifications webhook pour recevoir des mises à jour en temps réel lorsque les statuts des commandes changent.

5. Valider les données avant l'envoi

Vérifiez les données de commande de votre côté avant de les envoyer à l’API, afin de repérer les erreurs évidentes et d’offrir une meilleure expérience à vos utilisateurs.

6. Mettez en place une logique de nouvelle tentative

Ajoutez une logique de nouvelle tentative avec backoff exponentiel pour les erreurs transitoires, en particulier pour les réponses de limite de débit (429).

Pour en savoir plus sur la mise en œuvre de l’exponentiel backoff et du jitter, consultez la section « Bonnes pratiques concernant la limitation du débit » dans la documentation de l’Order Management API ou l’article du blog AWS sur l’exponentiel backoff et le jitter.

7. Optimiser les requêtes de recherche

Soyez précis avec vos critères de recherche pour réduire la taille des résultats et améliorer les performances.

8. Mémoriser les données de référence

Mémorisez les UIDs des produits et d'autres données de référence pour limiter le nombre d'appels à l'API nécessaires.

Conclusion

L’API de commande GelatoConnect offre un ensemble complet de points de terminaison pour gérer tout le cycle de vie d’une commande. En apprenant à utiliser ces points de terminaison de façon efficace, vous pouvez créer une intégration fluide entre vos systèmes et GelatoConnect.

Pour des informations plus détaillées, consultez la Documentation de l'API de gestion des commandes.

[Order Intake - GCW] Travailler avec les points de terminaison de l’API de commande

Prérequis

Valider la commande

Exemple de demande

Exemple de réponse

Utiliser des produits Personnalisé

Commandes internationales

Problèmes courants

Annuler la commande

Exemple de demande

Exemple de réponse

Problèmes courants

Mettre à jour l'expédition

Exemple de demande

Exemple de réponse

Problèmes courants

Obtenir la commande

Exemple de demande

Exemple de réponse

Utilisation des données de réponse

Problèmes courants

Rechercher des commandes

Exemple de demande

Exemple de réponse

Pagination

Situations courantes de recherche

Problèmes courants

Liaison des modèles aux points de terminaison API

Meilleures pratiques d'intégration

1. Identifiants de commande du magasin

2. Gérer les erreurs avec élégance

3. Mettre en place l'idempotence

4. Utiliser les notifications Webhook

5. Valider les données avant l'envoi

6. Mettez en place une logique de nouvelle tentative

7. Optimiser les requêtes de recherche

8. Mémoriser les données de référence

Conclusion