Guia para criar com IA

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.

LovableLovableChatGPTChatGPTClaudeClaude

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ão

Já é 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 API

Do zero à primeira assinatura

Cinco passos, na mesma ordem para qualquer ferramenta de IA.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

LovableLovable

Para quem está criando o app conversando com a IA.

  1. 1Abra seu projeto no Lovable e garanta que o backend (Lovable Cloud) está ativado.
  2. 2Cole o prompt no chat. O Lovable vai propor um plano; leia e aprove.
  3. 3Quando ele pedir os segredos, informe API Key e API Secret na janela segura — não no chat.
  4. 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”.

prompt-lovable.txt
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.
Contém apenas valores de exemplo. Nunca inclua suas chaves reais no prompt.

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.

LovableLovableChatGPTChatGPTClaudeClaude
Suporte pelo WhatsApp