# Canal de certificação

O canal de certificação é para o parceiro que atende **depósitos** e quer que os **fornecedores**
desses depósitos sejam certificados. Pela API, o seu sistema cadastra o depósito, convida os
fornecedores em nome dele, acompanha o andamento de cada um e lê o selo resultante. São oito caminhos
(nove operações, contando o método), uma credencial e um formato de erro.

A referência de cada operação — o que entra, o que volta e as recusas — está em
[Referência da API · Distribuidor](/referencia/distribuidor). Estas páginas explicam o funcionamento.

## A jornada

São seis passos, e só dois deles são seus.

1. **Você cadastra o depósito** —
   [cadastrar um cliente](/referencia/distribuidor#cadastrar-um-cliente-deposito-no-seu-canal). A conta
   é criada na hora, já ligada ao seu canal, e a resposta traz um **link de primeiro acesso**, que
   também vai por e-mail ao responsável que você informou.
2. **O depósito aceita.** O responsável abre o link, define a senha e, na mesma tela, aceita que a
   conta dele passe a ser atendida por você. **É aqui que o vínculo passa a valer.**
3. **Você emite o convite ao fornecedor** —
   [gerar o convite](/referencia/distribuidor#gerar-o-convite-de-certificacao-de-um-fornecedor). A
   resposta traz o **link de adesão**, o preço e as formas de pagamento que o fornecedor verá.
4. **O fornecedor adere e paga.** Ele abre o link, confirma os dados, recebe a cobrança e paga.
5. **A verificação roda e aprova.** Sem ação sua e sem ação do depósito.
6. **O selo acende.** O fornecedor aparece como `certified` na
   [lista de fornecedores](/referencia/distribuidor#listar-os-fornecedores-de-um-cliente-com-o-andamento-de-cada-um)
   do depósito, e o documento dele responde `certified: true` na
   [consulta de selo](/referencia/distribuidor#consultar-o-selo-de-um-fornecedor-pelo-documento).

## ⚠️ O degrau entre o passo 1 e o passo 3

**Cadastrar um depósito não basta para convidar fornecedores em nome dele.** Enquanto o depósito não
aceitar (passo 2), a emissão de convite responde **`409 CLIENT_CONSENT_PENDING`**, e o depósito aparece
na [lista dos seus depósitos](/referencia/distribuidor#listar-os-clientes-do-seu-canal) com
`status: "pending_first_access"`.

Gerar um convite é agir em nome do depósito: é o nome dele que o fornecedor vê. Essa autorização é do
titular da conta, e ninguém pode dá-la no lugar dele — nem você, nem nós. O aceite só existe quando a
pessoa do depósito o pratica, na própria tela, com registro do momento e do texto que ela leu.

Na prática: o depósito recém-cadastrado **existe**, tem `client_id` e aparece na sua lista, mas fica em
`pending_first_access` até aceitar. Trate esse estado como um passo do seu funil — reenvie o link
([reenviar o primeiro acesso](/referencia/distribuidor#reenviar-o-primeiro-acesso-de-um-cliente-pendente)),
lembre o cliente — e não como erro. Quem está `active` já recebe convites.

## A regra do alvo

A credencial diz **quem está chamando**; o `client_id` na URL diz **sobre qual depósito** a chamada age.
E a credencial só opera sobre depósitos **do seu canal** — os que você cadastrou e que aceitaram o
vínculo.

- Um `client_id` de fora do seu canal responde **exatamente igual** a um que não existe:
  **`404 CLIENT_NOT_FOUND`**. As duas situações são indistinguíveis de propósito — se a resposta
  diferenciasse "não existe" de "existe mas não é seu", a rota viraria uma sonda de quem tem conta.
- A [lista de fornecedores](/referencia/distribuidor#listar-os-fornecedores-de-um-cliente-com-o-andamento-de-cada-um)
  de um `client_id` de fora **não** devolve 404: devolve **200 com a lista vazia**, a mesma resposta de um
  depósito seu que ainda não tem fornecedor.
- A [consulta de selo](/referencia/distribuidor#consultar-o-selo-de-um-fornecedor-pelo-documento) também
  é do seu canal: um documento certificado em **outro** canal responde `certified: false` para você.
- **Não envie `Authorization: Bearer …` junto do `X-API-Key`.** As duas credenciais juntas são recusadas
  com **`400 AMBIGUOUS_CREDENTIALS`**, sem dizer qual delas foi aceita.

## As operações

| Você quer | Operação |
| --- | --- |
| Cadastrar um depósito | [`POST /distributor/clients`](/referencia/distribuidor#cadastrar-um-cliente-deposito-no-seu-canal) |
| Ver os seus depósitos e quem já aceitou | [`GET /distributor/clients`](/referencia/distribuidor#listar-os-clientes-do-seu-canal) |
| Ver um depósito | [`GET /distributor/clients/{id}`](/referencia/distribuidor#consultar-um-cliente-do-seu-canal) |
| Reenviar o primeiro acesso | [`POST /distributor/clients/{id}/first-access`](/referencia/distribuidor#reenviar-o-primeiro-acesso-de-um-cliente-pendente) |
| Convidar um fornecedor | [`POST /distributor/clients/{id}/invites`](/referencia/distribuidor#gerar-o-convite-de-certificacao-de-um-fornecedor) |
| Reenviar o convite (e trocar o e-mail) | [`POST /distributor/clients/{id}/invites/{invite_id}/resend`](/referencia/distribuidor#reenviar-o-convite-de-certificacao) |
| Acompanhar o andamento de cada fornecedor | [`GET /distributor/clients/{id}/suppliers`](/referencia/distribuidor#listar-os-fornecedores-de-um-cliente-com-o-andamento-de-cada-um) |
| Reenviar o link de verificação | [`POST /distributor/clients/{id}/suppliers/verification-link`](/referencia/distribuidor#reenviar-o-link-de-verificacao-ao-fornecedor) |
| Carimbar a tela com o selo de um documento | [`GET /distributor/seal`](/referencia/distribuidor#consultar-o-selo-de-um-fornecedor-pelo-documento) |

Toda resposta traz `success`, e todo erro tem a mesma forma: `{ "success": false, "error": "…", "code": "…" }`.
**Ramifique no `code`, nunca no texto de `error`** — o `code` é o contrato; o texto é legenda e pode
mudar. Veja também [Estados do fornecedor](/canal/estados-do-fornecedor),
[O que o canal devolve](/canal/o-que-o-canal-devolve) e [Boas práticas](/canal/boas-praticas).

Para ser avisado quando algo muda, em vez de perguntar, veja [Webhooks](/webhooks/visao-geral).