REST API · v1

REST API FalconCard

Gestisca card, lead e analisi in modo programmatico — per la sincronizzazione con il CRM, l'automazione e le Sue integrazioni personalizzate. Autenticazione con Bearer Token, JSON su HTTPS.

Per iniziare

Dal token alla Sua prima richiesta riuscita in tre passi. L'API comunica esclusivamente in JSON su HTTPS e segue le comuni convenzioni REST — se ha già integrato un'API HTTP, si troverà subito a Suo agio.

  1. 1

    Crei un token

    Apra la Sua dashboard e vada in Account → Token API. Scelga gli scope necessari alla Sua integrazione e copi subito il token — per motivi di sicurezza viene mostrato in chiaro una sola volta.

    Vai ai token API
  2. 2

    Imposti l'header Bearer

    Invii il token nell'header Authorization a ogni richiesta. Aggiunga Accept: application/json affinché anche gli errori vengano restituiti in JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. 3

    Invii la Sua prima richiesta

    Recuperi le Sue card. Una chiamata riuscita restituisce HTTP 200 con un array data e un oggetto meta per la paginazione:

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

    Se vede questa struttura, la Sua autenticazione è corretta. Ogni endpoint di elenco risponde con lo stesso schema data + meta — le singole risorse vengono restituite in un oggetto data senza meta.

URL di base: https://falconcard.net/api/v1 · tutte le risposte sono in JSON.

Autenticazione

Ogni richiesta si autentica con un token di accesso personale (Laravel Sanctum) nell'header:

Authorization: Bearer DEIN_API_TOKEN

Può creare e revocare i token in qualsiasi momento nella dashboard. Ogni token possiede uno o più scope che ne limitano i permessi.

Scope

cards:read Elencare e leggere le card
cards:write Creare, aggiornare ed eliminare le card
leads:read Elencare e leggere i lead
analytics:read Leggere le analisi di visualizzazioni e clic

Concetti

Quattro elementi fondamentali che funzionano in modo identico per ogni endpoint — li impari una volta, valgono ovunque.

Versioning

La versione attuale è /api/v1 ed è fissata nel path. Le modifiche incompatibili vengono rilasciate sotto un nuovo prefisso (ad es. /api/v2), così le integrazioni esistenti restano stabili.

Formato della richiesta

Gli endpoint di scrittura si aspettano un body JSON con Content-Type: application/json. I timestamp sono in ISO 8601 (UTC). I campi sconosciuti vengono ignorati, i campi facoltativi mancanti restano invariati.

Limitazione delle richieste

I token Enterprise possono inviare 1000 richieste al minuto. Ogni risposta include X-RateLimit-Limit e X-RateLimit-Remaining. Al superamento si riceve 429 Too Many Requests con un header Retry-After (secondi fino al reset) — attenda quel tempo prima di riprovare.

Header · ogni risposta
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginazione

Gli endpoint di elenco restituiscono fino a 15 elementi per pagina. Lo controlli con ?page= (in base 1) e ?per_page= (max 100). L'oggetto meta riporta current_page, last_page, per_page e total.

meta · ogni elenco
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Disponibilità. La REST API fa parte del piano Enterprise. I token di altri piani ricevono 403.

Riferimento endpoint

Riferimento completo per tutti e dieci gli endpoint, raggruppati per risorsa. Ogni definizione resta sincronizzata con la specifica OpenAPI — pronta per essere importata in Postman, Insomnia, Scalar o nel Suo generatore di codice.

Cards

Creare, leggere, aggiornare ed eliminare biglietti da visita digitali.

GET /api/v1/cards Scope cards:read

Elenca le card dell'account, dalle aggiornate più di recente.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
page query integer no Numero di pagina (in base 1).
per_page query integer no Elementi per pagina, max 100.

Risposta di successo

200 OK con un array data di card e un oggetto meta per la paginazione.

Codici di errore

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

Crea una nuova card. slug e title vengono generati automaticamente. I campi soggetti al piano vengono adattati ai valori consentiti.

Parametri

Nessun parametro.

Body della richiesta application/json

Campo Tipo Vincoli Descrizione
first_name Obbligatorio string maxLength 100 Nome.
last_name Obbligatorio string maxLength 100 Cognome.
job_title string | null maxLength 150 Posizione / ruolo professionale.
company string | null maxLength 150 Nome dell'azienda.
bio string | null maxLength 1000 Breve descrizione / bio.
email string | null email · maxLength 255 Email di contatto (formato email valido).
phone string | null maxLength 50 Numero di telefono. Caratteri ammessi: cifre, spazi e + - ( ) . /
website string | null uri · maxLength 500 URL del sito web.
booking_url string | null uri · maxLength 500 Link alla prenotazione di appuntamenti.
video_url string | null uri · maxLength 500 URL del video. Richiede la funzione di analisi avanzata, altrimenti viene ignorato. soggetto al piano
address string | null maxLength 500 Indirizzo postale.
social_links array | null Elenco di link ai social media (array di oggetti).
design_config object | null Personalizzazioni di design (colori, font, layout) come oggetto.
template_id string | null maxLength 50 ID del template da utilizzare.
is_public boolean | null default true Indica se la card è raggiungibile pubblicamente. Predefinito true.
show_branding boolean | null Mostra il branding FalconCard. Nasconderlo richiede la funzione whitelabel, altrimenti viene forzato a true. soggetto al piano
show_lead_form boolean | null Mostra il form lead sulla card. Richiede la funzione form lead, altrimenti viene forzato a false. soggetto al piano
seo_title string | null maxLength 100 Titolo SEO per la card pubblica.
seo_description string | null maxLength 250 Meta description SEO.
language string | null maxLength 5 Lingua principale della card (ad es. de).

Risposta di successo

201 Created con la nuova card nell'oggetto data più un message.

Codici di errore

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

Restituisce una singola card inclusi i lead acquisiti.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card percorso integer ID della card.

Risposta di successo

200 OK con la card (incluso un array leads incorporato) nell'oggetto data.

Codici di errore

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

Aggiorna una card. Tutti i campi sono facoltativi; cambiano solo i campi forniti. PUT e PATCH si comportano in modo identico.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card percorso integer ID della card.

Body della richiesta application/json

Campo Tipo Vincoli Descrizione
first_name string maxLength 100 Nome.
last_name string maxLength 100 Cognome.
job_title string | null maxLength 150 Posizione / ruolo professionale.
company string | null maxLength 150 Nome dell'azienda.
bio string | null maxLength 1000 Breve descrizione / bio.
email string | null email · maxLength 255 Email di contatto (formato email valido).
phone string | null maxLength 50 Numero di telefono. Caratteri ammessi: cifre, spazi e + - ( ) . /
website string | null uri · maxLength 500 URL del sito web.
booking_url string | null uri · maxLength 500 Link alla prenotazione di appuntamenti.
video_url string | null uri · maxLength 500 URL del video. Richiede la funzione di analisi avanzata, altrimenti viene ignorato. soggetto al piano
address string | null maxLength 500 Indirizzo postale.
social_links array | null Elenco di link ai social media (array di oggetti).
design_config object | null Personalizzazioni di design (colori, font, layout) come oggetto.
template_id string | null maxLength 50 ID del template da utilizzare.
is_public boolean | null Indica se la card è raggiungibile pubblicamente. Predefinito true.
show_branding boolean | null Mostra il branding FalconCard. Nasconderlo richiede la funzione whitelabel, altrimenti viene forzato a true. soggetto al piano
show_lead_form boolean | null Mostra il form lead sulla card. Richiede la funzione form lead, altrimenti viene forzato a false. soggetto al piano
seo_title string | null maxLength 100 Titolo SEO per la card pubblica.
seo_description string | null maxLength 250 Meta description SEO.
language string | null maxLength 5 Lingua principale della card (ad es. de).
status string | null enum: active, draft, archived Stato di pubblicazione: active, draft o archived.

Risposta di successo

200 OK con la card aggiornata nell'oggetto data più un message.

Codici di errore

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

Aggiorna una card. Tutti i campi sono facoltativi; cambiano solo i campi forniti. PUT e PATCH si comportano in modo identico.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card percorso integer ID della card.

Body della richiesta application/json

Campo Tipo Vincoli Descrizione
first_name string maxLength 100 Nome.
last_name string maxLength 100 Cognome.
job_title string | null maxLength 150 Posizione / ruolo professionale.
company string | null maxLength 150 Nome dell'azienda.
bio string | null maxLength 1000 Breve descrizione / bio.
email string | null email · maxLength 255 Email di contatto (formato email valido).
phone string | null maxLength 50 Numero di telefono. Caratteri ammessi: cifre, spazi e + - ( ) . /
website string | null uri · maxLength 500 URL del sito web.
booking_url string | null uri · maxLength 500 Link alla prenotazione di appuntamenti.
video_url string | null uri · maxLength 500 URL del video. Richiede la funzione di analisi avanzata, altrimenti viene ignorato. soggetto al piano
address string | null maxLength 500 Indirizzo postale.
social_links array | null Elenco di link ai social media (array di oggetti).
design_config object | null Personalizzazioni di design (colori, font, layout) come oggetto.
template_id string | null maxLength 50 ID del template da utilizzare.
is_public boolean | null Indica se la card è raggiungibile pubblicamente. Predefinito true.
show_branding boolean | null Mostra il branding FalconCard. Nasconderlo richiede la funzione whitelabel, altrimenti viene forzato a true. soggetto al piano
show_lead_form boolean | null Mostra il form lead sulla card. Richiede la funzione form lead, altrimenti viene forzato a false. soggetto al piano
seo_title string | null maxLength 100 Titolo SEO per la card pubblica.
seo_description string | null maxLength 250 Meta description SEO.
language string | null maxLength 5 Lingua principale della card (ad es. de).
status string | null enum: active, draft, archived Stato di pubblicazione: active, draft o archived.

Risposta di successo

200 OK con la card aggiornata nell'oggetto data più un message.

Codici di errore

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

Elimina definitivamente una card.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card percorso integer ID della card.

Risposta di successo

200 OK con un message di conferma.

Codici di errore

401403404429

Leads

Legga i contatti acquisiti tramite i form lead sulle Sue card.

GET /api/v1/leads Scope leads:read

Elenca i lead acquisiti su tutte le card, dai più recenti. Filtri su una singola card con card_id.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card_id query integer no Limita a una singola card di Sua proprietà.
page query integer no Numero di pagina (in base 1).
per_page query integer no Elementi per pagina, max 100.

Risposta di successo

200 OK con un array data di lead e un oggetto meta.

Codici di errore

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

Restituisce un singolo lead con un riferimento compatto alla card di acquisizione.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
id percorso integer ID del lead.

Risposta di successo

200 OK con il lead nell'oggetto data.

Codici di errore

401403404429

Analytics

Statistiche aggregate di visualizzazioni e clic — su tutte le card o per singola card.

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

Metriche di visualizzazione aggregate su tutte le card o — tramite card_id — per una singola card.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card_id query integer no Limita a una singola card di Sua proprietà.
period query string (enum) no Intervallo del report. Valori ammessi: 7d, 14d, 30d, 90d, 365d. Predefinito 30d.

Risposta di successo

200 OK con total_views, unique_views, views_per_day più devices, countries e referrers nell'oggetto data.

Codici di errore

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

Metriche di clic aggregate su tutte le card o — tramite card_id — per una singola card.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
card_id query integer no Limita a una singola card di Sua proprietà.
period query string (enum) no Intervallo del report. Valori ammessi: 7d, 14d, 30d, 90d, 365d. Predefinito 30d.

Risposta di successo

200 OK con total_clicks, clicks_by_type e clicks_per_day nell'oggetto data.

Codici di errore

401403422429

Esempi di codice

Snippet pronti all'uso in cURL, JavaScript e Python. Sostituisca DEIN_API_TOKEN con il Suo token reale.

Elenca le card
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"])
Crea una 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"])
Elenca i 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"])
Recupera le analisi
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"])

Esempio: creare una card

Richiesta · 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"
  }'
Risposta · 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."
}

Errori

Ogni errore restituisce una stringa message. Gli errori di validazione (422) contengono inoltre una mappa errors.

Status Name Descrizione Esempio di body
401 Unauthorized Token mancante o non valido.
{ "message": "Unauthenticated." }
403 Forbidden Il piano non include l'accesso API (solo Enterprise) oppure al token manca lo scope richiesto.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found La risorsa non esiste o non appartiene al Suo account.
{ "message": "Not found." }
422 Unprocessable Entity Validazione fallita — il body contiene una mappa errors (campo → messaggi).
429 Too Many Requests Rate limit superato. L'header Retry-After indica il tempo di attesa in secondi.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 contengono inoltre una mappa errors di campo → elenco di messaggi:

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."]
  }
}

Specifica leggibile dalle macchine

L'intera API è documentata come OpenAPI 3.1. Scarichi la specifica e la importi in Postman, Insomnia o Scalar — oppure la usi per generare client type-safe per il Suo linguaggio.

Compatibile con Postman · Insomnia · Scalar · generatori OpenAPI

Scarica openapi.json

Pronto a integrare?

Importi la specifica OpenAPI nei Suoi strumenti oppure crei il Suo primo token API direttamente nella dashboard.