Guide d’intégration de Xero pour l’ordonnancement de la production avec SkyPlanner APS

Xero est un produit cloud unique à architecture multilocataire : toutes les organisations utilisent la même API. Accounting API est une REST API accessible à l’adresse https://api.xero.com/api.xro/2.0/, au format JSON ou XML. Chaque appel identifie l’organisation dans l’en-tête Xero-tenant-id. (source)

Les points de terminaison nécessaires à l’ordonnancement :

• Données de base : /Contacts (clients et fournisseurs), /Items (Code, IsTrackedAsInventory, QuantityOnHand).
• Demande : /Quotes (Status ACCEPTED, LineItems) et, pour les ateliers qui facturent d’abord, /Invoices avec Type ACCREC.
• Approvisionnements : /PurchaseOrders (DeliveryDate, ExpectedArrivalDate, LineItems avec ItemCode).
• Écriture en retour : /Quotes/{QuoteID}/History, /Invoices, /Quotes et Projects API à l’adresse https://api.xero.com/projects.xro/2.0/projects/{projectId}/time.

Chaque point de terminaison de liste accepte un en-tête If-Modified-Since : chaque synchronisation ne lit donc que les données modifiées. Les créations et les mises à jour se font par lots. Aucun point de terminaison ne gère les nomenclatures, les gammes de fabrication ou les ordres de fabrication.

« Webhooks allow you to subscribe to certain events that happen in Xero. » (Les webhooks vous permettent de vous abonner à certains événements qui se produisent dans Xero.) (source) Les événements utiles à l’ordonnancement sont Contact et Invoice, chacun avec CREATE et UPDATE.

Leur fonctionnement :

• Un seul webhook par application couvre toutes les organisations connectées.
• Chaque envoi contient un tableau d’événements avec l’identifiant de la ressource et le type d’événement. Le destinataire lit ensuite la ressource.
• Chaque envoi est signé au moyen d’un en-tête x-xero-signature, généré à partir de la clé de webhook de l’application. Xero envoie une vérification « Intent to receive » avant de commencer les envois.
• Xero réessaie les envois qui échouent et désactive tout webhook dont les échecs persistent. Le destinataire répond donc rapidement, puis effectue le traitement.

Les devis, les articles et les commandes fournisseurs ne déclenchent aucun événement webhook. SkyPlanner les lit par interrogation à intervalles courts avec If-Modified-Since, ce qui consomme un appel par entité lorsqu’aucune donnée n’a changé.

1. Chargement initial des données de base. Parcourez les contacts et les articles page par page, puis les commandes fournisseurs ouvertes et les devis acceptés. Créez les clients dans SkyPlanner en utilisant le ContactID de Xero comme external_identifier, puis les produits et les matières avec le code article comme clé. Configurez ensuite ce que Xero ne contient pas : postes de travail, étapes de fabrication par produit, horaires d’équipe, congés et temps de réglage. Pour les étapes de fabrication, l’import CSV ou Excel est la méthode la plus rapide.

2. Synchronisation des commandes. Interrogez les devis avec If-Modified-Since. Lorsqu’un devis passe au statut ACCEPTED, SkyPlanner crée une commande avec le numéro du devis comme external_order_number. La valeur de delivery_date provient du champ utilisé par votre atelier pour la date promise ; cette correspondance est définie lors de la mise en place. Chaque ligne génère des opérations selon les étapes de fabrication du produit. Les lignes des commandes fournisseurs deviennent des réceptions de matières à leur date d’arrivée prévue : les opérations attendent donc la livraison. Une lecture complète des devis et des commandes fournisseurs ouverts, effectuée chaque nuit, récupère tout élément manqué.

3. Renvoi du planning et des commandes terminées. Trois appels inscrivent les résultats dans Xero :

• PUT /Quotes/{QuoteID}/History ajoute une note avec la date de fin prévue. Sur un devis accepté, seuls le contact et les notes peuvent être modifiés : la date est donc enregistrée dans une note de l’historique. (source)
• Lorsque la commande est terminée, POST /Invoices crée une facture de vente avec Type ACCREC, Status DRAFT, le contact et les lignes du devis, ainsi que le numéro du devis dans Reference. Votre comptable la valide et l’envoie dans Xero.
• POST /Quotes avec le QuoteID et Status INVOICED clôture le devis. Le passage de Accepted à Invoiced est un changement de statut autorisé dans Accounting API.

4. Déclarations en atelier et temps par projet. Les opérateurs déclarent leur travail avec SkyPlanner Mobile Confirmations, Production Timer ou Quick Log Mode. L’avancement met immédiatement le planning à jour, et Autopilot replanifie le reste. Pour les travaux liés à un projet, SkyPlanner transmet les heures sous forme de saisies de temps sur la tâche du projet, avec l’utilisateur Xero, la date et la durée. (source)

5. Systèmes de référence et règles de gestion des conflits. Consignez ces règles avant la mise en service :

• Xero ne gère pas d’objets de production. Conservez les opérations de chaque produit dans SkyPlanner, en les rattachant au code article Xero. Gardez des codes articles stables.
• Les devis n’ont pas de webhook. Interrogez-les à intervalles courts avec If-Modified-Since, en respectant les limites par minute et par jour.
• Les devis acceptés sont verrouillés. Après acceptation, seules les coordonnées du contact et les notes peuvent être modifiées. La date promise est donc lue une seule fois, à l’acceptation, et la date planifiée est inscrite dans une note de l’historique.
• Les stocks évoluent avec les factures clients et fournisseurs. Pour les articles suivis en stock, Xero met à jour la quantité en stock à partir des factures de vente, des factures fournisseurs et des avoirs. Définissez avec votre comptable comment comptabiliser les produits finis et les matières consommées.
• La saisie des temps de projet nécessite un utilisateur Xero. Chaque saisie de temps est rattachée à un utilisateur Xero. Déterminez quels opérateurs transmettent leurs temps à Xero Projects et conservez les autres saisies dans SkyPlanner.
• Autorisations granulaires. Demandez des autorisations granulaires dès le départ, car les autorisations à portée étendue sont en cours de suppression.
• Niveau de l’application. Le niveau partenaire détermine le nombre d’organisations qu’une application peut connecter et le nombre d’appels dont elle dispose par jour. Choisissez ce niveau en fonction du nombre d’usines.