REST API – Weaver WMS

Weaver WMS działa w oparciu o API w architekturze REST, które wykorzystuje protokół HTTP i jego metody, takie jak:

GET – służy do pobierania danych (np. wyświetlania listy materiałów),

POST – tworzy nowe dane (np. dodaje nowego odbiorcę),

PUT – aktualizuje wcześniej dodane zasoby (np.  wprowadza zmiany do materiału),

DELETE – służy do usuwania danych.

Dane wchodzące i wychodzące z API są w formacie JSON. Każdy obiekt zawarty jest pomiędzy nawiasami klamrowymi, a jego poszczególne elementy oddzielane są przecinkami. Wartości elementów wpisywane są po ich nazwach oraz dwukropku.

Podczas wysyłania zapytań do lokalnego API, program Weaver WMS musi być uruchomiony.

Swagger

Sprawdzenie działania poszczególnych adresów URI (endpoints) przy pomocy swaggera zawartego w programie Weaver WMS.  

W tym celu należy postępować zgodnie z instrukcją zawartą na poniższym zdjęciu.

Ustawienia -> Konfiguracja bazy danych > Konfiguracja API > /swagger

Następnie, żeby uzyskać pełny dostęp, należy przejść do zakładki Authentication i nacisnąć przycisk Try it out. Teraz w miejsca, gdzie wpisany jest „string”, należy odpowiednio wpisać login oraz hasło użytkownika WMS’a w cudzysłowie.

Po wypełnieniu pól należy wykonać zapytanie przyciskiem Execute, kod 200 świadczy o prawidłowym wykonaniu polecenia.

Strukturę API w swaggerze można również sprawdzić w testowym panelu, do którego link znajduje się poniżej.

https://weaversoft.pl/api-demo/

Zrzut ekranu po prawidłowym wykonaniu autoryzacji.

Po autoryzacji jesteśmy w stanie wykonywać pozostałe zapytania, odpowiednio uzupełniając wartości elementów.

Poniżej znajduje się przykład dodawania odbiorcy (elementy, których nie uzupełniamy, należy usunąć, w tym przypadku uzupełniliśmy tylko wymagane dane).

Postman

Kolejnym sposobem sprawdzenia działania zapytań jest program Postman.

Na początek należy zaimportować kolekcję z zapytaniami.
1. Wejdź do swaggera.
2. Przejdź do strony w formacie JSON.

3. Zaznacz cały tekst (Ctrl + A) i skopiuj go (Ctrl + C).
4. W głównym oknie Postman kliknij przycisk Import w lewym górnym rogu.
5. Przejdź do zakładki Raw text i wklej wcześniej skopiowany tekst.

Po wykonaniu powyższych kroków w menu po lewej stronie w zakładce Collections powinna pojawić się kolekcja „WMS API”.

Pozostaje jeszcze skonfigurowanie  środowiska.
1. Kliknij w ikonę Manage Environments w prawym, górnym rogu.

2. Kliknij przycisk Add, a następnie wypełnij pola według poniższego zrzutu ekranu i ponownie kliknij przycisk Add.

3. W prawym górnym rogu wybierz z listy dodane środowisko.

W programie Postman również trzeba wykonać autoryzację przed wykonywaniem kolejnych zapytań. W tym celu należy z dodanej kolekcji wybrać /auth/sign-in, przejść do sekcji Body i zastąpić domyślnie wpisane wartości, loginem oraz hasłem użytkownika WMS.

Podczas wykonywania poszczególnych zapytań należy usuwać elementy, w których nie uzupełniamy wartości, ponieważ może to skutkować powstawaniem błędów.

Dodawanie materiału

{"Selected":false,
"Type":3,
"Reference":" HD2285",
"Name":"Bezprzewodowy skaner 22Bluetooth HD85",
"DefaultQuantityInContainer":0.0,
"Removed":false,
"Inactive":false,
"SingleUnitPrice":0.0,
"Unit":
{
    "Description":"szt.",
    "DescriptionEng":"pcs",
    "DescriptionDe":"psc",
    "DescriptionRu":"psc",
    "Details":"sztuka",
    "IsLenght":false,
    "Precision":4,
    "IsDefault":false,
    "Id":1
    },
    "TaxRate":{
        "Value":0.23000,
        "Name":"23%",
        "IsDefault":false,
        "TaxRateLegalType":0,
        "Id":1
        },
        "SuggestedPlace":{
            "Selected":false,
            "Reference":"MAG_S1_0_0",
            "Level":0,
            "Number":0,
            "QuantityOfMaterial":0.0,
            "Id":1
            },
            "PercantageProfit":0.0,
            "InitialQuantity":0.0,
            "HasChildren":false,
            "IsOnMachines":false,
            "IsDangerous":false,
            "CountSeparately":false,
            "AdvisingQuantity":0.0,
            "Length":0.0,"Width":0.0,
            "Height":0.0,
            "PackageRequireReference":false,
            "PackageDoNotAddToShippingDocument":false,
            "PackageIsTemporary":false,
            "PackageType":0,
            "RequiredQuantity":0.0,
            "OnCustomOrder":false,
            "LengthIsWidth":false,
            "AbcClass":0,
            "XyzClass":0,
            "MaterialTradeInfo":{
                "IsEcommerceShopPosition":true,
                "IsEcommerceAuctionPosition":false,
                "Id":0},"LengthStrategy":0,
                "WidthStrategy":0,
                "HeightStrategy":0,
                    "SplitPayment":false,
                    "RequireLotNumber":false,
                    "RequireLotExpiration":false,
                    "Id":0
                    }
Podgląd materiału dodanego przez program Postman

Dodanie odbiorcy

{
    "reference": "HDWR",
            "nameLine1": "HDWR",
            "nameLine2": "Hardware for business",
            "removed": false,
            "address": {
                "street": "Os. Piastowskie 53",
                "postalCode": "63-000",
                "city": "Środa Wlkp",
                "id": 0
            },
            "companyDetail": {
                "nip": "786-165-45-57",
                "nipCleaned": "7861654557",
                "ueVatPayer": false,
                "id": 481
            },
            "mail": "biuro@hdwr.pl",
            "shippingAddressesCount": 0,
            "multiplyQuantityWhileImportEdi": false,
            "notificationSetting": {
                "newOrderEmailSend": false,
                "newOrderEmailJoinAttachement": false,
                "id": 3737
            },
            "currency": {
                "symbol": "PLN",
                "name": "PLN",
                "id": 1
            },
            "paymentWay": 0,
            "paymentDays": 0,
            "salesBlockade": false,
            "creditLimit": false,
            "creditLimitAmout": 0.00000,
            "nip": "786-165-45-57",
            "name": "Waever Software Andrzej Lenkowski",
            "id": 473
}
Podgląd odbiorcy dodanego w programie Postman

Przekazanie awizacji przyjęcia

W celu przekazania awizacji przyjęcia trzeba najpierw pobrać metodą GET dane z odpowiednich adresów.
Pierwszą z nich jest dostawca, pobierany z adresu „suppliers”.

/suppliers?IncludeAllId=false&IdList=1

Kolejną potrzebną informacją jest numeracja, pobierana z adresu „document-numbers”. Dodatkowo możemy zastosować parametr „IncludeAllTypes” oraz „Types”.

Parametr "Types" dla przyjęć może przyjmować wartości:
- 0 - Zamówienie do dostawcy,
- 1 - Przyjęcie zewnętrzne,
- 2 - Przychód wewnętrzny.
/document-numbers?IncludeAllTypes=false&Types=1

Kolejnymi danymi są materiały oraz stawki VAT, pobierane z adresów odpowiednio „materials” oraz „tax-rates”.
W przypadku stawek VAT nie jesteśmy w stanie filtrować widoku, dlatego pobrać trzeba wszystkie stawki znajdujące się w systemie.

/materials?IncludeAllId=false&IdList=101
/tax-rates

Po pobraniu wszystkich danych możemy przejść do przesłania metodą POST awizacji przyjęcia poprzez adres „delivery-documents”.

W poniższym przykładzie dla większej przejrzystości zostały wpisane dane, które nie muszą być uzupełniane. Dla sekcji, takich jak: supplier, material, unit, taxrate, document-number, currency wystarczy jedynie podanie id.

/delivery-documents
{"Selected":false,
"Number":"PZ/2021/4",
"IssueDate":"2021-03-08T11:23:14.08771+01:00",
"PlannedDate":"2021-03-08T11:23:14.08771+01:00",
"DocumentStatus":0,
"DocumentType":0,
"Supplier":{
    "Reference":"Andrzej Lenkowski Weaver Software",
    "NameLine1":"Andrzej Lenkowski Weaver Software",
    "CompanyDetail":{
        "Nip":"7861654557"
    },
    "Id":1
    },
"Positions":[{
    "PlannedQuantity":2.0,
    "Material":{
        "Reference":"MAT1",
        "Name":"Testowy",
        "Id":101
    },
    "NetUnitPrice":0.0,
    "Unit":{
        "Description":"szt.",
        "Id":1
    },
    "TaxRate":{
        "Value":0.23000,
        "Id":11
    },
    "Status":0,
    "Orgin":0,
    "NetUnitPriceInCurrency":55.0,
    "Page":0,
    "PositionOrder":0,
    "No":0,
    "Id":-1
}],
"Owner":{
    "Reference":"Andrzej Lenkowski Weaver Software",
    "IsOwner":true,
    "Id":1
 },
"DocumentNumber":{
    "DocumentType":1,
    "DocumentName":"PZ",
    "Number":3,
    "Next":"PZ/2021/4",
    "Id":3
},
"Currency":{
    "Symbol":"PLN",
    "Name":"PLN",
    "Id":1
},
"Id":0}

Pobranie zrealizowanych dokumentów przyjęcia

W celu pobrania dokładnych danych dotyczących zrealizowanych dokumentów PZ należy najpierw pobrać dane z adresu „delivery-documents”.

/delivery-documents

Dzięki tej operacji uzyskamy listę dokumentów przyjęć wraz z ich statusami.

O statusie mówi nam parametr "documentStatus" i wyróżniamy w nim wartości:
- 0 - Oczekujący na realizację,
- 15 - Anulowany,
- 20 - W trakcie realizacji,
- 30 - Zrealizowany.

W tej chwili znamy już ID zrealizowanych dokumentów przyjęć, dlatego możemy przejść do adresu „delivery-documents/position-items” i filtrować go parametrami „IncludeAllDocuments” oraz „Documents”, w których wpisujemy odpowiednio „false” oraz ID dokumentu.

/delivery-documents/position-items?IncludeAllDocuments=false&Documents=105

Przekazanie awizacji wydania

W celu przekazania awizacji wydania schemat różni się jedynie tym, że zamiast dostawcy, pobrać należy odbiorcę z adresu „recipients”.

Podczas pobierania numeracji dla dokumentów wydania użyjemy dla parametru „Types” inne wartości.

Parametr "Types" dla wydań przyjmuje wartości:
- 3 - Zamówienia od odbiorców,
- 4 - Wydania zewnętrzne,
- 5 - Rozchody wewnętrzne.
/shipping-documents
{
"Number":"WZ/2021/2",
"IssueDate":"2021-03-08T13:18:05.2976294+01:00",
"PlannedDate":"2021-03-08T13:18:05.2976294+01:00",
"Status":0,
"Recipient":{
    "Reference":"Andrzej Lenkowski Weaver Software",
    "NameLine1":"Andrzej Lenkowski Weaver Software",
    "CompanyDetail":{
        "Nip":"7861654557"
    },
    "Id":1
},
"Positions":[{
    "PlannedQuantity":10.0,
    "Material":{
        "Reference":"MAT1",
        "Name":"Testowy",
        "Id":101
    },
    "NetUnitPriceBeforeDiscount":150.0,
    "Unit":{
        "Description":"szt.",
        "Id":1
    },
    "TaxRate":{
        "Value":0.23000,
        "Id":11
    },
    "Status":0,
    "PositionOrder":0,
    "Id":-1
    }],
"Currency":{
    "Symbol":"PLN",
    "Id":1
},
"ShippingAddress":{
    "Name":"Weaver Software ",
    "Street":"os. Piastowskie 53",
    "PostalCode":"63-000",
    "City":"Środa Wielkopolska",
    "ContactPerson":"Bartosz Walerowicz",
    "PhoneNumber":"690042333",
    "Email":"support@weaversoft.pl",
    "Country":{
        "Name":"Polska",
        "Id":1
    },
    "Id":1
},
"DocumentNumber":{
    "DocumentType":4,
    "DocumentName":"WZ",
    "Number":1,
    "ActualPattern":"[Nazwa]/[Rok]/[Numer]",
    "Next":"WZ/2021/2",
    "Id":12
}
}

Pobieranie dokumentów WZ

Na poniższym przykładzie pobieramy dokumenty WZ z zaznaczonym filtrem (utworzone po dacie 01.09.2020r.) oraz podzielone na 2 elementy na stronę.

Pobieranie jednostek logistycznych dla właściciela

Żeby pobrać wszystkich dostawców, którzy mogą być właścicielami, trzeba użyć adresu „suppliers” z parametrem „IsOwner”.

/suppliers?IsOwner=true

W celu pobrania jednostek logistycznych przypisanych do konkretnego właściciela należy użyć adresu „logistic-units” z parametrami „IncludeAllOwners” oraz „Owners”, w których wpisujemy odpowiednio „false” i ID właściciela.

/logistic-units?IncludeAllOwners=false&Owners=1