-
Notifications
You must be signed in to change notification settings - Fork 26
API Dokumentacja v. 1.0
Wszystkie żądania do API wysyłamy POST-em z nagłówkiem "application/json".
Dodanie zamówienia do Subiekta do listy "Zamówienia od klientów". Wywołanie automatycznie tworzy zamówienie oraz sprawdza w bazie kontrahentów oraz towarowej czy istnieją rekordy o podanych "Symbolach". W przypadku gdy istnieje kontrahent o podanym symbolu lub NIP-ie zostaje od przypisany do zamówienia. W przypadku braku kontrahent jest automatycznie tworzony i dodawany bazy kontrahentów. W przypadku towarów również dana pozycja produktowa może zostać utworzona w przypadku jej braku lecz wymaga to ustawieniu parametru create_product_if_not_exists.
Utworzone zamówienie uruchamia rezerwację stanów magazynowych.
-
URL
order/add
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/order/add -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak comments string null nie komentarze do zamówienia reference string - tak referencja zamówienia np z systemu zewnętrznego create_product_if_not_exists boolean false nie utworzenie automatycznie produktu jeśli nie odnajdzie w bazie amount float - tak kwota zamówienia pay_type enum transfer nie rodzaj płatności za zamówienie dostępne typy
transfer:zapłacono przelewem
cart: centrum płatności kredytowych
money:zapłacono gotówką
credit:płatność z odroczonym terminemcustomer array - tak dane dotyczące klienta ref_id varchar(20) - tak symbol kontrahenta po którym szukamy lub który zostanie nadany firstname string - tak imię lastname string - tak nazwisko email string - tak email address string - tak adres address_no varchar(10) - tak numer budynku city string - tak miejscowość post_code varchar(6) - tak kod pocztowy phone string - nie numer telefonu is_company boolean - nie czy klient jest firmą company_name string - nie, (tak jeśli is_company=truenazwa firmy tax_id varchar(17) - nie, (tak jeśli is_company=trueNIP firmy products[] array(array) - tak dane dotyczące produktów code varchar(20) - tak symbol produktu ean varchar(13) - nie ean13 - dodawany do kolekcji kodów kreskowych price float - tak ostateczna cena produktu price_before_discount float - nie cena produktu przed rabatem name string - tak nazwa produktu id_store int 1 nie identyfikator magazynu subiekta z którego ma być zrobiona sprzedaż -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"comments": "Płatność: Przelew bankowy, Wysyłka: Pocztex Kurier 48",
"reference": "OTDR 5454443",
"create_product_if_not_exists": "1",
"amount": 65.5,
"pay_type": "transfer",
"customer": {
"firstname": "Katarzyna",
"lastname": "Nieznana",
"email": "[email protected]",
"address": "Smoleńska",
"address_no": "666",
"city": "Katowice",
"post_code": "40-770",
"phone": "666666666",
"ref_id": "OTDRCUST 5431884",
"is_company": false,
"company_name": "",
"tax_id": ""
},
"products": [
{
"code": "5908221340873",
"qty": "1",
"price": 56,
"price_before_discount": 56,
"name": "FJORD NANSEN Kubek termiczny LANDO silver",
"id_store": "1"
},
{
"ean": "KOSZT_WYSYLKI",
"code": "KOSZT_WYSYLKI",
"qty": 1,
"price": "9.50",
"price_before_discount": "9.50",
"name": "Koszty wysyłki",
"id_store": "1"
}
]
}
- Poprawna odpowiedź
Zwracany jest status success w przypadku jakiegokolwiek błędu jest zwracany status fail.
Uwaga - zwracane statusy błędów ze Sfery są czasami nieczytelne i trzeba sięgnąć do logu API. W logu można odczytać w jakiej linii kodu PHP nastąpił wyjątek i na podstawie tej informacji można zidentyfikować w kodzie PHP miejsce dla którego obiekt COM-owy Sfery GT rzucił wyjątek. Tak na chwilę obecną można przeprowadzić debuging i podjąć próby diagnozy problemu.
{
"state": "success",
"data": {
"order_ref": "ZK 355/01/2018"
}
}
Wywołanie wykonuje przetworzenie zamówienia na dokument sprzedaży. Jeśli kontrahentem była to osoba fizyczna jest tworzony paragon imienny PAi. W przypadku gdy kontrahentem jest firma to zamówienie zostaje przetworzone w fakturę sprzedaży FS.
Istotne jest to, że jeśli nie ma dostępnego towaru na stanie magazynowym dokument sprzedaży nie zostanie utworzony.
-
URL
order/makesaledoc
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/order/makesaledoc -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak order_ref string - tak numer zamówienia z subiekta -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"order_ref": "ZK 151/01/2018"
}
- Poprawna odpowiedź
Gdy dokument sprzedaży zostanie utworzony można się spodziewać odpowiedzi typu jak poniżej.
{
"state": "success",
"data": {
"doc_ref": "PA 233/01/2018"
}
}
- Błędna odpowiedź
W przypadku gdy zamówienie przewyższa stany dostępne magazynowe zostanie wygenerowana błędna odpowiedź przykład poniżej. Gdy towar zostanie dostarczony na odpowiedni magazyn to zamówienie wtedy może zostać przetworzone na dokument sprzedaży i zostanie zwrócona poprawna odpowiedź.
{
"state": "fail",
"message": "Nie można utworzyć dokumentu sprzedaży. Brakuje produktów na magazynie!",
"data": {
"order_ref": "ZK 151/01/2018"
}
}
Wywołanie wysyła żądanie pobrania zamówienia w postaci PDF-u. Generacja przez Subiekt i pobranie dokumentu wymaga podania numeru zamówienia. Dane PDF zakodowane w Base64.
-
URL
order/getpdf
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/order/getpdf -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak order_ref string - tak numer zamówienia z subiekta -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"order_ref": "ZK 151/01/2018"
}
Wywołanie zwraca podstawowe informację o zamówieniu.
Jest to cały obiekt API nie z Subiekta GT. Ilość danych jest ograniczona.
-
URL
order/get
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/order/get -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak order_ref string - tak numer zamówienia z subiekta -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"order_ref": "ZK 312/01/2018"
}
- Przykładowa odpowiedź
{
"state": "success",
"data": {
"products": [
{
"name": "LEKI Rękawice FUSE S MF TOUCH r.9 black",
"code": "4028173073672",
"qty": "1.0000",
"price": "415.6500"
},
{
"name": "Koszt wysyłki on-line",
"code": "KOSZT_WYSYLKI",
"qty": "1.0000",
"price": "3.0000"
}
],
"reference": "OTDR 5453343",
"comments": "Płatność: Gotówka przy odbiorze, Wysyłka: Kurier DPD",
"customer": {
"ref_id": "OTDRCUST 4673456",
"company_name": null,
"tax_id": "",
"fullname": "Monika Nieznana",
"email": "[email protected]",
"city": "Gdańsk",
"post_code": "80-865",
"address": "Smoleńska 666",
"phone": "666666666",
"is_company": false
},
"reservation": 1,
"order_ref": "ZK 312/01/2018",
"selling_doc": null,
"amount": "418.6600",
"paid_amount": 0,
"state": 7,
"date_of_delivery": {
"date": "2018-01-08 00:00:00.000000",
"timezone_type": 3,
"timezone": "Europe/Berlin"
},
"payment_comments": "",
"is_exists": true,
"gt_id": 184373
}
}
Wywołanie zwraca podstawowe statusy dokumentu typu: typ dokumentu, stan fiskalny, stan księgowy.
-
URL
document/getstate
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/document/getstate -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak doc_ref string - tak numer dokumentu z subiekta -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"doc_ref": "ZK 151/01/2018"
}
Wywołanie zwraca podstawowe podstawowe dane o dokumencie sprzedaży. Za pomocą wywołania można pobrać informację na temat paragonów, faktur zakupu oraz sprzedaży.
Jest to cały obiekt API nie z Subiekta GT. Ilość danych jest ograniczona.
-
URL
document/get
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/document/get -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak doc_ref string - tak numer dokumetu z subiekta -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"doc_ref": "FZ 3139/MAG/12/2017"
}
}
- Przykładowa odpowiedź
Gdy dokument zostanie odnaleziony w bazie Subiekta to przykładowa odpowiedź będzie wyglądać jak poniżej.
{
"state": "success",
"data": {
"products": [
{
"name": "SNOW PEAK Kubek DOUBLE WALL MUG 300 Folfing handle",
"code": "691688171597",
"qty": "1.0000",
"price": "139.3000"
},
{
"name": "SNOW PEAK Kubek DOUBLE WALL WARE H300",
"code": "691688720283",
"qty": "1.0000",
"price": "122.5100"
},
{
"name": "SNOW PEAK Pokrywka 300",
"code": "4960589171859",
"qty": "3.0000",
"price": "58.7800"
},
{
"name": "Koszty transportu",
"code": "111",
"qty": "1.0000",
"price": "20.0000"
}
],
"fiscal_state": 0,
"accounting_state": 0,
"reference": "1302/MAG/2017",
"comments": "",
"customer": {
"ref_id": "762-147-05-85",
"company_name": null,
"tax_id": "762-147-05-85",
"fullname": "Waterfall",
"email": "",
"city": "Warszawa",
"post_code": "02-797",
"address": "Klimczaka 22 D/3 ",
"phone": "",
"is_company": true
},
"doc_ref": "FZ 3139/MAG/12/2017",
"doc_type": "FZ",
"amount": "340.5900",
"state": 1,
"date_of_delivery": null,
"is_exists": true,
"gt_id": 171820
}
}
Wywołanie wysyła żądanie pobrania zamówienia w postaci PDF-u. Generacja przez Subiekt i pobranie dokumentu wymaga podania numeru zamówienia.
-
URL
document/getpdf
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/document/getpdf -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak doc_ref string - tak numer dokumentu z subiekta -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"doc_ref": "ZK 151/01/2018"
}
-
URL
product/add
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/product/add -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak code varchar(20) - tak symbol produktu ean varchar(13) - nie ean13 - dodawany do kolekcji kodów kreskowych price float - tak ostateczna cena produktu price_before_discount float - nie cena produktu przed rabatem name string - tak nazwa produktu id_store int 1 nie identyfikator magazynu subiekta z którego ma być zrobiona sprzedaż -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"name": "LEKI Rękawice FUSE S MF TOUCH r.9 black",
"code": "4028173073672",
"qty": "1.0000",
"price": "415.6500"
}
}
Aktualizacje można wykonać jedynie na nazwie, eanie, cenach.
-
URL
product/get
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/product/get -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak code varchar(20) - tak symbol produktu ean varchar(13) - nie ean13 - dodawany do kolekcji kodów kreskowych price float - tak ostateczna cena produktu price_before_discount float - nie cena produktu przed rabatem name string - tak nazwa produktu id_store int 1 nie identyfikator magazynu subiekta z którego ma być zrobiona sprzedaż -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"name": "LEKI Rękawice FUSE S MF TOUCH r.9 black",
"code": "4028173073672",
"qty": "1.0000",
"price": "415.6500"
}
}
-
URL
product/get
Przykład:
http://127.0.0.1/api-subiekt-gt/public/api/product/get -
Struktura danych
Nazwa Typ Domyślnie Wymagane Opis api_key string - tak klucz api data array - tak code varchar(20) - tak symbol produktu -
Przykładowa struktura
{
"api_key": "pc0hv61itbxbhtXYujsfdjer774kfsdasd",
"data": {
"code": "4028173073672"
}
}