Comarch Betterfly API działa w oparciu o protokół HTTP i jego metody (GET, POST, PUT, DELETE) oraz zasoby, które odzwierciedlają poszczególne funkcjonalności serwisu. Uwierzytelnianie realizowane jest w standardzie OAuth 2.0 (więcej o uwierzytelnianiu – API Instrukcja Użytkownika).
Dostęp do API odbywa się poprzez połączenie HTTPS do serwera app.comarchbetterfly.pl. Dane są wysyłane i odbierane z serwera w formacie JSON.
Dostęp do API jest możliwy z poziomu Konta Użytkownika > Zarządzaj kontem > Publiczne API. Użytkownik, który jest administratorem w ramach konta Comarch Betterfly, wnioskuje o przydzielenie dostępu (opcja „Zapytaj o API”). Po jego uzyskaniu generuje z tego poziomu dane dostępowe oraz rejestruje aplikację korzystającą z API.
Wykorzystywane metody HTTP:
| GET | pobieranie danych dotyczących wszystkich lub wskazanych elementów/zasobów, w tym pobieranie wydruków |
| POST | tworzenie nowego elementu/zasobu |
| PUT | edycja istniejącego elementu/zasobu |
| DELETE | usuwanie elementu/zasobu |
Zasoby:
| produkty | https://app.comarchbetterfly.pl/api2/public/products |
| kontrahenci | https://app.comarchbetterfly.pl/api2/public/v1.2/customers |
| formy płatności | https://app.comarchbetterfly.pl/api2/public/paymenttypes |
| rachunki bankowe | https://app.comarchbetterfly.pl/api2/public/bankaccounts |
| faktury sprzedaży | https://app.comarchbetterfly.pl/api2/public/v1.7/invoices |
| faktury proforma | https://app.comarchbetterfly.pl/api2/public/v1.4/proformas |
| szablony wydruków | https://app.comarchbetterfly.pl/api2/public/customprints |
| faktura VAT marża | https://app.comarchbetterfly.pl/api2/public/v1.5/profitmargininvoices |
| faktura zaliczkowa | https://app.comarchbetterfly.pl/api2/public/v1.7/advanceinvoices |
| faktura zakupu | https://app.comarchbetterfly.pl/api2/public/v1.4/purchaseinvoices |
| rejestr VAT Zakupu | https://app.comarchbetterfly.pl/api2/public/v1.4/vatpurchasebooks |
| korekta faktury sprzedaży | https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveinvoices |
| korekta faktury zaliczkowej | https://app.comarchbetterfly.pl/api2/public/v1.7/correctiveadvanceinvoices |
| korekta faktury zakupu | https://app.comarchbetterfly.pl/api2/public/v1.4/correctivepurchaseinvoices |
Każde żądanie do API zwraca status HTTP informujący o wyniku przetwarzania. Poniższa lista zawiera najczęściej używane statusy:
- 200 OK – pomyślnie przesłano dane w metodzie GET, POST
- 204 No Content – pomyślnie zakończono akcję w metodzie PUT, DELETE
- 400 Bad Request – błąd w treści żądanie
- 401 Unauthorized – brak uwierzytelniania
- 403 Forbidden – dostęp zablokowany
- 404 Not Found – nie znaleziono zasobu
- 500 Internal Server Error – wewnętrzny błąd serwera
Operacje wykonywane poprzez API są zapisywane w historii zmian kontrahenta oraz dokumentu. W opisie operacji znajduje się informacja na temat nazwy aplikacji, poprzez którą dokonano zmian.
