Salt la conținut

REST API · v1

FalconCard REST API

Gestionați carduri, lead-uri și analize în mod programatic — pentru sincronizare CRM, automatizare și propriile integrări. Autentificare prin Bearer-Token, JSON peste HTTPS.

01

Primii pași

De la token la prima cerere reușită în trei pași. API-ul vorbește exclusiv JSON peste HTTPS și respectă convențiile REST uzuale — dacă ați integrat vreodată un API HTTP, vă veți simți ca acasă.

  1. Creați un token

    Deschideți panoul de control și navigați la Cont → Token-uri API. Alegeți scopes-urile de care are nevoie integrarea dumneavoastră și copiați token-ul imediat — din motive de securitate, acesta este afișat în clar o singură dată.

    Mergeți la Token-uri API
  2. Setați header-ul Bearer

    Trimiteți token-ul în header-ul Authorization la fiecare cerere. Adăugați Accept: application/json pentru ca și erorile să fie returnate în format JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Trimiteți prima cerere

    Preluați-vă cardurile. Un apel reușit returnează HTTP 200 cu un array data și un obiect meta pentru paginare:

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

Dacă vedeți această structură, autentificarea dumneavoastră este corectă. Fiecare endpoint de listare răspunde cu aceeași schemă data + meta — resursele individuale sunt returnate într-un obiect data fără meta.

URL de bază: https://falconcard.net/api/v1 · toate răspunsurile sunt JSON.

02

Autentificare

Fiecare cerere se autentifică cu un token de acces personal (Laravel Sanctum) în header:

Authorization: Bearer DEIN_API_TOKEN

Puteți crea și revoca token-uri oricând în panoul de control. Fiecare token poartă unul sau mai multe scopes care îi limitează permisiunile.

Scopes

cards:read

Listarea și citirea cardurilor

cards:write

Crearea, actualizarea și ștergerea cardurilor

leads:read

Listarea și citirea lead-urilor

analytics:read

Citirea analizelor de vizualizări și clicuri

03

Concepte

Patru elemente fundamentale care funcționează identic pentru fiecare endpoint — învățați-le o dată, se aplică peste tot.

Versionare

Versiunea curentă este /api/v1 și este fixată în cale. Modificările cu impact major sunt livrate sub un nou prefix (de ex. /api/v2), astfel încât integrările existente rămân stabile.

Format cerere

Endpoint-urile de scriere așteaptă un corp JSON cu Content-Type: application/json. Timestamp-urile sunt ISO 8601 (UTC). Câmpurile necunoscute sunt ignorate, câmpurile opționale lipsă rămân neschimbate.

Rate limiting

Token-urile Enterprise pot trimite 1000 de cereri pe minut. Fiecare răspuns poartă X-RateLimit-Limit și X-RateLimit-Remaining. La depășire primiți 429 Too Many Requests cu un header Retry-After (secunde până la resetare) — așteptați acel interval înainte de a reîncerca.

Headere · fiecare răspuns
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginare

Endpoint-urile de listare returnează până la 15 elemente pe pagină. Controlați-o cu ?page= (începe de la 1) și ?per_page= (max. 100). Obiectul meta raportează current_page, last_page, per_page și total.

meta · fiecare listă
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Disponibilitate. REST API-ul face parte din planul Enterprise. Token-urile din alte planuri primesc 403.

04

Referință endpoint-uri

Referință completă pentru toate cele zece endpoint-uri, grupate pe resursă. Fiecare definiție rămâne sincronizată cu specificația OpenAPI — gata de importat în Postman, Insomnia, Scalar sau în generatorul dumneavoastră de cod.

01

Cards

Creați, citiți, actualizați și ștergeți cărți de vizită digitale.

GET
/api/v1/cards Scope cards:read

Listează cardurile contului, cele mai recent actualizate primele.

Parametri

Nume În Tip Obligatoriu Descriere
page query integer nu Numărul paginii (începe de la 1).
per_page query integer nu Elemente pe pagină, max. 100.

Răspuns de succes

200 OK cu un array data de carduri și un obiect meta pentru paginare.

Coduri de eroare

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

Creează un card nou. slug și title sunt generate automat. Câmpurile restricționate după plan sunt ajustate la valorile permise.

Parametri

Fără parametri.

Corpul cererii application/json

Câmp Tip Constrângeri Descriere
first_name Obligatoriu string maxLength 100 Prenume.
last_name Obligatoriu string maxLength 100 Nume de familie.
job_title string | null maxLength 150 Funcție / titlu profesional.
company string | null maxLength 150 Numele companiei.
bio string | null maxLength 1000 Descriere scurtă / biografie.
email string | null email · maxLength 255 Email de contact (format de email valid).
phone string | null maxLength 50 Număr de telefon. Caractere permise: cifre, spații și + - ( ) . /
website string | null uri · maxLength 500 URL-ul site-ului web.
booking_url string | null uri · maxLength 500 Link către programarea de întâlniri.
video_url string | null uri · maxLength 500 URL video. Necesită funcția de analize avansate, în caz contrar este ignorat. restricționat după plan
address string | null maxLength 500 Adresă poștală.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Listă de linkuri către rețele sociale (array de obiecte).
design_config object | null — Suprascrieri de design (culori, font, layout) sub formă de obiect.
template_id string | null maxLength 50 ID-ul șablonului de utilizat.
is_public boolean | null default true Dacă cardul este accesibil public. Implicit true.
show_branding boolean | null — Afișează branding-ul FalconCard. Ascunderea acestuia necesită funcția whitelabel, în caz contrar este forțat la true. restricționat după plan
show_lead_form boolean | null — Afișează formularul de lead pe card. Necesită funcția de formular de lead, în caz contrar este forțat la false. restricționat după plan
seo_title string | null maxLength 100 Titlu SEO pentru cardul public.
seo_description string | null maxLength 250 Meta descriere SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Limba principală a cardului (de ex. de).

Răspuns de succes

201 Created cu noul card în obiectul data plus un mesaj.

Coduri de eroare

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

Returnează un singur card, inclusiv lead-urile capturate de acesta.

Parametri

Nume În Tip Obligatoriu Descriere
card path integer da ID-ul cardului.

Răspuns de succes

200 OK cu cardul (inclusiv un array leads încorporat) în obiectul data.

Coduri de eroare

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

Actualizează un card. Toate câmpurile sunt opționale; se modifică doar câmpurile furnizate. PUT și PATCH se comportă identic.

Parametri

Nume În Tip Obligatoriu Descriere
card path integer da ID-ul cardului.

Corpul cererii application/json

Câmp Tip Constrângeri Descriere
first_name string maxLength 100 Prenume.
last_name string maxLength 100 Nume de familie.
job_title string | null maxLength 150 Funcție / titlu profesional.
company string | null maxLength 150 Numele companiei.
bio string | null maxLength 1000 Descriere scurtă / biografie.
email string | null email · maxLength 255 Email de contact (format de email valid).
phone string | null maxLength 50 Număr de telefon. Caractere permise: cifre, spații și + - ( ) . /
website string | null uri · maxLength 500 URL-ul site-ului web.
booking_url string | null uri · maxLength 500 Link către programarea de întâlniri.
video_url string | null uri · maxLength 500 URL video. Necesită funcția de analize avansate, în caz contrar este ignorat. restricționat după plan
address string | null maxLength 500 Adresă poștală.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Listă de linkuri către rețele sociale (array de obiecte).
design_config object | null — Suprascrieri de design (culori, font, layout) sub formă de obiect.
template_id string | null maxLength 50 ID-ul șablonului de utilizat.
is_public boolean | null — Dacă cardul este accesibil public. Implicit true.
show_branding boolean | null — Afișează branding-ul FalconCard. Ascunderea acestuia necesită funcția whitelabel, în caz contrar este forțat la true. restricționat după plan
show_lead_form boolean | null — Afișează formularul de lead pe card. Necesită funcția de formular de lead, în caz contrar este forțat la false. restricționat după plan
seo_title string | null maxLength 100 Titlu SEO pentru cardul public.
seo_description string | null maxLength 250 Meta descriere SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Limba principală a cardului (de ex. de).
status string | null enum: active, draft, archived Statut de publicare: active, draft sau archived.

Răspuns de succes

200 OK cu cardul actualizat în obiectul data plus un mesaj.

Coduri de eroare

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

Actualizează un card. Toate câmpurile sunt opționale; se modifică doar câmpurile furnizate. PUT și PATCH se comportă identic.

Parametri

Nume În Tip Obligatoriu Descriere
card path integer da ID-ul cardului.

Corpul cererii application/json

Câmp Tip Constrângeri Descriere
first_name string maxLength 100 Prenume.
last_name string maxLength 100 Nume de familie.
job_title string | null maxLength 150 Funcție / titlu profesional.
company string | null maxLength 150 Numele companiei.
bio string | null maxLength 1000 Descriere scurtă / biografie.
email string | null email · maxLength 255 Email de contact (format de email valid).
phone string | null maxLength 50 Număr de telefon. Caractere permise: cifre, spații și + - ( ) . /
website string | null uri · maxLength 500 URL-ul site-ului web.
booking_url string | null uri · maxLength 500 Link către programarea de întâlniri.
video_url string | null uri · maxLength 500 URL video. Necesită funcția de analize avansate, în caz contrar este ignorat. restricționat după plan
address string | null maxLength 500 Adresă poștală.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Listă de linkuri către rețele sociale (array de obiecte).
design_config object | null — Suprascrieri de design (culori, font, layout) sub formă de obiect.
template_id string | null maxLength 50 ID-ul șablonului de utilizat.
is_public boolean | null — Dacă cardul este accesibil public. Implicit true.
show_branding boolean | null — Afișează branding-ul FalconCard. Ascunderea acestuia necesită funcția whitelabel, în caz contrar este forțat la true. restricționat după plan
show_lead_form boolean | null — Afișează formularul de lead pe card. Necesită funcția de formular de lead, în caz contrar este forțat la false. restricționat după plan
seo_title string | null maxLength 100 Titlu SEO pentru cardul public.
seo_description string | null maxLength 250 Meta descriere SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Limba principală a cardului (de ex. de).
status string | null enum: active, draft, archived Statut de publicare: active, draft sau archived.

Răspuns de succes

200 OK cu cardul actualizat în obiectul data plus un mesaj.

Coduri de eroare

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

Șterge definitiv un card.

Parametri

Nume În Tip Obligatoriu Descriere
card path integer da ID-ul cardului.

Răspuns de succes

200 OK cu un mesaj de confirmare.

Coduri de eroare

401403404429
02

Leads

Citiți contactele capturate prin formularele de lead de pe cardurile dumneavoastră.

GET
/api/v1/leads Scope leads:read

Listează lead-urile capturate pe toate cardurile, cele mai noi primele. Filtrați la un singur card cu card_id.

Parametri

Nume În Tip Obligatoriu Descriere
card_id query integer nu Restrângeți la un singur card pe care îl dețineți.
page query integer nu Numărul paginii (începe de la 1).
per_page query integer nu Elemente pe pagină, max. 100.

Răspuns de succes

200 OK cu un array data de lead-uri și un obiect meta.

Coduri de eroare

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

Returnează un singur lead cu o referință compactă către cardul care l-a capturat.

Parametri

Nume În Tip Obligatoriu Descriere
id path integer da ID-ul lead-ului.

Răspuns de succes

200 OK cu lead-ul în obiectul data.

Coduri de eroare

401403404429
03

Analytics

Statistici agregate de vizualizări și clicuri — pentru toate cardurile sau pentru fiecare card în parte.

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

Metrici agregate de vizualizări pentru toate cardurile sau — prin card_id — pentru un singur card.

Parametri

Nume În Tip Obligatoriu Descriere
card_id query integer nu Restrângeți la un singur card pe care îl dețineți.
period query string (enum) nu Intervalul de raportare. Permise: 7d, 14d, 30d, 90d, 365d. Implicit 30d.

Răspuns de succes

200 OK cu total_views, unique_views, views_per_day plus devices, countries și referrers în obiectul data.

Coduri de eroare

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

Metrici agregate de clicuri pentru toate cardurile sau — prin card_id — pentru un singur card.

Parametri

Nume În Tip Obligatoriu Descriere
card_id query integer nu Restrângeți la un singur card pe care îl dețineți.
period query string (enum) nu Intervalul de raportare. Permise: 7d, 14d, 30d, 90d, 365d. Implicit 30d.

Răspuns de succes

200 OK cu total_clicks, clicks_by_type și clicks_per_day în obiectul data.

Coduri de eroare

401403422429

05

Exemple de cod

Fragmente de cod gata de copiat în cURL, JavaScript și Python. Înlocuiți DEIN_API_TOKEN cu token-ul dumneavoastră real.

Listare carduri
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"])
Creare card
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"])
Listare lead-uri
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"])
Preluare analize
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"])

Exemplu: crearea unui card

Cerere · 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"
  }'
Răspuns · 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

Erori

Fiecare eroare returnează un string message. Erorile de validare (422) conțin în plus o hartă errors.

Status Name Descriere Exemplu de corp
401 Unauthorized Token lipsă sau invalid.
{ "message": "Unauthenticated." }
403 Forbidden Planul nu include acces API (doar Enterprise) sau token-ului îi lipsește scope-ul necesar.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Resursa nu există sau nu aparține contului dumneavoastră.
{ "message": "Not found." }
422 Unprocessable Entity Validare eșuată — corpul conține o hartă errors (câmp → mesaje).
429 Too Many Requests Rate limit depășit. Header-ul Retry-After indică timpul de așteptare în secunde.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 conțin în plus o hartă errors cu câmp → listă de mesaje:

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

Specificație lizibilă de mașină

Întregul API este documentat ca OpenAPI 3.1. Descărcați specificația și importați-o în Postman, Insomnia sau Scalar — sau generați din ea clienți cu tipuri sigure pentru limbajul dumneavoastră.

Compatibil cu Postman · Insomnia · Scalar · generatoare OpenAPI

Descărcați openapi.json

08

Sunteți gata să integrați?

Importați specificația OpenAPI în instrumentele dumneavoastră sau creați primul token API direct în panoul de control.