Jak uruchomić usługę bs4 API
bs4 API jest dostępne tylko jeśli licencja bs4 core w danym wdrożeniu bs4 na to pozwala. Opcję musi włączyć support bs4 w ustawieniach licencji.
Musi być również uruchomiony dostęp do endpointu API przez główną domenę programu bs4 – nie może ona być ukryta za firewall lub w VPN jeśli ma być publiczny dostęp do API. Dla systemów bs4 w hostingu/cloud adres www API jest zawsze dostępny. Problem może być dla systemów on-premise.
Jak skonfigurować konektor API w programie bs4 core
W programie bs4 core należy dodać nowy konektor typu bs4-API. Należy ustawić go w trybie Aktywny. Przyciskiem „Generuj nowy token” utworzyć token dostępowy, który podaje się później w celach autoryzacji w programie/skrypcie korzystającym z bs4 API.
Należy wybrać jakie klasy obiektów chcemy przez API – odczytywać, dodawać, aktualizować usuwać. Ponadto dla odczytu i aktualizacji wskazać jakie pola w tych klasach mają być dostępne.
Na stronie konektora jest pole z pomocą dla developera. Wyświetla ono wszystkie znalezione błędy w konfiguracji i wskazuje jak je rozwiązać. Wyświetla także listę endpointów w Twoim, konkretnym wdrożeniu.
Jakie są endpointy i metody dla API?
Specyfikacja dla API znajduje się tutaj: https://bs4.io/apidocs/
Powyżej jest uniwersalna specyfikacja – nie zawiera Twojej domeny i nazw Twoich klas/pól, jakie są dostępne w Twoim wdrożeniu. Aktualne nazwy endpointów, z nazwami klas, nazwami pól znajdują się na stronie edycji konektora w polu pomocy dla developera.
Jak sprawdzić czy API odpowiada? Healthcheck.
Wywołanie metodą GET adresu URL Twojego API: {domena}/api/health – zwróci informację czy serwer pod tym adresem odpowiada. Taki health check wykonuje również pole pomocy dla developera.
Healthcheck sprawdza czy pod domeną odpowiada serwer/API, wyświetla ponadto numer wersji API. Nie sprawdza czy konektor jest aktywny ani poprawności tokenu (token nie jest wymagany)
Jaka jest wersja API?
Wersja wyświetla się na stronie pomocy dla developera a także po wywołaniu powyższego healthcheck.
Log zmian w kolejnych wersjach API znajduje się tutaj: https://bs4.io/bs4-api-changelog/
Jak debugować, gdy nie działa skrypt/program przez API?
Jeżeli Twój skrypt wywołuje jakąś operację nieprawidłowo, otrzyma w odpowiedzi z api kod błędu http oraz ogólny komunikat błędu.
Szczegółowe informacje o naturze błędu można podejrzeć w historii konektora po stronie programu bs4. Są one logowane niezależnie od trybu.
Można włączyć dokładniejsze logowanie requestów API na potrzeby bieżących prac rozwojowych. W ustawieniach konektora należy wskazać do kiedy (jakiego dnia i godziny) ma być szczegółowe logowanie włączone. W tym czasie w historii konektora będą się pojawiać nie tylko błędy ale również szereg informacji diagnostycznych.
Statystyki ilościowe konektora API również są dostępne – w dedykowanym zestawieniu w karcie konektora. Można tam sprawdzić ile obiektów dodano, odczytano, aktualizowano.
Jak korzystać z pomocy AI przy pisaniu skryptów/programów korzystających z API
W polu pomocy dla developera znajdują się szczegółowe informacje o endpointach, klasach i polach. Jest tam również poniższa wskazówka dla modeli AI. Do chata AI można wkleić informacje z pola pomocy dla developera wraz z opisem własnych potrzeb integracyjnych aby AI wstępnie napisało skrypt integracyjny we wskazanym języku programowania (np. PHP, Python).
AI / LLM integration:
Use OpenAPI spec:
https://bs4.io/apidocs/openapi.json
- nie wklejaj do prompta AI swojego tokenu i innych poufnych informacji,
- weryfikuj wynik pracy AI, nie korzystaj z niego bezkrytycznie,
- skrypt z AI nie zastąpi skonfigurowania konektora opisanego powyżej.
Wykonywanie triggerów bs4 przez API
Przez api można wykonywać triggery bs4 skonfigurowane po stronie programu bs4. Należy podać ID triggera, można podać id powiązanego obiektu do wywołania triggera. Można podać również do 3 parametrów dodatkowych, które można odczytać po stronie triggera.
<?php
$objectId = 123;
$triggerId = 5000100;
$url = "https://twoj-bs4.pl/api/exec/runtrigger/";
$token = 'TWÓJ_TOKEN_API';
$data = [
'triggerId'=>$triggerId,
'objectId'=>$objectId,
'param1'=>'Jan',
'param2'=>'Kowalski',
'param3'=>'10001'
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
'Accept: application/json'
],
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($ch);
Przykładowe skrypty korzystający z API (PHP)
Przykład nr 1. Skrypt aktualizujący dane wybranej firmy:
<?php
$objectId = 123;
$url = "https://twoj-bs4.pl/api/company/$objectId";
$token = 'TWÓJ_TOKEN_API';
$data = [
'name' => 'Nowa nazwa firmy Sp. z o.o.',
'vat_id' => '1234567890'
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json'
],
CURLOPT_POSTFIELDS => json_encode($data)
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo "HTTP CODE: $httpCode\n";
echo $response;Przykład nr 2. Skrypt pobierający dane wybranej firmy:
<?php
$objectId = 123;
$url = "https://twoj-bs4.pl/api/company/$objectId";
$token = 'TWÓJ_TOKEN_API';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Accept: application/json'
],
CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($httpCode !== 200) {
throw new RuntimeException("API returned HTTP $httpCode");
}
$data = json_decode($response, true);
if (!is_array($data)) {
throw new RuntimeException('Invalid JSON response');
}
echo "Company name: " . ($data['name'] ?? '') . PHP_EOL;
echo "VAT ID: " . ($data['vat_id'] ?? '') . PHP_EOL;