Prejsť na obsah

REST API · v1

FalconCard REST API

Spravujte vizitky, leady a analytiku programovo — pre synchronizáciu s CRM, automatizáciu a vlastné integrácie. Autentifikácia pomocou Bearer tokenu, JSON cez HTTPS.

01

Začíname

Od tokenu k prvej úspešnej požiadavke v troch krokoch. API komunikuje výhradne pomocou JSON cez HTTPS a riadi sa bežnými REST konvenciami — ak ste už niekedy integrovali HTTP API, budete sa cítiť ako doma.

  1. Vytvorte token

    Otvorte svoj dashboard a prejdite na Účet → API tokeny. Vyberte scopes, ktoré vaša integrácia potrebuje, a token si ihneď skopírujte — z bezpečnostných dôvodov sa v čitateľnej podobe zobrazí iba raz.

    Prejsť na API tokeny
  2. Nastavte Bearer hlavičku

    Token posielajte v hlavičke Authorization pri každej požiadavke. Pridajte Accept: application/json, aby sa aj chyby vracali ako JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Odošlite svoju prvú požiadavku

    Načítajte svoje vizitky. Úspešné volanie vráti HTTP 200 s poľom data a objektom meta pre stránkovanie:

cURL
curl https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
Odpoveď · 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
  }
}

Ak vidíte túto štruktúru, vaša autentifikácia je správna. Každý endpoint zoznamu odpovedá rovnakou schémou data + meta — jednotlivé zdroje sa vracajú v objekte data bez meta.

Základná URL: https://falconcard.net/api/v1 · všetky odpovede sú vo formáte JSON.

02

Autentifikácia

Každá požiadavka sa autentifikuje pomocou osobného prístupového tokenu (Laravel Sanctum) v hlavičke:

Authorization: Bearer DEIN_API_TOKEN

Tokeny môžete kedykoľvek vytvoriť a zrušiť v dashboarde. Každý token nesie jeden alebo viac scopes, ktoré obmedzujú jeho oprávnenia.

Scopes

cards:read

Zoznam a čítanie vizitiek

cards:write

Vytváranie, úprava a mazanie vizitiek

leads:read

Zoznam a čítanie leadov

analytics:read

Čítanie analytiky zobrazení a kliknutí

03

Koncepty

Štyri stavebné prvky, ktoré fungujú rovnako pre každý endpoint — naučte sa ich raz a platia všade.

Verzovanie

Aktuálna verzia je /api/v1 a je zafixovaná v ceste. Zmeny narúšajúce kompatibilitu prichádzajú pod novým prefixom (napr. /api/v2), takže existujúce integrácie zostávajú stabilné.

Formát požiadavky

Zapisovacie endpointy očakávajú telo JSON s Content-Type: application/json. Časové značky sú vo formáte ISO 8601 (UTC). Neznáme polia sa ignorujú, chýbajúce voliteľné polia zostávajú nezmenené.

Obmedzenie počtu požiadaviek (rate limiting)

Enterprise tokeny môžu poslať 1000 požiadaviek za minútu. Každá odpoveď nesie X-RateLimit-Limit a X-RateLimit-Remaining. Pri prekročení dostanete 429 Too Many Requests s hlavičkou Retry-After (sekundy do resetu) — pred opakovaním počkajte uvedený čas.

Hlavičky · každá odpoveď
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Stránkovanie

Endpointy zoznamov vracajú až 15 položiek na stranu. Riadite to pomocou ?page= (začína od 1) a ?per_page= (max 100). Objekt meta uvádza current_page, last_page, per_page a total.

meta · každý zoznam
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Dostupnosť. REST API je súčasťou plánu Enterprise. Tokeny z iných plánov dostanú 403.

04

Referencia endpointov

Úplná referencia pre všetkých desať endpointov, zoskupená podľa zdroja. Každá definícia zostáva synchronizovaná s OpenAPI špecifikáciou — pripravené na import do Postman, Insomnia, Scalar alebo vášho generátora kódu.

01

Cards

Vytváranie, čítanie, úprava a mazanie digitálnych vizitiek.

GET
/api/v1/cards Scope cards:read

Vypíše vizitky účtu, naposledy aktualizované ako prvé.

Parametre

Názov V Typ Povinné Popis
page query integer nie Číslo strany (začína od 1).
per_page query integer nie Počet položiek na stranu, max 100.

Úspešná odpoveď

200 OK s poľom data vizitiek a objektom meta pre stránkovanie.

Chybové kódy

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

Vytvorí novú vizitku. slug a title sa generujú automaticky. Polia obmedzené plánom sa prevedú na povolené hodnoty.

Parametre

Žiadne parametre.

Telo požiadavky application/json

Pole Typ Obmedzenia Popis
first_name Povinné string maxLength 100 Krstné meno.
last_name Povinné string maxLength 100 Priezvisko.
job_title string | null maxLength 150 Pozícia / pracovný titul.
company string | null maxLength 150 Názov spoločnosti.
bio string | null maxLength 1000 Krátky popis / bio.
email string | null email · maxLength 255 Kontaktný email (platný formát emailu).
phone string | null maxLength 50 Telefónne číslo. Povolené znaky: číslice, medzery a + - ( ) . /
website string | null uri · maxLength 500 URL webovej stránky.
booking_url string | null uri · maxLength 500 Odkaz na rezerváciu termínu.
video_url string | null uri · maxLength 500 URL videa. Vyžaduje funkciu pokročilej analytiky, inak sa ignoruje. obmedzené plánom
address string | null maxLength 500 Poštová adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Zoznam odkazov na sociálne siete (pole objektov).
design_config object | null — Prepísanie dizajnu (farby, font, rozloženie) ako objekt.
template_id string | null maxLength 50 ID šablóny, ktorá sa má použiť.
is_public boolean | null default true Či je vizitka verejne dostupná. Predvolene true.
show_branding boolean | null — Zobraziť branding FalconCard. Jeho skrytie vyžaduje funkciu whitelabel, inak je vynútené na true. obmedzené plánom
show_lead_form boolean | null — Zobraziť lead formulár na vizitke. Vyžaduje funkciu lead formulára, inak je vynútené na false. obmedzené plánom
seo_title string | null maxLength 100 SEO titulok pre verejnú vizitku.
seo_description string | null maxLength 250 SEO meta popis.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Primárny jazyk vizitky (napr. de).

Úspešná odpoveď

201 Created s novou vizitkou v objekte data plus správa.

Chybové kódy

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

Vráti jednu vizitku vrátane jej zachytených leadov.

Parametre

Názov V Typ Povinné Popis
card cesta integer áno ID vizitky.

Úspešná odpoveď

200 OK s vizitkou (vrátane vnoreného poľa leads) v objekte data.

Chybové kódy

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

Aktualizuje vizitku. Všetky polia sú voliteľné; zmenia sa iba poskytnuté polia. PUT a PATCH sa správajú identicky.

Parametre

Názov V Typ Povinné Popis
card cesta integer áno ID vizitky.

Telo požiadavky application/json

Pole Typ Obmedzenia Popis
first_name string maxLength 100 Krstné meno.
last_name string maxLength 100 Priezvisko.
job_title string | null maxLength 150 Pozícia / pracovný titul.
company string | null maxLength 150 Názov spoločnosti.
bio string | null maxLength 1000 Krátky popis / bio.
email string | null email · maxLength 255 Kontaktný email (platný formát emailu).
phone string | null maxLength 50 Telefónne číslo. Povolené znaky: číslice, medzery a + - ( ) . /
website string | null uri · maxLength 500 URL webovej stránky.
booking_url string | null uri · maxLength 500 Odkaz na rezerváciu termínu.
video_url string | null uri · maxLength 500 URL videa. Vyžaduje funkciu pokročilej analytiky, inak sa ignoruje. obmedzené plánom
address string | null maxLength 500 Poštová adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Zoznam odkazov na sociálne siete (pole objektov).
design_config object | null — Prepísanie dizajnu (farby, font, rozloženie) ako objekt.
template_id string | null maxLength 50 ID šablóny, ktorá sa má použiť.
is_public boolean | null — Či je vizitka verejne dostupná. Predvolene true.
show_branding boolean | null — Zobraziť branding FalconCard. Jeho skrytie vyžaduje funkciu whitelabel, inak je vynútené na true. obmedzené plánom
show_lead_form boolean | null — Zobraziť lead formulár na vizitke. Vyžaduje funkciu lead formulára, inak je vynútené na false. obmedzené plánom
seo_title string | null maxLength 100 SEO titulok pre verejnú vizitku.
seo_description string | null maxLength 250 SEO meta popis.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Primárny jazyk vizitky (napr. de).
status string | null enum: active, draft, archived Stav publikovania: active, draft alebo archived.

Úspešná odpoveď

200 OK s aktualizovanou vizitkou v objekte data plus správa.

Chybové kódy

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

Aktualizuje vizitku. Všetky polia sú voliteľné; zmenia sa iba poskytnuté polia. PUT a PATCH sa správajú identicky.

Parametre

Názov V Typ Povinné Popis
card cesta integer áno ID vizitky.

Telo požiadavky application/json

Pole Typ Obmedzenia Popis
first_name string maxLength 100 Krstné meno.
last_name string maxLength 100 Priezvisko.
job_title string | null maxLength 150 Pozícia / pracovný titul.
company string | null maxLength 150 Názov spoločnosti.
bio string | null maxLength 1000 Krátky popis / bio.
email string | null email · maxLength 255 Kontaktný email (platný formát emailu).
phone string | null maxLength 50 Telefónne číslo. Povolené znaky: číslice, medzery a + - ( ) . /
website string | null uri · maxLength 500 URL webovej stránky.
booking_url string | null uri · maxLength 500 Odkaz na rezerváciu termínu.
video_url string | null uri · maxLength 500 URL videa. Vyžaduje funkciu pokročilej analytiky, inak sa ignoruje. obmedzené plánom
address string | null maxLength 500 Poštová adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Zoznam odkazov na sociálne siete (pole objektov).
design_config object | null — Prepísanie dizajnu (farby, font, rozloženie) ako objekt.
template_id string | null maxLength 50 ID šablóny, ktorá sa má použiť.
is_public boolean | null — Či je vizitka verejne dostupná. Predvolene true.
show_branding boolean | null — Zobraziť branding FalconCard. Jeho skrytie vyžaduje funkciu whitelabel, inak je vynútené na true. obmedzené plánom
show_lead_form boolean | null — Zobraziť lead formulár na vizitke. Vyžaduje funkciu lead formulára, inak je vynútené na false. obmedzené plánom
seo_title string | null maxLength 100 SEO titulok pre verejnú vizitku.
seo_description string | null maxLength 250 SEO meta popis.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Primárny jazyk vizitky (napr. de).
status string | null enum: active, draft, archived Stav publikovania: active, draft alebo archived.

Úspešná odpoveď

200 OK s aktualizovanou vizitkou v objekte data plus správa.

Chybové kódy

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

Trvalo zmaže vizitku.

Parametre

Názov V Typ Povinné Popis
card cesta integer áno ID vizitky.

Úspešná odpoveď

200 OK s potvrdzujúcou správou.

Chybové kódy

401403404429
02

Leads

Čítanie kontaktov zachytených cez lead formuláre na vašich vizitkách.

GET
/api/v1/leads Scope leads:read

Vypíše leady zachytené naprieč všetkými vizitkami, najnovšie ako prvé. Filtrujte na jednu vizitku pomocou card_id.

Parametre

Názov V Typ Povinné Popis
card_id query integer nie Obmedziť na jednu vizitku, ktorú vlastníte.
page query integer nie Číslo strany (začína od 1).
per_page query integer nie Počet položiek na stranu, max 100.

Úspešná odpoveď

200 OK s poľom data leadov a objektom meta.

Chybové kódy

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

Vráti jeden lead s kompaktným odkazom na vizitku, ktorá ho zachytila.

Parametre

Názov V Typ Povinné Popis
id cesta integer áno ID leadu.

Úspešná odpoveď

200 OK s leadom v objekte data.

Chybové kódy

401403404429
03

Analytics

Agregované štatistiky zobrazení a kliknutí — naprieč všetkými vizitkami alebo pre jednu vizitku.

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

Agregované metriky zobrazení naprieč všetkými vizitkami alebo — pomocou card_id — pre jednu vizitku.

Parametre

Názov V Typ Povinné Popis
card_id query integer nie Obmedziť na jednu vizitku, ktorú vlastníte.
period query string (enum) nie Obdobie reportovania. Povolené: 7d, 14d, 30d, 90d, 365d. Predvolené 30d.

Úspešná odpoveď

200 OK s total_views, unique_views, views_per_day plus devices, countries a referrers v objekte data.

Chybové kódy

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

Agregované metriky kliknutí naprieč všetkými vizitkami alebo — pomocou card_id — pre jednu vizitku.

Parametre

Názov V Typ Povinné Popis
card_id query integer nie Obmedziť na jednu vizitku, ktorú vlastníte.
period query string (enum) nie Obdobie reportovania. Povolené: 7d, 14d, 30d, 90d, 365d. Predvolené 30d.

Úspešná odpoveď

200 OK s total_clicks, clicks_by_type a clicks_per_day v objekte data.

Chybové kódy

401403422429

05

Príklady kódu

Snippety na kopírovanie v cURL, JavaScripte a Pythone. Nahraďte DEIN_API_TOKEN svojím skutočným tokenom.

Zoznam vizitiek
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"])
Vytvoriť vizitku
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"])
Zoznam leadov
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"])
Načítať analytiku
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"])

Príklad: vytvorenie vizitky

Požiadavka · 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"
  }'
Odpoveď · 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

Chyby

Každá chyba vracia reťazec message. Validačné chyby (422)navyše obsahujú mapu errors.

Status Name Popis Príklad tela
401 Unauthorized Token chýba alebo je neplatný.
{ "message": "Unauthenticated." }
403 Forbidden Plán nezahŕňa prístup k API (iba Enterprise) alebo tokenu chýba požadovaný scope.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Zdroj neexistuje alebo nepatrí vášmu účtu.
{ "message": "Not found." }
422 Unprocessable Entity Validácia zlyhala — telo obsahuje mapu errors (pole → správy).
429 Too Many Requests Rate limit bol prekročený. Hlavička Retry-After udáva čas čakania v sekundách.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 navyše obsahujú mapu errors pole → zoznam správ:

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

Strojovo čitateľná špecifikácia

Kompletné API je zdokumentované ako OpenAPI 3.1. Stiahnite si špecifikáciu a importujte ju do Postman, Insomnia alebo Scalar — alebo z nej vygenerujte typovo bezpečných klientov pre váš jazyk.

Kompatibilné s Postman · Insomnia · Scalar · OpenAPI generátormi

Stiahnuť openapi.json

08

Pripravení na integráciu?

Importujte OpenAPI špecifikáciu do svojich nástrojov alebo si priamo v dashboarde vytvorte svoj prvý API token.