Tamanho mínimo do campo de assinatura

Desde 23/09/2026, POST /v1/documents recusa com 422 qualquer campo type: signature menor que 180 × 56 pontos do PDF. Nada é criado quando isso acontece.

:::info Mínimo reduzido em 15/10/2026 Até 15/10/2026 o mínimo era 220 × 70 pontos. O carimbo ficou menor — perdeu a linha de atribuição à KEMIS e o traço encolheu — e o mínimo caiu junto, para 180 × 56. Campos que já passavam continuam passando; nada precisa mudar do seu lado, a não ser que você queira usar caixas menores. :::

Esta página existe para quem já integra e precisa ajustar o que envia. Se você ainda não posiciona campos (não manda fields), nada muda para você: o documento assina por selo e não há caixa nenhuma para medir.

Por que a recusa existe

O Firmou desenha sobre o campo um carimbo de tamanho fixo — o traço, o nome de quem assinou, o CPF, a data e o código de validação. Esse carimbo não usa o tamanho da caixa que você mandou: usa só a posição dela. Numa caixa menor ele não encolhe — ele sai por cima do que estiver em volta: a linha da tabela, a cláusula seguinte, a assinatura do próximo signatário.

E isso só aparece no PDF final, depois que todo mundo assinou. Nessa altura não há correção possível sem refazer o documento inteiro. Por isso a recusa vem na criação, onde ainda existe alguém para ajustar o campo.

A regra

O mínimo é em pontos do PDF — a unidade em que o arquivo mede a si mesmo —, não na régua do seu desenho:

	mínimo
largura	180 pontos
altura	56 pontos

rubric e text não têm mínimo. Eles são desenhados dentro da própria caixa e encolhem para caber; exigir 180 × 56 de uma rubrica proibiria justamente o que ela é.

O jeito mais simples de acertar

Use a largura da página em pontos como render_width. Aí as suas coordenadas já são pontos, o mínimo é literalmente 180 × 56, e não há conversão nenhuma para manter:

{
  "render_width": 595,
  "fields": [
    { "recipient_index": 0, "type": "signature", "page": 1,
      "x": 320, "y": 700, "width": 240, "height": 80 }
  ]
}

render_width é uma régua arbitrária — qualquer valor serve, contanto que todas as coordenadas do documento sejam relativas a ele. Escolher a largura da página em pontos é o valor que faz a régua desaparecer do seu código.

Se você quer manter a régua que já usa

A conversão é uma razão simples entre a largura da página e a sua régua:

pontos_por_unidade = largura_da_página_em_pontos / render_width

largura_mínima = 180 / pontos_por_unidade
altura_mínima  =  56 / pontos_por_unidade

Repare que a altura também se converte pela largura da página: a régua é uma só e vale para os dois eixos.

Com render_width: 1000, nos tamanhos de página mais comuns:

página	largura em pontos	mínimo na sua régua
A4 retrato	595,28	303 × 95
A4 paisagem	841,89	214 × 67
Carta (Letter) retrato	612	295 × 92

Um documento pode misturar páginas de tamanhos diferentes. Quando isso acontece, o mínimo é o da página em que o campo está — é sempre a página apontada em field.page que manda.

Em PHP, com a largura da página já em mãos:

$pontosPorUnidade = $larguraDaPaginaEmPontos / $renderWidth;

$larguraMinima = (int) ceil(180 / $pontosPorUnidade);
$alturaMinima  = (int) ceil(56 / $pontosPorUnidade);

$width  = max($width,  $larguraMinima);
$height = max($height, $alturaMinima);

Como saber a largura da página em pontos

É o terceiro número do MediaBox da página, menos o primeiro. Em PHP, com smalot/pdfparser:

$mediaBox = (new \Smalot\PdfParser\Parser())
    ->parseFile($caminho)
    ->getPages()[0]
    ->get('MediaBox')
    ->getContent();

$larguraEmPontos = (float) $mediaBox[2]->getContent() - (float) $mediaBox[0]->getContent();

Se os seus PDFs vêm todos do mesmo gerador e no mesmo tamanho — o caso comum de ERP —, você não precisa ler nada: A4 retrato tem 595,28 pontos de largura, e basta fixar isso.

O que a recusa devolve

{
  "message": "O campo de assinatura da página 1 mede 138x46 pontos do PDF, e o mínimo é 180x56 — é o tamanho do carimbo que o Firmou desenha sobre ele, e num campo menor a assinatura sai por cima do que estiver em volta. Na régua deste desenho (render_width 800), o campo precisa ter pelo menos 242x76.",
  "errors": {
    "fields.0.width": ["..."]
  }
}

A chave em errors aponta o índice do campo no array fields que você enviou — fields.0.width é o primeiro campo. A mensagem já traz o tamanho que o campo tem, o mínimo, e quanto é esse mínimo na sua própria régua, então dá para corrigir sem refazer a conta.

Quando a recusa acontece, nenhum documento é criado e nenhum convite sai. Corrija os campos e repita a chamada.

Um detalhe sobre PDFs que não dão para medir

Se o Firmou não conseguir ler o tamanho da página do arquivo enviado, o campo passa sem ser medido. Sem a medida não há como afirmar que o campo é pequeno, e recusar no escuro seria barrar envio legítimo. Não conte com isso: o carimbo continua sendo de 180 × 56 pontos, e um campo menor continua saindo por cima do que estiver em volta — a validação é uma rede, não uma permissão.