API do skracania linków dla firm
API do skracania linków tworzy krótkie linki prosto z Twojego systemu: sklepu, CRM albo bramki SMS. Zmieniasz cel bez zmiany linku, pobierasz statystyki kliknięć i co minutę dostajesz webhook z nowymi kliknięciami. Prosty JSON, klucz z panelu, własna domena.
Pierwsze zapytanie
Klucz, nagłówek i gotowe
Klucz API tworzysz w panelu, w zakładce API. Każde zapytanie wysyłasz z nagłówkiem Authorization: Bearer nl_.... Adres bazowy to https://naszlink.pl/api/v1, a zapytania i odpowiedzi są w formacie JSON, w kodowaniu UTF-8.
Link utworzony przez API działa dokładnie tak jak link z panelu. Ma statystyki, kod QR, możesz go przypisać do kampanii i zmienić mu cel. Gdy podasz pole host, powstaje pod Twoją domeną, opisaną na stronie skracacz linków z własną domeną.
- Klucze z nazwą i datą użycia
- Wyłączenie klucza jednym kliknięciem
- Alias do 50 znaków
- Skan celu przy każdym zapisie
curl -X POST https://naszlink.pl/api/v1/linki \
-H "Authorization: Bearer nl_TWOJ_KLUCZ" \
-H "Content-Type: application/json" \
-d '{
"cel": "https://twojafirma.pl/zamowienie/48213",
"kod": "zamowienie-48213",
"tytul": "SMS status zamówienia",
"host": "link.twojafirma.pl"
}'{
"id": 91827,
"kod": "zamowienie-48213",
"url": "https://link.twojafirma.pl/zamowienie-48213",
"cel": "https://twojafirma.pl/zamowienie/48213",
"tytul": "SMS status zamówienia",
"host": "link.twojafirma.pl",
"status": "aktywny",
"klikniecia": 0,
"utworzono": "2026-10-08T09:14:02+02:00"
}Endpointy API
Pięć endpointów obsługuje cały cykl życia linku. Lista jest stronicowana parametrami page i per_page (domyślnie 50, najwyżej 200 linków na stronę).
| Metoda | Ścieżka | Co robi |
|---|---|---|
| GET | /linki | Lista linków firmy, od najnowszych, ze stronicowaniem |
| POST | /linki | Nowy link. Pole cel wymagane, kod (alias), tytul i host opcjonalne |
| GET | /linki/{id} | Jeden link z liczbą kliknięć |
| PATCH | /linki/{id} | Zmiana celu, tytułu albo statusu (aktywny, wylaczony) |
| GET | /linki/{id}/statystyki | Kliknięcia według dni, krajów, miast, urządzeń i źródeł |
| Pole JSON | Typ | Opis |
|---|---|---|
| id | liczba | Stały identyfikator linku |
| kod | tekst | Końcówka linku, do 50 znaków: litery, cyfry, myślnik, podkreślnik |
| cel | tekst | Adres docelowy z https albo http |
| tytul | tekst | Nazwa widoczna w panelu i raportach |
| host | tekst | Domena linku, naszlink.pl albo Twoja domena |
| status | tekst | aktywny, wylaczony albo wygasl |
| klikniecia | liczba | Kliknięcia od utworzenia, bez botów i podglądów linków |
| utworzono | data | Czas utworzenia w formacie ISO 8601 |
curl -X PATCH https://naszlink.pl/api/v1/linki/91827 \
-H "Authorization: Bearer nl_TWOJ_KLUCZ" \
-H "Content-Type: application/json" \
-d '{"cel": "https://twojafirma.pl/zamowienie/48213/odbior"}'curl "https://naszlink.pl/api/v1/linki/91827/statystyki?od=2026-09-08&do=2026-10-08" \
-H "Authorization: Bearer nl_TWOJ_KLUCZ"Limity i błędy
Przewidywalne odpowiedzi
Plan Agencja ma limit 60 zapytań na minutę na firmę, plan Enterprise 600 zapytań na minutę. Po przekroczeniu limitu dostajesz kod 429 i nagłówek Retry-After z liczbą sekund do kolejnej próby. Każdy błąd ma ten sam kształt, więc obsłużysz go jednym fragmentem kodu.
| Kod | Znaczenie |
|---|---|
| 401 | Brak klucza albo klucz wyłączony |
| 403 | Plan bez API albo domena spoza Twojej firmy |
| 404 | Link nie istnieje albo należy do innej firmy |
| 422 | Błąd walidacji, zajęty alias, cel na liście ostrzeżeń, wyczerpany limit linków |
| 429 | Za dużo zapytań, sprawdź Retry-After |
{
"blad": "walidacja",
"komunikat": "Popraw zaznaczone pola.",
"pola": {
"kod": ["Ten alias jest już zajęty w domenie link.twojafirma.pl."],
"cel": ["Adres musi zaczynać się od https:// albo http://."]
}
}HTTP/1.1 429 Too Many Requests
Retry-After: 18
{"blad": "limit", "komunikat": "Limit 60 zapytań na minutę."}Webhooki kliknięć z podpisem
W zakładce API dodajesz adres URL i dostajesz sekret. Co minutę wysyłamy na ten adres zapytanie POST z nowymi kliknięciami, zebranymi w jedno zdarzenie (do 500 kliknięć w jednym zapytaniu). Nagłówek X-NaszLink-Podpis zawiera podpis HMAC-SHA256 surowego ciała zapytania, liczony Twoim sekretem i zapisany szesnastkowo. Sprawdź podpis, zanim przetworzysz dane. Gdy Twój serwer nie odpowie kodem 2xx w ciągu 10 sekund, ponawiamy wysyłkę do 5 razy z rosnącym odstępem.
{
"id": "zd_7f3a91c2kq0m4x1p",
"typ": "klikniecie",
"czas": "2026-10-08T09:22:00+02:00",
"liczba": 1,
"klikniecia": [{
"link_id": 91827,
"kod": "zamowienie-48213",
"host": "naszlink.pl",
"czas": "2026-10-08T09:21:47+02:00",
"kraj": "PL",
"miasto": "Poznań",
"urzadzenie": "mobile",
"zrodlo": null,
"qr": false,
"utm": {"utm_source": "sms"}
}]
}$cialo = file_get_contents('php://input');
$sekret = getenv('NASZLINK_SEKRET');
$podpis = $_SERVER['HTTP_X_NASZLINK_PODPIS'] ?? '';
$oczekiwany = hash_hmac('sha256', $cialo, $sekret);
if (hash_equals($oczekiwany, $podpis) === false) {
http_response_code(401);
exit;
}
$zdarzenie = json_decode($cialo, true);
http_response_code(200);const crypto = require('crypto');
function podpisPoprawny(surowe, podpis, sekret) {
const oczekiwany = crypto
.createHmac('sha256', sekret)
.update(surowe)
.digest('hex');
const a = Buffer.from(oczekiwany);
const b = Buffer.from(podpis || '');
return a.length === b.length
&& crypto.timingSafeEqual(a, b);
}
// surowe = ciało zapytania przed JSON.parse
Zastosowania
Gdzie firmy wpinają API
SMS transakcyjne
Sklep tworzy osobny krótki link do każdego zamówienia i wkłada go w SMS o statusie. Link mieści się w jednej wiadomości, a Ty widzisz, ile osób go otworzyło.
Powiadomienia i maile
System przypomnień generuje link z tytułem i kampanią. Gdy adres strony się zmieni, poprawiasz cel jednym zapytaniem PATCH, bez ponownej wysyłki.
CRM i sprzedaż
Handlowiec wysyła ofertę z linkiem utworzonym w CRM. Webhook kliknięć w ciągu minuty zapisuje w karcie klienta, że oferta została otwarta.
Dane z API i webhooków to te same statystyki kliknięć linków, które widzisz w panelu. API jest w planach Agencja i Enterprise, szczegóły w cenniku skracacza linków.
Pytania o API
Pytania techniczne wysyłaj na kontakt@naszlink.pl.
W którym planie jest API do skracania linków?
API i webhooki kliknięć są w planach Agencja i Enterprise. Agencja ma limit 60 zapytań na minutę, Enterprise 600 zapytań na minutę. Linki utworzone przez API liczą się do tego samego miesięcznego limitu nowych linków co linki z panelu.
Gdzie znajdę klucz API?
W panelu, w zakładce API. Klucz zaczyna się od nl_ i widzisz go w całości tylko raz, zaraz po utworzeniu. Możesz mieć kilka kluczy, na przykład osobny dla sklepu i dla CRM, i w każdej chwili wyłączyć jeden z nich bez ruszania pozostałych.
Czy przez API mogę tworzyć linki pod własną domeną?
Tak. W polu host podajesz domenę podpiętą w panelu, na przykład link.twojafirma.pl. Gdy pole pominiesz, link powstaje pod domeną naszlink.pl. Domena musi mieć zweryfikowany rekord CNAME i aktywny certyfikat.
Czy link utworzony przez API jest sprawdzany pod kątem nadużyć?
Tak, tak samo jak link z panelu. Każdy cel skanujemy przy utworzeniu i przy każdej zmianie. Gdy cel trafi na listę ostrzeżeń, API zwraca błąd 422 z opisem, a link nie powstaje.
Co się stanie, gdy mój serwer nie odbierze webhooka?
Ponawiamy wysyłkę zdarzenia, gdy Twój adres odpowie kodem innym niż 2xx albo nie odpowie w ciągu 10 sekund. Robimy to do 5 razy, z rosnącym odstępem od 1 minuty do kilku godzin. Każde zdarzenie ma unikalne id, więc łatwo pominiesz duplikaty.
Czy API zwraca dane osobowe klikających?
Nie. Statystyki pokazują kraj, miasto, urządzenie, system, przeglądarkę i źródło. Adresów IP nie zapisujemy w pełnej postaci, więc nie ma ich ani w API, ani w webhookach.
Pierwszy link z API jeszcze dziś
Załóż konto firmy z NIP, wybierz plan Agencja albo Enterprise i utwórz klucz w zakładce API. Bez rozmów handlowych i czekania.