Jak korzystać z API programu?

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.

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.

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
                 ]
                }

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
      }

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"
        }
      }

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
        }
      }

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:

1. 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).

2. 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.

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.