Інтеграції / ERP / Xero
Посібник з інтеграції Xero для календарного планування виробництва зі SkyPlanner APS
Цей посібник пояснює радникам і консультантам з Xero та ІТ-командам, як підключити Xero до SkyPlanner APS. SkyPlanner обмінюється даними з Xero в обох напрямках через Xero Accounting API та Projects API:
- До SkyPlanner надходять контакти, номенклатурні позиції зі складським обліком та наявними залишками, прийняті комерційні пропозиції й замовлення на закупівлю з датами надходження.
- Запланована дата завершення передається назад як примітка в історії кожної комерційної пропозиції.
- Виконані замовлення передаються назад як чернетки рахунків покупцям із позиціями комерційної пропозиції та її реквізитом Reference, а сама пропозиція переходить у статус Invoiced.
- Зареєстровані години роботи над проєктами передаються назад як записи часу в Xero Projects.
- Вебхуки Xero повідомляють про зміни контактів і рахунків, а вебхуки SkyPlanner передають зміни графіка одразу після їх внесення.
Xero — це бухгалтерське програмне забезпечення, тому воно не містить специфікацій матеріалів, технологічних маршрутів, верстатів чи виробничих замовлень. Робочі центри, технологічні операції, зміни та час переналагодження зберігаються в SkyPlanner. Команда SkyPlanner налаштовує інтеграцію з вашою організацією Xero під час впровадження та підтримує її після запуску. Цей посібник призначений для радників і розробників, які хочуть долучитися до роботи або самостійно створити рішення на основі документованого REST API SkyPlanner (довідник API).
Xero Accounting API
Xero — один хмарний продукт із мультитенантною архітектурою: усі організації працюють з однаковим API. Accounting API — це REST API за адресою https://api.xero.com/api.xro/2.0/, що підтримує JSON або XML. У кожному виклику організація вказується в заголовку Xero-tenant-id. (джерело)
Кінцеві точки, потрібні для календарного планування:
- Основні дані:
/Contacts(клієнти й постачальники),/Items(Code, IsTrackedAsInventory, QuantityOnHand). - Попит:
/Quotes(Status ACCEPTED, LineItems), а для виробництв, які спочатку виставляють рахунок, —/Invoicesз Type ACCREC. - Постачання:
/PurchaseOrders(DeliveryDate, ExpectedArrivalDate, LineItems з ItemCode). - Зворотний запис:
/Quotes/{QuoteID}/History,/Invoices,/Quotesта Projects API за адресоюhttps://api.xero.com/projects.xro/2.0/projects/{projectId}/time.
Кожна кінцева точка для отримання списків приймає заголовок If-Modified-Since, тож під час кожної синхронізації зчитуються лише змінені дані. Створення й оновлення виконуються пакетами. Кінцевих точок для специфікацій матеріалів, технологічних маршрутів чи виробничих замовлень немає.
Автентифікація, права доступу та ліміти
Xero використовує OAuth 2.0. Адміністратор Xero один раз входить у систему, схвалює застосунок і вибирає організацію. Застосунок запитує offline_access, щоб підтримувати з’єднання за допомогою токенів оновлення. (джерело)
Xero замінює широкі права доступу деталізованими, і нові застосунки отримують уже деталізовані права. Для інтеграції з календарним плануванням потрібні:
accounting.invoicesдля комерційних пропозицій, рахунків, замовлень на закупівлю та номенклатурних позиційaccounting.contactsдля клієнтів і постачальниківaccounting.settings.readдля налаштувань номенклатурних позиційprojectsдля записів часуoffline_access
Xero обмежує кількість викликів для кожної організації (одночасних, за хвилину та за добу) і для кожного застосунку. Якщо застосунок перевищує ліміт, Xero повертає HTTP 429 із заголовком Retry-After. Добовий ліміт і кількість підключених організацій залежать від партнерського рівня застосунку. Обидва значення наведено на сторінці лімітів API Xero. Вебхуки, зчитування з If-Modified-Since та пакетний запис дають змогу інтеграції для календарного планування працювати зі значним запасом до цих лімітів.
На стороні SkyPlanner REST API використовує для автентифікації токен API в заголовку Authorization-Token (SkyPlanner Settings > API). Документацію подано у Swagger/OpenAPI. У посібнику з інтеграції покроково розглянуто перші виклики.
Вебхуки
“Webhooks allow you to subscribe to certain events that happen in Xero.” (Вебхуки дають змогу підписатися на певні події в Xero.) (джерело) Для календарного планування важливі події Contact та Invoice, кожна з типами CREATE і UPDATE.
Як вони працюють:
- Один вебхук для застосунку охоплює всі підключені організації.
- Кожне повідомлення містить масив подій з ідентифікатором ресурсу й типом події. Після цього отримувач зчитує сам ресурс.
- Кожне повідомлення підписується за допомогою заголовка
x-xero-signature, сформованого на основі ключа вебхука застосунку. Перш ніж почати надсилання, Xero виконує перевірку “Intent to receive” (готовність до отримання). - Xero повторює невдалі спроби надсилання й вимикає вебхук, якщо помилки тривають. Тому отримувач має швидко відповідати, а обробку виконувати після відповіді.
Для комерційних пропозицій, номенклатурних позицій і замовлень на закупівлю подій вебхуків немає. SkyPlanner зчитує їх, часто опитуючи API з If-Modified-Since. Якщо змін немає, на це потрібен один виклик для кожної сутності.
Зіставлення даних
| Об’єкт Xero (кінцева точка) | Об’єкт SkyPlanner | Напрямок | Періодичність |
|---|---|---|---|
Contact, IsCustomer (/Contacts) | Customer (external_identifier, delivery_priority) | Xero → SkyPlanner | Початкове завантаження, далі — за вебхуком |
Item, зі складським обліком і без нього, з QuantityOnHand (/Items) | Продукція й матеріали, складські залишки | Xero → SkyPlanner | Початкове завантаження, далі — за If-Modified-Since |
Quote зі Status ACCEPTED і LineItems (/Quotes) | Order (external_order_number, delivery_date), виробничі завдання для кожної позиції | Xero → SkyPlanner | Опитування з If-Modified-Since |
Invoice з Type ACCREC (для виробництв, які спочатку виставляють рахунок) (/Invoices) | Order та виробничі завдання | Xero → SkyPlanner | У реальному часі через вебхук |
PurchaseOrder з ExpectedArrivalDate або DeliveryDate (/PurchaseOrders) | Очікуване надходження матеріалу (estimated_delivery_date) | Xero → SkyPlanner | Опитування з If-Modified-Since |
Примітка в історії комерційної пропозиції (PUT /Quotes/{QuoteID}/History) | Запланована дата завершення | SkyPlanner → Xero | У разі зміни графіка |
Invoice з Type ACCREC, Status DRAFT, Reference = номер комерційної пропозиції (POST /Invoices) | Виконане замовлення | SkyPlanner → Xero | Після виконання замовлення |
Quote зі Status INVOICED (POST /Quotes) | Виконане замовлення | SkyPlanner → Xero | Після створення рахунку |
Запис часу в Projects (POST /projects/{projectId}/time) | Mobile Confirmations, записи робочого часу | SkyPlanner → Xero | У міру реєстрації виконаної роботи |
| Відсутні в Xero | Робочі центри, технологічні операції, зміни, відсутності працівників, матриця часу переналагодження, інструменти, кількість операторів, альтернативні робочі центри | Ведуться в SkyPlanner | Налаштовуються під час впровадження |
Варіанти інтеграції
1. Початкове завантаження основних даних. Посторінково зчитайте контакти й номенклатурні позиції, потім відкриті замовлення на закупівлю та прийняті комерційні пропозиції. Створіть клієнтів у SkyPlanner, указавши Xero ContactID як external_identifier, а для продукції й матеріалів використайте код номенклатурної позиції як ключ. Потім налаштуйте те, чого немає в Xero: робочі центри, технологічні операції для кожного виробу, зміни, відпустки та час переналагодження. Найшвидше завантажити технологічні операції можна через імпорт CSV або Excel.
2. Синхронізація замовлень. Опитуйте комерційні пропозиції з If-Modified-Since. Коли пропозиція переходить у статус ACCEPTED, SkyPlanner створює замовлення, використовуючи її номер як external_order_number. Значення delivery_date береться з поля, у якому ваше виробництво вказує обіцяну дату; відповідність цього поля налаштовується під час впровадження. Кожна позиція перетворюється на виробничі завдання відповідно до технологічних операцій виробу. Позиції замовлень на закупівлю стають очікуваними надходженнями матеріалів із відповідною датою прибуття, тому виробничі завдання чекають на постачання. Щонічне повне зчитування відкритих комерційних пропозицій і замовлень на закупівлю виявляє все пропущене.
3. Зворотний запис графіка й даних про виконання. Три виклики передають результати в Xero:
- PUT
/Quotes/{QuoteID}/Historyдодає примітку із запланованою датою завершення. У прийнятій комерційній пропозиції можна змінювати лише контакт і примітки, тому дата зберігається саме в примітці історії. (джерело) - Після виконання замовлення POST
/Invoicesстворює рахунок покупцеві з Type ACCREC, Status DRAFT, контактом і позиціями з комерційної пропозиції та її номером у полі Reference. Ваш бухгалтер затверджує й надсилає його в Xero. - POST
/Quotesз QuoteID та Status INVOICED закриває комерційну пропозицію. Accounting API дозволяє перехід зі статусу Accepted у Invoiced.
4. Підтвердження виконання в цеху та облік часу за проєктами. Оператори реєструють виконану роботу через SkyPlanner Mobile Confirmations, Production Timer або Quick Log Mode. Дані про виконання одразу оновлюють графік, а Autopilot переплановує решту робіт. Для проєктних робіт SkyPlanner передає години як записи часу за завданням проєкту, указуючи користувача Xero, дату й тривалість. (джерело)
5. Відповідальність за дані та правила розв’язання конфліктів. Зафіксуйте їх до запуску:
| Дані | Відповідальна система |
|---|---|
| Контакти, номенклатурні позиції, ціни, комерційні пропозиції, замовлення на закупівлю, рахунки, бухгалтерський облік | Xero |
| Робочі центри, технологічні операції, зміни, відсутності працівників, матриця часу переналагодження, інструменти, альтернативні виробничі ресурси | SkyPlanner |
| Послідовність виробничих завдань, час початку й завершення, робочий центр для кожного виробничого завдання | SkyPlanner |
| Примітка із запланованою датою завершення в комерційній пропозиції | SkyPlanner, із записом у Xero |
| Чернетка рахунку за виконаними замовленнями, облік часу за проєктами | Створює SkyPlanner, після затвердження відповідальність за дані переходить до Xero |
Типові етапи проєкту
Впровадження зазвичай завершується протягом кількох тижнів після початку налаштування системи. До цього ви можете пройти 30-денний безкоштовний пробний період на власних даних: контактах, продуктах і відкритих комерційних пропозиціях, експортованих із Xero у CSV.
Сам проєкт охоплює такі етапи:
- Підключення. Адміністратор Xero надає доступ SkyPlanner і вибирає організацію.
- Джерело попиту. Узгодьте, що запускатиме виробництво: прийняті комерційні пропозиції чи рахунки покупцям.
- Зіставлення даних. Затвердьте таблицю відповідностей, коди номенклатури, бухгалтерські рахунки для рахунків-фактур, податкові налаштування за замовчуванням та правила відповідальності за дані.
- Початкове завантаження. Контакти, номенклатура, відкриті замовлення на закупівлю, прийняті комерційні пропозиції.
- Виробнича модель. Робочі центри, технологічні операції для кожного продукту, зміни, матриця часу переналагодження, інструменти та кількість операторів у SkyPlanner.
- Синхронізація. Вебхуки для контактів і рахунків, періодичне опитування з
If-Modified-Sinceдля комерційних пропозицій, номенклатури й замовлень на закупівлю, а також щоночне звіряння даних. - Зворотний запис. Спочатку примітки до комерційних пропозицій, потім чернетки рахунків і статуси пропозицій, далі — облік часу за проєктами, якщо він використовується.
- Паралельне тестування та запуск. Порівняйте дати в SkyPlanner із поточним планом, доручіть бухгалтеру перевірити перші чернетки рахунків, а потім увімкніть зворотний запис.
Що врахувати під час інтеграції з Xero
- У Xero немає виробничих об’єктів. Зберігайте технологічні операції для кожного продукту в SkyPlanner, прив’язавши їх до коду номенклатури Xero. Не змінюйте ці коди.
- Для комерційних пропозицій немає вебхуків. Часто перевіряйте їхні зміни через опитування з
If-Modified-Since, не перевищуючи похвилинних і добових лімітів. - Прийняті комерційні пропозиції блокуються. Після прийняття можна змінювати лише контактні дані та примітки. Тому обіцяну дату зчитують один раз у момент прийняття, а заплановану дату записують як примітку в історії.
- Залишки змінюються за рахунками на продаж і рахунками постачальників. Для номенклатури зі складським обліком Xero змінює наявну кількість на підставі рахунків на продаж, рахунків постачальників і кредит-нот. Узгодьте з бухгалтером порядок обліку готової продукції та використаних матеріалів.
- Для обліку часу за проєктами потрібні користувачі Xero. Кожен запис часу належить користувачеві Xero. Визначте, для яких операторів передавати записи часу в Xero Projects, а для решти ведіть облік у SkyPlanner.
- Деталізовані дозволи. Відразу запитуйте деталізовані дозволи, оскільки дозволи з широкою сферою доступу поступово виводяться з використання.
- Рівень застосунку. Партнерський рівень визначає, скільки організацій може підключити застосунок і скільки викликів на добу йому доступно. Вибирайте рівень з урахуванням кількості виробничих майданчиків.
Інтеграція з Xero: хто її налаштовує та підтримує
Робота охоплює вашу номенклатуру, комерційні пропозиції, замовлення на закупівлю та передавання виконаних робіт на виставлення рахунків. Також додаються дані, яких немає в Xero: робочі центри, технологічні операції, зміни, матриця часу переналагодження, інструменти, кількість операторів та альтернативні виробничі ресурси.
- Команда SkyPlanner налаштовує інтеграцію під час впровадження та підтримує її після запуску. Кожне виробництво по-своєму налаштовує в Xero номенклатуру, комерційні пропозиції та складський облік. Під час інтеграції ці особливості враховуються.
- Ваш консультант із Xero або партнер з інтеграції може розробити її. SkyPlanner надає REST API, документацію Swagger/OpenAPI та вебхуки.
- Ваші розробники можуть створити власну інтеграцію за допомогою токена API. Для початку достатньо токена API, а за потреби команда SkyPlanner допоможе. Документацію продукту, зокрема щодо замовлень на закупівлю та API продуктів і матеріалів, наведено в документації SkyPlanner.
Вартість SkyPlanner починається від 199 € на місяць за щомісячної оплати; включено 5 робочих центрів. Цінову пропозицію на інтеграцію готують заздалегідь з урахуванням ваших процесів і потреб та надають разом із пропозицією щодо тарифного плану, щоб ви знали повну вартість ще до початку роботи. Перегляньте тарифи, можливості та дізнайтеся, що Xero забезпечує самостійно, у статті «Чи є в Xero календарне планування виробництва?». Огляд наведено на сторінці Xero, а інші системи — у розділі всіх інтеграцій.
Відгуки виробників про SkyPlanner
2 годекономії щотижня
«Завдяки SkyPlanner ми перейшли від планування виробництва в таблицях Excel до оптимізації виробництва в реальному часі».
Kalle Kalliomäki, фахівець із ланцюгів постачання
UTU · Електричні щити та розподільні пристрої
Планування виробництва заощаджує 2 години робочого часу щотижня, а нова черга завдань надходить на лінію за лічені секунди.
+90%до ефективності виробництва
«Ефективність виробництва зросла на 90%».
Abdul Rucyinga, керівник ІТ-відділу
Laboratory & Allied · Фармацевтичне виробництво
Ефективність виробництва зросла на 90%, а створення оптимізованого плану на три місяці для всіх робочих центрів займає менше ніж 30 хвилин.
Меншезупинок через нестачу матеріалів
«Цінність SkyPlanner для нас у тому, що це інструмент, який працює в щоденній роботі, особливо коли потрібно визначити дати постачання».
Tommi Männistö, керівник відділу планування виробництва
Eskomatic · Механічна обробка на замовлення
Автоматичне планування завантаження дає змогу точніше визначати дати постачання, а кількість зупинок виробництва через нестачу матеріалів різко скоротилася.
1 000+виробничих замовлень плануються автоматично
«Ми по-іншому контролюємо виробництво, а наше розуміння виробничих потужностей вийшло на зовсім інший рівень».
Hannu Ryynänen, генеральний директор
Mamec · Промислові змішувачі, насоси та високотехнологічне виробництво на замовлення
Тисячі виробничих замовлень плануються автоматично, а вся організація бачить стан виробництва в реальному часі.
Поширені запитання
Чи є в Xero API для виробничих даних?
Xero має Accounting API та Projects API — обидва побудовані на REST і використовують OAuth 2.0. Вони охоплюють контакти, номенклатуру, комерційні пропозиції, рахунки, замовлення на закупівлю та записи часу. Виробничі дані, як-от робочі центри й технологічні операції, зберігаються в SkyPlanner.
Чи може SkyPlanner передавати дані назад до Xero?
Так. SkyPlanner додає заплановану дату завершення до історії кожної комерційної пропозиції. Після виконання замовлення він створює чернетку рахунку на продаж із позиціями пропозиції, переводить пропозицію в статус Invoiced і передає записи часу за проєктом.
Чи надсилає Xero зміни в реальному часі?
Вебхуки Xero охоплюють контакти й рахунки. За допомогою If-Modified-Since SkyPlanner зчитує комерційні пропозиції, номенклатуру та замовлення на закупівлю, змінені після останньої синхронізації, і щоночі звіряє дані. Завдяки цьому нова прийнята пропозиція швидко потрапляє до графіка.
Звідки беруться специфікації матеріалів, технологічні маршрути та верстати, якщо їх немає в Xero?
Із SkyPlanner. Ви один раз налаштовуєте робочі центри, технологічні операції для кожного продукту, зміни та час налагодження — вручну або імпортом із CSV чи Excel. Кожен продукт прив’язаний до коду номенклатури Xero, тому нові прийняті комерційні пропозиції автоматично потрапляють до графіка.
Чи можна протестувати SkyPlanner до розробки інтеграції?
Так. Протягом 30-денного безкоштовного пробного періоду можна використовувати до 20 робочих центрів та імпортувати дані з Xero через CSV. Кредитна картка не потрібна. Спробуйте безкоштовно або зверніться до відділу продажів, щоб визначити обсяг інтеграції.
