Signatário

Este serviço executa o Fluxo completo de assinatura digital e retorna uma resposta 202 Accepted imediatamente. O serviço processa a operação de assinatura de forma assíncrona.

Implementa Assinatura Eletrônica Básica (AdES - BES), proporcionando uma solução robusta e confiável com vantagens significativas em conformidade regulatória, segurança, interoperabilidade e facilidade de uso.

Callback assíncrono

Ao ser concluída a operação — seja bem-sucedida ou malsucedida — o serviço envia uma solicitação POST para a URL especificada no parâmetro callbackUrl. Se forem fornecidos callbackHeaders, eles serão incluídos na solicitação de callback.

• Assinatura bem-sucedida: Content-Type multipart/form-data. Retorna o documento PDF assinado como anexo.

• Assinatura malsucedida: Content-Type application/json. Retorna um objeto de erro com operationId e mensagem de error.

Somente os formatos de imagem JPEG e PNG são suportados para a visualização da assinatura. Outros formatos resultarão em um erro.

Recomendação de segurança: Sempre consuma esta API a partir da sua infraestrutura de back-end em vez de aplicações de front-end. Essa abordagem protege dados sensíveis, evita a exposição de credenciais e garante o manuseio seguro de documentos durante todo o processo de assinatura.

Endpoint

POST /signer

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
x-api-key	string	Sim	API Key de autorização de acesso.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
document	string	Sim	Documento PDF a ser assinado digitalmente, codificado no formato Base64 (RFC4648).
images	string[]	Não	Array de imagens de visualização de assinatura para incorporar no documento. Cada imagem deve estar codificada em Base64. Formatos suportados: JPEG, PNG.
image	string	Não	Obsoleto. Use o array images em seu lugar. Imagem única para incorporar como visualização de assinatura, codificada em Base64.
page	integer	Não	Número da página de destino para a colocação da assinatura, indexado a partir de zero. Valor padrão: 0 (primeira página).
position	string	Não	Coordenadas do retângulo de assinatura em pixels a 72 DPI: X inferior esquerdo, Y inferior esquerdo, X superior direito, Y superior direito. Para páginas A4, faixas válidas: X: 0-595, Y: 0-842. Formato: x1,y1,x2,y2. Valor padrão: "135,210,480,300"
timezone	string	Não	Identificador de fuso horário IANA para o formato de data/hora nos metadados de assinatura. Exemplos: America/Lima, Europe/Madrid, Asia/Tokyo. Valor padrão: "UTC"
signature	string[]	Não	Linhas de texto personalizadas para mostrar junto à imagem de assinatura. Suporta placeholders dinâmicos: $(date)s é substituído pelo carimbo de data/hora atual formatado conforme dateFormat e timezone. Cada elemento do array representa uma linha de texto.
dateFormat	string	Não	String de formato de data/hora seguindo o padrão ISO 8601 com diretivas strftime. Suporta %z para offset de fuso horário. Exemplo: %d/%m/%Y %H:%M:%S%z. Valor padrão: "%Y/%m/%d %H:%M:%S%z"
callbackUrl	string	Sim	URL do webhook para receber o documento assinado ou a notificação de erro. O serviço enviará os resultados por POST para este endpoint de forma assíncrona.
callbackHeaders	string	Não	Headers HTTP opcionais para incluir na solicitação de callback. Formato: pares chave=valor separados por ponto e vírgula. Exemplo: Authorization=Bearer token;X-Custom=value

Exemplo de solicitação

{
  "document": "JVBERi0xLjUKJbXtrvsKNCAwIG9iag...",
  "images": ["iVBORw0KGgoAAAANSUhEUgAAAEoAAABK..."],
  "page": 0,
  "position": "135,210,480,300",
  "timezone": "America/Lima",
  "signature": ["ID - 9999999", "Date - $(date)s"],
  "dateFormat": "%d/%m/%Y %H:%M:%S%z",
  "callbackUrl": "https://example.com/callback",
  "callbackHeaders": "Authorization=Bearer token123;Content-Type=application/json"
}

Respostas

202 Accepted

A solicitação foi aceita e a operação de assinatura está sendo processada de forma assíncrona. O resultado será enviado para a URL de callback fornecida.

Callback — Assinatura bem-sucedida

Content-Type: multipart/form-data

O documento PDF assinado é retornado como anexo.

Callback — Assinatura malsucedida

Content-Type: application/json

{
  "operationId": "910e181e-305c-4d9b-b42b-f177bf3b06ef",
  "error": "image: formato desconocido"
}

400 Requisição inválida

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Não autorizado

{
  "message": "Unauthorized"
}

403 Proibido

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Gateway inválido

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}