Přejít na obsah

REST API · v1

FalconCard REST API

Spravujte karty, leady a analytiku programově — pro synchronizaci s CRM, automatizaci a vlastní integrace. Ověřování pomocí Bearer Token, JSON přes HTTPS.

01

Začínáme

Od tokenu k vašemu prvnímu úspěšnému požadavku ve třech krocích. API komunikuje výhradně přes JSON přes HTTPS a dodržuje běžné REST konvence — pokud jste někdy integrovali HTTP API, budete se cítit jako doma.

  1. Vytvořte token

    Otevřete svůj dashboard a přejděte do sekce Účet → API tokeny. Vyberte scopes, které vaše integrace potřebuje, a token si ihned zkopírujte — z bezpečnostních důvodů se v čitelné podobě zobrazí pouze jednou.

    Přejít na API tokeny
  2. Nastavte Bearer hlavičku

    Token odesílejte v hlavičce Authorization při každém požadavku. Přidejte Accept: application/json, aby se i chyby vracely jako JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Odešlete svůj první požadavek

    Načtěte své karty. Úspěšné volání vrátí HTTP 200 s polem data a objektem meta pro stránkování:

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

Pokud vidíte tuto strukturu, vaše ověřování je správné. Každý endpoint s výpisem odpovídá stejným schématem data + meta — jednotlivé zdroje se vracejí v objektu data bez meta.

Základní URL: https://falconcard.net/api/v1 · všechny odpovědi jsou ve formátu JSON.

02

Ověřování

Každý požadavek se ověřuje pomocí osobního přístupového tokenu (Laravel Sanctum) v hlavičce:

Authorization: Bearer DEIN_API_TOKEN

Tokeny můžete kdykoli vytvořit i odvolat v dashboardu. Každý token nese jeden nebo více scopes, které omezují jeho oprávnění.

Scopes

cards:read

Výpis a čtení karet

cards:write

Vytváření, úprava a mazání karet

leads:read

Výpis a čtení leadů

analytics:read

Čtení analytiky zobrazení a kliknutí

03

Koncepty

Čtyři stavební bloky, které fungují identicky pro každý endpoint — naučte se je jednou a uplatníte je všude.

Verzování

Aktuální verze je /api/v1 a je zakotvena v cestě. Změny narušující kompatibilitu vycházejí pod novým prefixem (např. /api/v2), takže stávající integrace zůstávají stabilní.

Formát požadavku

Zapisovací endpointy očekávají tělo ve formátu JSON s Content-Type: application/json. Časové značky jsou v ISO 8601 (UTC). Neznámá pole jsou ignorována, chybějící volitelná pole zůstávají beze změny.

Omezení počtu požadavků

Enterprise tokeny mohou odesílat 1000 požadavků za minutu. Každá odpověď nese X-RateLimit-Limit a X-RateLimit-Remaining. Při překročení obdržíte 429 Too Many Requests s hlavičkou Retry-After (počet sekund do resetu) — než to zkusíte znovu, tuto dobu vyčkejte.

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

Stránkování

Endpointy s výpisem vracejí až 15 položek na stránku. Ovládejte je pomocí ?page= (číslováno od 1) a ?per_page= (max. 100). Objekt meta uvádí current_page, last_page, per_page a total.

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

Dostupnost. REST API je součástí tarifu Enterprise . Tokeny z jiných tarifů obdrží 403.

04

Referenční přehled endpointů

Úplná reference pro všech deset endpointů, seskupených podle zdroje. Každá definice zůstává synchronizovaná s OpenAPI specifikací — připravená k importu do Postman, Insomnia, Scalar nebo vašeho generátoru kódu.

01

Cards

Vytváření, čtení, úprava a mazání digitálních vizitek.

GET
/api/v1/cards Scope cards:read

Vypíše karty účtu, naposledy aktualizované první.

Parametry

Název Umístění Typ Povinné Popis
page query integer ne Číslo stránky (číslováno od 1).
per_page query integer ne Počet položek na stránku, max. 100.

Úspěšná odpověď

200 OK s polem data obsahujícím karty a objektem meta pro stránkování.

Chybové kódy

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

Vytvoří novou kartu. slug a title se generují automaticky. Pole omezená tarifem jsou převedena na povolené hodnoty.

Parametry

Žádné parametry.

Tělo požadavku application/json

Pole Typ Omezení Popis
first_name Povinné string maxLength 100 Křestní jméno.
last_name Povinné string maxLength 100 Příjmení.
job_title string | null maxLength 150 Pozice / pracovní zařazení.
company string | null maxLength 150 Název společnosti.
bio string | null maxLength 1000 Krátký popis / bio.
email string | null email · maxLength 255 Kontaktní e-mail (platný formát e-mailu).
phone string | null maxLength 50 Telefonní číslo. Povolené znaky: číslice, mezery a + - ( ) . /
website string | null uri · maxLength 500 URL webových stránek.
booking_url string | null uri · maxLength 500 Odkaz na rezervaci schůzky.
video_url string | null uri · maxLength 500 URL videa. Vyžaduje funkci pokročilé analytiky, jinak je ignorováno. omezeno tarifem
address string | null maxLength 500 Poštovní adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Seznam odkazů na sociální sítě (pole objektů).
design_config object | null — Přepisy designu (barvy, písmo, rozvržení) jako objekt.
template_id string | null maxLength 50 ID použité šablony.
is_public boolean | null default true Zda je karta veřejně dostupná. Výchozí true.
show_branding boolean | null — Zobrazit branding FalconCard. Jeho skrytí vyžaduje funkci whitelabel, jinak je vynuceno true. omezeno tarifem
show_lead_form boolean | null — Zobrazit lead formulář na kartě. Vyžaduje funkci lead formuláře, jinak je vynuceno false. omezeno tarifem
seo_title string | null maxLength 100 SEO titulek pro veřejnou kartu.
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ární jazyk karty (např. de).

Úspěšná odpověď

201 Created s novou kartou v objektu data a zprávou.

Chybové kódy

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

Vrátí jednu kartu včetně jejích zachycených leadů.

Parametry

Název Umístění Typ Povinné Popis
card cesta integer ano ID karty.

Úspěšná odpověď

200 OK s kartou (včetně vnořeného pole leads) v objektu data.

Chybové kódy

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

Aktualizuje kartu. Všechna pole jsou volitelná; mění se pouze poskytnutá pole. PUT a PATCH se chovají identicky.

Parametry

Název Umístění Typ Povinné Popis
card cesta integer ano ID karty.

Tělo požadavku application/json

Pole Typ Omezení Popis
first_name string maxLength 100 Křestní jméno.
last_name string maxLength 100 Příjmení.
job_title string | null maxLength 150 Pozice / pracovní zařazení.
company string | null maxLength 150 Název společnosti.
bio string | null maxLength 1000 Krátký popis / bio.
email string | null email · maxLength 255 Kontaktní e-mail (platný formát e-mailu).
phone string | null maxLength 50 Telefonní číslo. Povolené znaky: číslice, mezery a + - ( ) . /
website string | null uri · maxLength 500 URL webových stránek.
booking_url string | null uri · maxLength 500 Odkaz na rezervaci schůzky.
video_url string | null uri · maxLength 500 URL videa. Vyžaduje funkci pokročilé analytiky, jinak je ignorováno. omezeno tarifem
address string | null maxLength 500 Poštovní adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Seznam odkazů na sociální sítě (pole objektů).
design_config object | null — Přepisy designu (barvy, písmo, rozvržení) jako objekt.
template_id string | null maxLength 50 ID použité šablony.
is_public boolean | null — Zda je karta veřejně dostupná. Výchozí true.
show_branding boolean | null — Zobrazit branding FalconCard. Jeho skrytí vyžaduje funkci whitelabel, jinak je vynuceno true. omezeno tarifem
show_lead_form boolean | null — Zobrazit lead formulář na kartě. Vyžaduje funkci lead formuláře, jinak je vynuceno false. omezeno tarifem
seo_title string | null maxLength 100 SEO titulek pro veřejnou kartu.
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ární jazyk karty (např. de).
status string | null enum: active, draft, archived Stav publikace: active, draft nebo archived.

Úspěšná odpověď

200 OK s aktualizovanou kartou v objektu data a zprávou.

Chybové kódy

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

Aktualizuje kartu. Všechna pole jsou volitelná; mění se pouze poskytnutá pole. PUT a PATCH se chovají identicky.

Parametry

Název Umístění Typ Povinné Popis
card cesta integer ano ID karty.

Tělo požadavku application/json

Pole Typ Omezení Popis
first_name string maxLength 100 Křestní jméno.
last_name string maxLength 100 Příjmení.
job_title string | null maxLength 150 Pozice / pracovní zařazení.
company string | null maxLength 150 Název společnosti.
bio string | null maxLength 1000 Krátký popis / bio.
email string | null email · maxLength 255 Kontaktní e-mail (platný formát e-mailu).
phone string | null maxLength 50 Telefonní číslo. Povolené znaky: číslice, mezery a + - ( ) . /
website string | null uri · maxLength 500 URL webových stránek.
booking_url string | null uri · maxLength 500 Odkaz na rezervaci schůzky.
video_url string | null uri · maxLength 500 URL videa. Vyžaduje funkci pokročilé analytiky, jinak je ignorováno. omezeno tarifem
address string | null maxLength 500 Poštovní adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Seznam odkazů na sociální sítě (pole objektů).
design_config object | null — Přepisy designu (barvy, písmo, rozvržení) jako objekt.
template_id string | null maxLength 50 ID použité šablony.
is_public boolean | null — Zda je karta veřejně dostupná. Výchozí true.
show_branding boolean | null — Zobrazit branding FalconCard. Jeho skrytí vyžaduje funkci whitelabel, jinak je vynuceno true. omezeno tarifem
show_lead_form boolean | null — Zobrazit lead formulář na kartě. Vyžaduje funkci lead formuláře, jinak je vynuceno false. omezeno tarifem
seo_title string | null maxLength 100 SEO titulek pro veřejnou kartu.
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ární jazyk karty (např. de).
status string | null enum: active, draft, archived Stav publikace: active, draft nebo archived.

Úspěšná odpověď

200 OK s aktualizovanou kartou v objektu data a zprávou.

Chybové kódy

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

Trvale smaže kartu.

Parametry

Název Umístění Typ Povinné Popis
card cesta integer ano ID karty.

Úspěšná odpověď

200 OK s potvrzovací zprávou.

Chybové kódy

401403404429
02

Leads

Čtení kontaktů zachycených prostřednictvím lead formulářů na vašich kartách.

GET
/api/v1/leads Scope leads:read

Vypíše leady zachycené napříč všemi kartami, nejnovější první. Filtrujte na jednu kartu pomocí card_id.

Parametry

Název Umístění Typ Povinné Popis
card_id query integer ne Omezení na jednu vámi vlastněnou kartu.
page query integer ne Číslo stránky (číslováno od 1).
per_page query integer ne Počet položek na stránku, max. 100.

Úspěšná odpověď

200 OK s polem data obsahujícím leady a objektem meta.

Chybové kódy

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

Vrátí jeden lead s kompaktním odkazem na zachycující kartu.

Parametry

Název Umístění Typ Povinné Popis
id cesta integer ano ID leadu.

Úspěšná odpověď

200 OK s leadem v objektu data.

Chybové kódy

401403404429
03

Analytics

Agregované statistiky zobrazení a kliknutí — napříč všemi kartami nebo pro jednotlivou kartu.

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

Agregované metriky zobrazení napříč všemi kartami nebo — pomocí card_id — pro jednotlivou kartu.

Parametry

Název Umístění Typ Povinné Popis
card_id query integer ne Omezení na jednu vámi vlastněnou kartu.
period query string (enum) ne Reportovací období. Povolené: 7d, 14d, 30d, 90d, 365d. Výchozí 30d.

Úspěšná odpověď

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

Chybové kódy

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

Agregované metriky kliknutí napříč všemi kartami nebo — pomocí card_id — pro jednotlivou kartu.

Parametry

Název Umístění Typ Povinné Popis
card_id query integer ne Omezení na jednu vámi vlastněnou kartu.
period query string (enum) ne Reportovací období. Povolené: 7d, 14d, 30d, 90d, 365d. Výchozí 30d.

Úspěšná odpověď

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

Chybové kódy

401403422429

05

Příklady kódu

Snippety k vložení v cURL, JavaScriptu a Pythonu. Nahraďte DEIN_API_TOKEN svým skutečným tokenem.

Výpis karet
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"])
Vytvoření karty
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"])
Výpis leadů
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čtení analytiky
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"])

Příklad: vytvoření karty

Požadavek · 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"
  }'
Odpověď · 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 vrací řetězec message . Validační chyby (422) navíc obsahují mapu errors .

Status Name Popis Příklad těla
401 Unauthorized Token chybí nebo je neplatný.
{ "message": "Unauthenticated." }
403 Forbidden Tarif nezahrnuje přístup k API (pouze Enterprise) nebo tokenu chybí požadovaný scope.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Zdroj neexistuje nebo nepatří k vašemu účtu.
{ "message": "Not found." }
422 Unprocessable Entity Validace selhala — tělo obsahuje mapu errors (pole → zprávy).
429 Too Many Requests Rate limit překročen. Hlavička Retry-After udává dobu čekání v sekundách.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 navíc obsahují mapu errors typu pole → seznam zprá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

Strojově čitelná specifikace

Kompletní API je zdokumentováno jako OpenAPI 3.1. Stáhněte si specifikaci a importujte ji do Postman, Insomnia nebo Scalar — nebo z ní vygenerujte typově bezpečné klienty pro váš jazyk.

Kompatibilní s Postman · Insomnia · Scalar · OpenAPI generátory

Stáhnout openapi.json

08

Připraveni integrovat?

Importujte OpenAPI specifikaci do svých nástrojů nebo si vytvořte svůj první API token přímo v dashboardu.