Skočite na vsebino

REST API · v1

FalconCard REST API

Upravljajte kartice, potencialne stranke in analitiko programsko – za sinhronizacijo s CRM, avtomatizacijo in lastne integracije. Avtentikacija z Bearer Token, JSON prek HTTPS.

01

Začetek uporabe

Od Tokena do vaše prve uspešne zahteve v treh korakih. API komunicira izključno v formatu JSON prek HTTPS in sledi običajnim konvencijam REST – če ste že kdaj integrirali HTTP API, se boste počutili kot doma.

  1. Ustvarite Token

    Odprite nadzorno ploščo in se pomaknite na Račun → API Tokeni. Izberite obsege (scopes), ki jih vaša integracija potrebuje, in Token takoj kopirajte – iz varnostnih razlogov je v navadnem besedilu prikazan samo enkrat.

    Pojdite na API Tokene
  2. Nastavite glavo Bearer

    Token pošljite v glavi Authorization pri vsaki zahtevi. Dodajte Accept: application/json, da se tudi napake vrnejo v formatu JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Pošljite svojo prvo zahtevo

    Pridobite svoje kartice. Uspešen klic vrne HTTP 200 z matriko data in objektom meta za paginacijo:

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

Če vidite to obliko, je vaša avtentikacija pravilna. Vsaka končna točka s seznamom se odzove z isto shemo data + meta – posamezni viri se vrnejo v objektu data brez meta.

Osnovni URL: https://falconcard.net/api/v1 · vsi odzivi so v formatu JSON.

02

Avtentikacija

Vsaka zahteva se avtenticira z osebnim dostopnim Tokenom (Laravel Sanctum) v glavi (header):

Authorization: Bearer DEIN_API_TOKEN

Tokene lahko kadar koli ustvarite in prekličete v nadzorni plošči. Vsak Token nosi enega ali več obsegov (scopes), ki omejujejo njegova dovoljenja.

Obsegi (Scopes)

cards:read

Prikaz seznama in branje kartic

cards:write

Ustvarjanje, posodabljanje in brisanje kartic

leads:read

Prikaz seznama in branje potencialnih strank

analytics:read

Branje analitike ogledov in klikov

03

Koncepti

Štirje gradniki, ki delujejo enako za vsako končno točko – naučite se jih enkrat, veljajo povsod.

Verzioniranje

Trenutna različica je /api/v1 in je pripeta v poti. Nezdružljive spremembe se objavijo pod novo predpono (npr. /api/v2), tako da obstoječe integracije ostanejo stabilne.

Format zahteve

Končne točke za pisanje pričakujejo telo JSON s Content-Type: application/json. Časovni žigi so v formatu ISO 8601 (UTC). Neznana polja se ignorirajo, manjkajoča neobvezna polja ostanejo nespremenjena.

Omejevanje hitrosti

Tokeni Enterprise lahko pošljejo 1000 zahtev na minuto. Vsak odziv nosi X-RateLimit-Limit in X-RateLimit-Remaining. Ob prekoračitvi prejmete 429 Too Many Requests z glavo Retry-After (sekunde do ponastavitve) – počakajte toliko časa, preden poskusite znova.

Glave · vsak odziv
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginacija

Končne točke s seznami vrnejo do 15 elementov na stran. Nadzirate jo z ?page= (začenši z 1) in ?per_page= (največ 100). Objekt meta poroča current_page, last_page, per_page in total.

meta · vsak seznam
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Razpoložljivost. REST API je del paketa Enterprise . Tokeni iz drugih paketov prejmejo 403.

04

Referenca končnih točk

Popolna referenca za vseh deset končnih točk, razvrščenih po viru. Vsaka definicija ostaja sinhronizirana s specifikacijo OpenAPI – pripravljeni za uvoz v Postman, Insomnia, Scalar ali vaš generator kode.

01

Cards

Ustvarjanje, branje, posodabljanje in brisanje digitalnih poslovnih vizitk.

GET
/api/v1/cards Obseg (Scope) cards:read

Prikaže seznam kartic računa, nazadnje posodobljene najprej.

Parametri

Ime V Vrsta Obvezno Opis
page Poizvedba integer ne Številka strani (začenši z 1).
per_page Poizvedba integer ne Elementov na stran, največ 100.

Uspešen odziv

200 OK z matriko data kartic in objektom meta za paginacijo.

Kode napak

401403429
POST
/api/v1/cards Obseg (Scope) cards:write

Ustvari novo kartico. slug in title se ustvarita samodejno. Polja, omejena s paketom, se prilagodijo dovoljenim vrednostim.

Parametri

Brez parametrov.

Telo zahteve application/json

Polje Vrsta Omejitve Opis
first_name Obvezno string maxLength 100 Ime.
last_name Obvezno string maxLength 100 Priimek.
job_title string | null maxLength 150 Položaj / naziv delovnega mesta.
company string | null maxLength 150 Ime podjetja.
bio string | null maxLength 1000 Kratek opis / biografija.
email string | null email · maxLength 255 Kontaktni e-poštni naslov (veljaven format e-pošte).
phone string | null maxLength 50 Telefonska številka. Dovoljeni znaki: števke, presledki in + - ( ) . /
website string | null uri · maxLength 500 URL spletnega mesta.
booking_url string | null uri · maxLength 500 Povezava do rezervacije termina.
video_url string | null uri · maxLength 500 URL videa. Zahteva funkcijo napredne analitike, sicer se ignorira. omejeno s paketom
address string | null maxLength 500 Poštni naslov.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Seznam povezav do družbenih omrežij (matrika objektov).
design_config object | null — Prepisi zasnove (barve, pisava, postavitev) kot objekt.
template_id string | null maxLength 50 ID predloge za uporabo.
is_public boolean | null default true Ali je kartica javno dostopna. Privzeto true.
show_branding boolean | null — Prikaz blagovne znamke FalconCard. Za skritje je potrebna funkcija whitelabel, sicer je nastavljeno na true. omejeno s paketom
show_lead_form boolean | null — Prikaz obrazca za potencialne stranke na kartici. Zahteva funkcijo obrazca za potencialne stranke, sicer je nastavljeno na false. omejeno s paketom
seo_title string | null maxLength 100 Naslov SEO za javno kartico.
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 Primarni jezik kartice (npr. de).

Uspešen odziv

201 Created z novo kartico v objektu data ter sporočilom.

Kode napak

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

Vrne posamezno kartico vključno z njenimi zajetimi potencialnimi strankami.

Parametri

Ime V Vrsta Obvezno Opis
card Pot integer da ID kartice.

Uspešen odziv

200 OK s kartico (vključno z vdelano matriko leads) v objektu data.

Kode napak

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

Posodobi kartico. Vsa polja so neobvezna; spremenijo se samo navedena polja. PUT in PATCH delujeta identično.

Parametri

Ime V Vrsta Obvezno Opis
card Pot integer da ID kartice.

Telo zahteve application/json

Polje Vrsta Omejitve Opis
first_name string maxLength 100 Ime.
last_name string maxLength 100 Priimek.
job_title string | null maxLength 150 Položaj / naziv delovnega mesta.
company string | null maxLength 150 Ime podjetja.
bio string | null maxLength 1000 Kratek opis / biografija.
email string | null email · maxLength 255 Kontaktni e-poštni naslov (veljaven format e-pošte).
phone string | null maxLength 50 Telefonska številka. Dovoljeni znaki: števke, presledki in + - ( ) . /
website string | null uri · maxLength 500 URL spletnega mesta.
booking_url string | null uri · maxLength 500 Povezava do rezervacije termina.
video_url string | null uri · maxLength 500 URL videa. Zahteva funkcijo napredne analitike, sicer se ignorira. omejeno s paketom
address string | null maxLength 500 Poštni naslov.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Seznam povezav do družbenih omrežij (matrika objektov).
design_config object | null — Prepisi zasnove (barve, pisava, postavitev) kot objekt.
template_id string | null maxLength 50 ID predloge za uporabo.
is_public boolean | null — Ali je kartica javno dostopna. Privzeto true.
show_branding boolean | null — Prikaz blagovne znamke FalconCard. Za skritje je potrebna funkcija whitelabel, sicer je nastavljeno na true. omejeno s paketom
show_lead_form boolean | null — Prikaz obrazca za potencialne stranke na kartici. Zahteva funkcijo obrazca za potencialne stranke, sicer je nastavljeno na false. omejeno s paketom
seo_title string | null maxLength 100 Naslov SEO za javno kartico.
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 Primarni jezik kartice (npr. de).
status string | null enum: active, draft, archived Stanje objave: active, draft ali archived.

Uspešen odziv

200 OK s posodobljeno kartico v objektu data ter sporočilom.

Kode napak

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

Posodobi kartico. Vsa polja so neobvezna; spremenijo se samo navedena polja. PUT in PATCH delujeta identično.

Parametri

Ime V Vrsta Obvezno Opis
card Pot integer da ID kartice.

Telo zahteve application/json

Polje Vrsta Omejitve Opis
first_name string maxLength 100 Ime.
last_name string maxLength 100 Priimek.
job_title string | null maxLength 150 Položaj / naziv delovnega mesta.
company string | null maxLength 150 Ime podjetja.
bio string | null maxLength 1000 Kratek opis / biografija.
email string | null email · maxLength 255 Kontaktni e-poštni naslov (veljaven format e-pošte).
phone string | null maxLength 50 Telefonska številka. Dovoljeni znaki: števke, presledki in + - ( ) . /
website string | null uri · maxLength 500 URL spletnega mesta.
booking_url string | null uri · maxLength 500 Povezava do rezervacije termina.
video_url string | null uri · maxLength 500 URL videa. Zahteva funkcijo napredne analitike, sicer se ignorira. omejeno s paketom
address string | null maxLength 500 Poštni naslov.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Seznam povezav do družbenih omrežij (matrika objektov).
design_config object | null — Prepisi zasnove (barve, pisava, postavitev) kot objekt.
template_id string | null maxLength 50 ID predloge za uporabo.
is_public boolean | null — Ali je kartica javno dostopna. Privzeto true.
show_branding boolean | null — Prikaz blagovne znamke FalconCard. Za skritje je potrebna funkcija whitelabel, sicer je nastavljeno na true. omejeno s paketom
show_lead_form boolean | null — Prikaz obrazca za potencialne stranke na kartici. Zahteva funkcijo obrazca za potencialne stranke, sicer je nastavljeno na false. omejeno s paketom
seo_title string | null maxLength 100 Naslov SEO za javno kartico.
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 Primarni jezik kartice (npr. de).
status string | null enum: active, draft, archived Stanje objave: active, draft ali archived.

Uspešen odziv

200 OK s posodobljeno kartico v objektu data ter sporočilom.

Kode napak

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

Trajno izbriše kartico.

Parametri

Ime V Vrsta Obvezno Opis
card Pot integer da ID kartice.

Uspešen odziv

200 OK s potrditvenim sporočilom.

Kode napak

401403404429
02

Leads

Branje stikov, zajetih prek obrazcev za potencialne stranke na vaših karticah.

GET
/api/v1/leads Obseg (Scope) leads:read

Prikaže seznam potencialnih strank, zajetih na vseh karticah, najnovejše najprej. Filtrirajte na eno kartico z card_id.

Parametri

Ime V Vrsta Obvezno Opis
card_id Poizvedba integer ne Omejite na posamezno kartico, ki jo imate v lasti.
page Poizvedba integer ne Številka strani (začenši z 1).
per_page Poizvedba integer ne Elementov na stran, največ 100.

Uspešen odziv

200 OK z matriko data potencialnih strank in objektom meta.

Kode napak

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

Vrne posamezno potencialno stranko s strnjenim sklicem na kartico, ki jo je zajela.

Parametri

Ime V Vrsta Obvezno Opis
id Pot integer da ID potencialne stranke.

Uspešen odziv

200 OK s potencialno stranko v objektu data.

Kode napak

401403404429
03

Analytics

Združena statistika ogledov in klikov – za vse kartice ali za posamezno kartico.

GET
/api/v1/analytics/views Obseg (Scope) analytics:read

Združene metrike ogledov za vse kartice ali – prek card_id – za posamezno kartico.

Parametri

Ime V Vrsta Obvezno Opis
card_id Poizvedba integer ne Omejite na posamezno kartico, ki jo imate v lasti.
period Poizvedba string (enum) ne Obdobje poročanja. Dovoljeno: 7d, 14d, 30d, 90d, 365d. Privzeto 30d.

Uspešen odziv

200 OK s total_views, unique_views, views_per_day ter devices, countries in referrers v objektu data.

Kode napak

401403422429
GET
/api/v1/analytics/clicks Obseg (Scope) analytics:read

Združene metrike klikov za vse kartice ali – prek card_id – za posamezno kartico.

Parametri

Ime V Vrsta Obvezno Opis
card_id Poizvedba integer ne Omejite na posamezno kartico, ki jo imate v lasti.
period Poizvedba string (enum) ne Obdobje poročanja. Dovoljeno: 7d, 14d, 30d, 90d, 365d. Privzeto 30d.

Uspešen odziv

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

Kode napak

401403422429

05

Primeri kode

Izrezki za kopiranje in lepljenje v cURL, JavaScript in Python. Nadomestite DEIN_API_TOKEN s svojim pravim Tokenom.

Prikaz seznama kartic
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"])
Ustvarjanje kartice
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"])
Prikaz seznama potencialnih strank
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"])
Pridobivanje analitike
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"])

Primer: ustvarjanje kartice

Zahteva · 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"
  }'
Odziv · 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

Napake

Vsaka napaka vrne niz message . Napake pri validaciji (422) dodatno vsebujejo zemljevid errors .

Status Name Opis Primer telesa
401 Unauthorized Token manjka ali je neveljaven.
{ "message": "Unauthenticated." }
403 Forbidden Paket ne vključuje dostopa do API (samo Enterprise) ali Tokenu manjka zahtevani obseg (scope).
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Vir ne obstaja ali ne pripada vašemu računu.
{ "message": "Not found." }
422 Unprocessable Entity Validacija ni uspela – telo vsebuje zemljevid errors (polje → sporočila).
429 Too Many Requests Omejitev hitrosti je prekoračena. Glava Retry-After navaja čas čakanja v sekundah.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 dodatno vsebujejo zemljevid errors s polji → seznam sporočil:

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

Strojno berljiva specifikacija

Celoten API je dokumentiran kot OpenAPI 3.1. Prenesite specifikacijo in jo uvozite v Postman, Insomnia ali Scalar – ali iz nje ustvarite tipsko varne odjemalce za svoj jezik.

Združljivo s Postman · Insomnia · Scalar · generatorji OpenAPI

Prenesite openapi.json

08

Pripravljeni na integracijo?

Uvozite specifikacijo OpenAPI v svoja orodja ali ustvarite svoj prvi API Token neposredno v nadzorni plošči.