Integre assinatura digital ao seu app usando IA.
Prompts prontos para Lovable, ChatGPT e Claude. Copie, cole e deixe a IA montar a integração com a API da assinatura.online — com as chaves guardadas no lugar certo e testes antes de documentos reais.
Está criando seu software com IA?
Você não precisa saber programar. Copie o prompt, cole na ferramenta e responda às perguntas dela. Explicamos cada termo no caminho.
Ver o glossário sem jargãoJá é desenvolvedor?
Use os prompts para acelerar o boilerplate ou vá direto à referência: autenticação por cabeçalho, webhooks com HMAC-SHA256 e modo de testes.
Ir para a referência da APIDo zero à primeira assinatura
Cinco passos, na mesma ordem para qualquer ferramenta de IA.
- 01
Pegue suas credenciais de acesso
Faça o cadastro de parceiro, confirme o código do e-mail e receba API Key e API Secret na hora, com 30 dias de avaliação.
- 02
Copie o prompt da sua ferramenta
Escolha Lovable, ChatGPT ou Claude abaixo e cole o prompt pronto. Ele já descreve a API corretamente para a IA.
- 03
Guarde as chaves em lugar seguro
Quando a IA pedir, cadastre as chaves como segredos do servidor. Nunca cole as chaves na conversa nem no código.
- 04
Valide o fluxo (opcional)
Se quiser testar sem certificado real, envie com test_mode: true. O PDF sai marcado como teste e sem validade.
- 05
Valide e vá para documentos reais
Depois do fluxo validado, envie sem o test_mode e faça uma assinatura real com Bird ID ou VIDaaS.
Escolha sua ferramenta e copie o prompt
Os prompts descrevem só o que a API realmente faz, para a IA não inventar endpoints. Use-os como estão ou ajuste os trechos entre colchetes.
Lovable
Para quem está criando o app conversando com a IA.
- 1Abra seu projeto no Lovable e garanta que o backend (Lovable Cloud) está ativado.
- 2Cole o prompt no chat. O Lovable vai propor um plano; leia e aprove.
- 3Quando ele pedir os segredos, informe API Key e API Secret na janela segura — não no chat.
- 4Abra a tela do documento no preview e clique em “Enviar para assinatura” para testar.
Se algo der errado, cole a mensagem de erro no chat e peça: “corrija sem mudar o resto”.
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",
"document_name": "Contrato 123",
"pdf_url": "https://..." // OU "pdf_base64": "..." (exatamente um dos dois)
"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: { "signature_id", "status", "sign_url" }. Envie sign_url ao signatário; ele autoriza no app do Bird ID ou VIDaaS.
- 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.
- Limitações atuais: um documento e um signatário por solicitação; sem lote; certificado A1 não é aceito pela API (só no assinador gratuito do site).
- Em test_mode o PDF é marcado como teste e NÃO tem assinatura digital válida.
- 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 acima e chama POST /signatures/create com test_mode: true.
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, CPF e e-mail do signatário, 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 com test_mode.Regra de ouro: chaves no servidor
A API Secret funciona como a senha da sua empresa na assinatura.online. Se ela vazar, alguém pode criar solicitações em seu nome. Por isso ela nunca vai para o navegador, para o chat da IA ou para um repositório público. Se suspeitar de vazamento, peça a troca das credenciais pelo suporte.
Erros comuns
- Colar a API Secret no chat da IA ou no código do navegador. Sempre use os segredos do servidor.
- Pedir para a IA “inventar” campos que não existem. Os prompts já trazem a lista correta.
- Esquecer de validar o HMAC do webhook — qualquer pessoa poderia mandar avisos falsos.
- Tratar o PDF do modo de testes como documento válido. Ele é só para testar o fluxo.
- Esperar vários signatários ou lote em uma solicitação: hoje é um documento e um signatário por vez.
Glossário sem jargão
As palavras que a IA vai usar durante a integração, em linguagem simples.
- API
- Uma “porta” pela qual o seu sistema pede coisas para outro sistema — aqui, pede uma assinatura.
- API Key e API Secret
- Usuário e senha do seu sistema na API. O Secret é sigiloso: fica só no servidor.
- Servidor (backend)
- A parte do app que roda fora do navegador do usuário. É lá que as chaves ficam guardadas.
- Webhook
- Um endereço do seu app que a assinatura.online chama para avisar que algo aconteceu, como “documento assinado”.
- HMAC
- Uma conferência matemática que prova que o aviso do webhook veio mesmo da assinatura.online.
- Modo de testes
- Com test_mode: true tudo funciona de ponta a ponta, mas o PDF não tem assinatura válida.
- sign_url
- O link que você envia ao signatário para ele autorizar a assinatura no Bird ID ou VIDaaS.
Perguntas frequentes
Pronto para testar?
Pegue suas credenciais de avaliação e cole o prompt na sua ferramenta favorita.