Spis treści
Poniższe operacje wykorzystują aliasy API klas i pól podane w pomocy dla developera konektora. Przykładowe company, name i vat_id nie są gwarantowanymi nazwami w każdej instalacji. Zastąp je aliasami swojego wdrożenia.
Adres i autoryzacja #
Podstawą adresu jest adres instalacji BS4, łącznie z podfolderem. Dołącz nagłówek Authorization: Bearer TOKEN. Dla treści JSON ustaw Content-Type: application/json. Token przechowuj poza kodem przykładowym, np. w chronionej konfiguracji lub zmiennej środowiskowej.
| Metoda | Ścieżka | Zastosowanie |
|---|---|---|
| GET | /api/{className}/{objectID} | Odczyt jednego obiektu albo kilku ID rozdzielonych przecinkami. |
| GET | /api/{className}/?limit=100 | Odczyt listy z ograniczeniem liczby wyników. |
| POST | /api/{className}/ | Dodanie obiektu; results zawiera nowe ID. |
| PUT | /api/{className}/{objectID} | Aktualizacja jednego obiektu; results to potwierdzenie operacji. |
| DELETE | /api/{className}/{objectID} | Usunięcie jednego obiektu. |
Jak czytać odpowiedź #
{"code":200,"results":[{"name":"Firma przykładowa"}],"success":true}GET zwraca tablicę obiektów w results, także przy odczycie jednego ID. Nie zakładaj, że nazwa firmy znajduje się bezpośrednio w głównym obiekcie JSON. API zwraca tylko udostępnione pola; jeżeli potrzebujesz ID w wyniku, również udostępnij odpowiednie pole.
Przykład PHP: odczyt i aktualizacja #
<?php
$base = rtrim(getenv('BS4_BASE_URL'), '/');
$token = getenv('BS4_API_TOKEN');
$id = 123;
$ch = curl_init($base . '/api/company/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, 'Accept: application/json'],
CURLOPT_TIMEOUT => 20,
]);
$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$answer = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
if ($http >= 400 || ($answer['success'] ?? false) !== true) {
throw new RuntimeException($answer['errors']['message'] ?? 'API error');
}
$company = $answer['results'][0] ?? null;
// Do aktualizacji użyj PUT pod ten sam adres i treści:
// {"name":"Nowa nazwa firmy","vat_id":"1234567890"}
Ważne zachowania #
- Nie ma ogólnego stronicowania offset/cursor w pokazanym GET. Limit ogranicza liczbę zwróconych obiektów; nie jest numerem strony.
- Nieznany alias pola przy zapisie może zostać pominięty i odnotowany w historii. Po zapisie odczytaj wartości, na których zależy integracji.
- POST i PUT różnią się kontrolą pól — zasady opisano w instrukcji konfiguracji konektora.
- W API 1.02 status HTTP odpowiada błędowi; utworzenie obiektu zwraca HTTP 201. Starsze instalacje mogą wymagać sprawdzania success i errors mimo HTTP 200.
- Automatyczne ponowienie POST po zerwaniu połączenia może utworzyć drugi obiekt. Najpierw sprawdź wynik w BS4.
