Prijeđite na sadržaj

REST API · v1

FalconCard REST API

Upravljajte karticama, potencijalnim kontaktima i analitikom programski — za sinkronizaciju s CRM-om, automatizaciju i vlastite integracije. Autentifikacija putem Bearer tokena, JSON preko HTTPS-a.

01

Početak rada

Od tokena do vašeg prvog uspješnog zahtjeva u tri koraka. API komunicira isključivo u formatu JSON preko HTTPS-a i slijedi uobičajene REST konvencije — ako ste ikad integrirali HTTP API, osjećat ćete se kao kod kuće.

  1. Izradite token

    Otvorite svoju nadzornu ploču i otiđite na Račun → API tokeni. Odaberite opsege koje vaša integracija treba i odmah kopirajte token — iz sigurnosnih razloga prikazuje se u čitljivom obliku samo jednom.

    Idite na API tokene
  2. Postavite Bearer header

    Pošaljite token u Authorization headeru pri svakom zahtjevu. Dodajte Accept: application/json kako bi se i pogreške vraćale u formatu JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Pošaljite svoj prvi zahtjev

    Dohvatite svoje kartice. Uspješan poziv vraća HTTP 200 s data poljem i meta objektom za straničenje:

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

Ako vidite ovaj oblik, vaša je autentifikacija ispravna. Svaka krajnja točka popisa odgovara istom data + meta shemom — pojedinačni resursi vraćaju se u data objektu bez meta.

Osnovni URL: https://falconcard.net/api/v1 · svi odgovori su u formatu JSON.

02

Autentifikacija

Svaki zahtjev autentificira se pomoću osobnog pristupnog tokena (Laravel Sanctum) u headeru:

Authorization: Bearer DEIN_API_TOKEN

Tokene možete izraditi i opozvati u bilo kojem trenutku na nadzornoj ploči. Svaki token nosi jedan ili više opsega koji ograničavaju njegova dopuštenja.

Opsezi

cards:read

Prikaz i čitanje kartica

cards:write

Izrada, ažuriranje i brisanje kartica

leads:read

Prikaz i čitanje potencijalnih kontakata

analytics:read

Čitanje analitike pregleda i klikova

03

Koncepti

Četiri gradivna bloka koji rade jednako za svaku krajnju točku — naučite ih jednom, vrijede svugdje.

Verzioniranje

Trenutna verzija je /api/v1 i fiksirana je u putanji. Nekompatibilne promjene isporučuju se pod novim prefiksom (npr. /api/v2), tako da postojeće integracije ostaju stabilne.

Format zahtjeva

Krajnje točke za pisanje očekuju JSON tijelo s Content-Type: application/json. Vremenske oznake su u formatu ISO 8601 (UTC). Nepoznata polja se zanemaruju, neobavezna polja koja nedostaju ostaju nepromijenjena.

Ograničavanje brzine

Enterprise tokeni mogu poslati 1000 zahtjeva po minuti. Svaki odgovor nosi X-RateLimit-Limit i X-RateLimit-Remaining. Kada se prekorači, dobivate 429 Too Many Requests s Retry-After headerom (sekunde do resetiranja) — pričekajte toliko prije ponovnog pokušaja.

Headeri · svaki odgovor
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Straničenje

Krajnje točke popisa vraćaju do 15 stavki po stranici. Kontrolirajte ga pomoću ?page= (počevši od 1) i ?per_page= (najviše 100). meta objekt prijavljuje current_page, last_page, per_page i total.

meta · svaki popis
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Dostupnost. REST API dio je Enterprise plana. Tokeni s drugih planova dobivaju 403.

04

Referenca krajnjih točaka

Potpuna referenca za svih deset krajnjih točaka, grupirana po resursu. Svaka definicija ostaje sinkronizirana s OpenAPI specifikacijom — spremno za uvoz u Postman, Insomnia, Scalar ili vaš generator koda.

01

Cards

Izrada, čitanje, ažuriranje i brisanje digitalnih poslovnih kartica.

GET
/api/v1/cards Opseg cards:read

Prikazuje kartice računa, prvo one nedavno ažurirane.

Parametri

Naziv U Tip Obavezno Opis
page query integer ne Broj stranice (počevši od 1).
per_page query integer ne Stavki po stranici, najviše 100.

Uspješan odgovor

200 OK s data poljem kartica i meta objektom za straničenje.

Kodovi pogrešaka

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

Izrađuje novu karticu. slug i title generiraju se automatski. Polja ograničena planom usklađuju se s dopuštenim vrijednostima.

Parametri

Bez parametara.

Tijelo zahtjeva application/json

Polje Tip Ograničenja Opis
first_name Obavezno string maxLength 100 Ime.
last_name Obavezno string maxLength 100 Prezime.
job_title string | null maxLength 150 Pozicija / naziv radnog mjesta.
company string | null maxLength 150 Naziv tvrtke.
bio string | null maxLength 1000 Kratak opis / biografija.
email string | null email · maxLength 255 Kontakt e-pošta (valjan format e-pošte).
phone string | null maxLength 50 Telefonski broj. Dopušteni znakovi: znamenke, razmaci te + - ( ) . /
website string | null uri · maxLength 500 URL web-mjesta.
booking_url string | null uri · maxLength 500 Poveznica za zakazivanje termina.
video_url string | null uri · maxLength 500 URL videozapisa. Zahtijeva značajku napredne analitike, inače se zanemaruje. ograničeno planom
address string | null maxLength 500 Poštanska adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Popis poveznica na društvene mreže (array objekata).
design_config object | null — Prepisivanja dizajna (boje, font, izgled) kao objekt.
template_id string | null maxLength 50 ID predloška koji se koristi.
is_public boolean | null default true Je li kartica javno dostupna. Zadano true.
show_branding boolean | null — Prikaz FalconCard brendiranja. Skrivanje zahtijeva značajku whitelabel, inače je prisilno postavljeno na true. ograničeno planom
show_lead_form boolean | null — Prikaz obrasca za potencijalne kontakte na kartici. Zahtijeva značajku obrasca za potencijalne kontakte, inače je prisilno postavljeno na false. ograničeno planom
seo_title string | null maxLength 100 SEO naslov za javnu karticu.
seo_description string | null maxLength 250 SEO meta opis.
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).

Uspješan odgovor

201 Created s novom karticom u data objektu te porukom.

Kodovi pogrešaka

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

Vraća pojedinačnu karticu uključujući njezine prikupljene potencijalne kontakte.

Parametri

Naziv U Tip Obavezno Opis
card path integer da ID kartice.

Uspješan odgovor

200 OK s karticom (uključujući ugrađeno leads polje) u data objektu.

Kodovi pogrešaka

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

Ažurira karticu. Sva su polja neobavezna; mijenjaju se samo navedena polja. PUT i PATCH ponašaju se identično.

Parametri

Naziv U Tip Obavezno Opis
card path integer da ID kartice.

Tijelo zahtjeva application/json

Polje Tip Ograničenja Opis
first_name string maxLength 100 Ime.
last_name string maxLength 100 Prezime.
job_title string | null maxLength 150 Pozicija / naziv radnog mjesta.
company string | null maxLength 150 Naziv tvrtke.
bio string | null maxLength 1000 Kratak opis / biografija.
email string | null email · maxLength 255 Kontakt e-pošta (valjan format e-pošte).
phone string | null maxLength 50 Telefonski broj. Dopušteni znakovi: znamenke, razmaci te + - ( ) . /
website string | null uri · maxLength 500 URL web-mjesta.
booking_url string | null uri · maxLength 500 Poveznica za zakazivanje termina.
video_url string | null uri · maxLength 500 URL videozapisa. Zahtijeva značajku napredne analitike, inače se zanemaruje. ograničeno planom
address string | null maxLength 500 Poštanska adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Popis poveznica na društvene mreže (array objekata).
design_config object | null — Prepisivanja dizajna (boje, font, izgled) kao objekt.
template_id string | null maxLength 50 ID predloška koji se koristi.
is_public boolean | null — Je li kartica javno dostupna. Zadano true.
show_branding boolean | null — Prikaz FalconCard brendiranja. Skrivanje zahtijeva značajku whitelabel, inače je prisilno postavljeno na true. ograničeno planom
show_lead_form boolean | null — Prikaz obrasca za potencijalne kontakte na kartici. Zahtijeva značajku obrasca za potencijalne kontakte, inače je prisilno postavljeno na false. ograničeno planom
seo_title string | null maxLength 100 SEO naslov za javnu karticu.
seo_description string | null maxLength 250 SEO meta opis.
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 Status objave: active, draft ili archived.

Uspješan odgovor

200 OK s ažuriranom karticom u data objektu te porukom.

Kodovi pogrešaka

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

Ažurira karticu. Sva su polja neobavezna; mijenjaju se samo navedena polja. PUT i PATCH ponašaju se identično.

Parametri

Naziv U Tip Obavezno Opis
card path integer da ID kartice.

Tijelo zahtjeva application/json

Polje Tip Ograničenja Opis
first_name string maxLength 100 Ime.
last_name string maxLength 100 Prezime.
job_title string | null maxLength 150 Pozicija / naziv radnog mjesta.
company string | null maxLength 150 Naziv tvrtke.
bio string | null maxLength 1000 Kratak opis / biografija.
email string | null email · maxLength 255 Kontakt e-pošta (valjan format e-pošte).
phone string | null maxLength 50 Telefonski broj. Dopušteni znakovi: znamenke, razmaci te + - ( ) . /
website string | null uri · maxLength 500 URL web-mjesta.
booking_url string | null uri · maxLength 500 Poveznica za zakazivanje termina.
video_url string | null uri · maxLength 500 URL videozapisa. Zahtijeva značajku napredne analitike, inače se zanemaruje. ograničeno planom
address string | null maxLength 500 Poštanska adresa.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Popis poveznica na društvene mreže (array objekata).
design_config object | null — Prepisivanja dizajna (boje, font, izgled) kao objekt.
template_id string | null maxLength 50 ID predloška koji se koristi.
is_public boolean | null — Je li kartica javno dostupna. Zadano true.
show_branding boolean | null — Prikaz FalconCard brendiranja. Skrivanje zahtijeva značajku whitelabel, inače je prisilno postavljeno na true. ograničeno planom
show_lead_form boolean | null — Prikaz obrasca za potencijalne kontakte na kartici. Zahtijeva značajku obrasca za potencijalne kontakte, inače je prisilno postavljeno na false. ograničeno planom
seo_title string | null maxLength 100 SEO naslov za javnu karticu.
seo_description string | null maxLength 250 SEO meta opis.
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 Status objave: active, draft ili archived.

Uspješan odgovor

200 OK s ažuriranom karticom u data objektu te porukom.

Kodovi pogrešaka

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

Trajno briše karticu.

Parametri

Naziv U Tip Obavezno Opis
card path integer da ID kartice.

Uspješan odgovor

200 OK s porukom potvrde.

Kodovi pogrešaka

401403404429
02

Leads

Čitanje kontakata prikupljenih putem obrazaca za potencijalne kontakte na vašim karticama.

GET
/api/v1/leads Opseg leads:read

Prikazuje potencijalne kontakte prikupljene na svim karticama, najnovije prve. Filtrirajte na jednu karticu pomoću card_id.

Parametri

Naziv U Tip Obavezno Opis
card_id query integer ne Ograničite na pojedinačnu karticu u vašem vlasništvu.
page query integer ne Broj stranice (počevši od 1).
per_page query integer ne Stavki po stranici, najviše 100.

Uspješan odgovor

200 OK s data poljem potencijalnih kontakata i meta objektom.

Kodovi pogrešaka

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

Vraća pojedinačni potencijalni kontakt s kompaktnom referencom na karticu koja ga je prikupila.

Parametri

Naziv U Tip Obavezno Opis
id path integer da ID potencijalnog kontakta.

Uspješan odgovor

200 OK s potencijalnim kontaktom u data objektu.

Kodovi pogrešaka

401403404429
03

Analytics

Agregirana statistika pregleda i klikova — za sve kartice ili po kartici.

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

Agregirane metrike pregleda na svim karticama ili — putem card_id — za pojedinačnu karticu.

Parametri

Naziv U Tip Obavezno Opis
card_id query integer ne Ograničite na pojedinačnu karticu u vašem vlasništvu.
period query string (enum) ne Razdoblje izvještavanja. Dopušteno: 7d, 14d, 30d, 90d, 365d. Zadano 30d.

Uspješan odgovor

200 OK s total_views, unique_views, views_per_day te devices, countries i referrers u data objektu.

Kodovi pogrešaka

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

Agregirane metrike klikova na svim karticama ili — putem card_id — za pojedinačnu karticu.

Parametri

Naziv U Tip Obavezno Opis
card_id query integer ne Ograničite na pojedinačnu karticu u vašem vlasništvu.
period query string (enum) ne Razdoblje izvještavanja. Dopušteno: 7d, 14d, 30d, 90d, 365d. Zadano 30d.

Uspješan odgovor

200 OK s total_clicks, clicks_by_type i clicks_per_day u data objektu.

Kodovi pogrešaka

401403422429

05

Primjeri koda

Isječci za kopiranje i lijepljenje u cURL-u, JavaScriptu i Pythonu. Zamijenite DEIN_API_TOKEN svojim stvarnim tokenom.

Prikaz kartica
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"])
Izrada 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 potencijalnih kontakata
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"])
Dohvaćanje 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"])

Primjer: izrada kartice

Zahtjev · 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"
  }'
Odgovor · 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

Pogreške

Svaka pogreška vraća message niz znakova. Pogreške pri validaciji (422) dodatno sadrže errors mapu.

Status Name Opis Primjer tijela
401 Unauthorized Token nedostaje ili je nevažeći.
{ "message": "Unauthenticated." }
403 Forbidden Plan ne uključuje pristup API-ju (samo Enterprise) ili tokenu nedostaje potreban opseg.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Resurs ne postoji ili ne pripada vašem računu.
{ "message": "Not found." }
422 Unprocessable Entity Validacija nije uspjela — tijelo sadrži errors mapu (polje → poruke).
429 Too Many Requests Ograničenje brzine je prekoračeno. Retry-After header navodi vrijeme čekanja u sekundama.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 dodatno sadrže errors mapu polje → popis poruka:

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 čitljiva specifikacija

Cjelokupni API dokumentiran je kao OpenAPI 3.1. Preuzmite specifikaciju i uvezite je u Postman, Insomnia ili Scalar — ili iz nje generirajte tipski sigurne klijente za svoj jezik.

Kompatibilno s Postman · Insomnia · Scalar · OpenAPI generatorima

Preuzmite openapi.json

08

Spremni za integraciju?

Uvezite OpenAPI specifikaciju u svoje alate ili izradite svoj prvi API token izravno na nadzornoj ploči.