Ir para o conteúdo principal
Certyneo
API REST — eIDAS

A API de assinatura eletrônica para desenvolvedores

Integre a assinatura eletrônica eIDAS na sua aplicação em poucas horas. REST, webhooks confiáveis, SDK Node/Python/Ruby, sandbox gratuito ilimitado.

Criar uma conta de desenvolvedor Documentação da API

Sandbox gratuito · 99,95% de uptime · Hospedagem soberana da UE

REST + OpenAPI 3.1

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

Webhooks confiáveis

Retry automático com backoff exponencial, assinatura HMAC SHA-256, log de eventos consultável. Sem polling para codificar.

Conformidade eIDAS nativa

Assinaturas AES, AES-Q e QES disponíveis via flag de API. Trilha de auditoria qualificada incluída, certificados TSP qualificados da UE.

Latência < 200 ms

API hospedada em Estrasburgo (UE), p95 < 200 ms a partir da Europa. SLA 99,95% de uptime, status público em tempo real.

Início em 5 minutos

Crie seu primeiro envelope com uma única requisição HTTP.

cURL — Criação de um envelope
curl https://api.certyneo.com/v1/envelopes \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrat de prestation",
    "documents": [{"file_url": "https://your.app/contract.pdf"}],
    "recipients": [{"email": "client@example.com", "name": "Jane Doe"}],
    "webhook_url": "https://your.app/webhooks/sign"
  }'

Uma única requisição POST é suficiente para criar um envelope, adicionar um documento, um signatário e a URL do webhook. A API retorna um sign_url pronto para compartilhar.

SDK oficial Node.js
import Certyneo from '@certyneo/sdk';

const client = new Certyneo({ apiKey: process.env.CERTYNEO_API_KEY });

const envelope = await client.envelopes.create({
  title: 'Contrat de prestation',
  documents: [{ file_url: 'https://your.app/contract.pdf' }],
  recipients: [{ email: 'client@example.com', name: 'Jane Doe' }],
});

console.log(envelope.sign_url); // ready to share with the signer

O SDK Node TypeScript fornece digitação completa, gerenciamento automático de erros com retry e um construtor de envelope fluido. Disponível também em Python e Ruby.

Webhooks — reaja em tempo real

Seis eventos (envelope.sent, viewed, signed, completed, declined, expired) com assinatura HMAC verificável e retry automático.

envelope.completed
{
  "event": "envelope.completed",
  "envelope_id": "env_3a2f...",
  "signed_at": "2026-05-25T14:32:18Z",
  "evidence_url": "https://api.certyneo.com/v1/envelopes/env_3a2f.../audit-trail.pdf",
  "signers": [
    { "email": "client@example.com", "signed": true, "ip": "82.x.x.x" }
  ]
}
  • Assinatura HMAC SHA-256 de cada payload — verifique a autenticidade no lado do servidor.
  • Retry automático em caso de falha: 5 tentativas em 24 horas com backoff exponencial.
  • Registro de eventos consultável a partir do dashboard: veja cada tentativa, o status HTTP retornado, o body.
  • URL de webhook configurável por envelope (override) ou global no projeto.

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 desenvolvedores, ela segue as convenções REST modernas: paginação cursor-based, idempotency keys, versionamento por URL, OpenAPI 3.1 para gerar seus clientes automaticamente. 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 por envelope através de um campo `signature_level`. O valor padrão é AES (suficiente para 95% dos casos B2B). A QES está disponível para atos que exigem uma equivalência legal estrita com a assinatura manuscrita manual (atos notariais, contratos públicos).

No lado técnico, AES exige autenticação forte do signatário (OTP por SMS por padrão, KYC por vídeo como opção) e uma trilha de auditoria com timestamp. A QES adiciona um certificado qualificado emitido por um TSP qualificado UE. Tudo isso é gerenciado pela API — você chama o endpoint, cuidamos do resto.

Arquitetura de integração recomendada

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

  • Seu backend chama POST /v1/envelopes para criar o envelope e recebe uma sign_url para apresentar ao usuário.
  • Você redireciona o usuário para a sign_url ou a incorpora em um iframe (com sua marca através do plano Pro).
  • 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.).

Sandbox gratuito ilimitado

O ambiente sandbox é gratuito e ilimitado. Todas as funcionalidades de produção estão disponíveis, exceto que as assinaturas não têm valor legal (o PDF é marcado SANDBOX). Prático para testes automatizados, demos para clientes, desenvolvimento local. As chaves sandbox são distintas das chaves prod, isolamento total entre as duas.

Migrar de DocuSign ou Yousign

Se você já tem uma integração DocuSign ou Yousign, o mapeamento de API é direto: envelopes → envelopes, recipients → recipients, status webhooks → status webhooks. Nosso guia de migração documenta as equivalências endpoint por endpoint. Conte de 1 a 3 dias para uma migração completa, muito menos se você usar um wrapper interno.

Perguntas frequentes — API

Qual é o limite de taxa da API?

1 000 requisições por minuto por padrão, aumentável sob demanda para uso elevado (factories, plataformas multi-tenant). O header X-RateLimit-Remaining em cada resposta indica a cota restante. Em caso de excesso, a API retorna 429 com um Retry-After.

Quanto custa a API?

O sandbox é gratuito e ilimitado. A produção funciona em pagamento por assinatura (a partir de 0,40 € pela assinatura AES com degressive de volume), sem assinatura mínima. O plano Enterprise inclui um SLA reforçado, um IP whitelisting e uma conta técnica dedicada.

Há um SLA?

99,95% de uptime nos planos Business e Enterprise (tempo máximo de inatividade de 4 horas por ano). Página de status pública com histórico de incidentes: status.certyneo.com. O plano Enterprise inclui crédito automático em caso de não conformidade com o SLA.

Qual autenticação você usa?

Bearer token (chave API) no header Authorization. As chaves são rotáveis a partir do dashboard, com revogação imediata. Para integrações OAuth (plataforma multi-tenant), oferecemos um OAuth 2.0 Client Credentials no plano Enterprise.

Como verificar a assinatura HMAC de um webhook?

Cada webhook inclui um header X-Certyneo-Signature contendo um HMAC SHA-256 do payload, assinado com seu webhook secret. No lado do servidor, recalcule o HMAC e compare em tempo constante (timing-safe comparison). O SDK oficial faz isso automaticamente via webhook.verify(payload, signature, secret).

Os SDKs são open source?

Sim. Os SDKs Node, Python e Ruby estão no GitHub sob licença MIT. Você pode fazer fork, contribuir ou simplesmente auditá-los. Os binários são publicados no npm, PyPI e RubyGems sob o namespace @certyneo / certyneo.

Posso testar sem inscrição?

Sim, por meio dos exemplos interativos da documentação da API: /developers/playground. As requisições são executadas em uma instância sandbox compartilhada, sem chave necessária. Para uso sério, crie uma conta de desenvolvedor gratuita (sandbox ilimitado).

Pronto para integrar a assinatura eletrônica?

Sandbox gratuito ilimitado, documentação completa, SDKs oficiais. Comece agora.

Ler a documentação Falar com um desenvolvedor Certyneo