API REST — eIDAS

A API de assinatura eletrônica para desenvolvedores

Integre a assinatura eletrônica eIDAS ao seu aplicativo: API REST, webhooks assinados com HMAC, assinatura incorporada em iframe e chaves de teste gratuitas já na conta gratuita.

Criar uma conta de desenvolvedor Documentação da API

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

REST + especificação OpenAPI

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

Webhooks confiáveis

5 tentativas com intervalos crescentes, assinatura HMAC SHA-256, eventos com falha que podem ser reenviados pelo dashboard. Nada de polling para programar.

Conformidade eIDAS nativa

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

Hospedada na UE

Servidores na Alemanha, na França e na Espanha. Limites de requisições publicados por plano e headers X-RateLimit em cada resposta. SLA de 99,9 % nos planos Business e Enterprise.

Comece em três chamadas

Envie o PDF, crie o envelope, dispare-o: três requisições HTTP bastam.

cURL — enviar o arquivo, criar, disparar

# 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 retorna o identificador do PDF, POST /envelopes cria um rascunho com os signatários e, em seguida, POST /envelopes/:id/send envia os convites. O andamento chega depois 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 });

Nenhum SDK é necessário: a API é consumida com o fetch nativo do Node 18 ou qualquer cliente HTTP. A especificação OpenAPI também permite 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 com falha ficam listados no dashboard e podem ser reenviados com um clique. Após 5 falhas consecutivas, o endpoint é suspenso e você recebe um aviso.
Até 5 endpoints no Standard, 15 no Business e 50 no Business Pro, cada um inscrito nos eventos que você escolher.

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.

Criada por e para desenvolvedores, ela segue as convenções REST: versão na URL (/api/v1), paginação por page e limit, erros em JSON com um código legível por máquina, especificação OpenAPI para gerar 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 (padrão), ADVANCED ou QUALIFIED. A assinatura simples cobre a maioria dos contratos comerciais do dia a dia; a QES é usada quando uma norma ou um destinatário exige equivalência com a assinatura manuscrita.

Do lado técnico, o nível avançado ativa automaticamente o OTP por SMS e exige um número de telefone para cada signatário. A trilha de auditoria recebe carimbo de tempo conforme a norma RFC 3161. A QES se baseia em um certificado qualificado emitido por um prestador de serviços de confiança qualificado da UE. Tudo é controlado pela API.

Arquitetura de integração recomendada

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

Seu backend envia o PDF (POST /api/v1/documents), cria o envelope como rascunho (POST /api/v1/envelopes) e depois o dispara (POST /api/v1/envelopes/:id/send).
O signatário recebe o convite por e-mail ou assina diretamente na sua interface graças à assinatura incorporada 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, inclusive o Gratuito, e os envelopes de teste não consomem sua cota mensal. No plano Gratuito, eles só podem ser enviados para o seu próprio e-mail e ficam limitados a 20 requisições por hora; os planos pagos vão de 200 a 1.000 requisições por hora. Os dados de teste são apagados após 30 dias. A primeira chave de teste de uma conta gratuita ainda libera um mês grátis do plano Standard.

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 você já tem uma integração com DocuSign ou Yousign, o vocabulário é parecido: envelopes → envelopes, recipients → recipients, webhooks de status → webhooks. O guia de migração de DocuSign e Yousign para a Certyneo detalha as etapas, da exportação dos modelos à troca 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 assinatura?

Não é preciso orçamento nem pedido de compra para contratar uma assinatura da API de assinatura eletrônica: as chaves de teste são gratuitas, a chave de API é gerada 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 cobrança por assinatura simples.

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

A assinatura qualificada (QES) é cobrada por ato e paga no momento do envio: 9,90 € por assinatura com um plano pago, cobrados no cartão cadastrado depois de esgotadas as QES incluídas no Business e no Business Pro, e 14,90 € sem plano.

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

Para aprofundar

Perguntas frequentes — API

Qual é o limite de taxa da API?

O limite se aplica a cada chave, por minuto, conforme o plano: 60 requisições no Standard, 120 no Business, 300 no Business Pro e 1.000 no Enterprise. Cada resposta traz os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; acima disso, a API retorna 429 com um header 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 cotas crescentes; a assinatura qualificada (QES) é cobrada por ato, 9,90 € com um plano pago. Para volumes maiores, o plano Enterprise é contratado com a equipe comercial.

Há um SLA?

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

Qual autenticação você usa?

Uma chave de API no header Authorization (Bearer sk_live_… ou sk_test_…). As chaves são criadas e revogadas no dashboard, com efeito imediato. Para um aplicativo de terceiros que age em nome dos seus usuários, o OAuth 2.0 está disponível com o fluxo authorization code e PKCE.

Como verificar a assinatura HMAC de um webhook?

Cada webhook traz um header X-Certyneo-Signature: a assinatura HMAC SHA-256, em hexadecimal, do corpo bruto da requisição, calculada com o segredo do seu endpoint. Recalcule-a 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 é chamada diretamente via 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 também libera um mês grátis do plano Standard. A coleção do 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 de assinatura continua existindo, mas o preço não é público e passa por um orçamento corporativo com a equipe comercial da Adobe, geralmente por faixas de transações anuais. Já a Certyneo divulga seus preços: o acesso à API de produção está incluído a partir do plano Standard a 19 €/mês, contratado on-line 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 agora.

Ler a documentação Falar com um desenvolvedor Certyneo