API do Firmou
A API que o seu sistema (ERP, CRM, o que for) usa para conversar com o Firmou: enviar documentos para assinatura, acompanhar o andamento e baixar o resultado.
Autenticação
Toda chamada exige um token de API no cabeçalho Authorization:
Authorization: Bearer frm_SEU_TOKEN_AQUI
O token é emitido pela tela Configurações › Tokens dentro do Firmou — a própria API não emite nem revoga tokens, de propósito: quem administra credencial é gente autenticada por sessão, não outro token. Veja o guia Autenticação.
Workspace
Cada token nasce amarrado a um workspace só, escolhido no momento da emissão. Todo documento criado ou consultado por este token pertence àquele workspace — não existe parâmetro para trocar de área numa chamada; quem precisa de mais de um workspace emite um token para cada.
Erros
Erros de validação vêm no formato padrão do Laravel:
{
"message": "A descrição do primeiro erro encontrado.",
"errors": {
"campo": ["A mensagem específica deste campo."]
}
}
Códigos de status usados nesta API:
| Código | Significado |
|---|---|
401 | Token ausente, inválido, revogado ou vencido |
403 | Conta sem plano ativo, ou conta encerrada |
404 | O recurso não existe para este token — inclusive quando existe para outro tenant ou outro workspace |
422 | Validação, ou regra de negócio recusou a operação |
Mudanças
15/10/2026 — mínimo do campo de assinatura caiu para 180 x 56
O carimbo desenhado sobre o campo ficou menor — perdeu a linha de
atribuição à KEMIS e o traço encolheu —, e o mínimo do campo type: signature caiu junto: de 220 x 70 para 180 x 56 pontos do PDF.
Numa A4 retrato com render_width: 1000, de 370 x 118 para 303 x 95.
Nada quebra: todo campo que passava continua passando. Só muda se você quiser usar caixas menores.
23/09/2026 — campo de assinatura passou a ter tamanho mínimo
POST /documents agora recusa, com 422, campo type: signature menor
que 220 x 70 pontos do PDF — o tamanho do carimbo que o Firmou
desenha sobre ele. Quando isso acontece, nada é criado: a resposta
traz o motivo em message e aponta o campo em errors, na chave
fields.N.width.
Antes, o campo pequeno era aceito e o problema só aparecia no documento pronto. O carimbo tem tamanho fixo e não encolhe para caber numa caixa menor: ele saía por cima do que estivesse em volta — a linha da tabela, a cláusula, a assinatura do signatário seguinte. Nessa altura todos já tinham assinado, e não havia como corrigir sem recomeçar o documento. É por isso que a recusa foi para a criação.
O que conferir na sua integração: o width e o height dos campos de
assinatura. A conta para converter os 220 x 70 pontos para a régua que
você usa, com tabela por tamanho de página e exemplos, está em
Tamanho do campo de assinatura.
Numa A4 retrato com render_width: 1000, o mínimo fica em 370 x 118.
rubric e text não mudaram: continuam sem mínimo, porque são desenhados
dentro da própria caixa e encolhem para caber.
Authentication
- HTTP: Bearer Auth
Token emitido em Configurações › Tokens, dentro do Firmou.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | frm_... |
Contact Suporte Firmou: URL: https://firmou.app