API / Techniczne

⌘K
  2. Strona główna
  4. Dokumentacja
  6. API / Techniczne
  8. Wprowadzenie do API xSale
  10. Wykonanie żądania do xSale REST API

Wykonanie żądania do xSale REST API

Do czego służy ta instrukcja

Ten artykuł pokazuje, jak poprawnie przygotować i wykonać żądanie do REST API xSale. W praktyce oznacza to: pozyskanie wymaganych tokenów i przesłanie ich w nagłówkach autoryzacyjnych przy wywołaniu endpointów.

W tym artykule znajdziesz

  • jakie tokeny są potrzebne do autoryzacji,
  • jakie nagłówki dołączyć do żądania,
  • gdzie sprawdzić, jak uzyskać tokeny.

Kiedy stosować

  • gdy wywołujesz endpointy REST API wymagające autoryzacji,
  • gdy integracja zwraca błąd braku uprawnień lub braku autoryzacji,
  • gdy testujesz komunikację z API (np. w Postmanie lub własnym skrypcie).

Wymagania

  • aktywna konfiguracja autoryzacji dla REST API xSale,
  • tokeny: access_token oraz id_token.

Szybki przepis (krok po kroku)

  1. Wygeneruj tokeny access_token i id_token.
  2. Dodaj do żądania nagłówki autoryzacyjne zgodnie z przykładem w części technicznej.
  3. Wykonaj żądanie do wybranego endpointu API.

Typowe problemy i jak je sprawdzić

  • 401/403 — sprawdź, czy tokeny są aktualne oraz czy nagłówki zostały wysłane w prawidłowej postaci.
  • Brak x-id-token — upewnij się, że dołączasz oba nagłówki wymagane przez xSale.

Szczegóły techniczne

Większość endpointów API wymaga autoryzacji i uwierzytelnienia. Aby poprawnie wysłać żądanie do API potrzebujemy tokenów „access_token” i „id_token”. Jak wygenerować tokeny [link]. Każdorazowo przy wywołaniu zabezpieczonego endpointa, powinno się wysyłać dwa dodatkowe nagłówki:

Authorization: Bearer {access_token}
x-id-token: {id_token}

Przykładowe wywołanie CURL:

curl -X GET \
--url 'https://api.xsale.ai/me'
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cC...' \
--header 'x-id-token: eyJodHRwczovL2Z1dHVyaXRpLnBsL3VzZXJfbWV0YWRhdGEiO...'

UWAGA! Należy upewnić się, że żądania wysyłane są protokołem HTTPS. W przypadku niektórych bibliotek, wysłanie żądania pod HTTP może skutkować automatycznym przekierowaniem na HTTPS bez ponownego załączenia nagłówków.

Parametr {organizationName} w URL

Nazwę organizacji (organizationName) można sprawdzić w ustawieniach integracji REST API utworzonej w panelu xSale.
Można także odpytać endpoint https://api.xsale.ai/me zwracający informacje o użytkowniku, dla którego wygenerowany jest token.
Przykładowe dane zwrócone przez endpoint https://api.xsale.ai/me

{
"Id": 1,
"Name": "Lorem Ipsum",
"Nickname": "loremipsum",
"Email": "loremipsum@futuriti.pl",
"EmailVerified": true,
"Organizations": [
{
"Id": 1,
"ShortName": "Futuriti",
"Name": "Futuriti_bb7b2a13-84e7-4261-8550-0250op0f9b55"
}
]
}

{organizationName} odpowiada polu „Name” w węźle „Organizations”.