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

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 é somente leitura e responde em JSON. 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:

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

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.accepted — cliente aceitou
• proposal.signed — proposta assinada
• proposal.expired — proposta expirou
• proposal.rejected — proposta recusada

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? Por enquanto não — esta versão é somente leitura. Criar propostas via API está no roteiro.

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.