Integre assinatura digital ao seu app usando IA.

FOCO DESTA INTEGRAÇÃO: implemente as duas modalidades e deixe o usuário escolher em cada documento: simples (mode: "simple", código por e-mail ou WhatsApp) ou qualificada ICP-Brasil (provider "birdid", "vidaas" ou "a1", com CPF; no A1 direto/sessão a resposta já vem "signed").

Quero adicionar assinatura digital de documentos ao meu app usando a API da assinatura.online.

CONTEXTO DA API assinatura.online (use exatamente isto, não invente endpoints):
- Base: https://assinatura.online/api/public/v1
- Autenticação: cabeçalhos "X-API-Key" e "X-API-Secret". As duas credenciais ficam SOMENTE no servidor (variáveis de ambiente / cofre de segredos). Nunca no navegador, nunca no código do front-end, nunca no Git.
- POST /signatures/create  (JSON)
  {
    "provider": "vidaas" | "birdid" | "a1",
    "document_name": "Contrato 123",
    "pdf_url": "https://...",     // OU pdf_base64 OU document: {title, body_text ou items}
    "signer": { "full_name": "...", "cpf": "somente números", "email": "..." },
    "external_id": "id do registro no meu sistema",
    "webhook_url": "https://meu-sistema/api/webhooks/assinatura",
    "test_mode": true              // use true durante o desenvolvimento
  }
  Resposta (Bird ID/VIDaaS ou A1 hospedado): { "signature_id", "status": "pending_authorization", "sign_url", "expires_at", "provider" }. Envie sign_url ao signatário: no Bird ID/VIDaaS ele autoriza no app; no A1 hospedado (provider "a1" sem certificado) ele envia o próprio .pfx e a senha na página, usados só em memória.
- A1 direto (síncrono): provider "a1" + certificate: {pfx_base64, password} (ou os aliases a1_pfx_base64 / a1_certificate_base64 + a1_password; não misture formatos). Certificado até 100 KB, validado (senha, par de chaves, validade, CPF = signer.cpf) antes de criar qualquer registro; usado só em memória. Resposta 201 já com status "signed", synchronous: true, signature_token, pdf_url e pdf_base64 (return_pdf: false omite). Nesse caso NÃO há sign_url a abrir.
- Sessões: POST /sessions/create {provider: "birdid"|"vidaas"|"a1", signer:{cpf}, session_lifetime_seconds?} → authorize_url. Depois, POST /signatures/create com session_id assina na hora. Sessão A1 é opcional (opt-in): até 604800 s (7 dias, limitada à validade do certificado); o titular envia o .pfx/senha em authorize_url e o material fica cifrado no servidor até expirar ou POST /sessions/revoke. Expirada: 410 session_expired; revogada: 410 session_revoked.
- Idempotency-Key (cabeçalho opcional, 8 a 128 caracteres: letras, números, . _ : -) vale para POST /signatures/create qualificado (birdid/vidaas/a1); não se aplica a mode "simple". Mesma chave com outro conteúdo → 409 idempotency_key_reused; em andamento → 409 idempotency_in_progress; repetição devolve a mesma resposta com cabeçalho idempotent-replayed: true. Erros após a criação trazem signature_id.
- Detalhes de A1 e sessões: https://assinatura.online/documentacao#a1-direto e https://assinatura.online/documentacao#sessoes
- GET /signatures/get?signature_id=...   -> status atual da solicitação
- GET /signatures/pdf?signature_id=...   -> PDF assinado (somente quando status = "signed")
- POST /signatures/cancel                -> cancela uma solicitação pendente
- Webhooks (POST no webhook_url), eventos: signature.completed, signature.failed, signature.cancelled, signature.expired, signature.dispensed.
  Cabeçalhos: X-Assinatura-Event, X-Assinatura-Timestamp, X-Assinatura-Signature no formato "t=<timestamp>,v1=<hex>".
  Validação: HMAC-SHA256 com o API Secret sobre a string "<timestamp>.<corpo bruto>"; compare em tempo constante e rejeite timestamps com mais de 5 minutos.
- Assinatura eletrônica simples: POST /signatures/create com mode: "simple", document_name, e signer (uma pessoa) ou signers (1 a 20 pessoas no mesmo PDF, em paralelo; nunca os dois). Cada pessoa precisa de email ou phone. otp_channel: "email" (padrão) ou "whatsapp"; sem o campo, usa e-mail quando existe, senão WhatsApp. Telefone brasileiro de 10/11 dígitos recebe DDI 55; outros países precisam de país+DDD+número. CPF é opcional. A resposta traz sign_url por pessoa, signer_count e signers[]. O documento só é concluído (e conta na cobrança) quando todos assinam.
- Na simples use pdf_base64 OU document: {title, body_text ou items}. Não use pdf_url nem test_mode: true. expires_in_hours: 1..720 (padrão 168); send_email_invitation: false e allow_drawn_signature: true por padrão.
- A simples retorna signature_id, status pending_authorization, mode simple, provider email/whatsapp, sign_url, expires_at e invitation_sent. Criar não envia OTP; o signatário solicita na tela e confirma após revisar e aceitar. WhatsApp usa template codigo_temporario em pt_BR com botão de copiar; envio gerenciado pela plataforma, sem credenciais Zapclient do parceiro.
- Marca configurada em /cliente (nome, logo e cor), preservada por solicitação. Tela, e-mails e registro PDF com a marca; mensagem WhatsApp sem logo personalizada. Embed: script https://assinatura.online/assinatura-sdk.js e AssinaturaOnline.open({signUrl,mode:"iframe",container:"#assinatura",height:900,onEvent}). Cadastre a origem e confirme eventos consultando status no servidor.
- PDF simples inclui registro de aceite e evidências; NÃO tem certificado ICP-Brasil. Assinatura avançada não disponível. Status, download, cancelamento e webhooks usam os mesmos endpoints.
- Lote assíncrono de solicitações independentes não disponível; envelopes simples multidocumentos estão disponíveis.
- Em test_mode o PDF é marcado como teste e NÃO tem assinatura digital válida.
- Envelopes simples: substitua a fonte única por documents: [{document_name, pdf_base64}] com 1..10 PDFs (10 MB/arquivo, 20 MB total, 500 páginas). Mesmos signatários em todos os PDFs, um link e OTP por pessoa; stamps.document_index começa em 0 e page em 1 no respectivo documento. Não combine documents com fonte na raiz nem qualified_signer. Cada PDF concluído é uma unidade de consumo. GET /signatures/get retorna document_count e documents. GET /signatures/pdf aceita document_id para arquivo individual ou format=zip para pacote; padrão PDF reunido. signature.completed único por envelope inclui document_count e documents.
- Carimbo qualificado: stamp_options.page aceita first/last/all e prevalece sobre pageIndex (0-based). Sem seleção mantém posição automática: topo/primeira sem SNCR, rodapé/última com SNCR. Rubricas simples continuam em signers[].stamps com page numérica 1-based.
- delivery: {filename: "Relatório Médico.pdf"} na criação simples/qualificada salva o nome do anexo; POST /signatures/deliver {signature_id,channels:["whatsapp","email"],delivery?:{filename},recipients?:[{name,phone?,email?}]} — delivery substitui o nome só naquele envio; recipients (1–5) entrega somente a essas pessoas (ex.: paciente que não assina) em vez dos signatários. Acentos preservados, extensão PDF e caracteres de caminho removidos. Não ativa entrega automática. Cobra por pessoa/canal, estorna falhas, indisponível para contas Prescri. WhatsApp usa template Meta aprovado com PDF anexo e botão dinâmico; o parceiro não configura template.

- Documentação completa: https://assinatura.online/documentacao

O QUE CONSTRUIR:
1. Guarde ASSINATURA_API_KEY e ASSINATURA_API_SECRET como segredos do backend (me peça os valores pela tela segura de segredos; não coloque no código).
2. Crie uma função de servidor "enviarParaAssinatura" que recebe o id do documento, monta o JSON e chama POST /signatures/create. Ofereça simples por e-mail/WhatsApp ou qualificada (Bird ID, VIDaaS ou A1); use test_mode: true só na qualificada. Se o status voltar "signed" na criação (A1 direto ou sessão), não mostre sign_url.
3. Crie uma tabela "assinaturas" com: id, documento_id, signature_id, status, sign_url, criado_em, atualizado_em. Ative a segurança por linha para que cada usuário veja só as suas.
4. Crie um endpoint público de webhook que valide o HMAC antes de qualquer coisa, e atualize o status na tabela conforme o evento.
5. Na tela do documento: botão "Enviar para assinatura", formulário com nome e e-mail, telefone no WhatsApp e CPF obrigatório só na qualificada, selo com o status atual e botão "Baixar PDF assinado" quando o status for "signed" (o download passa pelo meu servidor, nunca expondo as chaves).
6. Mostre mensagens de erro claras em português.

Antes de começar, me explique o plano em poucas linhas. Depois de implementar, me diga como testar a qualificada com test_mode e a simples com documento fictício e destinatário autorizado.