Autenticação e contas

In English. Every request carries the partner's integration key in the Authorization header, with no scheme prefix. The key identifies the partner; the account being operated comes in the route as accountId, and one key can operate several accounts. This guide covers where the key comes from, how accounts, plans and features relate, how to manage the account's users, and what produces 401 and 403. Text in Brazilian Portuguese.

A chave de integração

Toda requisição leva a chave no header Authorization, sem prefixo. Não use Bearer nem ApiKey na frente: com prefixo, a chave não é reconhecida e a resposta é 401.

GET /partners/v1/accounts HTTP/1.1
Host: api.letssign.com.br
Authorization: 3f9c0a1b2c3d4e5f6a7b8c9d0e1f2a3b

• Emissão. A equipe LetsSign emite a chave no cadastro do parceiro, ou a própria conta a gera na área de integrações do aplicativo (https://app.letssign.com.br/).
• Rotação. Regenerar a chave invalida a anterior na hora; não há período em que as duas valem. Atualize a configuração dos seus sistemas no mesmo instante em que regenerar.
• Guarda. A chave dá acesso a todas as contas vinculadas ao parceiro. Mantenha-a no servidor, fora de aplicativos móveis, páginas e repositórios. Ela também não deve aparecer em URLs.
• Sandbox e produção têm hosts e chaves distintos. A URL base deste ambiente é https://api.letssign.com.br/.

O documento OpenAPI declara dois esquemas de segurança. ApiKey é este header. Bearer (JWT) é o esquema da API de identidade usada pelo aplicativo e não se aplica às APIs de parceiros.

Parceiro, conta e usuário

• Parceiro é quem tem a chave: o sistema que integra.
• Conta é o espaço de uma empresa ou pessoa no LetsSign. Documentos, contatos, pastas, categorias, usuários e webhooks pertencem a uma conta. Quase todas as rotas levam o accountId no caminho.
• Usuário é uma pessoa que acessa o aplicativo dentro de uma conta, com perfil Owner, Admin ou User.

Um parceiro opera quantas contas estiverem vinculadas a ele. O ponto de partida é a lista de contas (partners_v1_accounts_list): só entram contas ativas e vinculadas ao parceiro, em ordem alfabética, sem paginação e sem exigir feature de plano.

[
  {
    "id": "0199143a-7c2e-7b1a-9f2d-3c4b5a6d7e8f",
    "name": "Imobiliária Horizonte",
    "companyName": "Horizonte Negócios Imobiliários Ltda",
    "createdAt": "2025-03-12T13:45:10Z",
    "isTrial": false,
    "initDate": "2025-03-12T00:00:00Z",
    "personType": "Company",
    "documentNumber": "12345678000195",
    "active": true
  }
]

id é o accountId. isTrial indica conta em período de teste; documentNumber é o CPF ou CNPJ do titular. Uma conta que sai da lista (desativada ou desvinculada) passa a responder 401 nas rotas que a citam.

Planos e features

O que uma conta pode fazer vem do plano do seu grupo de faturamento, expresso em features.

• partners_v1_features_list devolve as features da conta: id (o código usado nas descrições das operações e na extensão x-required-features do OpenAPI) e uma descrição legível. A lista muda quando o plano muda.
• Cada operação declara as features que exige. Sem alguma delas, a resposta é 403 com corpo vazio. Consulte a lista antes de habilitar uma funcionalidade na sua integração.
• partners_v1_plans_list lista os planos vinculados ao parceiro, isto é, os planos que a equipe LetsSign pode atribuir às contas dele. Não recebe accountId e é informativo: a atribuição de plano não é feita pela API.

O mapa de features por operação, as cotas e os demais limites estão em Limites e features.

Usuários da conta

• Adicionar (partners_v1_users_add): envia a cada e-mail um convite com o código de acesso. Um e-mail que já existe em outra conta do LetsSign é reaproveitado; um novo cria o usuário. onlyForSignature verdadeiro cria o usuário com perfil User (só vê e assina os próprios documentos) e exige a feature only_signature; falso cria como Admin. O lote é atômico: se qualquer e-mail já pertence à conta, ninguém é adicionado e a resposta 400 lista os repetidos. Conta inativa ou sem plano ativo também responde 400.
• Ativar e desativar (partners_v1_users_change_status).
• Listar (partners_v2_users_list): paginada, com filtros por identificador, nome, e-mail, situação, visibilidade e perfil.
• Logotipo da conta (partners_v1_accounts_change_logo): imagem PNG, JPG ou JPEG em base64; substitui a anterior.

O que responde 401 e 403

Em algumas operações a verificação da conta acontece dentro da regra de negócio, e não na autenticação. É o caso da troca de logotipo, que responde 400 com Conta não existe ou Parceiro não pode realizar operações na conta solicitada. O formato dos erros está em Erros.

Boas práticas

• Trate 401 como problema de configuração (chave, ambiente, vínculo da conta), não como falha transitória: repetir a mesma requisição não muda o resultado.
• Guarde requestId e traceId das respostas de erro; eles identificam a requisição no suporte.
• Nos webhooks não há cabeçalho de assinatura. Valide a origem pelo accountId do payload e, se precisar, por um segredo na própria URL cadastrada. Veja Webhooks.