50.50. Генериране и изтегляне на товарителници през API

Тази инструкция показва как външна Shopify интеграция може да генерира и изтегля товарителници от Izprati.bg — по една или на пакет. Готовата Postman колекция е приложена в края на статията.

Преди да започнете #

• Нужни са OAuth клиент и потребител с права за работа с пратките.
• Използвайте https://api.izprati.bg и изпращайте Authorization: Bearer <access token> след успешен вход.
• Действие със статус measured може да създаде реална пратка при куриера. Работете с подходяща тестова пратка.

Една Shopify поръчка: генериране на товарителница #

1. Намерете поръчката по нейния числов Shopify ID чрез GET /api/products/order, като филтрирате extId.
2. Намерете свързаната пратка чрез GET /api/delivery-services/requests, като филтрирате по ID на намерената поръчка.
3. Прочетете текущата задача и опашката чрез GET /api/delivery-services/delivery-request-service?action=tasks, като подадете ID на пратката.
4. Ако няма задача за предварителна обработка, създайте я с POST /api/delivery-services/preprocessing-task. Ако има валидна задача, използвайте PATCH /api/delivery-services/preprocessing-task/{taskId}.
5. В заявката подайте state: measured, ID на пратката, тегло в грамове, размери в милиметри и ID на опашката.

Не използвайте отново анулирана задача. При конфликт 409 прочетете задачите отново и използвайте текущата задача само ако вече е в обработка.

Една товарителница: изтегляне и печат #

За готова товарителница не създавайте нова задача. Използвайте:

GET /api/delivery-services/preprocessing-task/{taskId}
Accept: application/pdf

Ако отговорът е PDF, той е готов за запазване или печат. Ако отговорът е JSON, задачата още се обработва — повторете същата заявка след кратко изчакване.

По желание добавете packing slip: ?withPackingSlip=true&packingSlipFormat=10x15. Поддържаните формати са 10x15 и A4.

Пакет от товарителници #

1. За всяка избрана Shopify поръчка намерете съществуващото ID на пратката.
2. Създайте един import с POST /api/integrations/import, handler: delivery-services и масив shipments с ID на пратките.
3. В sourceData.asyncMode подайте Orderadmin\DeliveryServices\Service\ImportLabelsService: true.
4. Проверявайте GET /api/integrations/import/{importId}, докато състоянието стане confirmed.
5. Изтеглете обединения PDF от loadResult.url.

За пакета използвайте ID на пратките, а не Shopify ID на поръчките. При частичен успех failedTaskIds посочва пратките, които трябва да се прегледат и повторят отделно.

Postman колекция #

Колекцията съдържа вход с OAuth, търсене на Shopify поръчка, създаване или обновяване на задача, изтегляне на единичен PDF, пакетен import и проверка на неговия статус.

Изтеглете Postman колекцията за Shopify товарителници

След import в Postman попълнете променливите за OAuth, Shopify order ID и тестовите идентификатори. Колекцията не съдържа реални ключове или данни за клиенти.