Jak korzystać z API programu?
API (Application Programming Interface) to interfejs, który umożliwia różnym programom lub systemom wymianę danych i komunikację między sobą. Używa się go do automatyzacji oraz integracji różnych aplikacji, co pozwala na przepływ informacji bez konieczności ręcznej manipulacji danymi. Dzięki komunikacji poprzez API, inne programy mogą automatycznie pobierać lub przesyłać dane do i z systemu.
W programie ELISOFT Firma Premium, API umożliwia użytkownikom zautomatyzowany dostęp do kluczowych danych w systemie, takich jak kontrahenci, towary, usługi oraz faktury sprzedaży i zakupu. Dzięki temu możesz integrować system z innymi aplikacjami, pobierać, dodawać i aktualizować dane bez konieczności ręcznego wykonywania tych czynności przez interfejs programu. API pozwala na szybki dostęp do zasobów za pomocą tzw. zapytań OData, co upraszcza procesy biznesowe i umożliwia zautomatyzowanie wielu procesów i zintegrowanie innych systemów z aplikacją.
Dzięki API możesz np. automatycznie generować faktury na podstawie danych przychodzących z innych systemów (np. zamówień), aktualizować czy pobierać dane kontrahentów w oparciu o informacje z innych systemów, synchronizować stany magazynowe towarów albo integrować oprogramowanie księgowe z danymi z systemu. Wszystkie te procesy mogą odbywać się automatycznie w tle, co zwiększa efektywność i oszczędza czas.
Przykładowe możliwości użycia API:
- Pobranie listy wszystkich kontrahentów w systemie
- Pobranie szczegółowych danych konkretnego kontrahenta
- Uzyskanie listy wszystkich towarów dostępnych w magazynie
- Pobranie pełnej listy usług oferowanych przez firmę
- Pobranie listy wszystkich faktur sprzedaży w systemie
- Pobranie danych konkretnej faktury sprzedaży na podstawie jej identyfikatora
- Dodanie nowej faktury sprzedaży do systemu
- Dodanie nowej faktury zakupu do systemu na podstawie zewnętrznego systemu
- Zautomatyzowanie tworzenia faktur sprzedaży na podstawie zamówień klientów
- Synchronizacja listy towarów z systemem webowym dla klientów
- Eksportowanie listy sprzedanych towarów do innego systemu, np. dla analizy zysków/kosztów
- Zintegrowanie listy kontrahentów z innym systemem CRM, aby mieć aktualne dane o klientach
Kliknij na poniższe punkty aby rozwinąć więcej informacji.
KONFIGURACJA API
Aby skonfigurować dostęp do API w programie, wykonaj poniższe kroki:
1. Włączenie dostępu do API
- Przejdź do menu Ustawienia / Ustawienia programu / Ustawienia dostępu do API.
- W nowym oknie, które się otworzy, zaznacz opcję Włącz dostęp do API programu (1).
- W polach Identyfikator i Adres bazowy (2) znajdują się informacje potrzebne do wysyłania zapytań do API. Więcej o ich zastosowaniu opisano w dalszej części instrukcji.
2. Dodanie klucza dostępu do API
- Aby aktywować API, musisz wygenerować klucz dostępu, w tym celu użyj opcji Dodaj nowy klucz (1).
- Nadaj kluczowi nazwę (2) i ustaw, czy ma być ograniczony czasowo. Jeśli nie zaznaczysz opcji ograniczenia, klucz będzie ważny bezterminowo (można go później w dowolnym momencie unieważnić).
- Na koniec możesz przejść do wygenerowania klucza (3). Uwaga: Kod klucza pojawi się tylko raz podczas generowania. Zapisz go w bezpiecznym miejscu, ponieważ nie będzie możliwości ponownego odczytania go w programie.
- Po zapisaniu zmian przyciskiem OK, nowo utworzony klucz będzie widoczny na liście kluczy dostępu w głównym oknie ustawień dostępu do API.
DOKUMENTACJA API
Po skonfigurowaniu dostępu do API i utworzeniu klucza, możesz zapoznać się z dokumentacją, która pomoże Ci wykonywać zapytania do aplikacji. Dokumentacja API jest dostępna z poziomu Swagger UI, który można otworzyć bezpośrednio z programu i umożliwia testowanie/tworzenie zapytań.
1. Identyfikator i adres bazowy
- W ustawieniach dostępu do API znajdziesz, powyżej wspomniane już pola Identyfikator oraz Adres bazowy.
- Identyfikator to unikalny kod dla bazy danych, który jest potrzebny przy budowaniu zapytań do API.
- Adres bazowy to główny adres, pod którym dostępne są zasoby API. Korzystając z tego adresu, możesz testować funkcjonalności API i wykonywać zapytania.
2. Przejście do dokumentacji API
- Aby przejść do dokumentacji API, kliknij przycisk Otwórz dokumentację API w oknie ustawień dostępu.
- Program otworzy przeglądarkę z dokumentacją API w formacie Swagger. Swagger to interfejs, który umożliwia przeglądanie dostępnych zasobów API oraz testowanie zapytań bezpośrednio w przeglądarce.
3. Korzystanie z Swaggera i autoryzacja kluczem dostępu
- Przed wykonaniem zapytań w Swaggerze, musisz przeprowadzić autoryzację. Kliknij w poniżej wskazany przycisk Authorize, aby otworzyć okno, w którym należy wpisać klucz dostępu, który wygenerowałeś wcześniej w aplikacji.
- Po wprowadzeniu klucza dostępu zatwierdź autoryzację, co umożliwi wykonywanie zapytań do API.
- W interfejsie Swagger znajdziesz listę dostępnych zasobów API, takich jak na przykład FakturySprzedazy czy Kontrahenci.
- Każde zapytanie API zawiera ścieżkę, w której musisz podać swój identyfikator, np. GET /{apiConfigId/odata/FakturySprzedazy - to zapytanie zwraca listę faktur sprzedaży.
- W Swaggerze możesz przetestować działanie poszczególnych zapytań, wypełniając wymagane pola i klikając przycisk Execute. W pierwszej kolejności natomiast trzeba użyć przycisku Try it out (1) oraz wprowadzić Identyfikator (2).
Swagger pozwala także na szybkie przeglądanie przykładów zapytań, które można dostosować i zaimplementować we własnych aplikacjach.
PRZYKŁAD 1 - Pobieranie listy kontrahentów
Aby pobrać listę kontrahentów, należy wysłać żądanie GET na endpoint: /apiConfigId/odata/Kontrahenci . Endpoint zwraca listę kontrahentów na podstawie podanych parametrów filtrowania.
Parametry
- apiConfigId (wymagany)- identyfikator konfiguracji API
- $filter (opcjonalny)- możliwość filtrowania wyników, np. według miejscowości: Miejscowość eq ‘Warszawa’
- $select (opcjonalny)- wskazuje, które pola mają być zwrócone w odpowiedzi np. tylko nazwa i NIP- NazwaPelna, Nip .
- $orderby (opcjonalny)- sortowanie wyników np. według numeru Id malejąco: Id desc
- $top (opcjonalny)- liczba rekordów do zwrócenia np. 5 pierwszych elementów: 5
- $skip (opcjonalny)- liczba pominiętych rekordów
Przykładowe zapytanie:
GET https://localhost:11818/CEE7AD4A/odata/Kontrahenci?$filter=Miejscowosc eq 'Warszawa'&$top=5
Nagłówki:
accept: application/json
X-API-KEY: b3e7c5t16a14524e
Przykładowa odpowiedź:
{
"@odata.context": "https://localhost:11818/CEE7AD4A/odata/$metadata#Kontrahenci",
"@odata.nextLink": "https://localhost:11818/CEE7AD4A/odata/Kontrahenci?$filter=Miejscowosc%20eq%20%27Warszawa%27&$top=5&$skip=5",
"value": [
{
"Id": 1,
"Guid": "3cc0aeb8-6bb9-4bba-ac77-48c5057df016",
"Symbol": null,
"NazwaSkrocona": "Anna Nowak",
"NazwaPelna": "Anna Nowak\r\nPESEL: 93560892109",
"UzywajPelnejNazwy": true,
"Rodzaj": null,
"Ulica": "Chopina",
"NrDomu": "12",
"NrMieszkania": null,
"Kod": "00-006",
"Miejscowosc": "Warszawa",
"Wojewodztwo": "mazowieckie",
"Panstwo": "Polska",
"Telefon": null,
"TelefonKomorkowy": null,
"Fax": null,
"UnijnyKodPanstwa": null,
"Nip": null,
"Regon": null,
"Email": null,
"StronaWWW": null,
"FormaPlatnosci": "Przelew"
},
{
"Id": 3,
"Guid": "2e878209-08c9-46bb-9234-63bbf93621e4",
"Symbol": null,
"NazwaSkrocona": "LOOKING",
"NazwaPelna": null,
"UzywajPelnejNazwy": false,
"Rodzaj": null,
"Ulica": "Torowa",
"NrDomu": "23",
"NrMieszkania": null,
"Kod": "00-012",
"Miejscowosc": "Warszawa",
"Wojewodztwo": "mazowieckie",
"Panstwo": "Polska",
"Telefon": null,
"TelefonKomorkowy": null,
"Fax": null,
"UnijnyKodPanstwa": null,
"Nip": "0987654321",
"Regon": null,
"Email": null,
"StronaWWW": null,
"FormaPlatnosci": "Gotówka"
},
//... inne wyniki
]
}PRZYKŁAD 2 - Pobieranie szczegółowych danych faktury sprzedaży
Aby pobrać szczegółowe dane wybranej faktury sprzedaży, należy wysłać żądanie GET na endpoint: /{apiConfigId}/FakturySprzedazy/{id}. Endpoint zwraca szczegółowe informacje na podstawie podanego id faktury.
Parametry
- apiConfigId (wymagany)- identyfikator konfiguracji API
- id (Wymagany)- identyfikator faktury sprzedaży z programu
Przykładowe zapytanie:
GET https://localhost:11818/CEE7AD4A/FakturySprzedazy/1
Nagłówki:
accept: application/json
X-API-KEY: b3e7c5t16a14524e
Przykładowa odpowiedź:
{
"Id": 1,
"Guid": "436b03c3-7555-4a12-bf10-f87ad952fcb8",
"Numer": "FV 01/11/2024",
"DataWystawienia": "2024-11-05T00:00:00+01:00",
"DataSprzedazy": "2024-11-05T00:00:00+01:00",
"MiejsceWystawienia": "Warszawa",
"TerminZaplaty": "2024-11-12T00:00:00+01:00",
"Sprzedawca": {
"Id": 1,
"Guid": "c0cdd17e-6edd-4e22-b749-23ad35c224de",
"Nazwa": "House Invent",
"Adres": "Fryderyka Chopina 10/20\r\n00-950 Warszawa, Polska",
"NIP": "1234567890"
},
"Nabywca": {
"Id": 3,
"Guid": "2e878209-08c9-46bb-9234-63bbf93621e4",
"Nazwa": "LOOKING",
"Adres": "Torowa 23\r\n00-012 Warszawa, Polska",
"NIP": "0987654321"
},
"Odbiorca": null,
"SposobZaplaty": "Przelew",
"ProceduraMPP": false,
"ProceduraOSS": false,
"Pozycje": [
{
"Id": 1,
"Nazwa": "Łóżko tapicerowane chmurka 140x200",
"KodTowaru": null,
"KodGTU": null,
"KodPKWiU": null,
"KodCN": null,
"Jednostka": "szt",
"Ilosc": 1,
"Rabat": 0,
"StawkaVAT": {
"Procent": 23,
"Rodzaj": "Procentowa"
},
"CenaNetto": 1771.54,
"CenaBrutto": 2179,
"WartoscNettoPoRabacie": 1771.54,
"WartoscBruttoPoRabacie": 2179
}
],
"Waluta": {
"Symbol": "PLN",
"Kurs": 1
},
"RachunekBankowy": {
"NazwaBanku": "MBANK PLN",
"NumerKonta": "PL77111122223333444455556666"
},
"Kwoty": {
"WartoscNetto": 1771.54,
"WartoscBrutto": 2179,
"WartoscZaplacona": 0,
"PozostaloDoZaplaty": 2179
},
"DokumentWystawil": "Adam Kowalski",
"DokumentOdebral": null,
"Uwagi": null,
"InformacjeJPK": null
}PRZYKŁAD 3 - Dodawanie faktury zakupu
Aby dodać fakturę zakupu, należy wysłać żądanie POST na endpoint: /{apiConfigId}/FakturyZakupu/Importy. Endpoint umożliwia dodanie nowej faktury zakupu do aplikacji.
Parametry
- apiConfigId (wymagany) - identyfikator konfiguracji API
- Treść żądania (body) w formacie JSON (szczegóły poniżej)
Przykładowe zapytanie:
POST https://localhost:11818/CEE7AD4A/FakturyZakupu/Importy
Nagłówki:
accept: application/json
X-API-KEY: b3e7c5t16a14524e
Content-Type: application/json
Treść żądania (body):
{
"OpcjeImportu": {
"OpcjeImportuKontrahenta": {
"Operacja": "WyszukajKontrahenta"
}
},
"Dane": {
"Numer": "28/11/2024",
"NumerDokumentuSprzedawcy": "FZ 2/11/2024",
"DataWystawienia": "2024-11-27T00:00:00+01:00",
"DataSprzedazy": "2024-11-27T00:00:00+01:00",
"MiejsceWystawienia": "Warszawa",
"TerminZaplaty": "2024-11-27T00:00:00+01:00",
"Sprzedawca": {
"Id": 3,
"NIP": "0987654321",
"Nazwa": "LOOKING",
},
"Nabywca": {
"NIP": "1234567890"
},
"SposobZaplaty": "Gotówka",
"ProceduraMPP": null,
"SposobLiczenia": "OdCenNetto",
"Pozycje": [
{
"Nazwa": "Narożnik L",
"KodTowaru": "111111",
"KodGTU": "GTU_01",
"KodPKWiU": "46.11.12.0",
"KodCN": "0809 29 00",
"Jednostka": "szt.",
"Ilosc": 1,
"Rabat": 0,
"StawkaVAT": {
"Rodzaj": "Procentowa",
"Procent": 23
},
"CenaNetto": 100,
"CenaBrutto": 123
}
],
"Waluta": {
"Symbol": "PLN",
"Kurs": 1
},
"RachunekBankowy": {
"NazwaBanku": "Nazwa banku",
"NumerKonta": "PL77111122223333444455556666"
},
"Kwoty": {
"WartoscZaplacona": 123
},
"DokumentWystawil": null,
"DokumentOdebral": null,
"Uwagi": "Uwagi",
"InformacjeJPK": {
"KodyProcedur": "SW,TP",
"KodyGTU": "GTU_01"
}
}PRZYKŁAD 4 - Dodawanie faktury sprzedaży
Aby dodać fakturę sprzedaży, należy wysłać żądanie POST na endpoint: /{apiConfigId}/FakturySprzedazy/Importy. Endpoint umożliwia importowanie nowej faktury do aplikacji.
Parametry
- apiConfigId (wymagany) - identyfikator konfiguracji API
- Treść żądania (body) w formacie JSON (szczegóły poniżej)
Przykładowe zapytanie:
POST https://localhost:11818/CEE7AD4A/FakturySprzedazy/Importy
Nagłówki:
accept: application/json
X-API-KEY: b3e7c51e16a1542ae
Content-Type: application/json
Treść żądania (body):
{
"OpcjeImportu": {
"OpcjeImportuKontrahenta": {
"Operacja": "ImportujKontrahenta",
"OpcjeDopasowania": {
"KluczDopasowania": [
"NIP",
"NAZWA",
"ADRES"
]
},
"OpcjeAktualizacji": {
"Aktualizuj": "NIE"
}
}
},
"Dane": {
"DataWystawienia": "2024-11-27",
"DataSprzedazy": "2024-11-27",
"TerminZaplaty": "2024-11-27",
"Sprzedawca": {
"NIP": "1111111111"
},
"Nabywca": {
"NIP": "2222222222",
"Nazwa": "FIRMA X",
"Adres": {
"Ulica": "MAGNOLIOWA",
"NrDomu": "19",
"KodPocztowy": "00-999",
"Miejscowosc": "WARSZAWA"
}
},
"SposobLiczenia": "OdCenNetto",
"Pozycje": [
{
"Nazwa": "Wiertło do drewna",
"Ilosc": 4,
"StawkaVAT": {
"Rodzaj": "Procentowa",
"Procent": 23
},
"CenaNetto": 36,
"CenaBrutto": null
},
{
"Nazwa": "Wiertarka udarowa",
"Ilosc": 2,
"StawkaVAT": {
"Rodzaj": "Procentowa",
"Procent": 23
},
"CenaNetto": 410,
"CenaBrutto": null
}
],
"Waluta": {
"Symbol": "PLN",
"Kurs": 1
}
}OPCJE IMPORTU
Sekcja "OpcjeImportu"
Ta sekcja zawiera parametry kontrolujące sposób importowania kontrahenta w trakcie dodawania faktury.
"OpcjeImportuKontrahenta"
Zawiera dwa kluczowe parametry:
-
Operacja - decyduje o tym, jak postąpić z danymi kontrahenta. Możliwe wartości:
-
ImportujKontrahenta
- Tworzy nowego kontrahenta w bazie, jeśli nie istnieje.
- Jeśli kontrahent już istnieje, można skonfigurować opcję aktualizacji jego danych w bazie (patrz: OpcjeAktualizacji).
-
WyszukajKontrahenta
- Używa podanych danych, aby wyszukać kontrahenta w bazie.
- Jeśli nie można znaleźć jednoznacznego dopasowania, operacja zwróci błąd. W tym trybie nie dokonuje się aktualizacji ani dodania kontrahenta.
-
"OpcjeDopasowania" (tylko dla ImportujKontrahenta)
Wskazuje klucze, według których program ma sprawdzić, czy dany kontrahent istnieje już w bazie.
Przykład:
{
"OpcjeImportu": {
"OpcjeImportuKontrahenta": {
"Operacja": "ImportujKontrahenta",
"OpcjeDopasowania": {
"KluczDopasowania": [
"NIP",
"NAZWA",
"ADRES"
]
},
"OpcjeAktualizacji": {
"Aktualizuj": "NIE"
}Powyższy Klucz ["NIP", "NAZWA", "ADRES"] oznacza, że system sprawdzi w bazie, czy istnieje kontrahent z dokładnie takim NIP-em, nazwą i adresem. Jeśli takiego nie znajdzie, zostanie utworzony nowy rekord.
"OpcjeAktualizacji" (tylko dla ImportujKontrahenta)Parametr "Aktualizuj" decyduje, czy program ma aktualizować dane kontrahenta w bazie, jeśli zostanie znaleziony (domyślne wartości: "TAK" lub "NIE").
- "TAK": System zaktualizuje istniejące dane kontrahenta na podstawie nowo przesłanych informacji.
- "NIE" : Dane kontrahenta pozostają bez zmian, nawet jeśli w bazie znajdują się różnice.
WSKAZÓWKI DOTYCZĄCE BEZPIECZEŃSTWA PRZY KORZYSTANIU Z API
Aby zapewnić bezpieczne korzystanie z API, zalecamy zastosowanie się do poniższych wskazówek:
- Korzystaj z HTTPS - aby Twoje dane były chronione, zawsze używaj szyfrowanego połączenia HTTPS. Certyfikat HTTPS należy skonfigurować w usłudze ELISOFT Business Server.
Instrukcja konfiguracji:
1. Umieść certyfikat w magazynie certyfikatów systemowych - Certyfikat musi zostać wcześniej umieszczony w magazynie certyfikatów systemowych. Lokalizacja: [Magazyn Certyfikatów - komputer lokalny\Osobisty\Certyfikaty].
2. Uruchom ELISOFT Business Server - Kliknij w ikonę ELISOFT Business Server, która znajduje się w systemowym pasku zadań Windows
3. Przejdź do ustawień usługi API - W menu głównym ELISOFT Business Server wybierz opcję Usługa API. Otworzy się nowe okno konfiguracji.
4. Wskaż certyfikat w usłudze API
- Zabezpiecz dostęp - jeśli planujesz udostępnić API poza swoją sieć lokalną, zadbaj o odpowiednie zabezpieczenia np. za pomocą firewalla lub innych środków ochrony.