API REST · v1

API REST FalconCard

Gérez vos cartes, vos leads et vos analyses par programmation — pour la synchronisation CRM, l'automatisation et vos propres intégrations. Authentification par Bearer Token, JSON via HTTPS.

Pour commencer

Du token à votre première requête réussie en trois étapes. L'API communique exclusivement en JSON via HTTPS et suit les conventions REST habituelles — si vous avez déjà intégré une API HTTP, vous serez immédiatement à l'aise.

  1. 1

    Créer un token

    Ouvrez votre tableau de bord et accédez à Compte → Tokens API. Choisissez les scopes dont votre intégration a besoin et copiez le token immédiatement — pour des raisons de sécurité, il n'est affiché en clair qu'une seule fois.

    Accéder aux tokens API
  2. 2

    Définir le header Bearer

    Envoyez le token dans le header Authorization à chaque requête. Ajoutez Accept: application/json pour que les erreurs soient également renvoyées en JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. 3

    Envoyer votre première requête

    Récupérez vos cartes. Un appel réussi renvoie un HTTP 200 avec un tableau data et un objet meta pour la pagination :

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

    Si vous obtenez cette structure, votre authentification est correcte. Chaque endpoint de liste répond avec le même schéma data + meta — les ressources uniques sont renvoyées dans un objet data sans meta.

URL de base : https://falconcard.net/api/v1 · toutes les réponses sont au format JSON.

Authentification

Chaque requête s'authentifie avec un token d'accès personnel (Laravel Sanctum) dans le header :

Authorization: Bearer DEIN_API_TOKEN

Vous pouvez créer et révoquer des tokens à tout moment dans le tableau de bord. Chaque token porte un ou plusieurs scopes qui limitent ses permissions.

Scopes

cards:read Lister et lire les cartes
cards:write Créer, mettre à jour et supprimer des cartes
leads:read Lister et lire les leads
analytics:read Lire les analyses de vues et de clics

Concepts

Quatre éléments fondamentaux qui fonctionnent de manière identique pour chaque endpoint — apprenez-les une fois, ils s'appliquent partout.

Versionnage

La version actuelle est /api/v1 et est figée dans le chemin. Les changements incompatibles sont publiés sous un nouveau préfixe (par ex. /api/v2), afin que les intégrations existantes restent stables.

Format de requête

Les endpoints d'écriture attendent un corps JSON avec Content-Type: application/json. Les horodatages sont au format ISO 8601 (UTC). Les champs inconnus sont ignorés, les champs facultatifs omis restent inchangés.

Limitation de débit

Les tokens Enterprise peuvent envoyer 1000 requêtes par minute. Chaque réponse comporte X-RateLimit-Limit et X-RateLimit-Remaining. En cas de dépassement, vous obtenez un 429 Too Many Requests avec un header Retry-After (secondes jusqu'à la réinitialisation) — patientez ce délai avant de réessayer.

Headers · chaque réponse
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Pagination

Les endpoints de liste renvoient jusqu'à 15 éléments par page. Contrôlez-la avec ?page= (à partir de 1) et ?per_page= (max 100). L'objet meta indique current_page, last_page, per_page et total.

meta · chaque liste
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Disponibilité. L'API REST fait partie de l'offre Enterprise. Les tokens issus d'autres offres reçoivent 403.

Référence des endpoints

Référence complète des dix endpoints, regroupés par ressource. Chaque définition reste synchronisée avec la spécification OpenAPI — prête à être importée dans Postman, Insomnia, Scalar ou votre générateur de code.

Cards

Créez, lisez, mettez à jour et supprimez des cartes de visite numériques.

GET /api/v1/cards Scope cards:read

Liste les cartes du compte, les plus récemment mises à jour en premier.

Paramètres

Nom Dans Type Requis Description
page query integer non Numéro de page (à partir de 1).
per_page query integer non Éléments par page, max 100.

Réponse en cas de succès

200 OK avec un tableau data de cartes et un objet meta pour la pagination.

Codes d'erreur

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

Crée une nouvelle carte. Le slug et le titre sont générés automatiquement. Les champs soumis à l'offre sont ramenés aux valeurs autorisées.

Paramètres

Aucun paramètre.

Corps de la requête application/json

Champ Type Contraintes Description
first_name Requis string maxLength 100 Prénom.
last_name Requis string maxLength 100 Nom de famille.
job_title string | null maxLength 150 Poste / intitulé du poste.
company string | null maxLength 150 Nom de l'entreprise.
bio string | null maxLength 1000 Brève description / bio.
email string | null email · maxLength 255 E-mail de contact (format e-mail valide).
phone string | null maxLength 50 Numéro de téléphone. Caractères autorisés : chiffres, espaces et + - ( ) . /
website string | null uri · maxLength 500 URL du site web.
booking_url string | null uri · maxLength 500 Lien vers la prise de rendez-vous.
video_url string | null uri · maxLength 500 URL de la vidéo. Nécessite la fonctionnalité d'analyses avancées, sinon ignorée. selon l'offre
address string | null maxLength 500 Adresse postale.
social_links array | null Liste de liens vers les réseaux sociaux (tableau d'objets).
design_config object | null Personnalisations de design (couleurs, police, mise en page) sous forme d'objet.
template_id string | null maxLength 50 ID du template à utiliser.
is_public boolean | null default true Indique si la carte est accessible publiquement. Par défaut true.
show_branding boolean | null Afficher la marque FalconCard. La masquer nécessite la fonctionnalité whitelabel, sinon forcée à true. selon l'offre
show_lead_form boolean | null Afficher le formulaire de leads sur la carte. Nécessite la fonctionnalité de formulaire de leads, sinon forcée à false. selon l'offre
seo_title string | null maxLength 100 Titre SEO de la carte publique.
seo_description string | null maxLength 250 Méta-description SEO.
language string | null maxLength 5 Langue principale de la carte (par ex. de).

Réponse en cas de succès

201 Created avec la nouvelle carte dans l'objet data, ainsi qu'un message.

Codes d'erreur

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

Renvoie une seule carte, y compris ses leads capturés.

Paramètres

Nom Dans Type Requis Description
card path integer oui ID de la carte.

Réponse en cas de succès

200 OK avec la carte (y compris un tableau leads imbriqué) dans l'objet data.

Codes d'erreur

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

Met à jour une carte. Tous les champs sont facultatifs ; seuls les champs fournis sont modifiés. PUT et PATCH se comportent de manière identique.

Paramètres

Nom Dans Type Requis Description
card path integer oui ID de la carte.

Corps de la requête application/json

Champ Type Contraintes Description
first_name string maxLength 100 Prénom.
last_name string maxLength 100 Nom de famille.
job_title string | null maxLength 150 Poste / intitulé du poste.
company string | null maxLength 150 Nom de l'entreprise.
bio string | null maxLength 1000 Brève description / bio.
email string | null email · maxLength 255 E-mail de contact (format e-mail valide).
phone string | null maxLength 50 Numéro de téléphone. Caractères autorisés : chiffres, espaces et + - ( ) . /
website string | null uri · maxLength 500 URL du site web.
booking_url string | null uri · maxLength 500 Lien vers la prise de rendez-vous.
video_url string | null uri · maxLength 500 URL de la vidéo. Nécessite la fonctionnalité d'analyses avancées, sinon ignorée. selon l'offre
address string | null maxLength 500 Adresse postale.
social_links array | null Liste de liens vers les réseaux sociaux (tableau d'objets).
design_config object | null Personnalisations de design (couleurs, police, mise en page) sous forme d'objet.
template_id string | null maxLength 50 ID du template à utiliser.
is_public boolean | null Indique si la carte est accessible publiquement. Par défaut true.
show_branding boolean | null Afficher la marque FalconCard. La masquer nécessite la fonctionnalité whitelabel, sinon forcée à true. selon l'offre
show_lead_form boolean | null Afficher le formulaire de leads sur la carte. Nécessite la fonctionnalité de formulaire de leads, sinon forcée à false. selon l'offre
seo_title string | null maxLength 100 Titre SEO de la carte publique.
seo_description string | null maxLength 250 Méta-description SEO.
language string | null maxLength 5 Langue principale de la carte (par ex. de).
status string | null enum: active, draft, archived Statut de publication : active, draft ou archived.

Réponse en cas de succès

200 OK avec la carte mise à jour dans l'objet data, ainsi qu'un message.

Codes d'erreur

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

Met à jour une carte. Tous les champs sont facultatifs ; seuls les champs fournis sont modifiés. PUT et PATCH se comportent de manière identique.

Paramètres

Nom Dans Type Requis Description
card path integer oui ID de la carte.

Corps de la requête application/json

Champ Type Contraintes Description
first_name string maxLength 100 Prénom.
last_name string maxLength 100 Nom de famille.
job_title string | null maxLength 150 Poste / intitulé du poste.
company string | null maxLength 150 Nom de l'entreprise.
bio string | null maxLength 1000 Brève description / bio.
email string | null email · maxLength 255 E-mail de contact (format e-mail valide).
phone string | null maxLength 50 Numéro de téléphone. Caractères autorisés : chiffres, espaces et + - ( ) . /
website string | null uri · maxLength 500 URL du site web.
booking_url string | null uri · maxLength 500 Lien vers la prise de rendez-vous.
video_url string | null uri · maxLength 500 URL de la vidéo. Nécessite la fonctionnalité d'analyses avancées, sinon ignorée. selon l'offre
address string | null maxLength 500 Adresse postale.
social_links array | null Liste de liens vers les réseaux sociaux (tableau d'objets).
design_config object | null Personnalisations de design (couleurs, police, mise en page) sous forme d'objet.
template_id string | null maxLength 50 ID du template à utiliser.
is_public boolean | null Indique si la carte est accessible publiquement. Par défaut true.
show_branding boolean | null Afficher la marque FalconCard. La masquer nécessite la fonctionnalité whitelabel, sinon forcée à true. selon l'offre
show_lead_form boolean | null Afficher le formulaire de leads sur la carte. Nécessite la fonctionnalité de formulaire de leads, sinon forcée à false. selon l'offre
seo_title string | null maxLength 100 Titre SEO de la carte publique.
seo_description string | null maxLength 250 Méta-description SEO.
language string | null maxLength 5 Langue principale de la carte (par ex. de).
status string | null enum: active, draft, archived Statut de publication : active, draft ou archived.

Réponse en cas de succès

200 OK avec la carte mise à jour dans l'objet data, ainsi qu'un message.

Codes d'erreur

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

Supprime définitivement une carte.

Paramètres

Nom Dans Type Requis Description
card path integer oui ID de la carte.

Réponse en cas de succès

200 OK avec un message de confirmation.

Codes d'erreur

401403404429

Leads

Lisez les contacts capturés via les formulaires de leads de vos cartes.

GET /api/v1/leads Scope leads:read

Liste les leads capturés sur toutes les cartes, les plus récents en premier. Filtrez sur une seule carte avec card_id.

Paramètres

Nom Dans Type Requis Description
card_id query integer non Restreindre à une seule carte que vous possédez.
page query integer non Numéro de page (à partir de 1).
per_page query integer non Éléments par page, max 100.

Réponse en cas de succès

200 OK avec un tableau data de leads et un objet meta.

Codes d'erreur

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

Renvoie un seul lead avec une référence compacte à la carte de capture.

Paramètres

Nom Dans Type Requis Description
id path integer oui ID du lead.

Réponse en cas de succès

200 OK avec le lead dans l'objet data.

Codes d'erreur

401403404429

Analytics

Statistiques agrégées de vues et de clics — pour toutes les cartes ou par carte.

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

Métriques de vues agrégées sur toutes les cartes ou — via card_id — pour une seule carte.

Paramètres

Nom Dans Type Requis Description
card_id query integer non Restreindre à une seule carte que vous possédez.
period query string (enum) non Période de reporting. Valeurs autorisées : 7d, 14d, 30d, 90d, 365d. Par défaut 30d.

Réponse en cas de succès

200 OK avec total_views, unique_views, views_per_day ainsi que devices, countries et referrers dans l'objet data.

Codes d'erreur

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

Métriques de clics agrégées sur toutes les cartes ou — via card_id — pour une seule carte.

Paramètres

Nom Dans Type Requis Description
card_id query integer non Restreindre à une seule carte que vous possédez.
period query string (enum) non Période de reporting. Valeurs autorisées : 7d, 14d, 30d, 90d, 365d. Par défaut 30d.

Réponse en cas de succès

200 OK avec total_clicks, clicks_by_type et clicks_per_day dans l'objet data.

Codes d'erreur

401403422429

Exemples de code

Extraits à copier-coller en cURL, JavaScript et Python. Remplacez DEIN_API_TOKEN par votre véritable token.

Lister les cartes
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"])
Créer une carte
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"])
Lister les leads
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"])
Récupérer les analyses
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"])

Exemple : créer une carte

Requête · 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éponse · 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."
}

Erreurs

Chaque erreur renvoie une chaîne message . Les erreurs de validation (422) contiennent en plus une map errors .

Status Name Description Exemple de corps
401 Unauthorized Token manquant ou invalide.
{ "message": "Unauthenticated." }
403 Forbidden L'offre n'inclut pas l'accès à l'API (Enterprise uniquement) ou le token ne dispose pas du scope requis.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found La ressource n'existe pas ou n'appartient pas à votre compte.
{ "message": "Not found." }
422 Unprocessable Entity Échec de la validation — le corps contient une map errors (champ → messages).
429 Too Many Requests Limite de débit dépassée. Le header Retry-After indique le temps d'attente en secondes.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 contiennent en plus une map errors associant chaque champ → liste de messages :

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

Spécification lisible par machine

L'API complète est documentée au format OpenAPI 3.1. Téléchargez la spécification et importez-la dans Postman, Insomnia ou Scalar — ou générez-en des clients type-safe pour votre langage.

Compatible avec Postman · Insomnia · Scalar · générateurs OpenAPI

Télécharger openapi.json

Prêt à intégrer ?

Importez la spécification OpenAPI dans vos outils ou créez votre premier token API directement dans le tableau de bord.