API do Firmo

REST + JSON. Base: https://firmo.uni6.net/api/v1. Autentique com Authorization: Bearer <chave> (crie chaves em Configurações → API; disponível no plano Pro ou superior).

Documentos

Criar (e opcionalmente enviar)

POST /api/v1/documents
{
  "title": "Contrato de prestação de serviços",
  "content_html": "<h1>Contrato</h1><p>Entre {{contratante.nome}} e {{empresa.nome}}…</p>",
  // OU: "file_base64": "JVBERi0…", "file_name": "contrato.pdf"
  // OU: "file_url": "https://…/contrato.pdf"
  // OU: "template_id": "uuid-do-modelo"
  "signers": [
    { "name": "Maria Souza", "email": "maria@ex.com", "phone": "11999998888", "cpf_cnpj": "12345678909",
      "role": "signer", "label": "Contratante", "sign_order": 1, "auth_methods": ["whatsapp_otp", "geo"] },
    { "name": "João Lima", "email": "joao@ex.com", "role": "witness", "sign_order": 2 }
  ],
  "fields": [ { "signer_index": 1, "field_type": "signature", "page": 2, "pos_x": 10, "pos_y": 80, "width": 24, "height": 7 } ],
  "signing_mode": "parallel",          // ou "sequential"
  "valid_until": "2026-10-30",
  "message": "Segue o contrato combinado.",
  "options": { "send_whatsapp": true, "send_email": true, "reminders": { "enabled": true, "interval_days": 2, "max": 3 }, "require_initials": false, "redirect_url": "https://…" },
  "variables": { "valor": "R$ 1.200,00" },
  "external_id": "pedido-123",
  "metadata": { "crm_deal": 42 },
  "send": true
}

Papéis: signer, witness, guarantor, approver, party. Autenticações: email_otp, whatsapp_otp, cpf_check, geo, selfie, id_photo. Campos (PDF): signature, initials, date, name, cpf, text, checkbox; posições em % da página.

Resposta 201:

{ "success": true, "data": { "id": "…", "number": "DOC-2026-0012", "status": "sent", "public_url": "…", "content_hash": "…",
    "signers": [ { "id": "…", "name": "Maria Souza", "status": "pending", "sign_url": "https://firmo.uni6.net/assinar/…" } ] } }

Outras operações

`GET /api/v1/documents?status=signed&page=1&per_page=25&external_id=…`	Listar
`GET /api/v1/documents/{id}`	Detalhe + trilha de eventos
`POST /api/v1/documents/{id}/send`	Enviar rascunho
`POST /api/v1/documents/{id}/remind`	Lembrar pendentes agora
`POST /api/v1/documents/{id}/cancel` `{ "reason": "…" }`	Cancelar
`DELETE /api/v1/documents/{id}`	Excluir (não assinados)
`GET /api/v1/documents/{id}/pdf`	PDF (via final quando concluído)
`GET /api/v1/templates`	Modelos da organização
`GET /api/v1/verify/{sha256}`	Verificar autenticidade (público)
`GET /api/v1/me`	Organização e uso do mês

Webhooks

Cadastre endpoints em Configurações → Webhooks. Cada entrega é um POST JSON com cabeçalhos X-Firmo-Event, X-Firmo-Delivery e X-Firmo-Signature: sha256=<HMAC-SHA256 do corpo com o segredo>. Respostas 2xx confirmam; caso contrário reenviamos em 1, 5, 15 e 60 minutos.

{ "event": "document.completed", "created_at": "2026-09-23T14:10:00-03:00",
  "data": { "id": "…", "number": "DOC-2026-0012", "status": "signed", "external_id": "pedido-123", "final_pdf_url": "…", "signers": [ … ] } }

Eventos: document.sent, document.viewed, document.signed (por signatário, com data.signer e data.completed), document.completed, document.declined, document.expired, document.cancelled.

Exemplo (curl)

curl -X POST https://firmo.uni6.net/api/v1/documents \
  -H "Authorization: Bearer frm_live_…" -H "Content-Type: application/json" \
  -d '{"title":"NDA","content_html":"<p>Acordo…</p>","signers":[{"name":"Maria","phone":"11999998888"}],"send":true}'

Erros

Formato { "success": false, "error": "mensagem" } com HTTP 401 (chave), 403 (plano/suspensa), 404, 422 (validação) ou 500.