Ugrás a tartalomra

REST API · v1

FalconCard REST API

Kezelje a kártyákat, leadeket és analitikát programozott módon – CRM-szinkronhoz, automatizáláshoz és saját integrációkhoz. Bearer-token alapú hitelesítés, JSON HTTPS-en keresztül.

01

Első lépések

A tokentől az első sikeres kérésig három lépésben. Az API kizárólag JSON-t használ HTTPS-en keresztül, és a megszokott REST-konvenciókat követi – ha valaha is integrált már HTTP API-t, otthonosan fogja érezni magát.

  1. Token létrehozása

    Nyissa meg az irányítópultját, és lépjen ide: Fiók → API-tokenek. Válassza ki az integrációjához szükséges hatóköröket, és azonnal másolja ki a tokent – biztonsági okokból csak egyszer jelenik meg olvasható formában.

    Ugrás az API-tokenekhez
  2. A Bearer fejléc beállítása

    Küldje el a tokent az Authorization fejlécben minden kérésnél. Adja hozzá az Accept: application/json fejlécet, hogy a hibák is JSON formátumban érkezzenek vissza.

    Authorization: Bearer DEIN_API_TOKEN
  3. Az első kérés elküldése

    Kérje le a kártyáit. Egy sikeres hívás HTTP 200 választ ad vissza egy data tömbbel és egy meta objektummal a lapozáshoz:

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

Ha ezt a szerkezetet látja, a hitelesítése helyes. Minden listavégpont ugyanazzal a data + meta sémával válaszol – az egyedi erőforrások egy data objektumban érkeznek vissza, meta nélkül.

Alap-URL: https://falconcard.net/api/v1 · minden válasz JSON formátumú.

02

Hitelesítés

Minden kérés egy személyes hozzáférési tokennel (Laravel Sanctum) hitelesít a fejlécben:

Authorization: Bearer DEIN_API_TOKEN

A tokeneket bármikor létrehozhatja és visszavonhatja itt: irányítópult. Minden token egy vagy több hatókört hordoz, amelyek korlátozzák a jogosultságait.

Hatókörök

cards:read

Kártyák listázása és olvasása

cards:write

Kártyák létrehozása, frissítése és törlése

leads:read

Leadek listázása és olvasása

analytics:read

Megtekintési és kattintási analitika olvasása

03

Alapfogalmak

Négy építőelem, amely minden végpontnál egyformán működik – tanulja meg őket egyszer, és mindenhol alkalmazhatók.

Verziókezelés

A jelenlegi verzió a /api/v1 és az útvonalban van rögzítve. A kompatibilitást megtörő változások új előtag alatt jelennek meg (pl. /api/v2), így a meglévő integrációk stabilak maradnak.

Kérés formátuma

Az író végpontok JSON törzset várnak Content-Type: application/json fejléccel. Az időbélyegek ISO 8601 (UTC) formátumúak. Az ismeretlen mezőket figyelmen kívül hagyja, a hiányzó opcionális mezők változatlanok maradnak.

Sebességkorlátozás

Az Enterprise tokenek a következőt küldhetik: 1000 kérés percenként. Minden válasz tartalmaz X-RateLimit-Limit és X-RateLimit-Remaining. Túllépés esetén 429 Too Many Requests választ kap egy Retry-After fejléccel (másodpercek a visszaállásig) – várjon ennyit az újrapróbálkozás előtt.

Fejlécek · minden válasz
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Lapozás

A listavégpontok oldalanként legfeljebb 15 elemet adnak vissza. Vezérelje a következőkkel: ?page= (1-alapú) és ?per_page= (max. 100). A meta objektum jelenti a current_page, last_page, per_page és total értékeket.

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

Elérhetőség. A REST API a következő csomag része: Enterprise csomag. A más csomagokból származó tokenek a következőt kapják: 403.

04

Végpont-referencia

Teljes referencia mind a tíz végponthoz, erőforrás szerint csoportosítva. Minden definíció szinkronban marad a következővel: OpenAPI specifikáció – készen áll a Postman, Insomnia, Scalar vagy a saját kódgenerátorába történő importálásra.

01

Cards

Digitális névjegykártyák létrehozása, olvasása, frissítése és törlése.

GET
/api/v1/cards Hatókör cards:read

Listázza a fiók kártyáit, a legutóbb frissítettekkel az élen.

Paraméterek

Név Hol Típus Kötelező Leírás
page query integer nem Oldalszám (1-alapú).
per_page query integer nem Elemek oldalanként, max. 100.

Sikeres válasz

200 OK egy data tömbbel, amely a kártyákat tartalmazza, és egy meta objektummal a lapozáshoz.

Hibakódok

401403429
POST
/api/v1/cards Hatókör cards:write

Új kártyát hoz létre. A slug és a cím automatikusan generálódik. A csomaghoz kötött mezőket a megengedett értékekre igazítja.

Paraméterek

Nincs paraméter.

Kéréstörzs application/json

Mező Típus Megkötések Leírás
first_name Kötelező string maxLength 100 Keresztnév.
last_name Kötelező string maxLength 100 Vezetéknév.
job_title string | null maxLength 150 Pozíció / beosztás.
company string | null maxLength 150 Cégnév.
bio string | null maxLength 1000 Rövid leírás / bemutatkozás.
email string | null email · maxLength 255 Kapcsolattartási e-mail (érvényes e-mail formátum).
phone string | null maxLength 50 Telefonszám. Megengedett karakterek: számjegyek, szóközök és + - ( ) . /
website string | null uri · maxLength 500 Webhely URL.
booking_url string | null uri · maxLength 500 Hivatkozás az időpontfoglaláshoz.
video_url string | null uri · maxLength 500 Videó URL. A speciális analitika funkciót igényli, egyébként figyelmen kívül marad. csomaghoz kötött
address string | null maxLength 500 Postai cím.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Közösségimédia-hivatkozások listája (objektumok tömbje).
design_config object | null — Dizájn-felülbírálatok (színek, betűtípus, elrendezés) objektumként.
template_id string | null maxLength 50 A használni kívánt sablon azonosítója.
is_public boolean | null default true Hogy a kártya nyilvánosan elérhető-e. Alapértelmezett: true.
show_branding boolean | null — A FalconCard márkajelzés megjelenítése. Elrejtéséhez a whitelabel funkció szükséges, egyébként true-ra kényszerül. csomaghoz kötött
show_lead_form boolean | null — A lead-űrlap megjelenítése a kártyán. A lead-űrlap funkciót igényli, egyébként false-ra kényszerül. csomaghoz kötött
seo_title string | null maxLength 100 SEO-cím a nyilvános kártyához.
seo_description string | null maxLength 250 SEO meta-leírás.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk A kártya elsődleges nyelve (pl. de).

Sikeres válasz

201 Created az új kártyával a data objektumban, valamint egy üzenettel.

Hibakódok

401403422429
GET
/api/v1/cards/{card} Hatókör cards:read

Egyetlen kártyát ad vissza a rögzített leadekkel együtt.

Paraméterek

Név Hol Típus Kötelező Leírás
card path integer igen A kártya azonosítója.

Sikeres válasz

200 OK a kártyával (beágyazott leads tömbbel együtt) a data objektumban.

Hibakódok

401403404429
PUT
/api/v1/cards/{card} Hatókör cards:write

Frissít egy kártyát. Minden mező opcionális; csak a megadott mezők változnak. A PUT és a PATCH azonosan viselkedik.

Paraméterek

Név Hol Típus Kötelező Leírás
card path integer igen A kártya azonosítója.

Kéréstörzs application/json

Mező Típus Megkötések Leírás
first_name string maxLength 100 Keresztnév.
last_name string maxLength 100 Vezetéknév.
job_title string | null maxLength 150 Pozíció / beosztás.
company string | null maxLength 150 Cégnév.
bio string | null maxLength 1000 Rövid leírás / bemutatkozás.
email string | null email · maxLength 255 Kapcsolattartási e-mail (érvényes e-mail formátum).
phone string | null maxLength 50 Telefonszám. Megengedett karakterek: számjegyek, szóközök és + - ( ) . /
website string | null uri · maxLength 500 Webhely URL.
booking_url string | null uri · maxLength 500 Hivatkozás az időpontfoglaláshoz.
video_url string | null uri · maxLength 500 Videó URL. A speciális analitika funkciót igényli, egyébként figyelmen kívül marad. csomaghoz kötött
address string | null maxLength 500 Postai cím.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Közösségimédia-hivatkozások listája (objektumok tömbje).
design_config object | null — Dizájn-felülbírálatok (színek, betűtípus, elrendezés) objektumként.
template_id string | null maxLength 50 A használni kívánt sablon azonosítója.
is_public boolean | null — Hogy a kártya nyilvánosan elérhető-e. Alapértelmezett: true.
show_branding boolean | null — A FalconCard márkajelzés megjelenítése. Elrejtéséhez a whitelabel funkció szükséges, egyébként true-ra kényszerül. csomaghoz kötött
show_lead_form boolean | null — A lead-űrlap megjelenítése a kártyán. A lead-űrlap funkciót igényli, egyébként false-ra kényszerül. csomaghoz kötött
seo_title string | null maxLength 100 SEO-cím a nyilvános kártyához.
seo_description string | null maxLength 250 SEO meta-leírás.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk A kártya elsődleges nyelve (pl. de).
status string | null enum: active, draft, archived Közzétételi állapot: active, draft vagy archived.

Sikeres válasz

200 OK a frissített kártyával a data objektumban, valamint egy üzenettel.

Hibakódok

401403404422429
PATCH
/api/v1/cards/{card} Hatókör cards:write

Frissít egy kártyát. Minden mező opcionális; csak a megadott mezők változnak. A PUT és a PATCH azonosan viselkedik.

Paraméterek

Név Hol Típus Kötelező Leírás
card path integer igen A kártya azonosítója.

Kéréstörzs application/json

Mező Típus Megkötések Leírás
first_name string maxLength 100 Keresztnév.
last_name string maxLength 100 Vezetéknév.
job_title string | null maxLength 150 Pozíció / beosztás.
company string | null maxLength 150 Cégnév.
bio string | null maxLength 1000 Rövid leírás / bemutatkozás.
email string | null email · maxLength 255 Kapcsolattartási e-mail (érvényes e-mail formátum).
phone string | null maxLength 50 Telefonszám. Megengedett karakterek: számjegyek, szóközök és + - ( ) . /
website string | null uri · maxLength 500 Webhely URL.
booking_url string | null uri · maxLength 500 Hivatkozás az időpontfoglaláshoz.
video_url string | null uri · maxLength 500 Videó URL. A speciális analitika funkciót igényli, egyébként figyelmen kívül marad. csomaghoz kötött
address string | null maxLength 500 Postai cím.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Közösségimédia-hivatkozások listája (objektumok tömbje).
design_config object | null — Dizájn-felülbírálatok (színek, betűtípus, elrendezés) objektumként.
template_id string | null maxLength 50 A használni kívánt sablon azonosítója.
is_public boolean | null — Hogy a kártya nyilvánosan elérhető-e. Alapértelmezett: true.
show_branding boolean | null — A FalconCard márkajelzés megjelenítése. Elrejtéséhez a whitelabel funkció szükséges, egyébként true-ra kényszerül. csomaghoz kötött
show_lead_form boolean | null — A lead-űrlap megjelenítése a kártyán. A lead-űrlap funkciót igényli, egyébként false-ra kényszerül. csomaghoz kötött
seo_title string | null maxLength 100 SEO-cím a nyilvános kártyához.
seo_description string | null maxLength 250 SEO meta-leírás.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk A kártya elsődleges nyelve (pl. de).
status string | null enum: active, draft, archived Közzétételi állapot: active, draft vagy archived.

Sikeres válasz

200 OK a frissített kártyával a data objektumban, valamint egy üzenettel.

Hibakódok

401403404422429
DELETE
/api/v1/cards/{card} Hatókör cards:write

Véglegesen töröl egy kártyát.

Paraméterek

Név Hol Típus Kötelező Leírás
card path integer igen A kártya azonosítója.

Sikeres válasz

200 OK egy megerősítő üzenettel.

Hibakódok

401403404429
02

Leads

A kártyáin lévő lead-űrlapokon keresztül rögzített kapcsolatok olvasása.

GET
/api/v1/leads Hatókör leads:read

Listázza az összes kártyán rögzített leadeket, a legújabbakkal elöl. Egyetlen kártyára a card_id paraméterrel szűrhet.

Paraméterek

Név Hol Típus Kötelező Leírás
card_id query integer nem Korlátozás egyetlen, Ön tulajdonában lévő kártyára.
page query integer nem Oldalszám (1-alapú).
per_page query integer nem Elemek oldalanként, max. 100.

Sikeres válasz

200 OK egy data tömbbel, amely a leadeket tartalmazza, és egy meta objektummal.

Hibakódok

401403429
GET
/api/v1/leads/{id} Hatókör leads:read

Egyetlen leadet ad vissza a rögzítő kártyára mutató tömör hivatkozással.

Paraméterek

Név Hol Típus Kötelező Leírás
id path integer igen A lead azonosítója.

Sikeres válasz

200 OK a leaddel a data objektumban.

Hibakódok

401403404429
03

Analytics

Összesített megtekintési és kattintási statisztikák – az összes kártyára vagy kártyánként.

GET
/api/v1/analytics/views Hatókör analytics:read

Összesített megtekintési mutatók az összes kártyára vagy – a card_id segítségével – egyetlen kártyára.

Paraméterek

Név Hol Típus Kötelező Leírás
card_id query integer nem Korlátozás egyetlen, Ön tulajdonában lévő kártyára.
period query string (enum) nem Jelentési időszak. Megengedett: 7d, 14d, 30d, 90d, 365d. Alapértelmezett: 30d.

Sikeres válasz

200 OK a total_views, unique_views, views_per_day értékekkel, valamint a devices, countries és referrers adatokkal a data objektumban.

Hibakódok

401403422429
GET
/api/v1/analytics/clicks Hatókör analytics:read

Összesített kattintási mutatók az összes kártyára vagy – a card_id segítségével – egyetlen kártyára.

Paraméterek

Név Hol Típus Kötelező Leírás
card_id query integer nem Korlátozás egyetlen, Ön tulajdonában lévő kártyára.
period query string (enum) nem Jelentési időszak. Megengedett: 7d, 14d, 30d, 90d, 365d. Alapértelmezett: 30d.

Sikeres válasz

200 OK a total_clicks, clicks_by_type és clicks_per_day értékekkel a data objektumban.

Hibakódok

401403422429

05

Kódpéldák

Bemásolható kódrészletek cURL, JavaScript és Python nyelven. Cserélje le a DEIN_API_TOKEN értéket a valódi tokenjére.

Kártyák listázása
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"])
Kártya létrehozása
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"])
Leadek listázása
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"])
Analitika lekérése
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élda: kártya létrehozása

Kérés · 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"
  }'
Válasz · 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

Hibák

Minden hiba egy message sztringet ad vissza. A validációs hibák (422) ezenfelül tartalmaznak egy errors leképezést.

Status Name Leírás Példatörzs
401 Unauthorized A token hiányzik vagy érvénytelen.
{ "message": "Unauthenticated." }
403 Forbidden A csomag nem tartalmaz API-hozzáférést (csak Enterprise), vagy a tokenből hiányzik a szükséges hatókör.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Az erőforrás nem létezik, vagy nem az Ön fiókjához tartozik.
{ "message": "Not found." }
422 Unprocessable Entity A validáció sikertelen – a törzs egy errors leképezést tartalmaz (mező → üzenetek).
429 Too Many Requests A sebességkorlátot túllépte. A Retry-After fejléc megadja a várakozási időt másodpercben.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 ezenfelül tartalmaznak egy errors leképezést: mező → üzenetek listája:

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

Géppel olvasható specifikáció

A teljes API OpenAPI 3.1 formátumban van dokumentálva. Töltse le a specifikációt, és importálja a Postmanbe, Insomniába vagy Scalarba – vagy generáljon belőle típusbiztos klienseket a saját nyelvéhez.

Kompatibilis a következőkkel: Postman · Insomnia · Scalar · OpenAPI-generátorok

openapi.json letöltése

08

Készen áll az integrációra?

Importálja az OpenAPI specifikációt az eszközeibe, vagy hozza létre első API-tokenjét közvetlenül az irányítópulton.