Guide de migration vers l'API v3

Ce guide s'adresse aux intégrations encore construites sur l'API v1 ou v2. Il explique ce qui a changé, ce qui n'a aucun équivalent direct et demande une approche différente, et ce qui peut rester tel quel.

Depuis l'API v1 (historique)

v1 était l'API historique de Wing, aujourd'hui entièrement retirée. Elle exposait un modèle simple : un appel crée une commande et son unique colis d'un coup, sans distinction entre commande et colis.

type Mutation {
  createParcel(order: OrderInputPublicAPI!): LegacyParcel
  createParcelShipOnly(parcelId: ID!): LegacyParcel!
}

type Query {
  parcel(id: ID!): LegacyParcel
  collect(id: ID!): LegacyCollect
  collects(customers: String, pickup: ID, context: String): [LegacyCollect]
  allParcels(limit: Int = 25, offset: Int = 0, status: [LegacyParcelStatus!], ...): ParcelsList
}

OrderInputPublicAPI portait la commande et son unique colis dans la même structure plate (ref, service: WingServiceLegacy!, items, addressRec, addressExp, signature, isInsuranceEnabled, pickupId...) — pas de recipient/expeditor séparés, pas de sous-objet fulfillment order.

Modèle de données : v1 → v3

Le colis n'est plus une propriété de la commande : il devient une entité à part, portée par un FulfillmentOrder lui-même détaché de la commande — ce qui permet plusieurs colis, chacun avec son propre statut et son propre label.

Correspondance des opérations

Opération v1	Équivalent v3	Ce qui change
createParcel(order)	createOrder puis createFulfillmentParcel	Deux étapes distinctes : la commande (recipient + ref) est créée d'abord, avec un fulfillmentOrders d'une entrée ; le label est généré ensuite sur ce fulfillment order
createParcelShipOnly(parcelId)	createFulfillmentParcel	v3 sépare déjà nativement création de commande et génération de label — pas besoin d'un mode "ShipOnly" à part
parcel(id)	fulfillmentOrder(input: { id })	Les infos de colis vivent sous FulfillmentOrder.parcels
parcels / allParcels	fulfillmentOrders	Filtres largement repris (status, services, collects, warehouses, orderDate, collectDate, hasClaims, search...) sous des noms proches
collect(id) / collects	collects
addressRec / addressExp (champs plats sur la commande)	recipient (sur Order) + organizationPickupId (sur le FulfillmentOrder)	L'adresse d'expédition n'est plus saisie en clair à chaque commande : elle référence un point d'enlèvement existant
service: WingServiceLegacy! (paliers génériques : ECO, STANDARD, EXPRESS, ..._RELAY)	service: WingService! (transporteurs explicites : COLISSIMO, CHRONOPOST, DPD_FR, MONDIAL_RELAY...)	Le modèle est passé de paliers de service à des codes transporteur explicites — il n'existe pas de table de correspondance 1:1, le choix du transporteur remplace le choix du palier

Depuis l'API v2

v2 et v3 partagent exactement le même système de types (Order, FulfillmentOrder, Collect, OrganizationPickup, etc.) — ils ne diffèrent que par les opérations exposées à la racine.

Authentification

createAccessToken(email, password) fonctionne à l'identique sur les deux versions et renvoie la même forme de Token (accessToken, refreshToken, user). La seule vraie différence :

	v2	v3
Obtenir un token	createAccessToken	createAccessToken — inchangé
Rafraîchir un token expiré	refreshAccessToken(refreshToken)	Indisponible — rappelez createAccessToken

La réponse Token de v3 contient toujours un champ refreshToken, mais aucune opération v3 ne l'accepte en entrée. Prévoyez de vous ré-authentifier avec les identifiants à l'expiration (les tokens d'accès sont valides 1 heure) plutôt que de compter sur un flux de rafraîchissement.

Voir Authentication pour la référence complète.

Modèle Order & Fulfillment

Le changement de fond : ce qui était un colis unique en v2 (avant le retrait de sa gestion de commandes) devient une Order qui porte une ou plusieurs FulfillmentOrder, chacune expédiable et traçable indépendamment.

Modèle de données : v2 → v3

Créer une commande en v3 signifie la créer avec ses fulfillment orders imbriqués, puis créer un colis (un label) par fulfillment order :

mutation {
  createOrder(
    input: {
      ref: "ORDER-2024-001"
      recipient: {
        firstName: "Marie"
        lastName: "Dupont"
        email: "marie.dupont@example.com"
        phone: "+33612345678"
        line1: "45 Rue de la République"
        city: "Lyon"
        zip: "69002"
        countryCode: "FR"
      }
      fulfillmentOrders: [
        {
          service: STANDARD
          products: [
            {
              designation: "Clavier sans fil"
              sku: "KB-001"
              quantity: 1
              price: 49.99
              weight: 0.6
            }
          ]
        }
      ]
    }
  ) {
    id
    ref
    fulfillmentOrders {
      id
      status
    }
  }
}

mutation {
  createFulfillmentParcel(
    input: {
      fulfillmentOrderId: "fo_def456"
      organizationPickupId: "pickup_123"
    }
  ) {
    id
    trackingNumber
    trackingUrl
    carrierLabel
  }
}

Une commande à un seul colis est simplement une commande avec une seule entrée fulfillmentOrders — rien n'oblige à en utiliser plusieurs. Le déroulé complet est dans Single Parcel Order Workflow ; pour les commandes à plusieurs colis, voir Multi Parcel Order Workflow.

Correspondance des opérations

Si votre intégration référence encore l'un de ces anciens noms d'opération v2, voici où vit désormais la fonctionnalité équivalente :

Ancien concept v2	Opération v3	Remarques
Créer une commande (un colis)	createOrder	Prend désormais un tableau fulfillmentOrders — une seule entrée pour une commande à un colis
Créer un colis / label d'expédition	createFulfillmentParcel	Scopé sur un fulfillmentOrderId, pas sur l'id de la commande
Créer un colis retour	createFulfillmentReturnParcel	Même scoping
Créer une commande retour	—	Utiliser createReturnFulfillmentOrder (scopé sur une commande existante + une liste de produits)
Annuler un label	cancelFulfillmentOrderParcels	Prend une liste de fulfillmentOrderIds
Supprimer une commande	deleteOrders	Existe toujours — nom inchangé
Supprimer un fulfillment order	deleteFulfillmentOrders	Nouveau — suppression au niveau du fulfillment order, pas de toute la commande
Lister les commandes	orders
Lister les collects	collects
Lister les adresses de retrait	organizationPickups
Lister les expéditeurs	organizationExpeditors
Ajouter une/des commande(s) à un collect	addFulfillmentOrdersToCollect	Prend des fulfillmentOrderIds, pas des orderIds
Retirer une/des commande(s) d'un collect	removeFulfillmentOrdersFromCollect	Idem
Planifier le prochain collect	upsertNextCollect	Nom inchangé
Scinder une commande multi-articles en deux	splitFulfillmentOrder	Nouvelle capacité, sans équivalent v2 — scinde par liste de produits
Fusionner deux commandes/colis	mergeFulfillmentOrder	Nouvelle capacité, sans équivalent v2
Migrer la liste de produits d'une commande	migrateFulfillmentOrder	Nouvelle capacité, sans équivalent v2
Rechercher les points relais à proximité	relayPoints	Nom, arguments et type de retour inchangés

Chaque champ ci-dessus se trouve dans la Référence API, sous Orders, Fulfillment Orders, Parcels et Collections.

Checklist de migration

1. Déplacez toutes les opérations de commande, fulfillment order, colis et collect vers v3 (https://api-developer.wing.eu/v3) — les équivalents v1 et v2 n'existent plus.
2. Mettez à jour votre payload de création de commande pour imbriquer les produits sous fulfillmentOrders plutôt que directement sous la commande.
3. Suivez les colis par fulfillmentOrderId, pas par id de commande — une commande peut désormais en avoir plusieurs.
4. Retirez toute dépendance à refreshAccessToken ; ré-authentifiez-vous avec createAccessToken à l'expiration d'un token.
5. Migrez relayPoints vers v3 — mêmes noms, arguments et types de retour.
6. Testez avec les workflows Single Parcel Order et Multi Parcel Order avant de basculer le trafic de production.

Prochaines étapes

• Authentication — détails d'émission des tokens
• Single Parcel Order Workflow
• Multi Parcel Order Workflow
• Schema — référence complète v3