Ir para o conteúdo

REST API · v1

REST API da FalconCard

Faça a gestão de cartões, leads e analytics de forma programática — para sincronização com CRM, automação e as suas próprias integrações. Autenticação por Bearer Token, JSON sobre HTTPS.

01

Primeiros passos

Do token ao seu primeiro pedido bem-sucedido em três passos. A API comunica exclusivamente em JSON sobre HTTPS e segue as convenções REST habituais — se alguma vez integrou uma API HTTP, vai sentir-se em casa.

  1. Criar um token

    Abra o seu painel e navegue até Conta → API Tokens. Escolha os scopes de que a sua integração necessita e copie o token de imediato — por segurança, é apresentado em texto simples apenas uma vez.

    Ir para os API Tokens
  2. Definir o header Bearer

    Envie o token no header Authorization em cada pedido. Adicione Accept: application/json para que os erros também sejam devolvidos em JSON.

    Authorization: Bearer DEIN_API_TOKEN
  3. Enviar o seu primeiro pedido

    Obtenha os seus cartões. Uma chamada bem-sucedida devolve HTTP 200 com um array data e um objeto meta para a paginação:

cURL
curl https://falconcard.net/api/v1/cards \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Accept: application/json"
Resposta · 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 vir esta estrutura, a sua autenticação está correta. Cada endpoint de listagem responde com o mesmo schema data + meta — os recursos individuais são devolvidos num objeto data sem meta.

URL base: https://falconcard.net/api/v1 · todas as respostas são em JSON.

02

Autenticação

Cada pedido autentica-se com um token de acesso pessoal (Laravel Sanctum) no header:

Authorization: Bearer DEIN_API_TOKEN

Pode criar e revogar tokens a qualquer momento no painel. Cada token possui um ou mais scopes que limitam as suas permissões.

Scopes

cards:read

Listar e ler cartões

cards:write

Criar, atualizar e eliminar cartões

leads:read

Listar e ler leads

analytics:read

Ler analytics de visualizações e cliques

03

Conceitos

Quatro blocos de construção que funcionam de forma idêntica em todos os endpoints — aprenda-os uma vez e aplicam-se em todo o lado.

Versionamento

A versão atual é a /api/v1 e está fixada no path. As alterações disruptivas são lançadas sob um novo prefixo (p. ex. /api/v2), para que as integrações existentes se mantenham estáveis.

Formato do pedido

Os endpoints de escrita esperam um corpo JSON com Content-Type: application/json. As timestamps seguem o formato ISO 8601 (UTC). Os campos desconhecidos são ignorados e os campos opcionais em falta permanecem inalterados.

Rate-Limiting

Os tokens Enterprise podem enviar 1000 pedidos por minuto. Cada resposta inclui X-RateLimit-Limit e X-RateLimit-Remaining. Quando excedido, recebe 429 Too Many Requests com um header Retry-After (segundos até ao reset) — aguarde esse tempo antes de tentar novamente.

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

Paginação

Os endpoints de listagem devolvem até 15 itens por página. Controle-os com ?page= (começando em 1) e ?per_page= (máx. 100). O objeto meta indica current_page, last_page, per_page e total.

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

Disponibilidade. A REST API faz parte do plano Enterprise. Os tokens de outros planos recebem 403.

04

Referência de endpoints

Referência completa dos dez endpoints, agrupados por recurso. Cada definição mantém-se sincronizada com a especificação OpenAPI — pronta para importar no Postman, Insomnia, Scalar ou no seu gerador de código.

01

Cards

Criar, ler, atualizar e eliminar cartões de visita digitais.

GET
/api/v1/cards Scope cards:read

Lista os cartões da conta, ordenados pela atualização mais recente.

Parâmetros

Nome Em Tipo Obrigatório Descrição
page query integer não Número da página (começando em 1).
per_page query integer não Itens por página, máx. 100.

Resposta de sucesso

200 OK com um array data de cartões e um objeto meta para a paginação.

Códigos de erro

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

Cria um novo cartão. O slug e o title são gerados automaticamente. Os campos restritos por plano são ajustados para valores permitidos.

Parâmetros

Sem parâmetros.

Corpo do pedido application/json

Campo Tipo Restrições Descrição
first_name Obrigatório string maxLength 100 Nome próprio.
last_name Obrigatório string maxLength 100 Apelido.
job_title string | null maxLength 150 Cargo / função.
company string | null maxLength 150 Nome da empresa.
bio string | null maxLength 1000 Descrição breve / biografia.
email string | null email · maxLength 255 Email de contacto (formato de email válido).
phone string | null maxLength 50 Número de telefone. Caracteres permitidos: dígitos, espaços e + - ( ) . /
website string | null uri · maxLength 500 URL do website.
booking_url string | null uri · maxLength 500 Ligação para marcação de reuniões.
video_url string | null uri · maxLength 500 URL de vídeo. Requer a funcionalidade de analytics avançado, caso contrário é ignorado. restrito por plano
address string | null maxLength 500 Endereço postal.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista de ligações de redes sociais (array de objetos).
design_config object | null — Personalizações de design (cores, tipo de letra, layout) como um objeto.
template_id string | null maxLength 50 ID do template a utilizar.
is_public boolean | null default true Se o cartão está publicamente acessível. Predefinição true.
show_branding boolean | null — Mostrar a marca FalconCard. Ocultá-la requer a funcionalidade whitelabel, caso contrário é forçada a true. restrito por plano
show_lead_form boolean | null — Mostrar o formulário de leads no cartão. Requer a funcionalidade de formulário de leads, caso contrário é forçada a false. restrito por plano
seo_title string | null maxLength 100 Título SEO para o cartão público.
seo_description string | null maxLength 250 Meta-descrição SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Idioma principal do cartão (p. ex. de).

Resposta de sucesso

201 Created com o novo cartão no objeto data e uma message.

Códigos de erro

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

Devolve um único cartão, incluindo os leads captados.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card caminho integer sim ID do cartão.

Resposta de sucesso

200 OK com o cartão (incluindo um array leads incorporado) no objeto data.

Códigos de erro

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

Atualiza um cartão. Todos os campos são opcionais; apenas os campos fornecidos são alterados. O PUT e o PATCH comportam-se de forma idêntica.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card caminho integer sim ID do cartão.

Corpo do pedido application/json

Campo Tipo Restrições Descrição
first_name string maxLength 100 Nome próprio.
last_name string maxLength 100 Apelido.
job_title string | null maxLength 150 Cargo / função.
company string | null maxLength 150 Nome da empresa.
bio string | null maxLength 1000 Descrição breve / biografia.
email string | null email · maxLength 255 Email de contacto (formato de email válido).
phone string | null maxLength 50 Número de telefone. Caracteres permitidos: dígitos, espaços e + - ( ) . /
website string | null uri · maxLength 500 URL do website.
booking_url string | null uri · maxLength 500 Ligação para marcação de reuniões.
video_url string | null uri · maxLength 500 URL de vídeo. Requer a funcionalidade de analytics avançado, caso contrário é ignorado. restrito por plano
address string | null maxLength 500 Endereço postal.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista de ligações de redes sociais (array de objetos).
design_config object | null — Personalizações de design (cores, tipo de letra, layout) como um objeto.
template_id string | null maxLength 50 ID do template a utilizar.
is_public boolean | null — Se o cartão está publicamente acessível. Predefinição true.
show_branding boolean | null — Mostrar a marca FalconCard. Ocultá-la requer a funcionalidade whitelabel, caso contrário é forçada a true. restrito por plano
show_lead_form boolean | null — Mostrar o formulário de leads no cartão. Requer a funcionalidade de formulário de leads, caso contrário é forçada a false. restrito por plano
seo_title string | null maxLength 100 Título SEO para o cartão público.
seo_description string | null maxLength 250 Meta-descrição SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Idioma principal do cartão (p. ex. de).
status string | null enum: active, draft, archived Estado de publicação: active, draft ou archived.

Resposta de sucesso

200 OK com o cartão atualizado no objeto data e uma message.

Códigos de erro

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

Atualiza um cartão. Todos os campos são opcionais; apenas os campos fornecidos são alterados. O PUT e o PATCH comportam-se de forma idêntica.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card caminho integer sim ID do cartão.

Corpo do pedido application/json

Campo Tipo Restrições Descrição
first_name string maxLength 100 Nome próprio.
last_name string maxLength 100 Apelido.
job_title string | null maxLength 150 Cargo / função.
company string | null maxLength 150 Nome da empresa.
bio string | null maxLength 1000 Descrição breve / biografia.
email string | null email · maxLength 255 Email de contacto (formato de email válido).
phone string | null maxLength 50 Número de telefone. Caracteres permitidos: dígitos, espaços e + - ( ) . /
website string | null uri · maxLength 500 URL do website.
booking_url string | null uri · maxLength 500 Ligação para marcação de reuniões.
video_url string | null uri · maxLength 500 URL de vídeo. Requer a funcionalidade de analytics avançado, caso contrário é ignorado. restrito por plano
address string | null maxLength 500 Endereço postal.
social_links array | null maxItems 20 · platform: enum · url: http(s) uri or handle (completed) · maxLength 500 · label: maxLength 100 Lista de ligações de redes sociais (array de objetos).
design_config object | null — Personalizações de design (cores, tipo de letra, layout) como um objeto.
template_id string | null maxLength 50 ID do template a utilizar.
is_public boolean | null — Se o cartão está publicamente acessível. Predefinição true.
show_branding boolean | null — Mostrar a marca FalconCard. Ocultá-la requer a funcionalidade whitelabel, caso contrário é forçada a true. restrito por plano
show_lead_form boolean | null — Mostrar o formulário de leads no cartão. Requer a funcionalidade de formulário de leads, caso contrário é forçada a false. restrito por plano
seo_title string | null maxLength 100 Título SEO para o cartão público.
seo_description string | null maxLength 250 Meta-descrição SEO.
language string enum: de en bg cs da el es fr hr hu it nl pl pt ro sk sl sv uk Idioma principal do cartão (p. ex. de).
status string | null enum: active, draft, archived Estado de publicação: active, draft ou archived.

Resposta de sucesso

200 OK com o cartão atualizado no objeto data e uma message.

Códigos de erro

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

Elimina um cartão permanentemente.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card caminho integer sim ID do cartão.

Resposta de sucesso

200 OK com uma mensagem de confirmação.

Códigos de erro

401403404429
02

Leads

Ler contactos captados através dos formulários de leads dos seus cartões.

GET
/api/v1/leads Scope leads:read

Lista os leads captados em todos os cartões, os mais recentes primeiro. Filtre por um cartão com card_id.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card_id query integer não Restringir a um único cartão de que é proprietário.
page query integer não Número da página (começando em 1).
per_page query integer não Itens por página, máx. 100.

Resposta de sucesso

200 OK com um array data de leads e um objeto meta.

Códigos de erro

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

Devolve um único lead com uma referência compacta ao cartão de origem.

Parâmetros

Nome Em Tipo Obrigatório Descrição
id caminho integer sim ID do lead.

Resposta de sucesso

200 OK com o lead no objeto data.

Códigos de erro

401403404429
03

Analytics

Estatísticas agregadas de visualizações e cliques — em todos os cartões ou por cartão.

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

Métricas de visualizações agregadas em todos os cartões ou — via card_id — para um único cartão.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card_id query integer não Restringir a um único cartão de que é proprietário.
period query string (enum) não Janela de reporte. Permitido: 7d, 14d, 30d, 90d, 365d. Predefinição 30d.

Resposta de sucesso

200 OK com total_views, unique_views, views_per_day, além de devices, countries e referrers no objeto data.

Códigos de erro

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

Métricas de cliques agregadas em todos os cartões ou — via card_id — para um único cartão.

Parâmetros

Nome Em Tipo Obrigatório Descrição
card_id query integer não Restringir a um único cartão de que é proprietário.
period query string (enum) não Janela de reporte. Permitido: 7d, 14d, 30d, 90d, 365d. Predefinição 30d.

Resposta de sucesso

200 OK com total_clicks, clicks_by_type e clicks_per_day no objeto data.

Códigos de erro

401403422429

05

Exemplos de código

Excertos para copiar e colar em cURL, JavaScript e Python. Substitua DEIN_API_TOKEN pelo seu token real.

Listar cartões
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"])
Criar um cartão
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"])
Obter analytics
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"])

Exemplo: criar um cartão

Pedido · 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"
  }'
Resposta · 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

Erros

Cada erro devolve uma string message. Os erros de validação (422) contêm adicionalmente um errors em forma de mapa.

Status Name Descrição Exemplo de corpo
401 Unauthorized Token em falta ou inválido.
{ "message": "Unauthenticated." }
403 Forbidden O plano não inclui acesso à API (apenas Enterprise) ou o token não tem o scope necessário.
{
  "message": "API access is not available on your current plan. Please upgrade to Enterprise."
}
404 Not Found O recurso não existe ou não pertence à sua conta.
{ "message": "Not found." }
422 Unprocessable Entity A validação falhou — o corpo contém um map errors (campo → mensagens).
429 Too Many Requests Rate-Limit excedido. O header Retry-After indica o tempo de espera em segundos.
{
  "message": "Too Many Requests",
  "retry_after": 37
}

422 contêm adicionalmente um map errors de campo → lista de mensagens:

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

Especificação legível por máquina

A API completa está documentada como OpenAPI 3.1. Descarregue a especificação e importe-a no Postman, Insomnia ou Scalar — ou gere a partir dela clientes type-safe para a sua linguagem.

Compatível com Postman · Insomnia · Scalar · geradores OpenAPI

Descarregar openapi.json

08

Pronto para integrar?

Importe a especificação OpenAPI para as suas ferramentas ou crie o seu primeiro API Token diretamente no painel.