Boas práticas e checklist de produção

Uma integração que funciona no primeiro teste nem sempre aguenta o dia a dia: tempo esgotado no meio do envio, servidor fora do ar na hora do webhook, token vazado num log. Este guia reúne o que fazer antes de ligar a integração em produção, com a lista de conferência no final.

Proteja o token

• Guarde o token em variável de ambiente ou cofre de segredos. Nunca no código-fonte, no repositório, em planilhas, em mensagens ou em logs (mascare o cabeçalho Authorization nos registros de requisição).
• Chame a API só do seu servidor. O token não pode ir para páginas web, aplicativos de celular ou qualquer código que rode no aparelho do cliente.
• Crie o token com um usuário dedicado à integração (por exemplo, "Integração ERP"), com o perfil mínimo necessário: Remetente se a integração só gerencia os envelopes que ela mesma envia; Administrador se precisa ver os da conta toda.
• Um token por sistema integrado, com nome claro. Se um token vazar, peça a revogação ao suporte e troque (veja Se o token vazar).

Repita só o que pode ser repetido

Leituras (GET) podem ser repetidas à vontade. Para POST /envelopes, veja a seção abaixo antes de repetir.

Dica: Os cabeçalhos X-RateLimit-Remaining mostram quanto ainda cabe no minuto (120 requisições por usuário). Se o seu sistema faz envios em lote, espalhe as chamadas em vez de disparar todas de uma vez.

Evite envelopes duplicados

A API não tem chave de idempotência: se o POST /envelopes esgotar o tempo do seu lado depois de o ODSign já ter criado o envelope, repetir cria outro. Para não duplicar:

1. Use um tempo limite generoso no envio (60 s ou mais, por causa do upload e da conversão dos arquivos).
2. Grave o id devolvido junto do registro do seu sistema assim que a resposta chegar.
3. Se a resposta não veio, antes de repetir, liste os envelopes recentes e procure o seu: GET /envelopes?from_date=AAAA-MM-DD e compare o subject (inclua nele o número do seu contrato ou pedido, como "Contrato 123 - Prestação de serviços").
4. Se encontrar, use aquele id; se não, repita.

Um 422 com send=1 também não pede um novo envelope: ele ficou salvo como rascunho, com as pendências em errors.envelope. Corrija pelo app (Envelopes › Rascunhos) ou anule e recrie conscientemente.

Webhooks confiáveis

• Confira a assinatura de toda entrega antes de usar o conteúdo (veja Validar a assinatura dos webhooks).
• Responda em poucos segundos com 2xx e processe depois, numa fila. Respostas lentas contam como falha e geram novas tentativas.
• Ignore repetições: guarde a combinação event + envelope.id + recipient.id já processada.
• Não conte com a ordem: uma nova tentativa pode chegar depois de um evento mais novo. Na dúvida, consulte o envelope pela API.
• Confira periodicamente: são até 3 tentativas em cerca de 1 minuto. Se o seu servidor ficar fora do ar por mais tempo, o evento não chega de novo. Uma conferência de hora em hora com GET /envelopes?from_date=... resolve (veja Exemplos de integração).
• Descarte eventos muito antigos se quiser uma proteção a mais contra reenvio malicioso: o sent_at faz parte do corpo assinado.

Teste sem ambiente separado

Não há um ambiente de testes à parte: tudo acontece na conta do token. Para desenvolver com segurança:

• Crie rascunhos (sem send): eles não saem para ninguém e não contam no limite mensal. Exclua-os depois em Envelopes › Rascunhos.
• Para o fluxo completo, use o seu e-mail ou celular como destinatário.
• Se quiser isolar de vez, use uma conta separada para desenvolvimento e homologação, com o próprio token e o próprio webhook.
• Teste o receptor de webhooks sem eventos reais com a ferramenta Validar e simular e com o botão Testar em Configurações › Webhooks.

Escolha a forma de autenticação pelo risco

A forma de autenticação, o IP, a data e a hora de cada ação vão para a trilha de assinaturas do documento. Veja Validade jurídica para os tipos de documento que exigem forma especial em lei.

Proteção de dados (LGPD)

• Nos envelopes que o seu sistema cria, a sua empresa é a controladora dos dados dos destinatários e do conteúdo dos documentos; o ODSign trata esses dados em seu nome (veja o Acordo de tratamento de dados).
• Envie só o necessário: nome, e-mail e, quando for usar WhatsApp, SMS ou token pelo celular, o celular.
• Informe os signatários sobre o uso da assinatura eletrônica e dos dados, como faria com qualquer contrato.
• Guarde os PDFs baixados com o mesmo cuidado dos originais: eles trazem os dados de todos os participantes.

Checklist de produção

• Token em cofre de segredos, criado por um usuário dedicado, com o perfil mínimo necessário.
• Cabeçalho Authorization mascarado nos logs do seu sistema.
• Tempo limite de 60 s ou mais no POST /envelopes e o id gravado logo que a resposta chega.
• Novas tentativas só em 429 (com Retry-After) e 5xx/sem resposta (com espera progressiva).
• Busca antes de repetir um POST /envelopes sem resposta.
• 422 tratado: mostra a pendência para alguém resolver, sem recriar o envelope.
• Webhook com https, assinatura conferida em tempo constante e resposta 2xx em poucos segundos.
• Repetições de webhook ignoradas e processamento numa fila.
• Conferência periódica com GET /envelopes?from_date=....
• Download do documento assinado com conferência do SHA-256 contra final_sha256.
• Código que ignora campos e valores novos nas respostas e eventos desconhecidos.
• Alerta para 401 (token revogado ou usuário bloqueado) e para entregas de webhook com Falhou.