Referência dos endpoints

Esta é a referência completa da API REST v1. Antes de começar, crie um token (veja Criar e usar um token de API) e leia a Visão geral da API REST, que explica permissões, formatos de dados, limites e códigos de erro.

Antes de começar

Todos os caminhos são relativos a https://app.odsign.com.br/api/v1. Nos exemplos, o token está na variável de ambiente ODSIGN_TOKEN:

export ODSIGN_TOKEN="ods_SEU_TOKEN_AQUI"

Todas as chamadas levam os cabeçalhos Authorization: Bearer $ODSIGN_TOKEN e Accept: application/json.

Listar envelopes

GET /envelopes

Lista os envelopes do mais recentemente alterado para o mais antigo. Com token de administrador, traz os envelopes da conta toda; com os demais perfis, só os que o usuário enviou. Envelopes eliminados e modelos não aparecem.

curl "https://app.odsign.com.br/api/v1/envelopes?status=completed&from_date=2026-11-01&per_page=50" \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json"

Resposta 200 (resumida):

{
  "data": [
    {
      "id": "9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40",
      "subject": "Contrato de prestação de serviços",
      "status": "completed",
      "status_label": "Concluído",
      "recipients": "Maria Souza, João Lima",
      "progress": 100,
      "waiting_for": null,
      "sender": "Ana Prado",
      "updated_at": "2026-11-10T18:22:41+00:00",
      "expires_at": "2027-03-10T13:05:12+00:00"
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1 }
}

Em cada item, recipients traz os nomes dos destinatários em texto, progress é a porcentagem de quem já concluiu e waiting_for traz o nome de quem está na vez (ou null). Use meta.last_page para percorrer as páginas.

Criar um envelope

POST /envelopes (multipart/form-data)

Cria o envelope com documentos, destinatários e campos. Com send=1, envia em seguida. O usuário do token precisa poder enviar envelopes.

Imagens viram páginas em PDF. DOC e DOCX são convertidos para PDF quando a conversão está disponível na plataforma.

Destinatários

O convite sempre vai para o e-mail. Com phone, o convite e os lembretes também saem pelo WhatsApp da plataforma ou, com channel=sms, por SMS, conforme as cotas do plano (veja Cotas mensais de WhatsApp e SMS).

Campos

Use os tipos da tabela, que são os mesmos da paleta do editor (veja Tipos de campo). O menu suspenso precisa de uma lista de opções, que a API não recebe: crie-o pelo editor do app. Para enviar, cada signatário precisa ter ao menos um campo signature.

Dica: Uma página A4 tem 595 × 842 pontos. Para colocar a assinatura perto do rodapé, use algo como x=72 e y=740.

Exemplo

curl https://app.odsign.com.br/api/v1/envelopes \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json" \
  -F "subject=Contrato de prestação de serviços" \
  -F "message=Olá! Segue o contrato para assinatura." \
  -F "files[]=@contrato.pdf" \
  -F "recipients[0][name]=Maria Souza" \
  -F "recipients[0][email]=maria@exemplo.com.br" \
  -F "recipients[0][phone]=11987654321" \
  -F "recipients[0][channel]=whatsapp" \
  -F "fields[0][recipient_index]=0" \
  -F "fields[0][type]=signature" \
  -F "fields[0][page]=1" \
  -F "fields[0][x]=72" \
  -F "fields[0][y]=740" \
  -F "fields[1][recipient_index]=0" \
  -F "fields[1][type]=date_signed" \
  -F "fields[1][page]=1" \
  -F "fields[1][x]=220" \
  -F "fields[1][y]=760" \
  -F "send=1"

Resposta 201, com o envelope completo em data, no mesmo formato mostrado em Detalhar um envelope, logo abaixo.

Atenção: Com send=1, se houver alguma pendência (campo de assinatura faltando, WhatsApp indisponível, limite mensal de envelopes atingido), a resposta é 422 e o envelope fica salvo como rascunho, visível em Envelopes › Rascunhos no app.

Detalhar um envelope

GET /envelopes/{id}

curl https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40 \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json"

Resposta 200 (resumida):

{
  "data": {
    "id": "9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40",
    "subject": "Contrato de prestação de serviços",
    "message": "Olá! Segue o contrato para assinatura.",
    "status": "delivered",
    "status_label": "Em curso",
    "signing_order_enabled": false,
    "current_routing_order": 1,
    "sender": { "name": "Ana Prado", "email": "ana@suaempresa.com.br" },
    "original_sha256": "5b2f0c1e…",
    "final_sha256": null,
    "has_final": false,
    "sent_at": "2026-11-11T13:05:12+00:00",
    "completed_at": null,
    "expires_at": "2027-03-11T13:05:12+00:00",
    "documents": [
      { "id": 812, "name": "contrato.pdf", "order": 1, "pages": 3, "size": 184233 }
    ],
    "recipients": [
      {
        "id": 2051, "type": "signer", "name": "Maria Souza", "email": "maria@exemplo.com.br",
        "routing_order": 1, "status": "delivered", "status_label": "Visualizado",
        "phone": "5511987654321", "channel": "whatsapp", "whatsapp_auth": false, "sms_auth": false,
        "sent_at": "2026-11-11T13:05:12+00:00", "delivered_at": "2026-11-11T13:40:02+00:00",
        "signed_at": null, "declined_at": null, "decline_reason": null
      }
    ],
    "fields": [
      { "id": 9931, "document_id": 812, "recipient_id": 2051, "type": "signature", "page": 1,
        "x": 72.0, "y": 740.0, "width": 120.0, "height": 40.0, "required": true }
    ]
  }
}

Também vêm created_at, voided_at, declined_at, void_reason e as configurações de lembrete e validade do envelope. O endereço url de cada documento é o do app e exige login: para baixar pela API, use o endpoint da seção Baixar documentos, mais abaixo.

Enviar um rascunho

POST /envelopes/{id}/send

Envia um envelope em rascunho. Responde 200 com o envelope atualizado em data, ou 422 com as pendências em errors.envelope (por exemplo, "Este envelope já foi enviado." ou o limite mensal de envelopes do plano).

curl -X POST https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40/send \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json"

Reenviar o convite

POST /envelopes/{id}/resend

Reenvia o convite aos destinatários que estão na vez e ainda não concluíram. Responde 200 com {"message": "Reenviado."}. Só funciona com envelopes em curso; fora disso, responde 422 com "Só é possível reenviar envelopes em curso.". Em correção, a mensagem é "Envie as correções para reenviar o envelope.".

curl -X POST https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40/resend \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json"

Nota: Cada reenvio gera um novo link pessoal. O link do convite anterior deixa de funcionar.

Anular um envelope

POST /envelopes/{id}/void

curl -X POST https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40/void \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Valores revisados; um novo contrato será enviado."}'

Responde 200 com o envelope anulado em data. Envelopes que não estão em curso respondem 422 com "Só é possível anular envelopes em curso.". Os destinatários já avisados recebem a notificação da anulação e os links param de funcionar.

Trilha de auditoria

GET /envelopes/{id}/audit-events

Lista os eventos do envelope em ordem cronológica, os mesmos do histórico e do certificado de conclusão (veja Certificado de conclusão e trilha de auditoria).

curl https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40/audit-events \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -H "Accept: application/json"

Resposta 200 (resumida):

{
  "data": [
    {
      "id": 40211,
      "action": "signed",
      "action_label": "Assinado",
      "description": "Maria Souza assinou o envelope",
      "actor_name": "Maria Souza",
      "actor_email": "maria@exemplo.com.br",
      "source": "web",
      "ip": "200.150.10.20",
      "envelope_status": "delivered",
      "document_sha256": null,
      "created_at": "2026-11-11T13:42:10+00:00"
    }
  ]
}

source indica a origem do evento: web (app ou link de assinatura), api ou sistema (tarefas automáticas, como lembretes e expiração). Alguns valores de action: created, sent, resent, reminder_sent, opened, consented, signed, declined, voided, corrected, expired, completed e copy_sent.

Baixar documentos

GET /envelopes/{id}/documents/{kind}

A resposta é o próprio PDF (application/pdf). Antes da conclusão, responde 404 com "Documento ainda não concluído.".

curl https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40/documents/final \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -o contrato-assinado.pdf

curl https://app.odsign.com.br/api/v1/envelopes/9f1c6a2e-4b7d-4c1e-9a55-3d2f8e7b1c40/documents/certificate \
  -H "Authorization: Bearer $ODSIGN_TOKEN" \
  -o contrato-certificado.pdf

Dica: O campo final_sha256 do envelope é o hash do PDF assinado. Depois de baixar, compare o hash do arquivo com esse valor para confirmar que ele chegou íntegro (veja Verificação pública por código).

Problemas comuns

• 422 em recipients.0.email. Na API, o e-mail é obrigatório para todos os destinatários, inclusive os que também recebem pelo celular.
• 422 em files.0. O arquivo não é PDF, JPG, PNG, DOC ou DOCX, ou passa de 25 MB. Veja Problemas ao enviar arquivos.
• O campo apareceu no lugar errado. As coordenadas são em pontos, a partir do canto superior esquerdo da página. Confira também document_index e page.
• 422 com "Adicione um campo de assinatura para ...". Inclua um campo signature para cada destinatário do tipo signer ou in_person_signer.
• 404 ao baixar. O envelope ainda não foi concluído. Espere o webhook envelope.completed ou confira o status.