Przejście do treści

REST API · v1

REST API FalconCard

Zarządzanie wizytówkami, leadami i analityką programowo — na potrzeby synchronizacji z CRM, automatyzacji i własnych integracji. Uwierzytelnianie tokenem Bearer, JSON przez HTTPS.

01

Pierwsze kroki

Od tokenu do pierwszego udanego żądania w trzech krokach. API komunikuje się wyłącznie w formacie JSON przez HTTPS i stosuje powszechne konwencje REST — jeśli kiedykolwiek integrowali Państwo API HTTP, poczują się Państwo jak w domu.

  1. Utworzenie tokenu

    Proszę otworzyć panel i przejść do Konto → Tokeny API. Proszę wybrać zakresy potrzebne Państwa integracji i od razu skopiować token — ze względów bezpieczeństwa jest on wyświetlany jawnie tylko raz.

    Przejście do tokenów API
  2. Ustawienie nagłówka Bearer

    Proszę przesyłać token w nagłówku Authorization przy każdym żądaniu. Proszę dodać Accept: application/json, aby błędy również wracały w formacie JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Wysłanie pierwszego żądania

    Proszę pobrać swoje wizytówki. Udane wywołanie zwraca HTTP 200 z tablicą data oraz obiektem meta dla paginacji:

cURL
curl https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
Odpowiedź · 200 OK
{
  "data": [
    {
      "id": 42,
      "slug": "max-mustermann-a1b2",
      "title": "Max Mustermann",
      "first_name": "Max",
      "last_name": "Mustermann",
      "status": "active",
      "is_public": true,
      "public_url": "https://falconcard.net/c/max-mustermann-a1b2",
      "updated_at": "2026-06-12T10:30:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1
  }
}

Jeśli widzą Państwo taką strukturę, Państwa uwierzytelnianie jest poprawne. Każdy endpoint listy odpowiada tym samym schematem data + meta — pojedyncze zasoby wracają w obiekcie data bez meta.

Bazowy adres URL: https://falconcard.net/api/v1 · wszystkie odpowiedzi są w formacie JSON.

02

Uwierzytelnianie

Każde żądanie jest uwierzytelniane osobistym tokenem dostępu (Laravel Sanctum) w nagłówku:

Authorization: Bearer DEIN_API_TOKEN

Tokeny mogą Państwo tworzyć i unieważniać w dowolnej chwili w panelu. Każdy token ma jeden lub więcej zakresów ograniczających jego uprawnienia.

Zakresy

cards:read

Wyświetlanie listy i odczyt wizytówek

cards:write

Tworzenie, aktualizowanie i usuwanie wizytówek

leads:read

Wyświetlanie listy i odczyt leadów

analytics:read

Odczyt analityki wyświetleń i kliknięć

03

Koncepcje

Cztery elementy działające identycznie dla każdego endpointu — wystarczy poznać je raz, a obowiązują wszędzie.

Wersjonowanie

Aktualna wersja to /api/v1 i jest zakotwiczona w ścieżce. Zmiany niekompatybilne wstecz pojawiają się pod nowym prefiksem (np. /api/v2), dzięki czemu istniejące integracje pozostają stabilne.

Format żądania

Endpointy zapisu oczekują treści JSON z nagłówkiem Content-Type: application/json. Znaczniki czasu są w formacie ISO 8601 (UTC). Nieznane pola są ignorowane, pominięte pola opcjonalne pozostają bez zmian.

Limitowanie zapytań

Tokeny Enterprise mogą wysyłać 1000 żądań na minutę. Każda odpowiedź zawiera X-RateLimit-Limit oraz X-RateLimit-Remaining. Po przekroczeniu otrzymają Państwo 429 Too Many Requests z nagłówkiem Retry-After (sekundy do resetu) — proszę odczekać tyle przed ponowieniem.

Nagłówki · każda odpowiedź
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginacja

Endpointy listy zwracają do 15 elementów na stronę. Mogą Państwo tym sterować za pomocą ?page= (liczone od 1) oraz ?per_page= (maks. 100). Obiekt meta podaje current_page, last_page, per_page i total.

meta · każda lista
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Dostępność. REST API jest częścią planu Enterprise. Tokeny z innych planów otrzymują 403.

04

Dokumentacja endpointów

Pełna dokumentacja wszystkich dziesięciu endpointów, pogrupowanych według zasobu. Każda definicja pozostaje zsynchronizowana ze specyfikacją OpenAPI — gotową do zaimportowania do Postman, Insomnia, Scalar lub generatora kodu.

01

Cards

Tworzenie, odczyt, aktualizacja i usuwanie cyfrowych wizytówek biznesowych.

GET
/api/v1/cards Zakres cards:read

Wyświetla wizytówki na koncie, od ostatnio zaktualizowanych.

Parametry

Nazwa W Typ Wymagane Opis
page query integer nie Numer strony (liczony od 1).
per_page query integer nie Elementy na stronę, maks. 100.

Odpowiedź pomyślna

200 OK z tablicą data wizytówek oraz obiektem meta dla paginacji.

Kody błędów

401403429
POST
/api/v1/cards Zakres cards:write

Tworzy nową wizytówkę. slug i title są generowane automatycznie. Pola zależne od planu są sprowadzane do dozwolonych wartości.

Parametry

Brak parametrów.

Treść żądania application/json

Pole Typ Ograniczenia Opis
first_name Wymagane string maxLength 100 Imię.
last_name Wymagane string maxLength 100 Nazwisko.
job_title string | null maxLength 150 Stanowisko / tytuł zawodowy.
company string | null maxLength 150 Nazwa firmy.
bio string | null maxLength 1000 Krótki opis / biogram.
email string | null email · maxLength 255 E-mail kontaktowy (prawidłowy format adresu e-mail).
phone string | null maxLength 50 Numer telefonu. Dozwolone znaki: cyfry, spacje oraz + - ( ) . /
website string | null uri · maxLength 500 Adres URL strony internetowej.
booking_url string | null uri · maxLength 500 Link do rezerwacji terminu.
video_url string | null uri · maxLength 500 Adres URL wideo. Wymaga funkcji zaawansowanej analityki, w przeciwnym razie ignorowany. zależne od planu
address string | null maxLength 500 Adres pocztowy.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista linków do mediów społecznościowych (tablica obiektów).
design_config object | null — Nadpisania wyglądu (kolory, czcionka, układ) jako obiekt.
template_id string | null maxLength 50 ID szablonu do użycia.
is_public boolean | null default true Czy wizytówka jest publicznie dostępna. Domyślnie true.
show_branding boolean | null — Wyświetlanie brandingu FalconCard. Ukrycie wymaga funkcji whitelabel, w przeciwnym razie wymuszane na true. zależne od planu
show_lead_form boolean | null — Wyświetlanie formularza leadów na wizytówce. Wymaga funkcji formularza leadów, w przeciwnym razie wymuszane na false. zależne od planu
seo_title string | null maxLength 100 Tytuł SEO publicznej wizytówki.
seo_description string | null maxLength 250 Meta opis SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Główny język wizytówki (np. de).

Odpowiedź pomyślna

201 Created z nową wizytówką w obiekcie data oraz komunikatem.

Kody błędów

401403422429
GET
/api/v1/cards/{card} Zakres cards:read

Zwraca pojedynczą wizytówkę wraz z zarejestrowanymi leadami.

Parametry

Nazwa W Typ Wymagane Opis
card ścieżka integer tak ID wizytówki.

Odpowiedź pomyślna

200 OK z wizytówką (zawierającą osadzoną tablicę leads) w obiekcie data.

Kody błędów

401403404429
PUT
/api/v1/cards/{card} Zakres cards:write

Aktualizuje wizytówkę. Wszystkie pola są opcjonalne; zmieniają się tylko przekazane pola. PUT i PATCH działają identycznie.

Parametry

Nazwa W Typ Wymagane Opis
card ścieżka integer tak ID wizytówki.

Treść żądania application/json

Pole Typ Ograniczenia Opis
first_name string maxLength 100 Imię.
last_name string maxLength 100 Nazwisko.
job_title string | null maxLength 150 Stanowisko / tytuł zawodowy.
company string | null maxLength 150 Nazwa firmy.
bio string | null maxLength 1000 Krótki opis / biogram.
email string | null email · maxLength 255 E-mail kontaktowy (prawidłowy format adresu e-mail).
phone string | null maxLength 50 Numer telefonu. Dozwolone znaki: cyfry, spacje oraz + - ( ) . /
website string | null uri · maxLength 500 Adres URL strony internetowej.
booking_url string | null uri · maxLength 500 Link do rezerwacji terminu.
video_url string | null uri · maxLength 500 Adres URL wideo. Wymaga funkcji zaawansowanej analityki, w przeciwnym razie ignorowany. zależne od planu
address string | null maxLength 500 Adres pocztowy.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista linków do mediów społecznościowych (tablica obiektów).
design_config object | null — Nadpisania wyglądu (kolory, czcionka, układ) jako obiekt.
template_id string | null maxLength 50 ID szablonu do użycia.
is_public boolean | null — Czy wizytówka jest publicznie dostępna. Domyślnie true.
show_branding boolean | null — Wyświetlanie brandingu FalconCard. Ukrycie wymaga funkcji whitelabel, w przeciwnym razie wymuszane na true. zależne od planu
show_lead_form boolean | null — Wyświetlanie formularza leadów na wizytówce. Wymaga funkcji formularza leadów, w przeciwnym razie wymuszane na false. zależne od planu
seo_title string | null maxLength 100 Tytuł SEO publicznej wizytówki.
seo_description string | null maxLength 250 Meta opis SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Główny język wizytówki (np. de).
status string | null enum: active, draft, archived Status publikacji: active, draft lub archived.

Odpowiedź pomyślna

200 OK ze zaktualizowaną wizytówką w obiekcie data oraz komunikatem.

Kody błędów

401403404422429
PATCH
/api/v1/cards/{card} Zakres cards:write

Aktualizuje wizytówkę. Wszystkie pola są opcjonalne; zmieniają się tylko przekazane pola. PUT i PATCH działają identycznie.

Parametry

Nazwa W Typ Wymagane Opis
card ścieżka integer tak ID wizytówki.

Treść żądania application/json

Pole Typ Ograniczenia Opis
first_name string maxLength 100 Imię.
last_name string maxLength 100 Nazwisko.
job_title string | null maxLength 150 Stanowisko / tytuł zawodowy.
company string | null maxLength 150 Nazwa firmy.
bio string | null maxLength 1000 Krótki opis / biogram.
email string | null email · maxLength 255 E-mail kontaktowy (prawidłowy format adresu e-mail).
phone string | null maxLength 50 Numer telefonu. Dozwolone znaki: cyfry, spacje oraz + - ( ) . /
website string | null uri · maxLength 500 Adres URL strony internetowej.
booking_url string | null uri · maxLength 500 Link do rezerwacji terminu.
video_url string | null uri · maxLength 500 Adres URL wideo. Wymaga funkcji zaawansowanej analityki, w przeciwnym razie ignorowany. zależne od planu
address string | null maxLength 500 Adres pocztowy.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista linków do mediów społecznościowych (tablica obiektów).
design_config object | null — Nadpisania wyglądu (kolory, czcionka, układ) jako obiekt.
template_id string | null maxLength 50 ID szablonu do użycia.
is_public boolean | null — Czy wizytówka jest publicznie dostępna. Domyślnie true.
show_branding boolean | null — Wyświetlanie brandingu FalconCard. Ukrycie wymaga funkcji whitelabel, w przeciwnym razie wymuszane na true. zależne od planu
show_lead_form boolean | null — Wyświetlanie formularza leadów na wizytówce. Wymaga funkcji formularza leadów, w przeciwnym razie wymuszane na false. zależne od planu
seo_title string | null maxLength 100 Tytuł SEO publicznej wizytówki.
seo_description string | null maxLength 250 Meta opis SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Główny język wizytówki (np. de).
status string | null enum: active, draft, archived Status publikacji: active, draft lub archived.

Odpowiedź pomyślna

200 OK ze zaktualizowaną wizytówką w obiekcie data oraz komunikatem.

Kody błędów

401403404422429
DELETE
/api/v1/cards/{card} Zakres cards:write

Trwale usuwa wizytówkę.

Parametry

Nazwa W Typ Wymagane Opis
card ścieżka integer tak ID wizytówki.

Odpowiedź pomyślna

200 OK z komunikatem potwierdzającym.

Kody błędów

401403404429
02

Leads

Odczyt kontaktów zarejestrowanych przez formularze leadów na Państwa wizytówkach.

GET
/api/v1/leads Zakres leads:read

Wyświetla leady zarejestrowane na wszystkich wizytówkach, od najnowszych. Filtrowanie do jednej wizytówki za pomocą card_id.

Parametry

Nazwa W Typ Wymagane Opis
card_id query integer nie Ograniczenie do jednej posiadanej wizytówki.
page query integer nie Numer strony (liczony od 1).
per_page query integer nie Elementy na stronę, maks. 100.

Odpowiedź pomyślna

200 OK z tablicą data leadów oraz obiektem meta.

Kody błędów

401403429
GET
/api/v1/leads/{id} Zakres leads:read

Zwraca pojedynczy lead z kompaktowym odwołaniem do rejestrującej wizytówki.

Parametry

Nazwa W Typ Wymagane Opis
id ścieżka integer tak ID leada.

Odpowiedź pomyślna

200 OK z leadem w obiekcie data.

Kody błędów

401403404429
03

Analytics

Zagregowane statystyki wyświetleń i kliknięć — dla wszystkich wizytówek lub w przeliczeniu na wizytówkę.

GET
/api/v1/analytics/views Zakres analytics:read

Zagregowane metryki wyświetleń dla wszystkich wizytówek lub — za pomocą card_id — dla pojedynczej wizytówki.

Parametry

Nazwa W Typ Wymagane Opis
card_id query integer nie Ograniczenie do jednej posiadanej wizytówki.
period query string (enum) nie Okres raportowania. Dozwolone: 7d, 14d, 30d, 90d, 365d. Domyślnie 30d.

Odpowiedź pomyślna

200 OK z total_views, unique_views, views_per_day oraz devices, countries i referrers w obiekcie data.

Kody błędów

401403422429
GET
/api/v1/analytics/clicks Zakres analytics:read

Zagregowane metryki kliknięć dla wszystkich wizytówek lub — za pomocą card_id — dla pojedynczej wizytówki.

Parametry

Nazwa W Typ Wymagane Opis
card_id query integer nie Ograniczenie do jednej posiadanej wizytówki.
period query string (enum) nie Okres raportowania. Dozwolone: 7d, 14d, 30d, 90d, 365d. Domyślnie 30d.

Odpowiedź pomyślna

200 OK z total_clicks, clicks_by_type i clicks_per_day w obiekcie data.

Kody błędów

401403422429

05

Przykłady kodu

Gotowe do skopiowania fragmenty w cURL, JavaScript i Python. Proszę zastąpić DEIN_API_TOKEN swoim prawdziwym tokenem.

Lista wizytówek
curl https://falconcard.net/api/v1/cards?per_page=15 \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
const res = await fetch("https://falconcard.net/api/v1/cards?per_page=15", {
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    Accept: "application/json",
  },
});
const { data, meta } = await res.json();
console.log(data, meta);
import requests

res = requests.get(
    "https://falconcard.net/api/v1/cards",
    params={"per_page": 15},
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
)
res.raise_for_status()
payload = res.json()
print(payload["data"], payload["meta"])
Utworzenie wizytówki
curl -X POST https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Max",
    "last_name": "Mustermann",
    "job_title": "Geschäftsführer",
    "company": "FalconCard",
    "email": "max@example.com"
  }'
const res = await fetch("https://falconcard.net/api/v1/cards", {
  method: "POST",
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    first_name: "Max",
    last_name: "Mustermann",
    job_title: "Geschäftsführer",
    company: "FalconCard",
    email: "max@example.com",
  }),
});
const { data, message } = await res.json();
import requests

res = requests.post(
    "https://falconcard.net/api/v1/cards",
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
    json={
        "first_name": "Max",
        "last_name": "Mustermann",
        "job_title": "Geschäftsführer",
        "company": "FalconCard",
        "email": "max@example.com",
    },
)
res.raise_for_status()
print(res.json()["data"]["id"])
Lista leadów
curl "https://falconcard.net/api/v1/leads?card_id=42&per_page=50" \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
const params = new URLSearchParams({ card_id: "42", per_page: "50" });
const res = await fetch(`https://falconcard.net/api/v1/leads?${params}`, {
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    Accept: "application/json",
  },
});
const { data } = await res.json();
import requests

res = requests.get(
    "https://falconcard.net/api/v1/leads",
    params={"card_id": 42, "per_page": 50},
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
)
res.raise_for_status()
for lead in res.json()["data"]:
    print(lead["name"], lead["email"])
Pobranie analityki
curl "https://falconcard.net/api/v1/analytics/views?card_id=42&period=30d" \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
const params = new URLSearchParams({ card_id: "42", period: "30d" });
const res = await fetch(`https://falconcard.net/api/v1/analytics/views?${params}`, {
  headers: {
    Authorization: "Bearer DEIN_API_TOKEN",
    Accept: "application/json",
  },
});
const { data } = await res.json();
console.log(data.total_views, data.unique_views);
import requests

res = requests.get(
    "https://falconcard.net/api/v1/analytics/views",
    params={"card_id": 42, "period": "30d"},
    headers={"Authorization": "Bearer DEIN_API_TOKEN"},
)
res.raise_for_status()
stats = res.json()["data"]
print(stats["total_views"], stats["unique_views"])

Przykład: utworzenie wizytówki

Żądanie · cURL
curl -X POST https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Max",
    "last_name": "Mustermann",
    "job_title": "Geschäftsführer",
    "company": "FalconCard",
    "email": "max@example.com"
  }'
Odpowiedź · 201
{
  "data": {
    "id": 42,
    "slug": "max-mustermann-a1b2",
    "title": "Max Mustermann",
    "first_name": "Max",
    "last_name": "Mustermann",
    "status": "active",
    "is_public": true,
    "public_url": "https://falconcard.net/c/max-mustermann-a1b2",
    "created_at": "2026-06-12T10:30:00+00:00"
  },
  "message": "Karte erfolgreich erstellt."
}

06

Błędy

Każdy błąd zwraca ciąg message. Błędy walidacji (422)zawierają dodatkowo mapę errors.

Status Name Opis Przykładowa treść
401 Unauthorized Brak tokenu lub token nieprawidłowy.
{ "message": "Unauthenticated." }
403 Forbidden Plan nie obejmuje dostępu do API (tylko Enterprise) lub token nie ma wymaganego zakresu.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Zasób nie istnieje lub nie należy do Państwa konta.
{ "message": "Not found." }
422 Unprocessable Entity Walidacja nie powiodła się — treść zawiera mapę errors (pole → komunikaty).
429 Too Many Requests Przekroczono limit zapytań. Nagłówek Retry-After podaje czas oczekiwania w sekundach.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 zawierają dodatkowo mapę errors w postaci pole → lista komunikatów:

422 Unprocessable Entity
{
  "message": "The last name field is required.",
  "errors": {
    "last_name": ["The last name field is required."],
    "email": ["The email must be a valid email address."]
  }
}

07

Specyfikacja czytelna maszynowo

Całe API jest udokumentowane w formacie OpenAPI 3.1. Mogą Państwo pobrać specyfikację i zaimportować ją do Postman, Insomnia lub Scalar — albo wygenerować na jej podstawie bezpieczne typowo klienty dla swojego języka.

Kompatybilne z Postman · Insomnia · Scalar · generatorami OpenAPI

Pobranie openapi.json

08

Czy są Państwo gotowi na integrację?

Mogą Państwo zaimportować specyfikację OpenAPI do swoich narzędzi lub utworzyć pierwszy token API bezpośrednio w panelu.