REST API · v1

REST API de FalconCard

Gestione tarjetas, leads y analíticas de forma programática: para sincronización con su CRM, automatización e integraciones propias. Autenticación mediante Bearer Token, JSON sobre HTTPS.

Primeros pasos

Del token a su primera solicitud exitosa en tres pasos. La API habla exclusivamente JSON sobre HTTPS y sigue las convenciones REST habituales — si alguna vez ha integrado una API HTTP, se sentirá como en casa.

  1. 1

    Crear un token

    Abra su panel y navegue hasta Cuenta → Tokens de API. Elija los scopes que necesita su integración y copie el token de inmediato — por seguridad, se muestra en texto plano una sola vez.

    Ir a Tokens de API
  2. 2

    Definir el header Bearer

    Envíe el token en el header Authorization en cada solicitud. Añada Accept: application/json para que los errores también lleguen como JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. 3

    Enviar su primera solicitud

    Recupere sus tarjetas. Una llamada exitosa devuelve HTTP 200 con un array data y un objeto meta para la paginación:

    cURL
    curl https://falconcard.net/api/v1/cards \
      -H "Authorization: Bearer DEIN_API_TOKEN" \
      -H "Accept: application/json"
    Respuesta · 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 ve esta estructura, su autenticación es correcta. Cada endpoint de listado responde con el mismo esquema data + meta — los recursos individuales se devuelven en un objeto data sin meta.

URL base: https://falconcard.net/api/v1 · todas las respuestas son JSON.

Autenticación

Cada solicitud se autentica con un token de acceso personal (Laravel Sanctum) en el header:

Authorization: Bearer DEIN_API_TOKEN

Puede crear y revocar tokens en cualquier momento en el panel. Cada token lleva uno o varios scopes que limitan sus permisos.

Scopes

cards:read Listar y leer tarjetas
cards:write Crear, actualizar y eliminar tarjetas
leads:read Listar y leer leads
analytics:read Leer analíticas de visualizaciones y clics

Conceptos

Cuatro bloques de construcción que funcionan de forma idéntica en todos los endpoints — apréndalos una vez y se aplican en todas partes.

Versionado

La versión actual es /api/v1 y se fija en la ruta. Los cambios incompatibles se publican bajo un nuevo prefijo (p. ej. /api/v2), de modo que las integraciones existentes permanecen estables.

Formato de la solicitud

Los endpoints de escritura esperan un cuerpo JSON con Content-Type: application/json. Las marcas de tiempo son ISO 8601 (UTC). Los campos desconocidos se ignoran; los campos opcionales omitidos permanecen sin cambios.

Límite de velocidad

Los tokens Enterprise pueden enviar 1000 solicitudes por minuto. Cada respuesta incluye X-RateLimit-Limit y X-RateLimit-Remaining. Cuando se supera, recibe 429 Too Many Requests con un header Retry-After (segundos hasta el reinicio) — espere ese tiempo antes de reintentar.

Headers · cada respuesta
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Paginación

Los endpoints de listado devuelven hasta 15 elementos por página. Contrólelo con ?page= (empezando en 1) y ?per_page= (máx. 100). El objeto meta informa de current_page, last_page, per_page y total.

meta · cada listado
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Disponibilidad. La REST API forma parte del plan Enterprise. Los tokens de otros planes reciben 403.

Referencia de endpoints

Referencia completa de los diez endpoints, agrupados por recurso. Cada definición se mantiene sincronizada con la especificación OpenAPI — lista para importar en Postman, Insomnia, Scalar o su generador de código.

Cards

Cree, lea, actualice y elimine tarjetas de visita digitales.

GET /api/v1/cards Scope cards:read

Lista las tarjetas de la cuenta, las actualizadas más recientemente primero.

Parámetros

Nombre En Tipo Obligatorio Descripción
page query integer no Número de página (empezando en 1).
per_page query integer no Elementos por página, máx. 100.

Respuesta de éxito

200 OK con un array data de tarjetas y un objeto meta para la paginación.

Códigos de error

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

Crea una nueva tarjeta. slug y title se generan automáticamente. Los campos limitados por plan se ajustan a los valores permitidos.

Parámetros

Sin parámetros.

Cuerpo de la solicitud application/json

Campo Tipo Restricciones Descripción
first_name Obligatorio string maxLength 100 Nombre.
last_name Obligatorio string maxLength 100 Apellidos.
job_title string | null maxLength 150 Cargo / puesto de trabajo.
company string | null maxLength 150 Nombre de la empresa.
bio string | null maxLength 1000 Descripción breve / biografía.
email string | null email · maxLength 255 Correo electrónico de contacto (formato de email válido).
phone string | null maxLength 50 Número de teléfono. Caracteres permitidos: dígitos, espacios y + - ( ) . /
website string | null uri · maxLength 500 URL del sitio web.
booking_url string | null uri · maxLength 500 Enlace para reservar citas.
video_url string | null uri · maxLength 500 URL de vídeo. Requiere la función de analíticas avanzadas; de lo contrario, se ignora. limitado por plan
address string | null maxLength 500 Dirección postal.
social_links array | null Lista de enlaces de redes sociales (array de objetos).
design_config object | null Ajustes de diseño (colores, fuente, maquetación) como objeto.
template_id string | null maxLength 50 ID de la plantilla a utilizar.
is_public boolean | null default true Si la tarjeta es accesible públicamente. Predeterminado true.
show_branding boolean | null Mostrar la marca de FalconCard. Ocultarla requiere la función whitelabel; de lo contrario, se fuerza a true. limitado por plan
show_lead_form boolean | null Mostrar el formulario de leads en la tarjeta. Requiere la función de formulario de leads; de lo contrario, se fuerza a false. limitado por plan
seo_title string | null maxLength 100 Título SEO de la tarjeta pública.
seo_description string | null maxLength 250 Meta descripción SEO.
language string | null maxLength 5 Idioma principal de la tarjeta (p. ej. de).

Respuesta de éxito

201 Created con la nueva tarjeta en el objeto data más un message.

Códigos de error

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

Devuelve una sola tarjeta, incluidos los leads capturados.

Parámetros

Nombre En Tipo Obligatorio Descripción
card ruta integer ID de la tarjeta.

Respuesta de éxito

200 OK con la tarjeta (incluido un array leads incrustado) en el objeto data.

Códigos de error

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

Actualiza una tarjeta. Todos los campos son opcionales; solo cambian los campos proporcionados. PUT y PATCH se comportan de forma idéntica.

Parámetros

Nombre En Tipo Obligatorio Descripción
card ruta integer ID de la tarjeta.

Cuerpo de la solicitud application/json

Campo Tipo Restricciones Descripción
first_name string maxLength 100 Nombre.
last_name string maxLength 100 Apellidos.
job_title string | null maxLength 150 Cargo / puesto de trabajo.
company string | null maxLength 150 Nombre de la empresa.
bio string | null maxLength 1000 Descripción breve / biografía.
email string | null email · maxLength 255 Correo electrónico de contacto (formato de email válido).
phone string | null maxLength 50 Número de teléfono. Caracteres permitidos: dígitos, espacios y + - ( ) . /
website string | null uri · maxLength 500 URL del sitio web.
booking_url string | null uri · maxLength 500 Enlace para reservar citas.
video_url string | null uri · maxLength 500 URL de vídeo. Requiere la función de analíticas avanzadas; de lo contrario, se ignora. limitado por plan
address string | null maxLength 500 Dirección postal.
social_links array | null Lista de enlaces de redes sociales (array de objetos).
design_config object | null Ajustes de diseño (colores, fuente, maquetación) como objeto.
template_id string | null maxLength 50 ID de la plantilla a utilizar.
is_public boolean | null Si la tarjeta es accesible públicamente. Predeterminado true.
show_branding boolean | null Mostrar la marca de FalconCard. Ocultarla requiere la función whitelabel; de lo contrario, se fuerza a true. limitado por plan
show_lead_form boolean | null Mostrar el formulario de leads en la tarjeta. Requiere la función de formulario de leads; de lo contrario, se fuerza a false. limitado por plan
seo_title string | null maxLength 100 Título SEO de la tarjeta pública.
seo_description string | null maxLength 250 Meta descripción SEO.
language string | null maxLength 5 Idioma principal de la tarjeta (p. ej. de).
status string | null enum: active, draft, archived Estado de publicación: active, draft o archived.

Respuesta de éxito

200 OK con la tarjeta actualizada en el objeto data más un message.

Códigos de error

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

Actualiza una tarjeta. Todos los campos son opcionales; solo cambian los campos proporcionados. PUT y PATCH se comportan de forma idéntica.

Parámetros

Nombre En Tipo Obligatorio Descripción
card ruta integer ID de la tarjeta.

Cuerpo de la solicitud application/json

Campo Tipo Restricciones Descripción
first_name string maxLength 100 Nombre.
last_name string maxLength 100 Apellidos.
job_title string | null maxLength 150 Cargo / puesto de trabajo.
company string | null maxLength 150 Nombre de la empresa.
bio string | null maxLength 1000 Descripción breve / biografía.
email string | null email · maxLength 255 Correo electrónico de contacto (formato de email válido).
phone string | null maxLength 50 Número de teléfono. Caracteres permitidos: dígitos, espacios y + - ( ) . /
website string | null uri · maxLength 500 URL del sitio web.
booking_url string | null uri · maxLength 500 Enlace para reservar citas.
video_url string | null uri · maxLength 500 URL de vídeo. Requiere la función de analíticas avanzadas; de lo contrario, se ignora. limitado por plan
address string | null maxLength 500 Dirección postal.
social_links array | null Lista de enlaces de redes sociales (array de objetos).
design_config object | null Ajustes de diseño (colores, fuente, maquetación) como objeto.
template_id string | null maxLength 50 ID de la plantilla a utilizar.
is_public boolean | null Si la tarjeta es accesible públicamente. Predeterminado true.
show_branding boolean | null Mostrar la marca de FalconCard. Ocultarla requiere la función whitelabel; de lo contrario, se fuerza a true. limitado por plan
show_lead_form boolean | null Mostrar el formulario de leads en la tarjeta. Requiere la función de formulario de leads; de lo contrario, se fuerza a false. limitado por plan
seo_title string | null maxLength 100 Título SEO de la tarjeta pública.
seo_description string | null maxLength 250 Meta descripción SEO.
language string | null maxLength 5 Idioma principal de la tarjeta (p. ej. de).
status string | null enum: active, draft, archived Estado de publicación: active, draft o archived.

Respuesta de éxito

200 OK con la tarjeta actualizada en el objeto data más un message.

Códigos de error

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

Elimina una tarjeta de forma permanente.

Parámetros

Nombre En Tipo Obligatorio Descripción
card ruta integer ID de la tarjeta.

Respuesta de éxito

200 OK con un mensaje de confirmación.

Códigos de error

401403404429

Leads

Lea los contactos capturados a través de los formularios de leads de sus tarjetas.

GET /api/v1/leads Scope leads:read

Lista los leads capturados en todas las tarjetas, los más recientes primero. Filtre a una sola tarjeta con card_id.

Parámetros

Nombre En Tipo Obligatorio Descripción
card_id query integer no Restringir a una sola tarjeta de su propiedad.
page query integer no Número de página (empezando en 1).
per_page query integer no Elementos por página, máx. 100.

Respuesta de éxito

200 OK con un array data de leads y un objeto meta.

Códigos de error

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

Devuelve un solo lead con una referencia compacta a la tarjeta que lo capturó.

Parámetros

Nombre En Tipo Obligatorio Descripción
id ruta integer ID del lead.

Respuesta de éxito

200 OK con el lead en el objeto data.

Códigos de error

401403404429

Analytics

Estadísticas agregadas de visualizaciones y clics — en todas las tarjetas o por tarjeta.

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

Métricas de visualizaciones agregadas en todas las tarjetas o — mediante card_id — para una sola tarjeta.

Parámetros

Nombre En Tipo Obligatorio Descripción
card_id query integer no Restringir a una sola tarjeta de su propiedad.
period query string (enum) no Período del informe. Permitido: 7d, 14d, 30d, 90d, 365d. Predeterminado 30d.

Respuesta de éxito

200 OK con total_views, unique_views, views_per_day más devices, countries y referrers en el objeto data.

Códigos de error

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

Métricas de clics agregadas en todas las tarjetas o — mediante card_id — para una sola tarjeta.

Parámetros

Nombre En Tipo Obligatorio Descripción
card_id query integer no Restringir a una sola tarjeta de su propiedad.
period query string (enum) no Período del informe. Permitido: 7d, 14d, 30d, 90d, 365d. Predeterminado 30d.

Respuesta de éxito

200 OK con total_clicks, clicks_by_type y clicks_per_day en el objeto data.

Códigos de error

401403422429

Ejemplos de código

Fragmentos para copiar y pegar en cURL, JavaScript y Python. Reemplace DEIN_API_TOKEN por su token real.

Listar tarjetas
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"])
Crear una tarjeta
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"])
Listar 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"])
Recuperar analíticas
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"])

Ejemplo: crear una tarjeta

Solicitud · 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"
  }'
Respuesta · 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."
}

Errores

Cada error devuelve una cadena message. Los errores de validación (422) contienen además un mapa errors.

Status Name Descripción Cuerpo de ejemplo
401 Unauthorized Token ausente o no válido.
{ "message": "Unauthenticated." }
403 Forbidden El plan no incluye acceso a la API (solo Enterprise) o el token carece del scope requerido.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found El recurso no existe o no pertenece a su cuenta.
{ "message": "Not found." }
422 Unprocessable Entity La validación falló — el cuerpo contiene un mapa errors (campo → mensajes).
429 Too Many Requests Límite de velocidad superado. El header Retry-After indica el tiempo de espera en segundos.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 contienen además un mapa errors de campo → lista de mensajes:

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

Especificación legible por máquina

Toda la API está documentada como OpenAPI 3.1. Descargue la especificación e impórtela en Postman, Insomnia o Scalar — o genere a partir de ella clientes con tipado seguro para su lenguaje.

Compatible con Postman · Insomnia · Scalar · generadores OpenAPI

Descargar openapi.json

¿Listo para integrar?

Importe la especificación OpenAPI en sus herramientas o cree su primer token de API directamente en el panel.