Visão geral da API REST

A API REST do ODSign permite que o seu sistema (ERP, CRM, portal do cliente) crie e envie envelopes, acompanhe o andamento, anule, consulte a trilha de auditoria e baixe o documento assinado e o certificado, sem ninguém abrir o app. Combinada com os webhooks de saída, ela avisa o seu sistema assim que algo acontece.

O que a API cobre

A referência completa, com parâmetros e exemplos, está em Referência dos endpoints. Modelos, pastas, contatos e as configurações da conta são usados pelo app; a API trabalha com envelopes.

Endereço e autenticação

• Endereço base: https://app.odsign.com.br/api/v1
• Autenticação: token pessoal no cabeçalho Authorization: Bearer <token>. O token é criado por um administrador da conta em Configurações › Conta, no quadro Tokens da API (veja Criar e usar um token de API).
• Formato: as respostas são JSON (exceto os downloads, que são PDF). Envie também o cabeçalho Accept: application/json.

curl https://app.odsign.com.br/api/v1/envelopes \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json"

Permissões

O token age em nome do usuário que o criou, com o perfil dele na conta:

• Administrador: lista e gerencia os envelopes de toda a conta.
• Outros perfis: listam e gerenciam apenas os envelopes que enviaram. Para criar envelopes, o usuário precisa poder enviar (perfil Administrador ou Remetente, com o envio de envelopes liberado no plano).

Cada token só enxerga a própria conta. Um envelope de outra conta responde como não encontrado.

Formatos de dados

Estados do envelope (status)

Estados do destinatário (status)

created (aguardando a vez), sent (enviado), delivered (visualizado), signed (assinado), completed (cópia entregue na conclusão) e declined (recusou).

Limite de uso

Cada usuário pode fazer até 120 requisições por minuto. Acima disso, a API responde 429 Too Many Requests: espere alguns segundos e tente de novo. Para acompanhar o andamento, prefira os webhooks a consultar a API repetidamente.

Os limites do plano também valem pela API: um envelope enviado pela API conta na cota mensal de envelopes da conta, e os convites por WhatsApp ou SMS contam nas cotas de mensagens (veja Limites do plano).

Respostas de erro

Nos erros 422, o corpo traz message e, em errors, a lista de problemas por campo:

{
  "message": "Adicione um campo de assinatura para Maria Souza.",
  "errors": {
    "envelope": ["Adicione um campo de assinatura para Maria Souza."]
  }
}

Fluxo típico de integração

1. Crie um token em Configurações › Conta e guarde-o no cofre de segredos do seu sistema.
2. Cadastre um webhook em Configurações › Webhooks com o evento envelope.completed (veja Webhooks de saída).
3. Crie o envelope com POST /envelopes, enviando os arquivos, os destinatários, os campos de assinatura e send=1.
4. Guarde o id do envelope que volta na resposta.
5. Quando o webhook envelope.completed chegar, confira a assinatura (veja Validar a assinatura dos webhooks) e baixe o PDF assinado e o certificado com GET /envelopes/{id}/documents/final e GET /envelopes/{id}/documents/certificate.

Dica: Envelopes criados pela API usam os padrões de lembretes e validade definidos pela conta em Configurações › Conta › Padrões dos envelopes (veja Dados da conta).

Problemas comuns

• Toda chamada responde 401. Confira se o cabeçalho é Authorization: Bearer seguido do token completo (começa com ods_). Veja Criar e usar um token de API.
• O envelope foi criado, mas não foi enviado. Com send=1, se faltar algo (por exemplo, o campo de assinatura de um signatário), a resposta é 422 e o envelope fica salvo como rascunho. Ele aparece em Envelopes › Rascunhos, onde você pode completar e enviar pelo app.
• Recebo 422 em send, signing_order ou outro campo booleano. Em formulários multipart, envie booleanos como 1 ou 0, e não como true ou false.