Перейти до вмісту

REST API · v1

FalconCard REST API

Керуйте картками, лідами та аналітикою програмно — для синхронізації з CRM, автоматизації та власних інтеграцій. Автентифікація через Bearer Token, JSON через HTTPS.

01

Початок роботи

Від токена до першого успішного запиту за три кроки. API спілкується виключно через JSON по HTTPS і дотримується поширених конвенцій REST — якщо ви коли-небудь інтегрували HTTP API, то почуватиметеся як удома.

  1. Створіть токен

    Відкрийте панель керування та перейдіть до Обліковий запис → API-токени. Виберіть scopes, потрібні вашій інтеграції, і одразу скопіюйте токен — з міркувань безпеки він показується у відкритому вигляді лише один раз.

    Перейти до API-токенів
  2. Встановіть header Bearer

    Надсилайте токен у header Authorization у кожному запиті. Додайте Accept: application/json, щоб помилки також поверталися у форматі JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Надішліть свій перший запит

    Отримайте свої картки. Успішний виклик повертає HTTP 200 з масивом data та об'єктом meta для пагінації:

cURL
curl https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
Відповідь · 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
  }
}

Якщо ви бачите таку структуру, ваша автентифікація правильна. Кожен ендпоінт списку відповідає тією самою схемою data + meta — окремі ресурси повертаються в об'єкті data без meta.

Базова URL-адреса: https://falconcard.net/api/v1 · усі відповіді у форматі JSON.

02

Автентифікація

Кожен запит автентифікується персональним токеном доступу (Laravel Sanctum) у header:

Authorization: Bearer DEIN_API_TOKEN

Ви можете створювати та відкликати токени будь-коли у панелі керування. Кожен токен має один або кілька scopes, які обмежують його дозволи.

Scopes

cards:read

Перегляд списку та читання карток

cards:write

Створення, оновлення та видалення карток

leads:read

Перегляд списку та читання лідів

analytics:read

Читання аналітики переглядів і кліків

03

Концепції

Чотири будівельні блоки, які працюють однаково для кожного ендпоінта — вивчіть їх один раз, і вони застосовуються всюди.

Версіонування

Поточна версія — /api/v1 і вона закріплена в шляху. Несумісні зміни виходять під новим префіксом (напр. /api/v2), тож наявні інтеграції залишаються стабільними.

Формат запиту

Ендпоінти запису очікують тіло JSON з Content-Type: application/json. Мітки часу подаються у форматі ISO 8601 (UTC). Невідомі поля ігноруються, відсутні необов'язкові поля залишаються незмінними.

Обмеження частоти запитів

Токени Enterprise можуть надсилати 1000 запитів за хвилину. Кожна відповідь містить X-RateLimit-Limit та X-RateLimit-Remaining. У разі перевищення ви отримуєте 429 Too Many Requests з header Retry-After (секунди до скидання) — зачекайте цей час перед повторною спробою.

Headers · кожна відповідь
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994

Пагінація

Ендпоінти списків повертають до 15 елементів на сторінку. Керуйте цим за допомогою ?page= (від 1) та ?per_page= (макс. 100). Об'єкт meta повідомляє current_page, last_page, per_page і total.

meta · кожен список
"meta": {
  "current_page": 2,
  "last_page": 7,
  "per_page": 15,
  "total": 98
}

Доступність. REST API входить до тарифу Enterprise. Токени інших тарифів отримують 403.

04

Довідник ендпоінтів

Повний довідник для всіх десяти ендпоінтів, згрупованих за ресурсом. Кожне визначення синхронізоване зі специфікацією OpenAPI — готовою до імпорту в Postman, Insomnia, Scalar або ваш генератор коду.

01

Cards

Створення, читання, оновлення та видалення цифрових візитівок.

GET
/api/v1/cards Scope cards:read

Перелічує картки облікового запису, спочатку нещодавно оновлені.

Параметри

Назва У Тип Обов'язковий Опис
page запит integer ні Номер сторінки (від 1).
per_page запит integer ні Елементів на сторінку, макс. 100.

Успішна відповідь

200 OK з масивом data карток та об'єктом meta для пагінації.

Коди помилок

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

Створює нову картку. slug і title генеруються автоматично. Поля, залежні від тарифу, приводяться до дозволених значень.

Параметри

Без параметрів.

Тіло запиту application/json

Поле Тип Обмеження Опис
first_name Обов'язковий string maxLength 100 Ім'я.
last_name Обов'язковий string maxLength 100 Прізвище.
job_title string | null maxLength 150 Посада / назва посади.
company string | null maxLength 150 Назва компанії.
bio string | null maxLength 1000 Короткий опис / біографія.
email string | null email · maxLength 255 Контактна електронна пошта (дійсний формат email).
phone string | null maxLength 50 Номер телефону. Дозволені символи: цифри, пробіли та + - ( ) . /
website string | null uri · maxLength 500 URL-адреса вебсайту.
booking_url string | null uri · maxLength 500 Посилання на бронювання зустрічей.
video_url string | null uri · maxLength 500 URL-адреса відео. Потребує функції розширеної аналітики, інакше ігнорується. залежить від тарифу
address string | null maxLength 500 Поштова адреса.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Список посилань на соціальні мережі (масив об'єктів).
design_config object | null — Перевизначення дизайну (кольори, шрифт, макет) як об'єкт.
template_id string | null maxLength 50 ID шаблону для використання.
is_public boolean | null default true Чи доступна картка публічно. За замовчуванням true.
show_branding boolean | null — Показувати брендинг FalconCard. Приховування потребує функції whitelabel, інакше примусово true. залежить від тарифу
show_lead_form boolean | null — Показувати форму лідів на картці. Потребує функції форми лідів, інакше примусово false. залежить від тарифу
seo_title string | null maxLength 100 SEO-заголовок для публічної картки.
seo_description string | null maxLength 250 SEO meta-опис.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Основна мова картки (напр. de).

Успішна відповідь

201 Created з новою карткою в об'єкті data та повідомленням.

Коди помилок

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

Повертає окрему картку разом із зібраними лідами.

Параметри

Назва У Тип Обов'язковий Опис
card шлях integer так ID картки.

Успішна відповідь

200 OK з карткою (включно з вбудованим масивом leads) в об'єкті data.

Коди помилок

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

Оновлює картку. Усі поля необов'язкові; змінюються лише надані поля. PUT і PATCH працюють однаково.

Параметри

Назва У Тип Обов'язковий Опис
card шлях integer так ID картки.

Тіло запиту application/json

Поле Тип Обмеження Опис
first_name string maxLength 100 Ім'я.
last_name string maxLength 100 Прізвище.
job_title string | null maxLength 150 Посада / назва посади.
company string | null maxLength 150 Назва компанії.
bio string | null maxLength 1000 Короткий опис / біографія.
email string | null email · maxLength 255 Контактна електронна пошта (дійсний формат email).
phone string | null maxLength 50 Номер телефону. Дозволені символи: цифри, пробіли та + - ( ) . /
website string | null uri · maxLength 500 URL-адреса вебсайту.
booking_url string | null uri · maxLength 500 Посилання на бронювання зустрічей.
video_url string | null uri · maxLength 500 URL-адреса відео. Потребує функції розширеної аналітики, інакше ігнорується. залежить від тарифу
address string | null maxLength 500 Поштова адреса.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Список посилань на соціальні мережі (масив об'єктів).
design_config object | null — Перевизначення дизайну (кольори, шрифт, макет) як об'єкт.
template_id string | null maxLength 50 ID шаблону для використання.
is_public boolean | null — Чи доступна картка публічно. За замовчуванням true.
show_branding boolean | null — Показувати брендинг FalconCard. Приховування потребує функції whitelabel, інакше примусово true. залежить від тарифу
show_lead_form boolean | null — Показувати форму лідів на картці. Потребує функції форми лідів, інакше примусово false. залежить від тарифу
seo_title string | null maxLength 100 SEO-заголовок для публічної картки.
seo_description string | null maxLength 250 SEO meta-опис.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Основна мова картки (напр. de).
status string | null enum: active, draft, archived Статус публікації: active, draft або archived.

Успішна відповідь

200 OK з оновленою карткою в об'єкті data та повідомленням.

Коди помилок

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

Оновлює картку. Усі поля необов'язкові; змінюються лише надані поля. PUT і PATCH працюють однаково.

Параметри

Назва У Тип Обов'язковий Опис
card шлях integer так ID картки.

Тіло запиту application/json

Поле Тип Обмеження Опис
first_name string maxLength 100 Ім'я.
last_name string maxLength 100 Прізвище.
job_title string | null maxLength 150 Посада / назва посади.
company string | null maxLength 150 Назва компанії.
bio string | null maxLength 1000 Короткий опис / біографія.
email string | null email · maxLength 255 Контактна електронна пошта (дійсний формат email).
phone string | null maxLength 50 Номер телефону. Дозволені символи: цифри, пробіли та + - ( ) . /
website string | null uri · maxLength 500 URL-адреса вебсайту.
booking_url string | null uri · maxLength 500 Посилання на бронювання зустрічей.
video_url string | null uri · maxLength 500 URL-адреса відео. Потребує функції розширеної аналітики, інакше ігнорується. залежить від тарифу
address string | null maxLength 500 Поштова адреса.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Список посилань на соціальні мережі (масив об'єктів).
design_config object | null — Перевизначення дизайну (кольори, шрифт, макет) як об'єкт.
template_id string | null maxLength 50 ID шаблону для використання.
is_public boolean | null — Чи доступна картка публічно. За замовчуванням true.
show_branding boolean | null — Показувати брендинг FalconCard. Приховування потребує функції whitelabel, інакше примусово true. залежить від тарифу
show_lead_form boolean | null — Показувати форму лідів на картці. Потребує функції форми лідів, інакше примусово false. залежить від тарифу
seo_title string | null maxLength 100 SEO-заголовок для публічної картки.
seo_description string | null maxLength 250 SEO meta-опис.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Основна мова картки (напр. de).
status string | null enum: active, draft, archived Статус публікації: active, draft або archived.

Успішна відповідь

200 OK з оновленою карткою в об'єкті data та повідомленням.

Коди помилок

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

Остаточно видаляє картку.

Параметри

Назва У Тип Обов'язковий Опис
card шлях integer так ID картки.

Успішна відповідь

200 OK з повідомленням про підтвердження.

Коди помилок

401403404429
02

Leads

Читання контактів, зібраних через форми лідів на ваших картках.

GET
/api/v1/leads Scope leads:read

Перелічує ліди, зібрані з усіх карток, спочатку найновіші. Фільтруйте за однією карткою за допомогою card_id.

Параметри

Назва У Тип Обов'язковий Опис
card_id запит integer ні Обмежити однією карткою, що належить вам.
page запит integer ні Номер сторінки (від 1).
per_page запит integer ні Елементів на сторінку, макс. 100.

Успішна відповідь

200 OK з масивом data лідів та об'єктом meta.

Коди помилок

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

Повертає окремий лід із компактним посиланням на картку, що його зібрала.

Параметри

Назва У Тип Обов'язковий Опис
id шлях integer так ID ліда.

Успішна відповідь

200 OK з лідом в об'єкті data.

Коди помилок

401403404429
03

Analytics

Агрегована статистика переглядів і кліків — для всіх карток або для окремої картки.

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

Агреговані метрики переглядів для всіх карток або — через card_id — для окремої картки.

Параметри

Назва У Тип Обов'язковий Опис
card_id запит integer ні Обмежити однією карткою, що належить вам.
period запит string (enum) ні Період звітування. Дозволені значення: 7d, 14d, 30d, 90d, 365d. За замовчуванням 30d.

Успішна відповідь

200 OK з total_views, unique_views, views_per_day, а також devices, countries і referrers в об'єкті data.

Коди помилок

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

Агреговані метрики кліків для всіх карток або — через card_id — для окремої картки.

Параметри

Назва У Тип Обов'язковий Опис
card_id запит integer ні Обмежити однією карткою, що належить вам.
period запит string (enum) ні Період звітування. Дозволені значення: 7d, 14d, 30d, 90d, 365d. За замовчуванням 30d.

Успішна відповідь

200 OK з total_clicks, clicks_by_type і clicks_per_day в об'єкті data.

Коди помилок

401403422429

05

Приклади коду

Сніпети для копіювання у cURL, JavaScript і Python. Замініть DEIN_API_TOKEN своїм справжнім токеном.

Список карток
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"])
Створити картку
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"])
Список лідів
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"])
Отримати аналітику
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"])

Приклад: створення картки

Запит · 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"
  }'
Відповідь · 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

Помилки

Кожна помилка повертає рядок message. Помилки валідації (422) додатково містять мапу errors.

Status Name Опис Приклад тіла
401 Unauthorized Токен відсутній або недійсний.
{ "message": "Unauthenticated." }
403 Forbidden Тариф не включає доступ до API (лише Enterprise) або токену бракує потрібного scope.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found Ресурс не існує або не належить вашому обліковому запису.
{ "message": "Not found." }
422 Unprocessable Entity Валідація не пройдена — тіло містить мапу errors (поле → повідомлення).
429 Too Many Requests Перевищено обмеження частоти запитів. Header Retry-After вказує час очікування в секундах.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 додатково містять мапу errors: поле → список повідомлень:

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

Машиночитна специфікація

Повний API задокументовано як OpenAPI 3.1. Завантажте специфікацію та імпортуйте її в Postman, Insomnia або Scalar — або згенеруйте з неї типобезпечні клієнти для вашої мови.

Сумісно з Postman · Insomnia · Scalar · генераторами OpenAPI

Завантажити openapi.json

08

Готові до інтеграції?

Імпортуйте специфікацію OpenAPI у свій інструментарій або створіть свій перший API-токен прямо в панелі керування.