API – Kontrahenci - Baza Wiedzy programu Comarch Betterfly

POBIERANIE KONTRAHENTÓW

Pobieranie kontrahentów: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers

Opis struktury JSON odpowiedzi:

Parametr	Opis
$id	Numer porządkowy w ramach odpowiedzi JSON
Name	Nazwa kontrahenta
CountryCode	Oznaczenie kodu kraju kontrahenta (prefix NIP) Możliwa jest pusta wartość, która powinna być stosowana dla kontrahenta krajowego niezarejestrowanego w VAT-UE
CustomerTaxNumber	Identyfikator podatkowy NIP/PESEL – w zależności od pola CustomerType
CustomerCode	Kod kontrahenta
Mail	Adres e-mail kontrahenta
PhoneNumber	Nr telefonu kontrahenta
CustomerType	Rodzaj kontrahenta (0 – osoba fizyczna / 1 – podmiot gospodarczy)
RepresentativeFirstName	Imię przedstawiciela
RepresentativeLastName	Nazwisko przedstawiciela
Address	Sekcja z adresem kontrahenta
$id	Numer porządkowy w ramach odpowiedzi JSON
Street	Ulica
BuildingNumber	Numer budynku
FlatNumber	Lokal
PostalCode	Kod pocztowy
City	Poczta
Id	ID adresu w bazie danych
CustomerStatus	Status kontrahenta: 0 – krajowy 1 – wewnątrzunijny 2 – pozaunijny 3 – wewnątrzunijny trójstronny 10 – procedura OSS
Id	ID kontrahenta w bazie danych

Przykładowa odpowiedź JSON:

[code_snippet id=33]

Możliwe jest także pobranie karty określonego kontrahenta:

[GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/{id}

oraz pobieranie danych o określonym NIP:

[GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?nip={nip}

Przykładowe zapytanie: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?nip=6770065406

Dostępne jest również filtrowanie listy kontrahentów:

wg nazwy: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Name eq {nazwa}
wg adresu e-mail: [GET] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Mail eq {adres_email}

Wskazówka

Filtrować można z użyciem kilku kryteriów wykorzystując wspierane operatory logiczne: or, and, not oraz operatory do porównań: eq (równość), ne (nierówność), gt (większe od), ge (większe lub równe), lt (mniejsze od), le (mniejsze lub równe)

Przykład

https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Name eq 'Comarch'
https://app.comarchbetterfly.pl/api2/public/v1.2/customers/?$filter=Mail eq 'demo@comarch.pl'

DODAWANIE NOWEGO KONTRAHENTA

Dodawanie kontrahenta: [POST] https://app.comarchbetterfly.pl/api2/public/v1.2/customers

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa kontrahenta	Tak
CountryCode	Oznaczenie kraju kontrahenta	W wybranych przypadkach, zależnie od rodzaju kontrahenta⁴
CustomerTaxNumber	Identyfikator podatkowy NIP/PESEL	Nie
CustomerCode	Kod kontrahenta	Nie¹
Mail	Adres e-mail kontrahenta	Nie
PhoneNumber	Nr telefonu kontrahenta	Nie
CustomerType	Rodzaj kontrahenta (0 – osoba fizyczna / 1 – podmiot gospodarczy)	Nie²
RepresentativeFirstName	Imię przedstawiciela	Nie
RepresentativeLastName	Nazwisko przedstawiciela	Nie
Address	Sekcja z adresem kontrahenta
Street	Ulica	Nie
BuildingNumber	Numer domu	Nie
FlatNumber	Lokal	Nie
PostalCode	Kod pocztowy	Nie
City	Poczta	Nie
CustomerStatus	Status kontrahenta: 0 – krajowy 1 – wewnątrzunijny 2 – pozaunijny 3 – wewnątrzunijny trójstronny 10 – procedura OSS	Nie³

1) W przypadku braku kodu zostanie on nadany poprzez serwer.

2) W przypadku braku rodzaju zostanie zastosowane ustawienie domyślne (podmiot gospodarczy).

3) W przypadku braku statusu zostanie on nadany wg kodu kraju, a w przypadku braku kodu kraju zostanie zastosowane ustawienie domyślne (kontrahent krajowy)

4) Kod kraju jest obowiązkowy dla kontrahentów wewnątrzunijnych i procedury OSS.

Przykładowe zapytanie JSON:

[code_snippet id=34]

W odpowiedzi zostanie wysłane ID dodanego kontrahenta.

EDYCJA KONTRAHENTA

Edycja kontrahenta: [PUT] https://app.comarchbetterfly.pl/api2/public/v1.2/customers

Opis struktury JSON zapytania:

Parametr	Opis	Czy parametr obowiązkowy?
Name	Nazwa kontrahenta	Tak
CountryCode	Oznaczenie kraju kontrahenta	W wybranych przypadkach, zależnie od rodzaju kontrahenta.
CustomerTaxNumber	Identyfikator podatkowy NIP/PESEL	Nie
CustomerCode	Kod kontrahenta	Nie
Mail	Adres e-mail kontrahenta	Nie
PhoneNumber	Nr telefonu kontrahenta	Nie
CustomerType	Rodzaj kontrahenta (0 – osoba fizyczna / 1 – podmiot gospodarczy)	Nie
RepresentativeFirstName	Imię przedstawiciela	Nie
RepresentativeLastName	Nazwisko przedstawiciela	Nie
Address	Sekcja z adresem kontrahenta
Street	Ulica	Nie
BuildingNumber	Numer domu	Nie
FlatNumber	Lokal	Nie
PostalCode	Kod pocztowy	Nie
City	Poczta	Nie
Id	Id adresu	Nie
Id	Id kontrahenta	Tak
CustomerStatus	Status kontrahenta: 0 – krajowy 1 – wewnątrzunijny 2 – pozaunijny 3 – wewnątrzunijny trójstronny 10 – procedura OSS	Nie

Uwaga

W przypadku pominięcia parametrów nieobowiązkowych, zostaną one nadpisane domyślnymi lub pustymi wartościami.

W odpowiedzi zostanie wysłany status i ewentualnie JSON odpowiedzi:

Przykładowe zapytanie JSON (dodanie adresu e-mail dla kontrahenta o Id=2):

[code_snippet id=35]

Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.

USUWANIE KARTY KONTRAHENTA

Usuwanie kontrahenta: [DEL] https://app.comarchbetterfly.pl/api2/public/v1.2/customers/XXX (gdzie XXX to Id kontrahenta w bazie danych)

Przykładowe zapytanie: [DEL] https://app.comarchbetterfly.pl/api2/public/customers/3

Przykładowa odpowiedź JSON – status 204 No Content – operacja zakończona powodzeniem.