Към съдържанието

REST API · v1

REST API на FalconCard

Управлявайте карти, потенциални клиенти и анализи програмно — за CRM синхронизация, автоматизация и собствени интеграции. Удостоверяване с Bearer-token, JSON през HTTPS.

01

Първи стъпки

От token до първата успешна заявка в три стъпки. API работи изключително с JSON през HTTPS и следва обичайните REST конвенции — ако някога сте интегрирали HTTP API, ще се почувствате като у дома си.

  1. Създайте token

    Отворете таблото за управление и навигирайте до Акаунт → API tokens. Изберете обхватите, от които вашата интеграция се нуждае, и копирайте token веднага — от съображения за сигурност той се показва в чист текст само веднъж.

    Към API tokens
  2. Задайте header Bearer

    Изпращайте token в 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

Удостоверяване

Всяка заявка се удостоверява с личен access token (Laravel Sanctum) в header:

Authorization: Bearer DEIN_API_TOKEN

Можете да създавате и отзовавате tokens по всяко време в таблото за управление. Всеки token носи един или повече обхвати, които ограничават неговите права.

Обхвати

cards:read

Списък и четене на карти

cards:write

Създаване, обновяване и изтриване на карти

leads:read

Списък и четене на потенциални клиенти

analytics:read

Четене на анализи за прегледи и кликове

03

Концепции

Четири градивни елемента, които работят идентично за всяка крайна точка — научете ги веднъж, прилагат се навсякъде.

Версиониране

Текущата версия е /api/v1 и е фиксирана в пътя. Несъвместимите промени излизат под нов префикс (напр. /api/v2), така че съществуващите интеграции остават стабилни.

Формат на заявката

Крайните точки за запис очакват JSON тяло с Content-Type: application/json. Времевите маркери са в ISO 8601 (UTC). Непознатите полета се игнорират, липсващите незадължителни полета остават непроменени.

Ограничаване на честотата

Enterprise tokens могат да изпращат 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. Tokens от други планове получават 403.

04

Справочник на крайните точки

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

01

Cards

Създаване, четене, обновяване и изтриване на дигитални визитки.

GET
/api/v1/cards Обхват cards:read

Извежда картите на акаунта, последно обновените първи.

Параметри

Име В Тип Задължителен Описание
page заявка integer не Номер на страница (започва от 1).
per_page заявка integer не Елементи на страница, макс. 100.

Успешен отговор

200 OK с масив data от карти и обект meta за странициране.

Кодове за грешки

401403429
POST
/api/v1/cards Обхват 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 Имейл за контакт (валиден имейл формат).
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 мета описание.
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} Обхват cards:read

Връща единична карта, включително заловените потенциални клиенти.

Параметри

Име В Тип Задължителен Описание
card път integer да ID на картата.

Успешен отговор

200 OK с картата (включително вграден масив leads) в обекта data.

Кодове за грешки

401403404429
PUT
/api/v1/cards/{card} Обхват 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 Имейл за контакт (валиден имейл формат).
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 мета описание.
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} Обхват 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 Имейл за контакт (валиден имейл формат).
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 мета описание.
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} Обхват cards:write

Окончателно изтрива карта.

Параметри

Име В Тип Задължителен Описание
card път integer да ID на картата.

Успешен отговор

200 OK със съобщение за потвърждение.

Кодове за грешки

401403404429
02

Leads

Четене на контакти, заловени чрез формулярите за потенциални клиенти на вашите карти.

GET
/api/v1/leads Обхват leads:read

Извежда потенциалните клиенти, заловени от всички карти, най-новите първи. Филтрирайте до една карта с card_id.

Параметри

Име В Тип Задължителен Описание
card_id заявка integer не Ограничаване до отделна ваша карта.
page заявка integer не Номер на страница (започва от 1).
per_page заявка integer не Елементи на страница, макс. 100.

Успешен отговор

200 OK с масив data от потенциални клиенти и обект meta.

Кодове за грешки

401403429
GET
/api/v1/leads/{id} Обхват leads:read

Връща единичен потенциален клиент с компактна препратка към заловилата го карта.

Параметри

Име В Тип Задължителен Описание
id път integer да ID на потенциалния клиент.

Успешен отговор

200 OK с потенциалния клиент в обекта data.

Кодове за грешки

401403404429
03

Analytics

Обобщена статистика за прегледи и кликове — за всички карти или за отделна карта.

GET
/api/v1/analytics/views Обхват 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 Обхват 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 с вашия реален 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 Token липсва или е невалиден.
{ "message": "Unauthenticated." }
403 Forbidden Планът не включва достъп до API (само Enterprise) или на token липсва необходимият обхват.
{
  "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 token директно в таблото за управление.