Início rápido da API

Este guia leva você da criação do token até o documento assinado baixado pelo seu sistema, usando curl no terminal. Leva uns 10 minutos. Se preferir clicar em vez de digitar, cada passo também pode ser feito na referência interativa, pelo navegador.

Nota: As chamadas agem na sua conta real. Os passos 3 e 4 usam um rascunho, que não sai para ninguém; no passo 5, o convite vai para o e-mail que você informar. Use o seu.

Antes de começar

• Uma conta no ODSign e acesso como Administrador (para criar o token).
• Um PDF qualquer para testar, salvo como contrato.pdf na pasta onde você vai rodar os comandos.
• curl instalado (já vem no macOS, no Linux e no Windows 10 ou mais novo).

1. Crie o token

1. No app, abra Configurações › Conta e vá até o quadro Tokens da API.
2. Em Nome do token, escreva "Testes da API" e clique em Criar token.
3. Copie o valor completo que aparece em Copie seu token agora (começa com ods_).

No terminal, guarde o token numa variável (assim ele não fica nos comandos):

export ODSIGN_TOKEN="ods_COLE_AQUI_O_SEU_TOKEN"

No Windows (PowerShell), use $env:ODSIGN_TOKEN = "ods_..." e troque \ por ` no fim das linhas.

2. Confira o acesso

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

A resposta 200 traz data (a lista, talvez vazia) e meta (a paginação). Se vier 401 com {"message": "Não autenticado."}, o token foi copiado pela metade ou com espaços: crie outro e repita.

3. Crie um rascunho

Sem send, o envelope fica como rascunho: nada é enviado e ele não conta no limite mensal do plano.

curl -X POST "https://app.odsign.com.br/api/v1/envelopes" \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json" \
  -F "subject=Meu primeiro envelope pela API" \
  -F "message=Teste de integração." \
  -F "recipients[0][name]=Seu Nome" \
  -F "recipients[0][email]=voce@suaempresa.com.br" \
  -F "recipients[0][auth_method]=email" \
  -F "files[]=@contrato.pdf"

• auth_method=email faz o signatário confirmar a assinatura com um código de 6 dígitos enviado ao e-mail dele na hora de assinar. As outras formas estão em Escolher a forma de autenticação.
• A resposta 201 traz o envelope completo em data, com "status": "created". Guarde o id:

export ENVELOPE_ID="COLE_AQUI_O_ID"

O rascunho já aparece no app, em Envelopes › Rascunhos.

4. Confira o envelope

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

Em recipients, confira o nome, o e-mail, a forma de envio (channel) e a de autenticação (auth_method). Em documents, o nome e o número de páginas do PDF.

5. Envie para assinatura

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

A resposta traz "status": "sent" e, no destinatário, "status": "sent". O convite chega ao e-mail informado. Abra, aceite o termo, peça o código e assine: o envelope passa a completed (veja O que acontece depois do envio).

Dica: No seu sistema, você pode criar e enviar numa chamada só, com -F "send=1" no passo 3. Se faltar algo, a resposta é 422 com a pendência e o envelope fica como rascunho.

6. Receba o aviso e baixe o documento assinado

Em produção, o seu sistema fica sabendo da conclusão pelo webhook envelope.completed (veja Webhooks de saída). Para este teste, consulte o envelope de novo (passo 4) até status ser completed e baixe:

curl "https://app.odsign.com.br/api/v1/envelopes/$ENVELOPE_ID/documents/signed" \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -o contrato-assinado.pdf

O arquivo é o documento com a trilha de assinaturas no fim. Para conferir a integridade, compare o SHA-256 dele com o campo final_sha256 do envelope:

shasum -a 256 contrato-assinado.pdf   # no Linux: sha256sum contrato-assinado.pdf

Próximos passos

• Monte o fluxo completo no seu sistema com os Exemplos de integração (PHP, Node.js e Python, com o receptor de webhook).
• Veja todos os parâmetros na Referência dos endpoints ou na referência interativa.
• Antes de ir para produção, passe pelo checklist de boas práticas.

Problemas comuns

• 422 com "The files field is required." O caminho depois do @ não aponta para o arquivo. Rode o comando na pasta do PDF ou use o caminho completo (-F "files[]=@/caminho/contrato.pdf").
• 422 com "Escolha a forma de autenticação de ...". Faltou recipients[0][auth_method]. Sem ele, o signatário precisaria de um campo de assinatura posicionado no documento.
• O convite não chegou. Confira a caixa de spam e o e-mail em recipients. O reenvio é POST /envelopes/{id}/resend (gera um novo link e invalida o anterior).
• 404 ao baixar. O envelope ainda não está completed: assine primeiro.