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. Estas páginas explicam o funcionamento.
A jornada
São seis passos, e só dois deles são seus.
- Você cadastra o depósito — cadastrar um cliente. 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.
- 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.
- Você emite o convite ao fornecedor — gerar o convite. A resposta traz o link de adesão, o preço e as formas de pagamento que o fornecedor verá.
- O fornecedor adere e paga. Ele abre o link, confirma os dados, recebe a cobrança e paga.
- A verificação roda e aprova. Sem ação sua e sem ação do depósito.
- O selo acende. O fornecedor aparece como
certifiedna lista de fornecedores do depósito, e o documento dele respondecertified: truena consulta de selo.
⚠️ 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 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),
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_idde 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
de um
client_idde 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 também
é do seu canal: um documento certificado em outro canal responde
certified: falsepara você. - Não envie
Authorization: Bearer …junto doX-API-Key. As duas credenciais juntas são recusadas com400 AMBIGUOUS_CREDENTIALS, sem dizer qual delas foi aceita.
As operações
| Você quer | Operação |
|---|---|
| Cadastrar um depósito | POST /distributor/clients |
| Ver os seus depósitos e quem já aceitou | GET /distributor/clients |
| Ver um depósito | GET /distributor/clients/{id} |
| Reenviar o primeiro acesso | POST /distributor/clients/{id}/first-access |
| Convidar um fornecedor | POST /distributor/clients/{id}/invites |
| Reenviar o convite (e trocar o e-mail) | POST /distributor/clients/{id}/invites/{invite_id}/resend |
| Acompanhar o andamento de cada fornecedor | GET /distributor/clients/{id}/suppliers |
| Reenviar o link de verificação | POST /distributor/clients/{id}/suppliers/verification-link |
| Carimbar a tela com o selo de um documento | GET /distributor/seal |
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,
O que o canal devolve e Boas práticas.
Para ser avisado quando algo muda, em vez de perguntar, veja Webhooks.