← Central de ajuda

Equipe e permissões

API e webhooks — integre o FechaFácil aos seus sistemas

No plano Business, gere uma chave de API para ler suas propostas, criar rascunhos e receber eventos em tempo real por webhook.

No plano Business você pode conectar o FechaFácil aos seus sistemas: uma API REST para consultar suas propostas e clientes, e webhooks que avisam o seu servidor a cada mudança (proposta enviada, visualizada, assinada…).

Tudo é gerenciado na página Desenvolvedor, no menu lateral (seção Conta).

Criar uma chave de API

  1. Abra Desenvolvedor no menu
  2. Em Chaves de API, clique em Nova chave e dê um nome (ex.: "Integração ERP")
  3. Copie a chave que aparece — ela começa com ff_live_ e só é exibida uma vez

Guarde a chave em local seguro. Se perder, basta revogar e criar outra. Revogar uma chave faz qualquer integração que a use parar de funcionar na hora.

Usar a API

A API responde em JSON. Consultar funciona com qualquer chave; criar rascunho exige chave com Permitir criar rascunhos. Autentique com a chave no header Authorization:

curl https://fechafacil.app/api/public/v1/proposals \
  -H "Authorization: Bearer ff_live_sua_chave_aqui"

Endpoints disponíveis:

Método Rota Descrição
GET /api/public/v1/proposals Lista suas propostas (filtros status, q, limit, offset)
GET /api/public/v1/proposals/{id} Detalhe de uma proposta
GET /api/public/v1/proposals/{id}/engagement O que o cliente leu: abriu, % lido, tempo, visitas, tempo por seção e chance de fechar
GET /api/public/v1/attention O que pede ação: perguntas esperando resposta e propostas lidas paradas há 3+ dias
GET /api/public/v1/reading-now Propostas que o cliente está com aberta agora (atividade nos últimos 5 min) e a seção em que está
GET /api/public/v1/proposals/{id}/timeline Linha do tempo: status, cada visita do cliente (tempo, até onde rolou, tempo nos preços, aparelho), perguntas e assinaturas
GET /api/public/v1/proposals/{id}/signature Quem assinou e quando, e o link do PDF assinado (sem CPF/CNPJ)
GET /api/public/v1/proposals/{id}/signed.pdf Baixa o PDF assinado
GET /api/public/v1/questions Perguntas de clientes esperando alguém do time (filtro proposal_id)
POST /api/public/v1/questions/{id}/suggestion Grava uma sugestão de resposta para o vendedor revisar. Não envia nada
GET /api/public/v1/proposals/{id}/send-check Confere se a proposta pode ser enviada: o que bloqueia, o que pede confirmação e o que a revisão automática achou. Não envia nada
GET /api/public/v1/clients Lista seus clientes
GET /api/public/v1/templates Seus modelos e os do FechaFácil
GET /api/public/v1/catalog Itens do catálogo, com preço
POST /api/public/v1/proposals Cria a proposta como rascunho: modelo, cliente, itens do catálogo (o preço vem dele) e contexto. Não envia nada

A documentação interativa completa fica em /api/docs — dá para testar as chamadas direto do navegador.

Prefere perguntar em português em vez de programar? O conector MCP usa a mesma chave e leva esses dados para o Claude, o Cursor e outros assistentes.

Cada chave só enxerga os dados da sua empresa. Há um limite de 120 requisições por minuto por chave.

Receber eventos por webhook

Em vez de ficar consultando a API, você pode receber um aviso automático a cada evento.

  1. Na página Desenvolvedor, em Webhooks, informe a URL do seu servidor
  2. Marque os eventos que quer receber e clique em Adicionar endpoint
  3. Use o botão Testar para disparar um evento ping e conferir que chega

A cada evento, o FechaFácil faz um POST com o corpo em JSON:

{
  "event": "proposal.signed",
  "created_at": "2026-06-15T12:00:00+00:00",
  "data": {
    "id": "…",
    "number": 42,
    "title": "Proposta de SOC 24x7",
    "status": "signed",
    "client_name": "Indústrias Martins S.A.",
    "grand_total": "25700.00"
  }
}

Eventos disponíveis

  • proposal.sent — proposta enviada ao cliente
  • proposal.viewed — cliente abriu pela primeira vez
  • proposal.reopened — cliente voltou à proposta, depois de pelo menos 30 minutos sem mexer nela. Em data.detail.away_hours, quantas horas ficou longe
  • proposal.pricing_focus — cliente ficou 2 minutos ou mais nos preços. Avisa no máximo uma vez a cada 12 horas por proposta. Em data.detail.pricing_seconds, o tempo nos preços
  • proposal.accepted — cliente aceitou
  • proposal.signed — proposta assinada
  • proposal.expired — proposta expirou
  • proposal.rejected — proposta recusada

proposal.reopened e proposal.pricing_focus são os sinais de que o cliente está decidindo. Eles valem só para proposta enviada, aberta ou aceita, e não contam robôs nem você conferindo o próprio link.

Entregas e retentativas

O FechaFácil entrega cada evento e, se o seu servidor não responder com sucesso (HTTP 2xx), tenta de novo com intervalos crescentes (1 min, 5 min, 30 min, 2 h, 6 h). As entregas recentes aparecem na própria página, com status e código HTTP.

Verificar a assinatura (HMAC)

Toda entrega vem assinada para você confirmar que veio mesmo do FechaFácil. No header:

X-FechaFacil-Signature: sha256=<hash>
X-FechaFacil-Event: proposal.signed

O hash é um HMAC-SHA256 do corpo da requisição, usando o segredo do endpoint (mostrado na página). Para validar, calcule o HMAC do corpo recebido e compare:

import hashlib, hmac

def assinatura_valida(corpo: bytes, header: str, segredo: str) -> bool:
    esperado = "sha256=" + hmac.new(segredo.encode(), corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, header)

Se as assinaturas não baterem, ignore a requisição — ela não é confiável.

Perguntas frequentes

A API permite criar ou editar propostas? Criar, sim: POST /api/public/v1/proposals cria um rascunho, com chave de escrita, e devolve o link do editor. Enviar e editar continuam no FechaFácil, por uma pessoa.

Perdi minha chave. E agora? Revogue a chave antiga em Desenvolvedor e crie uma nova. Lembre de atualizar a chave nas suas integrações.

Está disponível no meu plano? API e webhooks fazem parte do plano Business. Veja os planos em /pricing.