Parceiros, clientes B2B e representantes

Lojas que vendem para empresas (B2B) trabalham com três figuras que a plataforma 1.0 já tinha e que esta API mantém:

• Parceiro de negócio (business_partner): uma empresa ou pessoa que pede cadastro para comprar (distribuidor, revendedor). Identifica-se por CPF ou CNPJ e passa por uma validação antes de comprar.
• Cliente B2B: o usuário comprador, identificado pelo CNPJ da empresa. Um ERP costuma atualizar em lote a situação, os grupos de preço e as formas de pagamento permitidas de cada cliente.
• Representante comercial (rep): o vendedor interno ou externo que atende uma carteira de clientes, às vezes limitada a alguns sellers.

Como funciona

1. Validar o documento

   Antes de abrir um cadastro, confira o CPF/CNPJ com Parceiros de negócio (scope: verify_document).

2. Aprovar e configurar o cliente

   Depois que o cliente existe na loja, o ERP envia Carga de clientes por CNPJ: ativa o usuário, coloca-o nos grupos certos e define as formas de pagamento que ele pode usar.

3. Escopo do representante

   O app do representante lê Representantes comerciais para saber de quais sellers e de quantos clientes ele cuida.

Conceitos importantes

Ids e o caminho sem versão

Estas rotas existem em /api/v1.0/... e em /api/.... O CNPJ e o código do representante são os identificadores de negócio e não mudam de uma forma para a outra. O {id} de parceiro de negócio é um número inteiro.

Grupos de usuários e formas de pagamento por cliente

Um grupo de usuários agrupa clientes para regras de preço e visibilidade (por exemplo "Atacado"). A forma de pagamento por cliente restringe quais meios (boleto, PIX, faturado) aparecem no checkout dele. Lista vazia significa "sem restrição".

Endpoints

Cada linha vale também sem /v1.0 (/api/business_partners..., /api/customer, /api/representatives...).

Erros comuns

• Tratar 201 de POST /business_partners como cadastro feito. Fora da verificação de documento, nada é gravado (id: 0).
• Mandar o CNPJ com outra chave. A carga lê a chave CNPJ em maiúsculas.
• Esquecer que payments substitui. Quem manda payments redefine a lista inteira de formas de pagamento do cliente.
• Ignorar o 207. Ele indica sucesso parcial: leia skipped.
• Chamar a visibilidade como administrador sem rep_id. O administrador não é um representante e recebe 404.

Próximos passos