Começar grátis

API externa (integrações via /api/v1)

Nos planos Premium e Platinum, o FlakeDesk expõe uma API REST para conectar suas ferramentas (ERP, site, planilhas, automações) aos contatos e empresas do CRM: leitura, criação e atualização, com chaves de API por organização e escopos de acesso por chave.

Criar uma chave de API

Em Administração → Configurações → API keys (apenas administradores da organização):

  1. Dê um nome à chave (ex.: "Integração ERP").
  2. Marque os escopos que a integração precisa — conceda o mínimo necessário.
  3. Clique em Criar API key. O segredo (formato fd_live_...) é exibido uma única vez — copie e guarde em local seguro; depois só o prefixo fica visível.

A lista mostra cada chave com status (Ativa, Revogada, Expirada), escopos, data de criação e último uso. Para desativar, use o ícone de lixeira — a revogação é imediata e definitiva: aplicações que usam a chave param de funcionar na hora.

A chave acompanha quem a criou. Ela para de funcionar se essa pessoa for inativada ou removida da equipe, ou tiver a conta bloqueada — assim, quem sai da empresa não leva junto o acesso à carteira de clientes. Por isso, crie as chaves das integrações permanentes com a conta de um administrador que vai continuar na organização. Se a integração parar de responder com 401 depois de uma mudança na equipe, crie uma chave nova com um administrador ativo e troque na integração.

Escopos

Escopo Permite
organization:read Ler dados básicos da organização (GET /api/v1/me)
contacts:read Listar e consultar contatos
contacts:write Criar e atualizar contatos
companies:read Listar e consultar empresas
companies:write Criar e atualizar empresas

Autenticação

Envie a chave no header Authorization:

curl -H "Authorization: Bearer fd_live_SEU_TOKEN" \
  https://app.flakedesk.com/api/v1/contacts?page=1&pageSize=50

Todos os dados são isolados por organização: a chave só enxerga (e escreve) os registros do próprio tenant.

Endpoints

  • GET /api/v1/openapi.json — especificação OpenAPI completa (público; importe no Postman/Insomnia).
  • GET /api/v1/me — identifica a organização e a chave em uso.
  • GET /api/v1/contacts · GET /api/v1/contacts/{id} — listagem paginada (page, pageSize até 100, search) e consulta.
  • POST /api/v1/contacts · PATCH /api/v1/contacts/{id} — criação e atualização (campos: name obrigatório; email, phone, company, currentRole, headline, location, country, linkedinUrl, status, isLead).
  • GET /api/v1/companies · GET /api/v1/companies/{id} · POST /api/v1/companies · PATCH /api/v1/companies/{id} — o equivalente para empresas (name obrigatório; tradeName, website, sector, size etc.).
  • GET /api/v1/plans — catálogo público de planos.

Listagens retornam { data: [...], pagination: { page, pageSize, total, totalPages } }.

Idempotência

Nas escritas (POST/PATCH), envie o header opcional Idempotency-Key com um valor único por operação: repetir a mesma chave devolve a resposta original sem duplicar o registro — ideal para retries seguros em integrações.

  • A chave vale para uma operação: reusá-la em outro endpoint ou método responde 422 IDEMPOTENCY_KEY_REUSED.
  • Se duas chamadas com a mesma chave chegarem ao mesmo tempo, só uma executa; a outra recebe 409 IDEMPOTENCY_KEY_IN_PROGRESS — aguarde e repita para receber a resposta original.
  • Só respostas de sucesso ficam guardadas: se a chamada falhar, repetir com a mesma chave executa de novo.

Limites e erros

  • Rate limit padrão: 60 requisições por 15 minutos por IP. Ao estourar, a resposta é 429 com o header Retry-After.
  • Erros seguem o envelope { "error": { "code", "message", "requestId" } }:
    • 401 UNAUTHORIZED — chave ausente, inválida, revogada, expirada ou criada por alguém que saiu da equipe.
    • 403 FORBIDDEN — escopo insuficiente, ou o plano da organização não inclui a API externa.
    • 404 NOT_FOUND — registro inexistente (ou de outra organização).
    • 400 BAD_REQUEST — corpo inválido (o campo details aponta os erros por campo).
  • Guarde o requestId ao reportar um problema — ele acelera o suporte.

Boas práticas

  • Uma chave por integração (nunca compartilhe a mesma chave entre sistemas) — revogar uma não derruba as outras.
  • Trate a chave como senha: variáveis de ambiente/cofre de segredos, nunca em código-fonte ou front-end.
  • Após downgrade de plano, as chaves continuam listadas mas a API responde 403 até o plano voltar a incluir o recurso.
  • Toda escrita via API fica registrada na auditoria da organização, identificada pela chave que a executou.

Veja também

API externa (integrações via /api/v1) | Ajuda FlakeDesk