{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Szybki start: Autoryzacja i podstawy API","description":"Znajdziesz tutaj wszystkie niezbędne informacje dotyczące integracji i obsługi systemu płatności SimPay.pl","siteUrl":"https://docs.simpay.pl","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"szybki-start-autoryzacja-i-podstawy-api","__idx":0},"children":["Szybki start: Autoryzacja i podstawy API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nasze API zostało zaprojektowane w architekturze REST, a wymiana danych odbywa się wyłącznie w formacie ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JSON"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-pobranie-i-przesyłanie-klucza-api","__idx":1},"children":["1. Pobranie i przesyłanie klucza API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dostęp do API jest chroniony. Aby móc wysyłać do nas żądania, potrzebujesz unikalnego klucza dostępu (Bearer Token)."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Zaloguj się do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Panelu Klienta SimPay"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Przejdź do zakładki ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Moje Konto > Klucze API"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wygeneruj nowy klucz i skopiuj jego wartość."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wygenerowany token musisz dołączać do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["każdego"]}," żądania wysyłanego do naszego API, używając nagłówka ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]},". Pamiętaj również o odpowiednich nagłówkach określających format danych."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Przykładowy szkielet żądania HTTP:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /api/endpoint HTTP/1.1\nHost: api.simpay.pl\nAuthorization: Bearer TWÓJ_KLUCZ_API\nAccept: application/json\nContent-Type: application/json\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-bezpieczeństwo-klucza-api","__idx":2},"children":["2. Bezpieczeństwo klucza API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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ą."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Ważne zasady bezpieczeństwa"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Nie commituj klucza do repozytorium kodu."]}," Używaj zmiennych środowiskowych (np. plików ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]},"), które są ignorowane przez systemy kontroli wersji (Git)."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-limitowanie-i-uprawnienia-klucza","__idx":3},"children":["3. Limitowanie i uprawnienia klucza"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"uprawnienia-abilities","__idx":4},"children":["Uprawnienia (Abilities)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"restrykcje-adresów-ip-whitelist","__idx":5},"children":["Restrykcje adresów IP (Whitelist)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-kody-błędów-http-status-codes","__idx":6},"children":["4. Kody błędów (HTTP Status Codes)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nasze API używa standardowych kodów statusu HTTP, aby poinformować Cię o wyniku operacji. Kody z grupy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," oznaczają sukces, natomiast ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," wskazują na błąd po stronie Twojego żądania."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Każda odpowiedź z błędem zawiera obiekt JSON z polem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," ułatwiającym debugowanie. W przypadku błędów walidacji (422), dodatkowo zwracamy obiekt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," z listą nieprawidłowych pól."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Kod HTTP"},"children":["Kod HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Typ błędu"},"children":["Typ błędu"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Opis"},"children":["Opis"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Przykładowe errorCode"},"children":["Przykładowe ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sukces"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Żądanie zostało przetworzone poprawnie."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Brak autoryzacji"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Nie podano tokenu API w nagłówku lub jest on nieprawidłowy/wygasły."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Brak dostępu"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Twój token nie ma odpowiednich uprawnień (Abilities) do wykonania tej akcji, lub żądanie przyszło z adresu IP spoza białej listy."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ABILITY_PROVIDED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IP_ADDRESS_NOT_WHITELISTED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Nie znaleziono"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Próbujesz odpytać nieistniejący endpoint, albo podano błędne ID usługi/transakcji w URL."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROUTE_NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SERVICE_NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_NOT_FOUND"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 Unprocessable Entity"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Błąd walidacji"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Wysłane dane są niekompletne lub mają zły format (np. brak wymaganej kwoty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," lub niepoprawna waluta)."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATION_ERROR"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Przykład odpowiedzi dla błędu 422 (VALIDATION_ERROR):"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"errorCode\": \"VALIDATION_ERROR\",\n  \"errors\": {\n    \"amount\": [\n      \"The amount field is required.\"\n    ],\n    \"currency\": [\n      \"The selected currency is invalid.\"\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"co-dalej","__idx":7},"children":["Co dalej?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Znasz już zasady komunikacji i potrafisz prawidłowo autoryzować swoje żądania. Czas przejść do generowania prawdziwych transakcji!"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wybierz moduł, z którym chcesz się zintegrować:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["👉 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payment"},"children":["Płatności Online (Przelewy, BLIK, Karty)"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["👉 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/notifications/payment"},"children":["Obsługa Notyfikacji IPN"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["👉 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/directbilling"},"children":["Płatności DirectBilling (DCB)"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["👉 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sms"},"children":["Płatności SMS Premium"]}]}]}]}]},"headings":[{"value":"Szybki start: Autoryzacja i podstawy API","id":"szybki-start-autoryzacja-i-podstawy-api","depth":1},{"value":"1. Pobranie i przesyłanie klucza API","id":"1-pobranie-i-przesyłanie-klucza-api","depth":2},{"value":"2. Bezpieczeństwo klucza API","id":"2-bezpieczeństwo-klucza-api","depth":2},{"value":"3. Limitowanie i uprawnienia klucza","id":"3-limitowanie-i-uprawnienia-klucza","depth":2},{"value":"Uprawnienia (Abilities)","id":"uprawnienia-abilities","depth":3},{"value":"Restrykcje adresów IP (Whitelist)","id":"restrykcje-adresów-ip-whitelist","depth":3},{"value":"4. Kody błędów (HTTP Status Codes)","id":"4-kody-błędów-http-status-codes","depth":2},{"value":"Co dalej?","id":"co-dalej","depth":2}],"frontmatter":{"seo":{"title":"Szybki start: Autoryzacja i podstawy API"}},"lastModified":"2026-05-12T14:41:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}