Wprowadzenie


W tej sekcji dowiesz się jak korzystać z API zintegrowanego z zewnętrznym systemem BMS - Business Management System.


KORZYSTANIE Z INTERFEJSU API

W tym miejscu opisaliśmy w skrócie z czego składa się dokumentacja którą podzieliliśmy na 4 główne obszary:

Pierwsze kroki

Aktualną wersję API znajdziesz pod adresem https://integrator.over-bms.com


Dane integratora bazują na dokumentach JSON. API napisane jest na zasadzie REST. Każdy zasób posiada swoją oddzielną kolekcje historii przesyłanych danych wraz z godziną oraz wszystkimi polami.


Integrator działa w taki sposób że po wysłaniu paczki nowych/edytowanych zasobów zapisuje je w kolekcji historii. Kolejny request pobierający ten zasób, pobiera wszystkie nowe/edytowane po dacie ostatniej historii.


Aby korzystać z ENDPOINT API, wymagany jest token autoryzujący. Klucz autoryzujący jest ważny 30 min. Po tym czasie trzeba wygenerować nowy klucz.


Interfejs API umożliwia wymiane danych między systemami takie jak:

  • Pobieranie oraz aktualizacja produktów
  • Pobieranie oraz aktualizacja klientów
  • Pobieranie zamówień
  • Dodawanie faktur
  • Pobieranie oraz aktualizacja stanów magazynowych oraz dokumentów MM

Dostępne wersje API

Wersja Data utworzenia Zmiany
1.3 2021-03-24 Dodanie multi-warianty przy produkcie
1.2 2020-07-20 Dodanie ENDPOINT-u do pobiernia zamówień w dowolym zakresie poza historią
1.1 2020-02-15 Rozbudowa zakresu przesyłanych danych.
1.0 2018-12-01 Wymiana wszystkich dostępnych zasobów takich jak produkty, klienci, zamówienia, faktury, magazyny oraz stany

Punkty końcowe

Punkt końcowy Metoda Zastosowanie
/application/login GET Metoda zwraca token autoryzacyjny ważny przez 30 min
/product/product GET Metoda zwraca tablicę wszystkich nowych oraz edytowanych produktów od daty ostatniego pobierania danych produktowych
/product/product POST Metoda przyjmuje tablicę produktów do dodania lub edycji
/company/company GET Metoda zwraca tablicę wszystkich nowych oraz edytowanych klientów od daty ostatniego pobierania danych klientów
/company/company POST Metoda przyjmuje tablicę klientów do dodania lub edycji
/order/order GET Metoda zwraca tablicę wszystkich nowych zamówień od daty ostatniego pobierania
/invoice/invoice POST Metoda przyjmuje tablicę faktur do dodania lub edycji
/warehouse/warehouse POST Metoda przyjmuje tablicę magazynów wraz z produktami i ich stanami do dodania lub edycji
/warehouse/state POST Metoda przyjmuje tablicę dokumentów MM wraz z przesuniętymi produktami i ich stanami do dodania

Zapoznaj się z naszym Interfejsem API.


Jeżeli potrzebujesz pomocy, zajrzyj jeszcze do działu pierwsze kroki, aby dowiedzieć się wiecej o korzystaniu z tego interfejsu API.

Poniżej znajduje się dokumentacja wymiany danych podzielona na poszczególne zasoby:


GET
Autoryzacja dostępu do Interfejsu API
Autoryzacja użytkownika

Poniższe żądanie autoryzuje użytkownika. Po poprawnym zautoryzowaniu zwraca token zawiarający dostęp do danych aplikacji. Parametry wymagane to login oraz hasło przekazane w nagłówku żądania.


#Headers
Parametr typ Opis
login string [required] Login do autoryzacji użytkownika z dostępem do interfejsu API
password string [required] Hasło zgodnę z loginem użytkownika
#Url

https://integrator.over-bms.com/application/login

#Method

GET

#Params

Brak

#Other params

Brak

Żądanie do serwera:

                                            
connection →keep-alive
content-length →352
content-type →application/json; charset=utf-8
date →Wed, 05 Dec 2018 13:15:41 GMT
etag →W/"160-cnA+cWHXr/OTDtLYcY9+iQcr9Tg"
x-powered-by →Express

Poprawna odpowiedź serwera [200]

                                            
{
    "success": true,
    "token": "token autoryzujący dołączany do każdego requestu"
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracany token jest ważny przez 30 min od momentu poprawnej autoryzacji, w celu odświeżenia tokenu, wymagana jest ponowna autoryzacja
GET
Lista dodanych oraz zaktualizowanych produktów
Pobieranie listy produktów dodanych lub edytowanych

Poniższe żądanie pobiera listę produktów dodanych oraz zaktualizowanych. Interfejs API po zwróceniu listy produktów zapisuje w historii datę ostatniego pobierania danych. Kolejne żądanie zwróci produkty dodane oraz zaktualizowane po dacie ostatniego poberania danych.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/product/product

#Method

GET

#Params

Brak

#Other params

Parametry produktów

Żądanie do serwera:

                                            
connection →keep-alive
content-length →352
content-type →application/json; charset=utf-8
date →Wed, 05 Dec 2018 13:15:41 GMT
etag →W/"160-cnA+cWHXr/OTDtLYcY9+iQcr9Tg"
x-powered-by →Express

Poprawna odpowiedź serwera z wynikami [200]

                                            
{
    "success": true,
    "documents": [
        {
            "_id": "5bd30aa2f2475774bf3d59b6",
            "createdAt": "2018-10-26T09:38:02.990Z",
            "name": {
                "pl": "Sok bananowy 300 ml"
            },
            "active": true,
            "categories": [],
            "variants": [
                {
                    "_id": "5c03d4bd3293670563ce4580",
                    "name": {
                        "pl": "Sok bananowy 300 ml"
                    },
                    "subProducts": [],
                    "converters": [
                        {
                            "_id": "5c05016b17377ba6262498b1",
                            "createdAt": "2018-12-03T10:11:55.000Z",
                            "unit": "l",
                            "value": 0.3
                        }
                    ],
                    
                    "description": "",
                    "priceCurrency": {
                        "PLN": 14.0
                    },
                    "bindingId": "34324",
                    "foreignId": "101 SOK BANANOWY 300 ML",
                    "logisticMinimum": 0,
                    "ean": "5907632637138",
                    "pkwiu": "10.32.17.0"
                }
            ],
            "updatedAt": "2018-12-02T12:49:01.134Z",
            "productID": "101 SOK BANANOWY 300 ML",
            "description": {
                "pl": ""
            },
            "type": 1,
            "unit": "500",
            "tax": "8"
        }
    ]
}

Poprawna odpowiedź serwera bez wyników [200]

                                            
{
    "success": true,
    "documents":  null
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
POST
Dodawanie oraz edycja produktów
Dodawanie/aktualizowanie produktów

Poniższe żądanie dodaje oraz aktualizuje produkty dla wielu pojedyńczego wariantu. Kluczem wiążącym produkt jest bindingId oraz foreignId. Interfejs API po tych kluczach rozpoznaje produkt oraz następnie aktualizuje go wraz z wariantem.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/product/product

#Method

POST

#Params
Parametr typ Opis
name string [required] Nazwa produktu
type number [required] Typ produktu. Wartość osłownikowana. Przykład (Artykuł - 1, Usługa - 2, Gratis - 3)
active number [required] Status produktu definiuje czy produkt jest aktywny czy nieaktywny w systemie. Tzw. produkt "wyłaczony" ze sprzedaży.
ean string Kod ean produktu
pkwiu string Kod pkwiu produktu
bindingId string [required] Klucz obcy produktu - klucz wiążący z systemem zewnętrznym
foreignId string [required] Kod produktu
priceCurrency object [required] Cena jednostkowa produktu z podziałem na waluty
tax string [required] Wartość podatku na dany produkt
unit string [required] Jednostka produktowa. (Kilogram - 100, Gram - 101, Tona - 102, Litr - 200, DM3 - 201, M3 - 202, M2 - 300, CM2 - 301, Metr - 400, Centymetr - 401, Sztuka - 500)
description string [opcjonal] Opis produktu
logisticMinimum string [opcjonal] Minimum logistyczne na magazynie. To informacja dla produkcji która przy poniżej (min) stanu logistycznego zaczyna produkcje danego produktu
purchasePrice float/double [opcjonal] Cena zakupu
#Other params

Parametry pól produktów

Żądanie do serwera:

                                            
[{
   "name":"Sok porzeczkowy 300 ml", 
   "type":1,
   "active":1,
   "ean": "5875945849994",
   "pkwiu": "1.234.34.5",
   "bindingId":"586766",
   "foreignId": "101 SOK PORZECZKOWY 330",
   "priceCurrency":{
      "PLN":22
   },
   "tax": "23",
   "description":"Sok porzeczkowy, zagęszczony 100%",
   "unit":500,
   "logisticMinimum":150,
   "purchasePrice": 29.20
}]

Poprawna odpowiedź serwera z wynikami [200]

                                            
{
    "success": true,
    "inserted": 1, // ilość rekordów dodanych/zaktualizowanych
    "errors": null // błędy dotyczące poszczególnych produktów
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych produktów. Produkty w sekcji "errors" nie są aktualizowane w systemie.
POST
Dodawanie oraz edycja produktów (dla wielu wariantów)
Dodawanie/aktualizowanie produktów (dla wielu wariantów)

Poniższe żądanie dodaje oraz aktualizuje produkty dla wielu wariantów. Kluczem wiążącym produkt jest bindingId oraz foreignId. Interfejs API po tych kluczach rozpoznaje produkt oraz następnie aktualizuje go wraz z wariantami które do niego należą


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/product/product

#Method

POST

#Params
Parametr typ Opis
name string [required] Nazwa produktu
type number [required] Typ produktu. Wartość osłownikowana. Przykład (Artykuł - 1, Usługa - 2, Gratis - 3)
active number [required] Status produktu definiuje czy produkt jest aktywny czy nieaktywny w systemie. Tzw. produkt "wyłaczony" ze sprzedaży.
ean string Kod ean produktu
pkwiu string Kod pkwiu produktu
bindingId string [required] Klucz obcy produktu - klucz wiążący z systemem zewnętrznym
foreignId string [required] Kod produktu
priceCurrency object [required] Cena jednostkowa produktu z podziałem na waluty
tax string [required] Wartość podatku na dany produkt
unit string [required] Jednostka produktowa. (Kilogram - 100, Gram - 101, Tona - 102, Litr - 200, DM3 - 201, M3 - 202, M2 - 300, CM2 - 301, Metr - 400, Centymetr - 401, Sztuka - 500)
description string [opcjonal] Opis produktu
logisticMinimum string [opcjonal] Minimum logistyczne na magazynie. To informacja dla produkcji która przy poniżej (min) stanu logistycznego zaczyna produkcje danego produktu
purchasePrice float/double [opcjonal] Cena zakupu
variants array [required] Dane wariantów należące do danego produktu
#Other params

Parametry pól produktów

Żądanie do serwera:

                                            
[{
   "name":"KRZESŁO KR44", 
   "description":"Krzesło 120x50",
   "type":1,
   "unit":500,
   "tax": "23",
   "active":1,
   "bindingId":"4444-1",
   "foreignId": "PRODUCT-4444-1",
   "variants" : [{
        "name":"KRZESŁO KR44",
        "description":"Krzesło 120x50",
        "bindingId": "4444-1",
        "foreignId":"PRODUCT-4444-1",
        "logisticMinimum":150,
        "ean": "5875945849994",
        "pkwiu": "1.234.34.5",
        "purchasePrice": 100,
        "priceCurrency":{
            "PLN":140
        }
   },
   {
        "name":"KRZESŁO KR44 BIAŁE",
        "description":"Krzesło 120x50 białe",
        "bindingId": "4444-2",
        "foreignId":"PRODUCT-4444-2",
        "logisticMinimum":150,
        "ean": "5875945849995",
        "pkwiu": "1.234.34.44",
        "purchasePrice": 100,
        "priceCurrency":{
            "PLN":120
        }
   }, 
   {
        "name":"KRZESŁO KR44 CZERWONE",
        "description":"Krzesło 120x50 czerwone",
        "bindingId": "4444-3",
        "foreignId":"PRODUCT-4444-3",
        "logisticMinimum":150,
        "ean": "5875945849997",
        "pkwiu": "1.234.34.78",
        "purchasePrice": 100,
        "priceCurrency":{
            "PLN":180
        }
   },
   {
        "name":"KRZESŁO KR44 NIEBIESKIE",
        "description":"Krzesło 120x50 niebieskie",
        "bindingId": "4444-4",
        "foreignId":"PRODUCT-4444-4",
        "logisticMinimum":150,
        "ean": "5875945849999",
        "pkwiu": "1.234.34.22",
        "purchasePrice": 122,
        "priceCurrency":{
            "PLN":180
        }
   },
   {
        "name":"KRZESŁO KR44 POMARAŃCZOWE",
        "description":"Krzesło 120x50 pomaranczowe",
        "bindingId": "4444-5",
        "foreignId":"PRODUCT-4444-5",
        "logisticMinimum":150,
        "ean": "5875945849966",
        "pkwiu": "1.234.34.52",
        "purchasePrice": 122,
        "priceCurrency":{
            "PLN":155
        }
   }]
}]

Poprawna odpowiedź serwera z wynikami [200]

                                            
{
    "success": true,
    "inserted": 1, // ilość rekordów dodanych/zaktualizowanych
    "errors": null // błędy dotyczące poszczególnych produktów
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych produktów. Produkty w sekcji "errors" nie są aktualizowane w systemie.
GET
Lista dodanych oraz zaktualizowanych klientów
Pobieranie listy klientów dodanych oraz edytowanych

Poniższe żądanie pobiera listę klientów dodanych oraz zaktualizowanych. Interfejs API po zwróceniu listy klientów zapisuje w historii datę ostatniego pobierania danych. Kolejne żądanie zwróci klientów dodanych oraz zaktualizowanych po dacie ostatniego pobierania danych.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/company/company

#Method

GET

#Params

Brak

#Other params

Parametry pól klienta

Żądanie do serwera:

                                            
connection →keep-alive
content-length →352
content-type →application/json; charset=utf-8
date →Wed, 05 Dec 2018 13:15:41 GMT
etag →W/"160-cnA+cWHXr/OTDtLYcY9+iQcr9Tg"
x-powered-by →Express

Poprawna odpowiedź serwera z wynikami [200]

                                            
{
    "success": true,
    "documents": [
         {
            "_id": "5c0288683293670563c4d406",
            "createdAt": "2018-11-16T10:08:40.726Z",
            "active": true,
            "phones": [
                {
                    "createdAt": "2018-12-03T14:25:37.610Z",
                    "_id": "5c05671cf99119ae5c6fd526",
                    "description": "",
                    "type": "2",
                    "number": "111-222-333"
                }
            ],
            "addresses": [
                {
                    "_id": "5c05671cf99119ae5c6fd53b",
                    "createdAt": "2018-12-03T14:25:37.610Z",                            
                    "type": 4,
                    "route": "Konstantynowska 34",
                    "country": "Polska",
                    "administrative_area_level_1": "łódzkie",
                    "administrative_area_level_3": "Łódź",
                    "locality": "Łódź",
                    "postal_code": "94-303",
                    "street_number": "34",
                    "formatted_address": "Konstantynowska 34, Łodź, Polska",
                    "coordinates": [], 
                }
            ],
            "updatedAt": "2018-12-03T17:25:48.694Z",
            "name": "Testowy klient 1",
            "description": "",
            "vatNumber": "",
            "bindingId": "55466",
            "foreignId": "testowy_klient_1",
            "groups": [],
            "email": "testowy_klient@gmail.com",
            "formOfPayment": 1
        }
    ]
}

Poprawna odpowiedź serwera bez wyników [200]

                                            
{
    "success": true,
    "documents":  null
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
POST
Dodawanie/aktualizowanie klientów
Dodawanie/aktualizowanie klientów

Poniższe żądanie dodaje oraz aktualizuje klientów. Kluczem wiążącym klienta jest bindingId oraz foreignId. Interfejs API po tych kluczach rozpoznaje klienta oraz następnie aktualizuje go bądź dodaje jeżeli go nie odnajdzie.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/company/company

#Method

POST

#Params
Parametr typ Opis
name string [required] Nazwa klienta
active number [required] Status klienta definiuje czy klient jest aktywny czy nieaktywny w systemie.
foreignId string [required] Kod klienta
bindingId string [required] Klucz obcy klienta - klucz łączący z systemu zewnętrznego
phones array [opcjonal] Dodatkowe telefony klienta w postaci tablicy z obiektami. Obiekt pojedyńczego telefonu posiada dodatkowe pola takie jak (description, type, number). Typy telefonu (Prywatny - 1, Firmowy - 2, Fax - 3)
addresses array [required] Adresy klienta w postaci tablicy z obiektami. Pojedyńczy obiekt posiada typ adresu (Domowy - 1, Firmowy - 2, Magazyn - 3, Główny - 4)
vatNumber string [opcjonal] NIP klienta
email string [opcjonal] Adres mailowy klienta
description string [opcjonal] Opis klienta
formOfPayment number [opcjonal] Forma płatności ze słownika np. (Przelew 7 dni - 1, Przelew 14 dni - 2, Gotówka- 3)
#Other params

Parametry pól klienta

Żądanie do serwera:

                                            
[  
   {  
      "name":"JAK KOWALSKI SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
      "description":"osoba decyzyjna - Mirosław Klamka",
      "active":true,
      "vatNumber":"8898878787",
      "email":"",
      "bindingId": "45666", 
      "foreignId":"JAN_KOWALSKI_SPOLKA_ZOO",
      "formOfPayment": 1,
      "phones":[  
         {  
            "description":"Telefon z bazy REGON",
            "type":2,
            "number":"12345678"
         },
         {  
            "description":"Telefon z bazy REGON",
            "type":2,
            "number":"87653421"
         }
      ],
      "addresses":[  
         {  
            "route":"Konstantynowska",
            "country":"Polska",
            "administrative_area_level_1":"Łódzkie",
            "administrative_area_level_2":"Łódź",
            "administrative_area_level_3":"Łódź",
            "locality":"Łódź",
            "postal_code":"94-303",
            "street_number":"34",
            "type": 4,
            "formatted_address":"Konstantynowska 34, Łódź, Polska"
         }
      ]
   }
   ]

Poprawna odpowiedź serwera [200]

                                            
{
    "success": true,
    "inserted": 1, // ilość rekordów dodanych/zaktualizowanych
    "errors": null // błędy dotyczące poszczególnych produktów
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych klientów. Klienci w sekcji "errors" nie są aktualizowane w systemie.
GET
Lista dodanych zamówień
Pobieranie zamówień

Poniższe żądanie pobiera listę zamówień dodanych oraz zaktualizowanych. Interfejs API po zwróceniu listy zamówień zapisuje w historii datę ostatniego pobierania danych. Kolejne żądanie zwróci produkty dodane oraz zaktualizowane po dacie ostatniego pobierania danych.


Aby pobrać zamówienia poza [historią] wysyłamy żądanie na adres /order/order [GET] przekazując następujące parametry do wyboru:

  • createdAt[gte] - timestamp (od daty)
  • createdAt[lte] - timestamp ( do daty)
  • offset - (zacznij od elementu)
  • sort[nazwa_pola] - obsługuje wartości -1 i 1 (asc, desc)
  • select - pola do pobrania w dokumencie
  • _id - indentyfikator zasobu

Jeżeli do parametrów dodamy _id, to system szuka tylko tego rekordu o danym indentyfikatorze(reszta parametrów nie ma znaczenia). Jeżeli natomiast do żądania /order/order dojdą jakiekolwiek parametry wyżej wymienione, wtedy limit rekordów to 100. Nie da się go zwiększyć. Trzeba operować offsetem.

Przykład:

Czyli jeżeli z danego zakresu dat mamy 1200 rekordów to puszczamy kolejno offsety, 0, 100, 200 itd.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/order/order

#Method

GET

#Params

Brak

#Other params

Parametry pól zamówienia

Żądanie do serwera:

                                            
connection →keep-alive
content-length →352
content-type →application/json; charset=utf-8
date →Wed, 05 Dec 2018 13:15:41 GMT
etag →W/"160-cnA+cWHXr/OTDtLYcY9+iQcr9Tg"
x-powered-by →Express

Poprawna odpowiedź serwera z wynikami [200]

                                            
{
    "success": true,
    "documents":  [
        {
            "_id": "5c067a0d17377b4e0b4c4a98",
            "createdAt": "2018-12-04T12:58:53.000Z",
            "products": [
                {
                    "unitPriceNetto": 2.95,
                    "discount": 1,
                    "unitPriceDiscountedNetto": 2.95,
                    "tax": "5",
                    "amount": 12,
                    "priceNetto": 35.4,
                    "priceBrutto": 37.17,
                    "name": "Sok bananowy 300ml",
                    "description": null,
                    "foreignId": "sok_bananowy_300ml",
                    "unit": "500",
                    "type": "1",
                    "pkwiu": "10.10.22.334",
                    "ean": "898787876",
                    "logisticMinimum": 260
                }
            ],
            "cashPayment": false,
            "contractor": "jan_kowalski",
            "customer": "testowy_klient",
            "recipient": {
                "address": {
                    "_id": "5c067a0d17377b4e0b4c4aaf",
                    "createdAt": "2018-12-04T12:58:53.000Z",
                    "likes": [],
                    "type": 4,
                    "route": "Konstantynowska",
                    "country": "Polska",
                    "administrative_area_level_1": "łódzkie",
                    "administrative_area_level_3": "Łódź",
                    "locality": "Łódź",
                    "postal_code": "94-303",
                    "street_number": "34",
                    "formatted_address": "Konstantynowska 34, Łódź, Polska"
                }
            },
            "warehouse": "MGC"
        }
    ]
}

Poprawna odpowiedź serwera bez wyników [200]

                                            
{
    "success": true,
    "documents":  null
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych produktów. Produkty w sekcji "errors" nie są aktualizowane w systemie.
POST
Dodawanie oraz edycja faktur
Dodawanie/aktualizowanie faktur

Poniższe żądanie dodaje oraz aktualizuje faktury. Kluczem wiążącym fakturę jest jej numer. Interfejs rozpoznaje fakturę i w zależności od tego czy faktura instnieje w systemie dodaje ją lub aktualizuje.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/order/order

#Method

POST

#Params
Parametr typ Opis
type number [required] Typ faktury. (VAT - 1, PARAGON - 2, KOREKTA - 3)
status number [required] Status faktury (Zapłacona - 1 , niezapłacona - 2, anulowana - 3)
number string [required] Numer faktury
saleDate number (TIMESTAMP) [required] Data sprzedaży
leftToPay float,double [opcjonal] Pozostało do zapłaty
issueDate number (TIMESTAMP) [required] Data wydania towaru
paymentForm number [required] Typ płatności. (Gotówka - 1, Przelew - 2)
customer string [required] Klucz obcy klienta - klucz wiążący z systemem zewnętrznym
products array [required] Tablica produktów w formie obiektów. Pojedyńczy obiekt produktu zawiera wymagane pole bindingId (klucz wiążący produkty między systemami) oraz opcjonalne pole foreignId (kod produktu).
contractor string [required] Klucz obcy handlowca (składającego zamówienie) - klucz wiążący z systemem zewnętrznym
recipient object [opcjonal] Adres odbioru zamówienia
#Other params

Parametry pól faktury

Żądanie do serwera:

                                            
[
  {
    "type": 1,
    "status": 1,
    "number": "2018-FVS/0001/BOK",
    "saleDate": "2018-12-01 00:00:00.000",
    "issueDate": "2018-12-01 00:00:00.000",
    "paymentForm": 1,
    "contractor": "jan_kowalski",
    "customer": "testowy_klient",
    "leftToPay" : "123.45",
    "recipient" : {
    	"address":  { 
        "createdAt": "2017-01-14T09:00:03.000Z",
        "type": 4,
        "country": "Polska",
        "administrative_area_level_1": "łódzkie",
        "administrative_area_level_2": "Łódź",
        "administrative_area_level_3": "Łódź",
        "locality": "Konstantynowska",
        "street_number": "34",
        "postal_code": "94-303",
        "formatted_address": "Konstantynowska 34, Łódź, Polska"
        }
    },
    "products": [
        {
            "bindingId": "878787",
            "foreignId": "SOK_BANANOWY_300_ML",
            "unitPriceNetto": 10,
            "priceNetto": 100,
            "priceBrutto": 123,
            "amount": 10,
            "tax": 23,
            "taxValue": 23,
            "importedUnitPriceNetto": 10,
            "discount": 1
        },
        {
            "bindingId": "67788",
            "foreignId" : "SOK_WISNIOWY_100_ML",
            "unitPriceNetto": 10,
            "priceNetto": 100,
            "priceBrutto": 123,
            "amount": 10,
            "tax": 23,
            "taxValue": 23,
            "importedUnitPriceNetto": 10,
            "discount": 1
        }
    ]
  }
]

Poprawna odpowiedź serwera z wynikami [200]

                                            
{
    "success": true,
    "inserted": 1, // ilość rekordów dodanych/zaktualizowanych
    "errors": null // błędy dotyczące poszczególnych produktów
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych faktur. Faktury w sekcji "errors" nie są aktualizowane w systemie.
POST
Dodawanie oraz edycja stanów magazynowych
Dodawanie/aktualizowanie magazynów

Poniższe żądanie dodaje oraz aktualizuje magazyny. Kluczem wiążącym magazyn jest jej klucz obcy (foreignId). Interfejs rozpoznaje magazyn i w zależności od tego czy magazyn instnieje w systemie dodaje go lub aktualizuje stan magazynowy.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/warehouse/warehouse

#Method

POST

#Params
Parametr typ Opis
name string [required] Nazwa magazynu
fereignId string [required] klucz obcy magazynu - wiążący magazyn z system zewnętrznym
products array [required] Tablica obiektów produktów składająca się z ilości (amount) oraz klucza wiążącego produkt z systemem zewnętrznym (foreignId)
#Other params

Parametry pól magazynów

Żądanie do serwera:

                                            
[
    {
    	"name":"Magazyn główny - ŁÓDŹ",
    	"foreignId":"MAG",
    	"products":[
    		{
    			"foreignId":"sok_bananowy_30ml",
    			"amount":10
    			
    		}
    	]
    }
]

Poprawna odpowiedź serwera [200]

                                            
{
    "success": true,
    "inserted": 1, // ilość rekordów dodanych/zaktualizowanych
    "errors": null // błędy dotyczące poszczególnych produktów
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych magazynów. Magazyny w sekcji "errors" nie są aktualizowane w systemie.
POST
Dodawanie dokumentów MM (przesunięcia magazynowe)
Dodawanie dokumentów MM

Poniższe żądanie dodaje dokumenty MM (przesunięcia magazynowe). Interfejs dodaje dokument przesunięcia magazynowego. Kluczem wiążącym jest foreignId w warehouseFrom oraz warehouseTo.


#Headers
Parametr typ Opis
token string [required] Token autoryzujący, zwracany podczas autoryzacji użytkownika
#Url

https://integrator.over-bms.com/warehouse/state

#Method

POST

#Params
Parametr typ Opis
warehouseFrom object [required] Obiekt magazynu zawierający klucz obcy magazynu - wiążący magazyn z system zewnętrznym
warehouseTo object [required] Obiekt magazynu zawierający klucz obcy magazynu - wiążący magazyn z system zewnętrznym
transferedProducts array [required] Tablica obiektów produktów wraz z kluczem obcym produktu oraz ilością przesuniętą między magazynami
#Other params

Parametry pól MM

Żądanie do serwera:

                                            
[  
    {
    	"warehouseFrom": {
    	"foreignId" : "MAG"
    	},
        "warehouseTo": {
    	"foreignId" : "MAG_LODZ"
    	},
	"transferedProducts" : [
		{
                    "foreignId" : "sok_bananowy_300ml",
                    "amount" : "10"
		},
		{
                    "foreignId" : "sok_wisniowy_100ml",
                    "amount" : "20"
		}
	]
    }
]

Poprawna odpowiedź serwera [200]

                                            
{
    "success": true,
    "inserted": 1, // ilość rekordów dodanych/zaktualizowanych
    "errors": null // błędy dotyczące poszczególnych produktów
}

Niepoprawna odpowiedź serwera [401]

                                            
{
    "success": false
}
Zwracane { errors: null } dotyczą poszczególnych MM (przesunięć magazynowych). MM w sekcji "errors" nie są aktualizowane w systemie.

Opis pól


Interfejs API zwraca poniższe pola dla pojedyńczych zasobów.


POLA DLA ZASOBU PRODUKTY

Nazwa pola Typ Opis
name object Główna nazwa produktu zwracana jako obiekt przetrzymujący nazwy dla różnych języków
createdAt string Data utworzenia produktu np. (2019-05-10 10:15:42.304Z)
updatedAt string Data edycji produktu np. (2019-05-10 10:15:42.304Z)
type number Typ produktu. Wartość osłownikowana. Przykład (Artykuł - 1, Usługa - 2, Gratis - 3)
active boolean Status produktu defniuje czy produkt jest aktywny czy nieaktywny tzw. dostępny w sprzedaży
foreignId string Kod produktu
bindingId string Klucz obcy produktu - klucz wiążący z systemem zewnętrznym
priceCurrency object Cena produktu dla danej waluty
tax string Wartość podatku
description string Opis produktu
unit string Jednostka produktowa. (Kilogram - 100, Gram - 101, Tona - 102, Litr - 200, DM3 - 201, M3 - 202, M2 - 300, CM2 - 301, Metr - 400, Centymetr - 401, Sztuka - 500)
logsiticMinimum string Minimum logistyczne na magazynie. To informacja dla produkcji która przy poniżej (min) stanu logistycznego zaczyna produkcje danego produktu
purchasePrice double Cena zakupu produktu
ean string Kod ean produktu
pkwiu string Kod pkwiu produktu
variants array Warianty produktowe

POLA DLA ZASOBU KLIENCI

Nazwa pola Typ Opis
name string Nazwa klienta
description string Opis klienta
vatNumber string Numer VAT klienta
formPayment number Typ formy płatności. Wartość osłownikowana (dynamicznie)
active boolean Status klienta defniuje czy klient jest aktywny czy nieaktywny tzw. dostępny w realizacji sprzedaży
email string Mail główny klienta
foreignId string Kod klienta
bindingId string Klucz obcy klienta - klucz wiążący z systemem zewnętrznym
emails array Dodatkowe maile klienta w postaci tablicy z obiektami. Obiekt pojedyńczego adresu mail posiada dodatkowe pola takie jak (type, address). Typy maili (Prywatny - 1, Firmowy - 2, Dodatkowy do zamówień - 3)
phones array Dodatkowe telefony klienta w postaci tablicy z obiektami. Obiekt pojedyńczego telefonu posiada dodatkowe pola takie jak (description, type, number). Typy telefonu (Prywatny - 1, Firmowy - 2, Fax - 3)
addresses array Adresy klienta w postaci tablicy z obiektami. Pojedyńczy obiekt posiada typ adresu (Domowy - 1, Firmowy - 2, Magazyn - 3, Główny - 4)
formOfPayment number Forma płatności ze słownika np. (Przelew 7 dni - 1, Przelew 14 dni - 2, Gotówka- 3)

POLA DLA ZASOBU ZAMÓWIEŃ

Nazwa pola Typ Opis
createdAt string Data utworzenia zamówienia np. (2019-05-10 10:15:42.304Z)
products array Tablica produktów z zamówienia
cashPayment boolean Czy klient płacił gotówką (true/false)
contractor string Klucz obcy handlowca (osoby składającej zamówienie) - klucz wiążący z systemem zewnętrznym
customer string Klucz obcy klienta (na zamówieniu) - klucz wiążący z systemem zewnętrznym
recipient object Adres odbioru zamówienia
warehouse string Klucz obcy magazynu (wybranego w zamówieniu) - klucz wiążący z systemem zewnętrznym

POLA DLA ZASOBU FAKTURY

Nazwa pola Typ Opis
numer string Numer faktury
status number Status płatności faktury (Zapłacona - 1, Niezapłacona - 2, Anulowana - 3)
type number Typ faktury(Faktura VAT - 1, Paragon - 2, Korekta - 3)
saleDate string Data sprzedaży na fakturze np. (2019-05-10 10:15:42.304Z)
paymentForm number Typ formy płatności (Gotówka - 1, Przelew - 2)
leftToPay float, double Wartość faktury która została do zapłaty. Np. płatności dzielone.
contractor string Klucz obcy handlowca (osoby składającej zamówienie) - klucz wiążący z systemem zewnętrznym
customer string Klucz obcy klienta (na zamówieniu) - klucz wiążący z systemem zewnętrznym
recipient object Adres odbioru zamówienia
products array Tablica produktów w formie obiektów

POLA DLA ZASOBU MAGAZYNY

Nazwa pola Typ Opis
name string Nazwa magazynu
foreignId string Klucz obcy magazynu - klucz wiążący z systemem zewnętrznym
products array Tablica produktów magazynowych ze stanami w formie obiektów

POLA DLA ZASOBU DOKUEMNTY MM

Nazwa pola Typ Opis
warehouseFrom object Obiekt z kluczem obcym magazynu z którego nastąpiło przesunięcie magazynowe
warehouseTo object Obiekt z kluczem obcym magazynu do którego nastąpiło przesunięcie magazynowe
transferedProducts array Tablica obiektów produktów wraz z kluczem obcym produktu i jego stanem

Ważne informacje końcowe

Każde zamówienie wygenerowane w systemie BMS posiada kontraktora czyli identyfikator osoby która składała dane zamówienie. Faktura która została wygenerowane w systemie zew. powinna zwracać ten identyfikator aby integrator BMS mógł przypisać odpowiednią osobę na fakturze (tutaj firma integrująca musi zastosować jakiś mechanizm który te informacje przetrzymuje i zwraca je przy fakturze).


Dodatek zew. który zintegrowany jest z integratorem BMS powienien wymieniać zasoby w kolejności:


  • Towary - w dwie strony
  • Kontrahenci - w dwie strony
  • Faktury - do systemu BMS
  • Dokumenty MM - z systemu BMS
  • Stan magazynowy do systemu BMS

Każda firma która chcę zintegrować się z systemem BMS dostaje unikalne dane autoryzacyjne wraz z instancją podglądową aby móc przetestować cały proces integracyjny.

Kontakt

Aby otrzymać pomoc lub zadać pytania dotyczące korzystania z powyższego Interfejsu API, skontaktuj się z nami pod adresem it@over-cloud.pl lub numerem telefonu 660-440-558.