Jak korzystać z API Perno?

Jak wejść do dokumentacji

Do dokumentacji API możesz dotrzeć na dwa sposoby: ze strony głównej Perno albo z poziomu zalogowanego panelu.

Ze strony głównej

• Wejdź na perno.io.
• W górnym menu kliknij API documentation.

Z poziomu zalogowanego panelu

• Zaloguj się do panelu Perno.
• Kliknij swoje inicjały w prawym górnym rogu, aby otworzyć menu konta.
• Wybierz API access.
• Na dole strony, w sekcji Documentation, kliknij Open API reference - obok znajdziesz też pole API base URL z adresem API.

Oba sposoby prowadzą do tej samej dokumentacji pod adresem perno.io/api/v1/reference/.

Gdzie znaleźć dokumentację

Pełna dokumentacja znajduje się pod adresem perno.io/api/v1/reference/. Zawiera listę wszystkich endpointów wraz z ich parametrami, przykładowym żądaniem i przykładową odpowiedzią, pogrupowanych w przeszukiwalnym menu bocznym według produktu.

Ta sama specyfikacja dostępna jest również jako:

• Redoc - jednostronicowa wersja całego API, przeznaczona tylko do odczytu.
• Swagger - widok interaktywny, w którym możesz wysyłać żądania bezpośrednio z przeglądarki.
• Surowy schemat OpenAPI - przydatny, jeśli chcesz wygenerować bibliotekę kliencką dla swojego języka programowania lub zaimportować API do narzędzia takiego jak Postman czy Insomnia.

Gdzie znaleźć klucze API

Token API może zobaczyć i wygenerować wyłącznie właściciel konta (owner):

• Zaloguj się do panelu Perno.
• Kliknij swoje inicjały w prawym górnym rogu, aby otworzyć menu konta - obok API access znajdziesz tam też m.in. Company data, Merchant accounts i Your subscriptions.
• Wybierz API access.
• W sekcji API token kliknij Show token, aby go wyświetlić, albo Copy token, aby od razu skopiować go do schowka.

Jeśli nie jesteś właścicielem konta, ta opcja menu nie będzie dla Ciebie widoczna - poproś właściciela konta Perno w Twojej organizacji o udostępnienie lub zarządzanie dostępem do API.

Strona API access ostrzega wprost: "Treat this token like a password. Do not include it in browser code, public repositories, screenshots, or support messages." Traktuj token jak hasło: nie umieszczaj go w kodzie działającym po stronie przeglądarki, publicznych repozytoriach, zrzutach ekranu ani wiadomościach do supportu.

Token wysyłaj z każdym chronionym żądaniem w nagłówku Authorization - dokładnie ten sam przykład znajdziesz też na stronie API access, w sekcji How to authenticate:

Authorization: Token YOUR_API_TOKEN

Pierwsze żądanie

Sekcja Quick start w dokumentacji zawiera gotowy do uruchomienia przykład, który wywołuje endpoint health check:

export PERNO_API_TOKEN="YOUR_API_TOKEN"

curl "https://perno.io/api/v1/health_check" \
  -H "Authorization: Token $PERNO_API_TOKEN"

Jeśli token jest prawidłowy, otrzymasz w odpowiedzi poprawny JSON. Jeśli token jest brakujący, błędny lub wygasł, każdy chroniony endpoint zwróci ten sam błąd 401 - to szybki sposób, aby sprawdzić, czy token został poprawnie skonfigurowany, zanim zbudujesz na nim właściwą integrację.

Endpointy są zorganizowane w podziale na produkty

Menu boczne dokumentacji grupuje endpointy tak samo, jak panel grupuje konteksty (zobacz Czym jest kontekst w Perno?) - produkt, który wybierasz w panelu, to ta sama sekcja, w której znajdziesz jego endpointy:

• Core resources - health check i schemat OpenAPI, dostępne niezależnie od produktu.
• Orchestration - linki płatnicze, konta sprzedawców i metody płatności, służące do przetwarzania płatności przez Perno Orchestration.
• Perno Commerce - wszystko związane ze sklepem: kategorie, producentów i produkty, a także dane katalogu firm, takie jak firmy, kraje, miasta, województwa/stany, usługi i specjalizacje.

Endpointy Perno Commerce są przypisane do konkretnego sklepu, dlatego żądania list i szczegółów przyjmują parametr store_id, który wskazuje, którego z Twoich sklepów dotyczy żądanie.

Te same konwencje REST obowiązują wszędzie

Niezależnie od produktu, zasoby w API działają według tego samego wzorca, więc gdy poznasz jeden endpoint, pozostałe zachowują się tak samo:

• GET na kolekcji zwraca listę rekordów, a na adresie pojedynczego rekordu - jego szczegóły.
• POST tworzy nowy rekord.
• PUT zastępuje rekord w całości, a PATCH aktualizuje tylko przesłane pola.
• DELETE usuwa rekord.

Przykład: tworzenie linku płatniczego

Tak wygląda w praktyce para żądanie/odpowiedź, na przykładzie endpointu Orchestration służącego do tworzenia hostowanego linku płatniczego:

curl -X POST "https://perno.io/api/v1/payment_links/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_account": 1,
    "amount": "10.00",
    "currency": "USD",
    "customer_email": "[email protected]",
    "trx_id": "123"
  }'

Poprawne żądanie zwraca kod 201 wraz z utworzonym zasobem:

{
  "payment_hash": "string",
  "merchant_account": 1,
  "trx_hash": "string",
  "trx_id": "string",
  "amount": "string",
  "customer_email": "string",
  "one_time_link": true,
  "used": true
}

Kody odpowiedzi i błędów

Każdy endpoint zwraca JSON i używa tych samych kodów statusu niezależnie od produktu:

• 200 - żądanie zakończyło się powodzeniem, a treść odpowiedzi zawiera żądany zasób lub listę.
• 201 - nowy zasób został utworzony pomyślnie.
• 400 - błąd walidacji; treść odpowiedzi zawiera błędy dla poszczególnych pól lub komunikat ze szczegółami, więc sprawdź pola żądania i wartości parametrów.
• 401 - token jest brakujący, nieprawidłowy lub wygasł; wyślij prawidłowy nagłówek Authorization.