API REST — eIDAS

A API de assinatura eletrônica para desenvolvedores

Integre a assinatura eletrónica eIDAS na sua aplicação: API REST, webhooks assinados com HMAC, assinatura integrada em iframe e chaves de teste gratuitas logo na conta gratuita.

Criar uma conta de desenvolvedor Documentação da API

Chaves de teste gratuitas · SLA de 99,9% (Business e Enterprise) · Alojamento na UE

API REST + OpenAPI

Endpoints previsíveis, JSON limpo, códigos HTTP padrão. Especificação OpenAPI descarregável para gerar os seus próprios clientes.

Webhooks confiáveis

5 tentativas com intervalos crescentes, assinatura HMAC SHA-256, eventos falhados reenviáveis a partir do dashboard. Sem polling para programar.

Conformidade eIDAS nativa

Assinaturas simples, avançada (OTP por SMS) e qualificada, escolhidas por envelope com o campo signatureLevel. Registo de auditoria com carimbo temporal anexado a cada documento assinado.

Alojada na UE

Servidores na Alemanha, em França e em Espanha. Limites de pedidos publicados por plano e cabeçalhos X-RateLimit em cada resposta. SLA de 99,9% em Business e Enterprise.

Comece com três chamadas

Carregue o PDF, crie o envelope, envie-o: bastam três pedidos HTTP.

cURL — carregar, criar, enviar

# 1. Upload the PDF
curl https://certyneo.com/api/v1/documents \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -F "file=@contrat.pdf"
# → { "id": "cm8doc...", "status": "READY", ... }

# 2. Create the envelope (draft)
curl https://certyneo.com/api/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Contrat de prestation",
    "documentIds": ["cm8doc..."],
    "recipients": [{ "email": "client@example.com", "name": "Jane Doe" }]
  }'
# → { "id": "cm8env...", "status": "DRAFT", ... }

# 3. Send the invitations
curl -X POST https://certyneo.com/api/v1/envelopes/cm8env.../send \
  -H "Authorization: Bearer $CERTYNEO_API_KEY"

POST /documents devolve o identificador do PDF, POST /envelopes cria um rascunho com os signatários e, depois, POST /envelopes/:id/send envia os convites. O progresso chega em seguida por webhook.

Node.js — fetch nativo, sem dependências

// Node 18+ — native fetch, no dependency
import { readFile } from "node:fs/promises";

const API = "https://certyneo.com/api/v1";
const auth = { Authorization: `Bearer ${process.env.CERTYNEO_API_KEY}` };

// 1. Upload the PDF
const form = new FormData();
const pdf = new Blob([await readFile("contrat.pdf")], { type: "application/pdf" });
form.append("file", pdf, "contrat.pdf");
const doc = await (await fetch(`${API}/documents`, { method: "POST", headers: auth, body: form })).json();

// 2. Create the envelope (draft)
const envelope = await (await fetch(`${API}/envelopes`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    subject: "Contrat de prestation",
    documentIds: [doc.id],
    recipients: [{ email: "client@example.com", name: "Jane Doe" }],
  }),
})).json();

// 3. Send the invitations
await fetch(`${API}/envelopes/${envelope.id}/send`, { method: "POST", headers: auth });

Não é necessário nenhum SDK: a API consome-se com o fetch nativo do Node 18 ou com qualquer cliente HTTP. A especificação OpenAPI permite também gerar um cliente tipado na sua linguagem.

Webhooks — reaja em tempo real

Os eventos de envelope e destinatário, assinatura HMAC verificável e reenvio automático.

envelope.completed

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "subject": "Contrat de prestation",
    "status": "COMPLETED",
    "completedAt": "2026-09-26T08:42:13.000Z",
    "recipientCount": 1,
    "recipients": [
      { "email": "client@example.com", "name": "Jane Doe", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/...pdf?X-Amz-Expires=604800&..."
  },
  "timestamp": "2026-09-26T08:42:13.521Z"
}

Assinatura HMAC SHA-256 de cada payload — verifique a autenticidade no lado do servidor.
Retentativa automática em caso de falha temporária: 5 tentativas ao longo de aproximadamente 1 h 20 com backoff exponencial.
Os eventos falhados são listados no dashboard e podem ser reenviados com um clique. Após 5 falhas consecutivas, o endpoint é suspenso e recebe um aviso.
Até 5 endpoints no Standard, 15 no Business e 50 no Business Pro, cada um subscrito aos eventos da sua escolha.

Por que uma API dedicada à assinatura eletrônica?

Integrar a assinatura eletrônica em seu produto não é trivial. Você precisa de garantias sobre conformidade legal (eIDAS), confiabilidade técnica (webhooks que realmente chegam) e soberania dos dados (hospedagem europeia para evitar o Cloud Act). A API Certyneo cobre os três.

Concebida por e para programadores, segue as convenções REST: versão no URL (/api/v1), paginação com page e limit, erros JSON com um código legível por máquina, especificação OpenAPI para gerar os seus clientes. Sem SOAP, sem XML, sem surpresas.

Conformidade eIDAS explicada para desenvolvedores

O regulamento eIDAS define três níveis de assinatura: simples (SES), avançada (AES) e qualificada (QES). A API Certyneo permite escolher o nível de cada envelope com o campo signatureLevel: SIMPLE (predefinido), ADVANCED ou QUALIFIED. A assinatura simples cobre a maioria dos contratos comerciais correntes; a QES serve quando uma lei ou um destinatário exige a equivalência com a assinatura manuscrita.

Do ponto de vista técnico, o nível avançado ativa automaticamente o OTP por SMS e exige um número de telefone para cada signatário. O registo de auditoria recebe carimbo temporal segundo a norma RFC 3161. A QES assenta num certificado qualificado emitido por um prestador qualificado de serviços de confiança da UE. Tudo é controlado através da API.

Arquitetura de integração recomendada

O padrão de integração mais comum segue este fluxo:

O seu backend carrega o PDF (POST /api/v1/documents), cria o envelope em rascunho (POST /api/v1/envelopes) e depois envia-o (POST /api/v1/envelopes/:id/send).
O signatário recebe o convite por e-mail, ou assina diretamente na sua interface graças à assinatura integrada em iframe (POST /api/v1/envelopes/:id/embed-url, a partir do plano Standard).
Uma vez que a assinatura é concluída, Certyneo chama seu webhook com o evento envelope.completed.
Você atualiza seu banco de dados e notifica o usuário (e-mail, in-app, etc.).

Chaves de teste gratuitas

As chaves sk_test_ estão disponíveis em todos os planos, incluindo o Grátis, e os envelopes de teste não consomem a sua quota mensal. No plano Grátis, só permitem envios para o seu próprio endereço de e-mail e estão limitadas a 20 pedidos por hora; os planos pagos vão de 200 a 1000 pedidos por hora. Os dados de teste são apagados ao fim de 30 dias. A primeira chave de teste de uma conta gratuita desbloqueia ainda um mês de plano Standard oferecido.

E se você não quiser escrever código

Tudo o que esta API faz também é controlado sem escrever uma linha, a partir de um fluxo: criar um envelope, enviá-lo, reagir a uma assinatura, recuperar o PDF selado e sua trilha de auditoria. A mesma base, com um designer visual no lugar do cliente HTTP. Ver a integração Power Automate e Microsoft 365.

Migrar de DocuSign ou Yousign

Se já tem uma integração de assinatura com DocuSign ou Yousign, o vocabulário é semelhante: envelopes → envelopes, recipients → recipients, webhooks de estado → webhooks. O guia de migração de DocuSign e Yousign para a Certyneo detalha os passos, da exportação dos modelos à mudança dos webhooks.

Você está migrando do Adobe Acrobat Sign (anteriormente EchoSign, depois Adobe Sign)? O mapeamento é igualmente direto — agreements → envelopes, participants → recipients, webhooks → webhooks. Comparar Certyneo e Adobe Acrobat Sign →

Preço de uma API de assinatura eletrônica: onde comprar uma subscrição?

Não é necessário orçamento nem ordem de compra para subscrever a API de assinatura: as chaves de teste são gratuitas, a chave API gera-se no dashboard e o acesso à API REST de produção está incluído a partir do plano Standard a 19 €/mês — webhooks incluídos, sem custos por assinatura simples.

Standard — 19 €/mês: 100 envelopes/mês, API REST + webhooks, 10 utilizadores
Business — 39 €/mês: 300 envelopes/mês, envio em grupo, formulários web
Business Pro — 99 €/mês: 1 000 envelopes/mês, API de alta frequência (300 req/min), utilizadores ilimitados

A assinatura qualificada (QES) é faturada por ato e paga no momento do envio: 9,90 € por assinatura com subscrição, debitados no cartão registado depois de esgotadas as QES incluídas em Business e Business Pro, e 14,90 € sem subscrição.

Para volumes significativos ou uma necessidade de compromisso contratual (SLA, DPA dedicado, faturamento anual), o plano Enterprise é contratado junto à equipa comercial. Em qualquer caso, os preços são públicos — compare-os antes de se comprometer.

Aprofunde o seu conhecimento

Perguntas frequentes — API

Qual é o limite de taxa da API?

O limite aplica-se a cada chave, por minuto, conforme o plano: 60 pedidos em Standard, 120 em Business, 300 em Business Pro e 1000 em Enterprise. Cada resposta inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; acima disso, a API devolve 429 com um cabeçalho Retry-After.

Quanto custa a API?

As chaves de teste (sk_test_) são gratuitas em todos os planos. O acesso à API REST de produção está incluído a partir do plano Standard a 19 €/mês (100 envelopes/mês), depois Business a 39 €/mês e Business Pro a 99 €/mês com quotas crescentes; a assinatura qualificada (QES) é faturada por ato, 9,90 € com subscrição. Para volumes superiores, o plano Enterprise é contratado junto da equipa comercial.

Há um SLA?

Sim: 99,9% de disponibilidade mensal nos planos Business e Enterprise, com um crédito na fatura de 10 a 50% consoante o desvio verificado. O estado do serviço é publicado continuamente na página de estado da Certyneo.

Qual autenticação você usa?

Uma chave API no cabeçalho Authorization (Bearer sk_live_… ou sk_test_…). As chaves criam-se e revogam-se no dashboard, com efeito imediato. Para uma aplicação de terceiros que atue em nome dos seus utilizadores, está disponível OAuth 2.0 com o fluxo authorization code e PKCE.

Como verificar a assinatura HMAC de um webhook?

Cada webhook traz uma assinatura no cabeçalho X-Certyneo-Signature: o HMAC SHA-256, em hexadecimal, do corpo bruto do pedido, calculado com o segredo do seu endpoint. Recalcule-o no servidor sobre o corpo não modificado e compare em tempo constante (crypto.timingSafeEqual em Node, hmac.compare_digest em Python).

Existe um SDK oficial?

Ainda não foi publicado. A API chama-se diretamente por HTTP a partir de qualquer linguagem, e a especificação OpenAPI permite gerar um cliente tipado com o openapi-generator ou uma ferramenta equivalente. Sem código, a Certyneo também está disponível no Make, n8n, Postman e RapidAPI.

Posso testar sem pagar?

Sim: crie uma conta gratuita e gere uma chave sk_test_ no dashboard. A primeira chave de teste de uma conta gratuita desbloqueia também um mês de plano Standard oferecido. A coleção Postman permite encadear as primeiras chamadas sem escrever código.

Quanto custa a API EchoSign (que se tornou Adobe Acrobat Sign)?

A EchoSign foi comprada pela Adobe em 2011 e renomeada Adobe Sign e depois Adobe Acrobat Sign: a API continua a existir, mas o preço não é público e passa por um orçamento empresarial junto da equipa comercial da Adobe, geralmente por escalões de transações anuais. Pelo contrário, a Certyneo mostra os seus preços: o acesso à API de assinatura em produção está incluído a partir do plano Standard a 19 €/mês, subscrito online sem orçamento, com chaves de teste gratuitas para avaliar a API antes de pagar.

Pronto para integrar a assinatura eletrônica?

Chaves de teste gratuitas, especificação OpenAPI, webhooks assinados. Comece já.

Ler a documentação Falar com um desenvolvedor Certyneo