VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/Parceiros, clientes B2B e representantes

Parceiros de negócio

Verifica CPF/CNPJ de um parceiro; cadastro, consulta e alteração ainda são esboços.

Um parceiro de negócio é a empresa ou pessoa que pede cadastro numa loja B2B para comprar. Na plataforma 1.0 o cadastro tinha formulário em seções, validação do documento e aprovação.

Quase tudo aqui é esboço

Hoje apenas POST com scope: "verify_document" faz trabalho real (valida os dígitos do CPF ou CNPJ). Todas as outras chamadas respondem com sucesso, mas sem gravar nem ler nada, e a resposta traz uma message dizendo que não está implementado. Não monte fluxo de cadastro em cima delas.

Resumo do que cada chamada faz:

ChamadaO que acontece
GET /business_partnersDevolve listas vazias (companies, bp_types, bp_users) e search.total_items: 0.
GET /business_partners/{id}Devolve bp_user_data: null, listas vazias e message Business partner service not yet implemented. Partner ID: 7.
POST com scope: "verify_document"Funciona. Valida CPF ou CNPJ.
POST com scope: "get_ai_data" ou "upload_file_data"201 com message de "not yet implemented". Nada é processado.
POST sem scopeValida os campos obrigatórios e responde 201 com id: 0 e a mensagem "Business partner creation not yet implemented". Nada é criado.
PUT /business_partners/{id} (padrão scope: "update")Exige form_values; depois responde 200 com "Business partner update not yet implemented". Nada é alterado.
PUT com scope: "validate"Responde validated: true sem validar nada.
GET/api/v1.0/business_partnersAdmin

Listar parceiros de negócio (esboço)

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 250.
GET/api/business_partnersAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de GET /api/v1.0/business_partners. Use este caminho se o seu cliente já foi escrito para ele.

GET/api/v1.0/business_partners/{id}Admin

Consultar parceiro de negócio (esboço)

Parâmetros de caminho

idintegerobrigatório
Id do parceiro, inteiro. Qualquer valor é aceito; a rota só o repete na mensagem.
GET/api/business_partners/{id}Admin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de GET /api/v1.0/business_partners/{id}. Use este caminho se o seu cliente já foi escrito para ele.

POST/api/v1.0/business_partnersAdmin

Verificar documento ou cadastrar parceiro

Corpo da requisição

scopestring
verify_documentget_ai_dataupload_file_data
O que fazer. Sem valor é o cadastro (esboço).
document_typestring
cpf ou cnpj, sem diferenciar maiúsculas. Obrigatório em verify_document e no cadastro.
document_numberstring
Número do documento, com ou sem pontuação. Obrigatório em verify_document e no cadastro.
type_idinteger
Tipo do parceiro. Obrigatório no cadastro (esboço).
company_idsarray
Ids das empresas (sellers) a que o parceiro se vincula, inteiros. Obrigatório no cadastro (esboço), pelo menos um.
idinteger
Parceiro existente, usado em upload_file_data (esboço).
POST/api/business_partnersAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de POST /api/v1.0/business_partners. Use este caminho se o seu cliente já foi escrito para ele.

PUT/api/v1.0/business_partners/{id}Admin

Alterar ou validar parceiro (esboço)

Parâmetros de caminho

idintegerobrigatório
Id do parceiro, inteiro. Qualquer valor é aceito; a rota só o repete na mensagem.

Corpo da requisição

scopestringpadrão: update
updatevalidate
update (padrão) ou validate.
form_valuesobject
Valores do formulário. Obrigatório (não vazio) quando scope é update.
PUT/api/business_partners/{id}Admin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de PUT /api/v1.0/business_partners/{id}. Use este caminho se o seu cliente já foi escrito para ele.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1.0/business_partners" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "verify_document",
  "document_type": "cnpj",
  "document_number": "11.222.333/0001-81"
}'

Resposta

200Documento verificado
json
{ "is_valid": true, "message": "" }

Campos da resposta

is_validboolean
true quando os dígitos verificadores do documento conferem. Não consulta a Receita Federal: só confirma que o número é bem formado.
messagestring
Sempre vazio.
201Esboço (nada gravado)
json
{
  "id": 0,
  "message": "Business partner creation not yet implemented"
}

Erros

StatusQuandoCorpo de exemplo
401Sem credencial.{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}
401E-mail ou chave de API inválidos.{"status":401,"message":"Invalid credentials"}
403A credencial é válida, mas o usuário não é administrador.{"status":403,"message":"Forbidden: admin scope required"}
400Corpo que não é JSON.{"status":400,"message":"Invalid JSON body"}
400verify_document sem document_type ou document_number.{"status":400,"message":"document_number and document_type are required"}
400document_type diferente de cpf/cnpj.{"status":400,"message":"document_type must be 'cpf' or 'cnpj'"}
400Cadastro sem document_number, document_type, type_id ou company_ids (a mensagem cita o primeiro que falta).{"status":400,"message":"type_id is required"}
400PUT com scope update e sem form_values.{"status":400,"message":"form_values is required for update scope"}
O que dá para usar hoje

Use verify_document para validar CPF/CNPJ antes de abrir um cadastro em outro sistema. Para cadastrar compradores B2B de verdade, a loja usa o registro de clientes e a aprovação no painel, não estas rotas.

Veja também

  • Carga de clientes por CNPJ
  • Visão geral
Anterior
Parceiros, clientes B2B e representantes
Próxima
Carga de clientes por CNPJ
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também