# Szybki start: Autoryzacja i podstawy API

Witaj w dokumentacji API SimPay! Zanim przejdziesz do integracji konkretnych usług (Płatności Online, DirectBilling czy SMS), musisz poznać podstawowe zasady komunikacji z naszymi serwerami.

Nasze API zostało zaprojektowane w architekturze REST, a wymiana danych odbywa się wyłącznie w formacie **JSON**.

## 1. Pobranie i przesyłanie klucza API

Dostęp do API jest chroniony. Aby móc wysyłać do nas żądania, potrzebujesz unikalnego klucza dostępu (Bearer Token).

1. Zaloguj się do **Panelu Klienta SimPay**.
2. Przejdź do zakładki **Moje Konto > Klucze API**.
3. Wygeneruj nowy klucz i skopiuj jego wartość.


Wygenerowany token musisz dołączać do **każdego** żądania wysyłanego do naszego API, używając nagłówka `Authorization`. Pamiętaj również o odpowiednich nagłówkach określających format danych.

**Przykładowy szkielet żądania HTTP:**


```http
POST /api/endpoint HTTP/1.1
Host: api.simpay.pl
Authorization: Bearer TWÓJ_KLUCZ_API
Accept: application/json
Content-Type: application/json
```

## 2. Bezpieczeństwo klucza API

Twój klucz API to wirtualny odpowiednik kluczy do Twojej firmy – daje dostęp do generowania transakcji, a nawet zlecania zwrotów środków. Traktuj go z najwyższą ostrożnością.

Ważne zasady bezpieczeństwa
* **Nigdy nie udostępniaj klucza API po stronie klienta (Frontend).** Klucz nie może znaleźć się w kodzie JavaScript (React, Vue, Angular) ani w aplikacjach mobilnych. Komunikacja z SimPay musi zawsze odbywać się z poziomu Twojego serwera (Backend).
* **Nie commituj klucza do repozytorium kodu.** Używaj zmiennych środowiskowych (np. plików `.env`), które są ignorowane przez systemy kontroli wersji (Git).


## 3. Limitowanie i uprawnienia klucza

SimPay oferuje potężne narzędzia do granulacji dostępu, które pozwalają zminimalizować ryzyko w przypadku wycieku klucza. Zdecydowanie zalecamy korzystanie z nich przy generowaniu tokenów w Panelu Klienta:

### Uprawnienia (Abilities)

Zamiast tworzyć jeden klucz do wszystkiego ("God Mode"), twórz klucze dedykowane konkretnym zadaniom. Jeśli klucz ma służyć tylko do generowania nowych płatności online na stronie sklepu, odznacz mu uprawnienia do obsługi zwrotów (Refunds) czy przeglądania historii transakcji.

### Restrykcje adresów IP (Whitelist)

To najsilniejsze zabezpieczenie. W ustawieniach klucza możesz zdefiniować dokładne adresy IP Twoich serwerów. Jeśli ktoś wykradnie Twój klucz API i spróbuje go użyć z innego komputera, nasze API natychmiast odrzuci takie żądanie (błąd 403).

## 4. Kody błędów (HTTP Status Codes)

Nasze API używa standardowych kodów statusu HTTP, aby poinformować Cię o wyniku operacji. Kody z grupy `2xx` oznaczają sukces, natomiast `4xx` wskazują na błąd po stronie Twojego żądania.

Każda odpowiedź z błędem zawiera obiekt JSON z polem `errorCode` ułatwiającym debugowanie. W przypadku błędów walidacji (422), dodatkowo zwracamy obiekt `errors` z listą nieprawidłowych pól.

| Kod HTTP | Typ błędu | Opis | Przykładowe `errorCode` |
|  --- | --- | --- | --- |
| **`200 OK`** | Sukces | Żądanie zostało przetworzone poprawnie. | - |
| **`401 Unauthorized`** | Brak autoryzacji | Nie podano tokenu API w nagłówku lub jest on nieprawidłowy/wygasły. | `UNAUTHORIZED` |
| **`403 Forbidden`** | Brak dostępu | Twój token nie ma odpowiednich uprawnień (Abilities) do wykonania tej akcji, lub żądanie przyszło z adresu IP spoza białej listy. | `INVALID_ABILITY_PROVIDED`, `IP_ADDRESS_NOT_WHITELISTED` |
| **`404 Not Found`** | Nie znaleziono | Próbujesz odpytać nieistniejący endpoint, albo podano błędne ID usługi/transakcji w URL. | `ROUTE_NOT_FOUND`, `SERVICE_NOT_FOUND`, `TRANSACTION_NOT_FOUND` |
| **`422 Unprocessable Entity`** | Błąd walidacji | Wysłane dane są niekompletne lub mają zły format (np. brak wymaganej kwoty `amount` lub niepoprawna waluta). | `VALIDATION_ERROR` |


**Przykład odpowiedzi dla błędu 422 (VALIDATION_ERROR):**


```json
{
  "success": false,
  "errorCode": "VALIDATION_ERROR",
  "errors": {
    "amount": [
      "The amount field is required."
    ],
    "currency": [
      "The selected currency is invalid."
    ]
  }
}
```

## Co dalej?

Znasz już zasady komunikacji i potrafisz prawidłowo autoryzować swoje żądania. Czas przejść do generowania prawdziwych transakcji!

Wybierz moduł, z którym chcesz się zintegrować:

* 👉 **[Płatności Online (Przelewy, BLIK, Karty)](/payment)**
* 👉 **[Obsługa Notyfikacji IPN](/notifications/payment)**
* 👉 **[Płatności DirectBilling (DCB)](/directbilling)**
* 👉 **[Płatności SMS Premium](/sms)**