Documentação da API

Referência de integração da assinatura.online. Esta versão descreve o contrato proposto e identifica, em cada seção, o que já está verificado na infraestrutura de origem e o que depende de implementação.

Nenhum endereço ou credencial desta página está disponível em produção. Todos os exemplos usam dados e credenciais fictícias.

Verificado na API da PrescriContrato proposto — ilustrativoDepende de implementação/validação

Visão geral

A API recebe um documento em PDF gerado pelo seu sistema, coleta a autorização do signatário e devolve o documento assinado, além de notificar seu sistema por webhook. A modelagem usa quatro conceitos: organização (sua empresa), documento, signatário e solicitação de assinatura.

Requisições e respostas em JSON (UTF-8).
Datas em ISO 8601 (UTC).
Chamadas autenticadas exclusivamente a partir do seu servidor.

Fluxo PDF → autorização → assinado (verificado)Nomes de recursos e campos (contrato proposto)

base-url

# Contrato proposto — ilustrativo (não disponível em produção)
BASE_URL=https://api.assinatura.online/v1

Autenticação

Autenticação por par de credenciais enviadas em cabeçalhos. As credenciais pertencem à organização e devem ficar em variáveis de ambiente do seu servidor.

headers

X-API-Key: pk_exemplo_0000000000000000
X-API-Secret: sk_exemplo_0000000000000000
Content-Type: application/json

Credenciais de exemplo. Nunca coloque o segredo em código que roda no navegador.

401 Unauthorized

{
  "error": "Credenciais inválidas"
}

Autenticação por chave e segredo (verificado)Emissão de credenciais da assinatura.online

Envio de documentos

Uma solicitação de assinatura é criada com o documento em PDF (por URL ou base64) e os dados do signatário. Informe external_id para correlacionar com o registro do seu sistema.

POST /v1/signature-requests

POST https://api.assinatura.online/v1/signature-requests

{
  "document_name": "Contrato de prestação de serviço",
  "document_url": "https://seusistema.com.br/contratos/2431.pdf",
  "signer": {
    "full_name": "Maria Exemplo",
    "document_number": "00000000000",
    "email": "maria@exemplo.com.br",
    "phone": "5511900000000"
  },
  "external_id": "pedido-2431",
  "metadata": { "unidade": "matriz" },
  "webhook_url": "https://seusistema.com.br/webhooks/assinatura",
  "redirect_url": "https://seusistema.com.br/assinatura-concluida"
}

Contrato proposto — ilustrativo.

201 Created

{
  "signature_request_id": "sr_8f21c4",
  "status": "pending_authorization",
  "authorize_url": "https://assinatura.online/autorizar/EXEMPLO",
  "expires_at": "2026-09-16T15:30:00.000Z"
}

Envie document_url ou document_base64, nunca os dois.
webhook_url e redirect_url precisam usar HTTPS.
Um signatário por solicitação nesta versão do contrato.

Envio de PDF por URL ou base64 (verificado)Signatário genérico sem campos de saúde obrigatóriosMúltiplos signatários e assinatura em lote não confirmados

Autorização do signatário

A resposta da criação devolve authorize_url. Seu sistema encaminha esse endereço ao signatário, que confirma a autorização. A solicitação tem prazo de validade e pode ser cancelada enquanto não estiver assinada.

POST /v1/signature-requests/{id}/cancel

curl -X POST "$BASE_URL/signature-requests/sr_8f21c4/cancel" \
  -H "X-API-Key: $ASSINATURA_API_KEY" \
  -H "X-API-Secret: $ASSINATURA_API_SECRET"

# 200 OK
{ "ok": true, "status": "cancelled" }

Autorização individual e cancelamento (verificado)Tipos de certificado aceitos dependem de validação técnica

Consulta de status

Consulte o estado atual da solicitação sempre que precisar, além de receber o webhook de conclusão.

GET /v1/signature-requests/{id}

curl "$BASE_URL/signature-requests/sr_8f21c4" \
  -H "X-API-Key: $ASSINATURA_API_KEY" \
  -H "X-API-Secret: $ASSINATURA_API_SECRET"

# 200 OK
{
  "signature_request_id": "sr_8f21c4",
  "status": "signed",
  "document_name": "Contrato de prestação de serviço",
  "signed_document_url": "https://assinatura.online/d/EXEMPLO",
  "signed_at": "2026-09-15T12:04:11.482Z",
  "external_id": "pedido-2431",
  "metadata": { "unidade": "matriz" },
  "error": null
}

Estados: pending_authorization, authorized, signed, failed, cancelled.

Conjunto de estados (verificado)

Download do documento assinado

Depois da conclusão, o arquivo assinado pode ser baixado em application/pdf.

GET /v1/signature-requests/{id}/document

curl "$BASE_URL/signature-requests/sr_8f21c4/document" \
  -H "X-API-Key: $ASSINATURA_API_KEY" \
  -H "X-API-Secret: $ASSINATURA_API_SECRET" \
  -o contrato-assinado.pdf

# 409 Conflict — ainda não assinado
{
  "error": "Documento ainda não foi assinado",
  "status": "pending_authorization"
}

Download do PDF assinado (verificado)

Webhooks

Ao mudar o estado da solicitação, enviamos um POST para o webhook_url configurado, com assinatura HMAC-SHA256 no cabeçalho e novas tentativas em caso de falha. Valide sempre a assinatura usando o corpo cru da requisição.

headers + payload

X-Assinatura-Event: signature_request.signed
X-Assinatura-Timestamp: 1788280943
X-Assinatura-Signature: t=1788280943,v1=exemplo
X-Assinatura-Delivery: dl_exemplo
X-Assinatura-Attempt: 1

{
  "signature_request_id": "sr_8f21c4",
  "status": "signed",
  "external_id": "pedido-2431",
  "signed_document_url": "https://assinatura.online/d/EXEMPLO",
  "signed_at": "2026-09-15T12:04:11.482Z",
  "error": null
}

validacao-hmac.ts

import crypto from "node:crypto";

// Use SEMPRE o corpo cru (raw body), não o JSON re-serializado.
const timestamp = request.headers.get("X-Assinatura-Timestamp") ?? "";
const received = (request.headers.get("X-Assinatura-Signature") ?? "").split("v1=")[1] ?? "";
const rawBody = await request.text();

const expected = crypto
  .createHmac("sha256", process.env.ASSINATURA_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

const valido =
  received.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Webhook assinado com HMAC-SHA256 e novas tentativasNomes dos cabeçalhos e eventos (contrato proposto)

Erros

Códigos de erro previstos
HTTP	Causa	Como resolver
400	Campo inválido ou ausente	Confira a mensagem em error e o corpo enviado
401	Credenciais ausentes ou inválidas	Revise X-API-Key e X-API-Secret
403	Signatário ou organização sem permissão	Verifique o cadastro da organização
404	Solicitação não encontrada	Confirme o signature_request_id
409	Estado incompatível com a operação	Consulte o status antes de cancelar ou baixar
429	Excesso de requisições	Reduza a frequência e tente novamente
500	Erro interno	Tente novamente; registre o corpo da resposta

400, 401, 403, 404, 409 e 500 (verificado)429 e limites de uso (contrato proposto)

Dependências abertas

Itens que precisam de implementação ou validação antes de a API entrar em produção para outros segmentos:

Pendente
Contrato de signatário genérico: hoje a infraestrutura de origem exige dados de profissional de saúde habilitado (documento pessoal, registro profissional e especialidade). Enquanto isso não mudar, nenhuma solicitação real é criada para signatários de outros segmentos.
Pendente
Modelo de organização: cadastro, credenciais e isolamento de dados por organização.
Pendente
Endereço público da API, emissão e rotação de credenciais.
Pendente
Definição dos certificados e requisitos de assinatura aceitos fora do segmento de origem.
Pendente
Confirmação de múltiplos signatários, ordem de assinatura e assinatura em lote.
Pendente
Ambiente de testes isolado e limites de uso.