API legada/Referência completa/Parceiros, clientes B2B e representantes

Representantes comerciais

Consulta o escopo (sellers e carteira) de um representante e define o grupo de usuários padrão dele.

Um representante comercial (rep) atende uma carteira de clientes B2B. Pode estar limitado a alguns sellers (escopo por vendor) ou enxergar todos. Estas duas rotas servem ao app do representante e à administração.

GET /representatives/visibility responde "o que este representante enxerga": os sellers permitidos e quantos clientes tem.
PUT /representatives/{cod}/usergroup define o grupo de usuários padrão dos clientes que o representante cadastra, o que decide preços e visibilidade deles.

O código do representante (cod, rep_id) é um inteiro.

GET/api/v1.0/representatives/visibilityAutenticada

Consultar a visibilidade de um representante

Parâmetros de consulta

rep_idinteger

Id do representante a consultar. Sem ele, a rota usa o representante ligado ao usuário autenticado. Um representante só pode consultar o próprio id; o administrador consulta qualquer um.

GET/api/representatives/visibilityAutenticada

Mesma operação, caminho alternativo

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

PUT/api/v1.0/representatives/{cod}/usergroupAdmin

Definir o grupo padrão de um representante

Parâmetros de caminho

codintegerobrigatório

Código (id inteiro) do representante.

Corpo da requisição

usergroup_idstringobrigatório

Id do grupo de usuários. Obrigatório. A rota grava o texto como veio e não confere se o grupo existe.

PUT/api/representatives/{cod}/usergroupAdmin

Mesma operação, caminho alternativo

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1.0/representatives/visibility?rep_id=12" \
  -u "$EMAIL:$API_KEY"

bash

curl -X PUT "$BASE_URL/api/v1.0/representatives/12/usergroup" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "usergroup_id": "5b0c9d1e-7a0e-4d6e-9d0a-2c9b7f3a1e11"
}'

Resposta

200Visibilidade

json

{
  "rep_id": 12,
  "visibility": {
    "vendors": ["94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"],
    "customer_count": 37,
    "scope": "vendor-scoped"
  }
}

Campos da resposta

rep_idinteger

Código do representante consultado.

visibility.vendorsarray

Ids (UUID) dos sellers que o representante pode ver. Vazio quando não há restrição.

visibility.customer_countinteger

Quantidade de clientes na carteira do representante.

visibility.scopestring

vendor-scopedall

vendor-scoped quando o representante tem sellers vinculados, all quando não tem nenhum.

200Grupo definido

json

{
  "rep_id": 12,
  "usergroup_id": "5b0c9d1e-7a0e-4d6e-9d0a-2c9b7f3a1e11",
  "status": "updated"
}

Campos da resposta

rep_idinteger

Código do representante alterado.

usergroup_idstring

Grupo gravado.

statusstring

Sempre updated.

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	`PUT`: a credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: financial data requires admin scope"}`
400	`rep_id` que não é inteiro.	`{"status":400,"message":"rep_id must be an integer"}`
403	Quem não é administrador pediu o `rep_id` de outro representante.	`{"status":403,"message":"Forbidden: can only read your own rep visibility"}`
404	Sem `rep_id`, e nenhum representante ativo está ligado ao usuário (acontece com administradores).	`{"status":404,"message":"No representative linked to this user"}`
400	`cod` que não é inteiro.	`{"status":400,"message":"'cod' must be an integer"}`
400	Corpo que não é JSON.	`{"status":400,"message":"Invalid JSON body"}`
400	Sem `usergroup_id`.	`{"status":400,"message":"usergroup_id is required"}`
404	Nenhum representante com esse código.	`{"status":404,"message":"Representative not found"}`

Veja também

Representantes comerciais

Consulta o escopo (sellers e carteira) de um representante e define o grupo de usuários padrão dele.

GET /representatives/visibility responde "o que este representante enxerga": os sellers permitidos e quantos clientes tem.
PUT /representatives/{cod}/usergroup define o grupo de usuários padrão dos clientes que o representante cadastra, o que decide preços e visibilidade deles.

O código do representante (cod, rep_id) é um inteiro.

GET/api/v1.0/representatives/visibilityAutenticada

Consultar a visibilidade de um representante

Parâmetros de consulta

rep_idinteger

Id do representante a consultar. Sem ele, a rota usa o representante ligado ao usuário autenticado. Um representante só pode consultar o próprio id; o administrador consulta qualquer um.

GET/api/representatives/visibilityAutenticada

Mesma operação, caminho alternativo

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

PUT/api/v1.0/representatives/{cod}/usergroupAdmin

Definir o grupo padrão de um representante

Parâmetros de caminho

codintegerobrigatório

Código (id inteiro) do representante.

Corpo da requisição

usergroup_idstringobrigatório

Id do grupo de usuários. Obrigatório. A rota grava o texto como veio e não confere se o grupo existe.

PUT/api/representatives/{cod}/usergroupAdmin

Mesma operação, caminho alternativo

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1.0/representatives/visibility?rep_id=12" \
  -u "$EMAIL:$API_KEY"

bash

curl -X PUT "$BASE_URL/api/v1.0/representatives/12/usergroup" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "usergroup_id": "5b0c9d1e-7a0e-4d6e-9d0a-2c9b7f3a1e11"
}'

Resposta

200Visibilidade

json

{
  "rep_id": 12,
  "visibility": {
    "vendors": ["94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"],
    "customer_count": 37,
    "scope": "vendor-scoped"
  }
}

Campos da resposta

rep_idinteger

Código do representante consultado.

visibility.vendorsarray

Ids (UUID) dos sellers que o representante pode ver. Vazio quando não há restrição.

visibility.customer_countinteger

Quantidade de clientes na carteira do representante.

visibility.scopestring

vendor-scopedall

vendor-scoped quando o representante tem sellers vinculados, all quando não tem nenhum.

200Grupo definido

json

{
  "rep_id": 12,
  "usergroup_id": "5b0c9d1e-7a0e-4d6e-9d0a-2c9b7f3a1e11",
  "status": "updated"
}

Campos da resposta

rep_idinteger

Código do representante alterado.

usergroup_idstring

Grupo gravado.

statusstring

Sempre updated.

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	`PUT`: a credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: financial data requires admin scope"}`
400	`rep_id` que não é inteiro.	`{"status":400,"message":"rep_id must be an integer"}`
403	Quem não é administrador pediu o `rep_id` de outro representante.	`{"status":403,"message":"Forbidden: can only read your own rep visibility"}`
404	Sem `rep_id`, e nenhum representante ativo está ligado ao usuário (acontece com administradores).	`{"status":404,"message":"No representative linked to this user"}`
400	`cod` que não é inteiro.	`{"status":400,"message":"'cod' must be an integer"}`
400	Corpo que não é JSON.	`{"status":400,"message":"Invalid JSON body"}`
400	Sem `usergroup_id`.	`{"status":400,"message":"usergroup_id is required"}`
404	Nenhum representante com esse código.	`{"status":404,"message":"Representative not found"}`