# 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](https://api.letssign.com.br/docs/partners-v1/openapi.json).

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](https://api.letssign.com.br/docs/partners/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](https://api.letssign.com.br/docs/guides/autenticacao-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`):

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

```json
[
  {
    "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`):

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

```json
[
  { "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](https://api.letssign.com.br/docs/guides/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`:

```bash
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
```

```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](https://api.letssign.com.br/docs/guides/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.

```bash
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](https://api.letssign.com.br/docs/guides/webhooks).

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

```bash
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
```

```json
{
  "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`):

```bash
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
```

```json
{
  "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](https://api.letssign.com.br/docs/guides/paginacao-e-filtros).
- **Referência completa**: [v1](https://api.letssign.com.br/docs/partners/v1) e [v2](https://api.letssign.com.br/docs/partners/v2). Quando um endpoint existir na
  v2, prefira a v2; a [migração](https://api.letssign.com.br/docs/guides/migracao-v1-para-v2) explica as diferenças.