Documentação Guias Quickstart

Quickstart: da chave à assinatura em cinco passos

In English. The shortest path through the Partners API: authenticate with the partner key, find the account, send a PDF for electronic signature in a single request, follow the signatures through webhooks or polling, and download the signed file. The guide is written in Brazilian Portuguese; every step names the operationId you will find in the OpenAPI document.

Este guia leva do zero à primeira assinatura concluída. Cada passo cita o operationId da operação, que é o nome dela na referência da v1 e no documento OpenAPI.

Antes de começar

  • Chave de integração. Emitida no cadastro do parceiro pela equipe LetsSign ou gerada pela própria conta na área de integrações do aplicativo (https://app.letssign.com.br/). Ela identifica o parceiro e vai em toda requisição no header Authorization, sem prefixo. Detalhes em Autenticação e contas.
  • Ambiente. Sandbox e produção têm hosts e chaves distintos. A URL base deste ambiente é https://api.letssign.com.br/.
  • Um PDF para testar e o e-mail de quem vai assinar. Use endereços que você controla.

Os exemplos usam curl. Troque SUA_CHAVE e os identificadores pelos seus.

1. Descubra a conta

A chave identifica o parceiro; as operações agem sobre uma conta, identificada pelo accountId no caminho. Liste as contas que a chave pode operar (partners_v1_accounts_list):

curl -H "Authorization: SUA_CHAVE" https://api.letssign.com.br/partners/v1/accounts

[
  {
    "id": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
    "name": "Imobiliária Horizonte",
    "companyName": "Horizonte Negócios Imobiliários Ltda",
    "isTrial": false,
    "personType": "Company",
    "documentNumber": "12345678000195",
    "active": true
  }
]

Guarde o id: ele é o accountId dos próximos passos. Só contas ativas e vinculadas ao parceiro aparecem, em ordem alfabética, sem paginação.

2. Confira as features do plano

Cada operação exige features do plano da conta; sem elas a resposta é 403. Para enviar um documento para assinatura são necessárias documents e documents_signatures; para webhooks, integrations (partners_v1_features_list):

curl -H "Authorization: SUA_CHAVE" \
  https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/features

[
  { "id": "documents", "description": "Documentos" },
  { "id": "documents_signatures", "description": "Assinatura de documentos" },
  { "id": "integrations", "description": "Integrações" }
]

A relação entre features e operações está em Limites e features.

3. Envie o documento para assinatura

Uma única chamada cria o documento e dispara a solicitação a cada signatário (partners_v1_document_signatures_create_from_file). O arquivo vai em base64 no campo contentFile, com o tipo MIME em contentType:

CONTEUDO=$(base64 -i contrato.pdf)   # Linux: base64 -w0 contrato.pdf
curl -X POST -H "Authorization: SUA_CHAVE" -H "Content-Type: application/json" \
  https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/document-signatures \
  -d @- <<JSON
{
  "documentName": "Contrato de locação - Apto 501",
  "contentType": "application/pdf",
  "contentFile": "$CONTEUDO",
  "signers": [
    { "email": "maria.silva@exemplo.com.br", "name": "Maria da Silva", "role": "Parte", "authenticationMethod": "Email" },
    { "email": "joao.souza@exemplo.com.br", "name": "João de Souza", "role": "Testemunha", "authenticationMethod": "Email" }
  ]
}
JSON

{
  "id": "01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "uri": "https://app.letssign.com.br/app/documents/01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f/signatures"
}

O que acontece:

  • O documento nasce com status Finished e status de assinatura WaitingSignatures. Cada signatário recebe o link pelo canal do seu método de autenticação (e-mail, SMS ou WhatsApp) e o webhook DocumentSentToSignature é disparado.
  • role é o papel do signatário ("assina como") e precisa existir na conta. Toda conta nasce com Parte, Testemunha, Aprovador, Contratante e Contratada, entre outros; a lista está em partners_v1_document_signature_roles_list. Aprovador aprova em vez de assinar.
  • Cada chamada cria um documento novo e consome um documento da cota do plano: não há chave de idempotência. Se a requisição estourar o tempo sem resposta, confira se o documento foi criado (partners_v2_documents_list, filtrando por Name e CreatedFrom) antes de repetir.
  • Opcionais que valem conhecer: signatureAreas posiciona assinatura e rubrica no PDF por página e coordenadas em percentual; order nos signatários torna a assinatura sequencial; deadlineForSignature define o prazo; reminderFrequency liga lembretes automáticos; observers recebem o documento assinado ao final; additionalAuthenticationMethods pede evidências como selfie ou documento com foto. O exemplo completo está na referência da operação.
  • 400 para papel inexistente, pasta inexistente, cota esgotada ou recurso do plano ausente (SMS, WhatsApp, biometria); 422 para payload inválido. Veja Erros.

4. Acompanhe as assinaturas

Há duas formas, e a primeira é a recomendada.

Webhooks. Cadastre uma URL uma vez (partners_v1_webhooks_create) e receba um POST a cada evento: DocumentSignatureMember quando um signatário assina e DocumentSignatureFinished quando o último assina.

curl -X POST -H "Authorization: SUA_CHAVE" -H "Content-Type: application/json" \
  https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/webhooks \
  -d '{ "uri": "https://integracao.exemplo.com.br/letssign/webhook" }'

No cadastro um evento Test é enviado de imediato; sua URL deve responder 200 ou 202. O contrato de entrega, os dez eventos e os payloads estão em Webhooks.

Consulta. Quando não houver webhook, ou para conferir, consulte a situação (partners_v1_document_signatures_status):

curl -H "Authorization: SUA_CHAVE" \
  https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/document-signatures/01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f/status

{
  "signatureStatusId": "WaitingSignatures",
  "signatureStatus": "Aguardando assinaturas",
  "signatures": [
    { "id": "01991441-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "email": "maria.silva@exemplo.com.br", "role": "Parte", "signed": true, "signedAt": "2026-08-21T10:12:45Z" },
    { "id": "01991441-9f8e-7d6c-8b5a-4c3d2e1f0a9b", "email": "joao.souza@exemplo.com.br", "role": "Testemunha", "signed": false }
  ]
}

signatureStatusId passa a Signed quando o último signatário assina. signatures[].id é o signatureId usado para editar, remover ou reenviar a solicitação a um signatário.

5. Baixe o arquivo assinado

Peça a URL de download do PDF assinado (partners_v1_documents_download_signed):

curl -H "Authorization: SUA_CHAVE" \
  https://api.letssign.com.br/partners/v1/accounts/0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f/documents/01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f/download/signed

{
  "name": "Contrato de locação - Apto 501",
  "url": "https://s3.sa-east-1.amazonaws.com/documents/.../01991440-5a6b-7c8d-9e0f-1a2b3c4d5e6f-signed.pdf?X-Amz-Expires=300&..."
}
  • A URL é pré-assinada e vale por 5 minutos; baixe logo após obtê-la. Cada chamada gera uma URL nova.
  • Com assinaturas pendentes, o arquivo é um PDF parcial com as assinaturas já feitas; antes da primeira assinatura a resposta é 400.
  • Para o PDF com os anexos incorporados, use partners_v2_documents_download_with_attachments; para documentos assinados com certificado digital, partners_v1_documents_download_digital_certificate.

Depois do quickstart

  • Mexer nos signatários de um documento em assinatura: adicionar (partners_v1_document_signatures_add_signer), editar (partners_v1_document_signatures_edit_signer), remover (partners_v1_document_signatures_remove_signer), reenviar a solicitação (partners_v1_document_signatures_resend) e cancelar (partners_v1_document_signatures_cancel).
  • Documentos a partir de formulários: liste os modelos (partners_v1_form_templates_list), crie o formulário (partners_v1_forms_create) e, quando o webhook FormFilled chegar, solicite as assinaturas (partners_v1_documents_request_signatures).
  • Organização: pastas (partners_v1_folders_list, partners_v1_folders_create), categorias (partners_v2_categories_list, partners_v1_categories_create) e contatos (partners_v1_contacts_upsert_person, partners_v1_contacts_upsert_company).
  • Listagens: partners_v2_documents_list com filtros por status, categoria e datas; o modelo de paginação está em Paginação e filtros.
  • Referência completa: v1 e v2. Quando um endpoint existir na v2, prefira a v2; a migração explica as diferenças.

Este guia também existe em Markdown, e o conjunto completo da documentação em llms.txt.