# 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`.

```http
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.

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

| Situação | Status | Corpo |
|---|---|---|
| Chave ausente, inválida ou com prefixo | `401` | vazio |
| Conta não vinculada ao parceiro (ou inativa) | `401` | vazio |
| Período de teste da conta expirado | `401` | Problem Details com o motivo em `detail` |
| Grupo de faturamento da conta sem plano ativo | `401` | Problem Details com o motivo em `detail` |
| Plano da conta sem uma feature exigida pela operação | `403` | vazio |

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