Assinaturas no fluxo
do seu sistema.

Operações disponíveis

Autenticação e limites

Use Authorization: Bearer SUA_CREDENCIAL no servidor. Cada chave permite até 60 chamadas por minuto, sendo até 10 criações. PDF de até 5 MB, corpo JSON de até 8 MB, até 50 participantes e 500 campos por criação. Também se aplicam os limites do plano da empresa.

A credencial deixa de funcionar quando expira, é revogada ou seu administrador perde o acesso ativo. As permissões atuais da organização são verificadas em cada chamada. A API não oferece acesso de superadministrador.

Criação com prevenção de duplicidade

POST /api/v1/documents
Authorization: Bearer SUA_CREDENCIAL
Content-Type: application/json
Idempotency-Key: contrato_2026_001

{
  "title": "Contrato de serviços",
  "pdfBase64": "BASE64_DO_PDF",
  "send": false,
  "orderEnabled": true,
  "signers": [
    { "name": "Ana Costa", "email": "ana@example.com", "role": "signer" }
  ],
  "fields": [
    { "signerIndex": 0, "type": "signature", "page": 1,
      "x": 1200, "y": 7500, "width": 3000, "height": 600, "required": true }
  ]
}

Os campos usam coordenadas de 0 a 10.000, contadas a partir do canto superior esquerdo da página. Cada participante é identificado pelo índice, começando em zero. Tipos: signature, initials, checkbox, text, name, cpf e date.

Envio real: use send: true somente quando desejar criar o documento e disparar os convites. Omitir essa opção ou usar false salva um rascunho. Os campos do rascunho devem ser conferidos na preparação antes do envio.

Reutilizar a mesma Idempotency-Key com o mesmo conteúdo retorna a resposta já registrada. Com conteúdo diferente, a API retorna 409. Se uma operação ficar sem resultado confirmado, consulte o documento pelo painel usando o metadado integrationRequestId antes de emitir uma nova chave.

Resposta de criação

A resposta contém document com identificação e estado, signers com os links individuais aplicáveis e emailDelivery com o resultado do encaminhamento. A criação bem-sucedida não significa que os participantes já assinaram. Trate os links de assinatura como acessos pessoais.

Eventos de retorno

Consulte GET /api/v1/events e guarde o nextCursor. Na próxima chamada, envie ?cursor=VALOR, codificado para URL. Eventos incluem criação, visualização, assinatura, recusa e lembretes quando ocorrerem. A consulta retorna identificador, documento, tipo e horário, sem as evidências sensíveis.

Considere o identificador do evento para evitar processamento duplicado. Nesta versão o acompanhamento ocorre por consulta periódica. Webhooks de saída e conectores prontos para ERPs ou CRMs dependem de escopo específico.

Erros e retomada

• 400/415: revise formato e campos.
• 401/403: confira validade, permissões e situação do acesso.
• 402: limite do plano ou contratação.
• 404: documento indisponível ou sem acesso.
• 409: processamento, conflito ou arquivo ainda não disponível.
• 413: tamanho excedido.
• 429: respeite Retry-After e reduza a frequência.
• 500: consulte o resultado antes de repetir uma criação.

O fluxo ICP-Brasil continua utilizando o aplicativo do certificado do titular e a devolução do PDF para conferência. A API não recebe PFX, chave privada ou senha do certificado.