API legada/Guia rápido/Gerentes de venda

Gerenciar gerentes

Liste, consulte, crie e altere gerentes de venda e a carteira de clientes de cada um, na API compatível com a Venddor 1.0.

Use estas operações para manter os gerentes sincronizados com o seu ERP ou com o app do vendedor: cadastrar o gerente novo, ajustar o limite de desconto, trocar a carteira de clientes quando a região muda, desativar quem saiu. Os conceitos estão em Gerentes de venda.

Todas as respostas trazem success e message, no estilo do módulo antigo.

GET/api/v1.0/managersAdmin

Listar gerentes de vendas

Também responde em /api/managers. O bloco search traz a paginação.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora desse intervalo vale o padrão.

namestring

Texto procurado no nome do gerente.

emailstring

Texto procurado no nome e no e-mail. Só vale quando name não é enviado.

internal_codestring

Código do gerente no ERP (igualdade).

statusstring

ADactivedisabled

Só ativos ou só desativados.

companystring

Id do seller dono do gerente.

Exemplo de requisição (listar)

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/managers?status=A&items_per_page=10"

Resposta (listar)

200Gerentes retornados

json

{
  "managers": [
    {
      "manager_id": "30",
      "user_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0",
      "name": "Ana Paula Ribeiro",
      "email": "ana.ribeiro@example.com",
      "phone": "11955554444",
      "status": "A",
      "timestamp": 1791752276,
      "company_id": "",
      "company_name": "",
      "internal_code": "GER-SUL-01",
      "ec_user_level": "1",
      "manager_discount_limit": "5.00",
      "users": [],
      "users_count": 0,
      "orders_count": 0,
      "notify": "Y",
      "credit_balance": "0.00"
    }
  ],
  "search": { "page": 1, "items_per_page": 10, "total_items": 13 },
  "success": true,
  "message": ""
}

Campos da resposta

managers[].manager_idstring

Id do gerente: um inteiro dentro de string. É o id usado nas rotas.

managers[].user_idstring

UUID do usuário (login) do gerente.

managers[].namestring

Nome.

managers[].emailstring

E-mail.

managers[].phonestring

Telefone.

managers[].statusstring

AD

Ativo ou desativado.

managers[].timestampinteger

Cadastro em Unix (segundos).

managers[].company_idstring

Seller dono do gerente. Vazio se for da loja.

managers[].company_namestring

Sempre vazio nesta rota.

managers[].internal_codestring

Código no ERP.

managers[].ec_user_levelstring

Nível hierárquico, como texto. Vazio se não definido.

managers[].manager_discount_limitstring

Desconto máximo em percentual, duas casas ("7.50").

managers[].usersarray

Ids dos clientes da carteira. Na lista vem sempre vazio; use a consulta de um gerente para ver a carteira. users_count também só é preenchido na consulta.

managers[].orders_countinteger

Pedidos do gerente.

managers[].notifystring

Sempre "Y".

managers[].credit_balancestring

Saldo de crédito, string decimal.

searchobject

Paginação: page, items_per_page, total_items.

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

Consultar um gerente de vendas

Devolve o gerente com a carteira (users e users_count). Um gerente que não existe responde 200 com manager_data: null, não 404.

Parâmetros de caminho

idstringobrigatório

manager_id, inteiro. Outro formato responde 400 invalid manager_id.

200Gerente e carteira

json

{
  "manager_data": {
    "manager_id": "30",
    "user_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0",
    "name": "Ana Paula Ribeiro",
    "email": "ana.ribeiro@example.com",
    "phone": "11955554444",
    "status": "A",
    "internal_code": "GER-SUL-01",
    "ec_user_level": "1",
    "manager_discount_limit": "5.00",
    "users": ["3dc023ca-3746-4b6e-8afd-686a4a9af99f"],
    "users_count": 1,
    "orders_count": 0,
    "notify": "Y",
    "credit_balance": "0.00",
    "company_id": "",
    "company_name": "",
    "timestamp": 1791752276
  },
  "success": true,
  "message": ""
}

POST/api/v1.0/managersAdmin

Criar um gerente de vendas

Cria o gerente e o usuário de login dele (tipo vendor, com o mesmo e-mail e a senha enviada). Repare: a resposta é sempre 200, e quando falta um campo obrigatório o 200 vem com a mensagem "<campo> is required" e nada é criado.

Corpo da requisição

namestringobrigatório

Nome completo. Separado em nome e sobrenome pelo primeiro espaço.

emailstringobrigatório

E-mail de login. Precisa estar livre.

phonestringobrigatório

Telefone.

statusstringobrigatório

AD

Status inicial.

password1stringobrigatório

Senha.

password2stringobrigatório

Confirmação da senha. Diferente de password1: 400 error_passwords_dont_match.

company_idstring

Id do seller dono do gerente. 0 ou omitido, sem seller.

internal_codestring

Código no ERP.

manager_discount_limitstring

Desconto máximo em percentual ("5" ou "7.5").

ec_user_levelinteger

Nível hierárquico.

usersstring

Carteira: ids de clientes em lista (["uuid", "uuid"]) ou texto separado por vírgula.

200Gerente criado

json

{ "manager_id": 30, "message": "" }

Exemplo de requisição (criar)

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/managers" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Paula Ribeiro",
    "email": "ana.ribeiro@example.com",
    "phone": "11955554444",
    "status": "A",
    "password1": "Troque-Esta-Senha-9!",
    "password2": "Troque-Esta-Senha-9!",
    "internal_code": "GER-SUL-01",
    "manager_discount_limit": "5",
    "ec_user_level": 1
  }'

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

Atualizar um gerente de vendas

Altera só os campos enviados. Quando users é enviado, a carteira é substituída (inclusive por uma lista vazia, que a esvazia). password1 e password2, se enviados, precisam ser iguais, mas não trocam a senha. Um id que não existe também responde 200: confira antes com a consulta.

Parâmetros de caminho

idstringobrigatório

manager_id, inteiro.

Corpo da requisição

namestring

Nome.

emailstring

E-mail do gerente (o login do usuário não é alterado).

phonestring

Telefone.

statusstring

AD

Só A ativa; qualquer outro valor desativa, inclusive a palavra active. Mande sempre a letra.

company_idstring

Seller dono do gerente.

internal_codestring

Código no ERP.

manager_discount_limitstring

Desconto máximo, em percentual.

ec_user_levelinteger

Nível hierárquico.

usersstring

Nova carteira completa (lista ou texto com vírgulas). Omita para não mexer.

password1string

Se enviada, deve ser igual a password2. Não altera a senha.

password2string

Confirmação.

200Gerente alterado

json

{ "manager_id": 30, "message": "" }

DELETE/api/v1.0/managers/{id}Admin

Excluir um gerente de vendas (não suportado)

Não exclui. Responde sempre 404 com Delete not supported for managers, como o módulo original. Para desligar um gerente, use PUT com status: "D".

Parâmetros de caminho

idstringobrigatório

manager_id.

404Não suportado

json

{ "message": "Delete not supported for managers", "status": 404 }

Erros

Status	Quando	Corpo
200	Falta um campo obrigatório ao criar (não é erro HTTP)	`{"message":"email is required"}`
400	`password1` diferente de `password2`	`{"message":"error_passwords_dont_match","status":400}`
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}`
400	`id` que não é inteiro	`{"message":"invalid manager_id","status":400}`
400	E-mail já em uso, ao criar	`{"message":"email already registered","status":400}`
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	`DELETE`	`{"message":"Delete not supported for managers","status":404}`

Veja também

Gerenciar gerentes

Liste, consulte, crie e altere gerentes de venda e a carteira de clientes de cada um, na API compatível com a Venddor 1.0.

Todas as respostas trazem success e message, no estilo do módulo antigo.

GET/api/v1.0/managersAdmin

Listar gerentes de vendas

Também responde em /api/managers. O bloco search traz a paginação.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora desse intervalo vale o padrão.

namestring

Texto procurado no nome do gerente.

emailstring

Texto procurado no nome e no e-mail. Só vale quando name não é enviado.

internal_codestring

Código do gerente no ERP (igualdade).

statusstring

ADactivedisabled

Só ativos ou só desativados.

companystring

Id do seller dono do gerente.

Exemplo de requisição (listar)

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/managers?status=A&items_per_page=10"

Resposta (listar)

200Gerentes retornados

json

{
  "managers": [
    {
      "manager_id": "30",
      "user_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0",
      "name": "Ana Paula Ribeiro",
      "email": "ana.ribeiro@example.com",
      "phone": "11955554444",
      "status": "A",
      "timestamp": 1791752276,
      "company_id": "",
      "company_name": "",
      "internal_code": "GER-SUL-01",
      "ec_user_level": "1",
      "manager_discount_limit": "5.00",
      "users": [],
      "users_count": 0,
      "orders_count": 0,
      "notify": "Y",
      "credit_balance": "0.00"
    }
  ],
  "search": { "page": 1, "items_per_page": 10, "total_items": 13 },
  "success": true,
  "message": ""
}

Campos da resposta

managers[].manager_idstring

Id do gerente: um inteiro dentro de string. É o id usado nas rotas.

managers[].user_idstring

UUID do usuário (login) do gerente.

managers[].namestring

Nome.

managers[].emailstring

E-mail.

managers[].phonestring

Telefone.

managers[].statusstring

AD

Ativo ou desativado.

managers[].timestampinteger

Cadastro em Unix (segundos).

managers[].company_idstring

Seller dono do gerente. Vazio se for da loja.

managers[].company_namestring

Sempre vazio nesta rota.

managers[].internal_codestring

Código no ERP.

managers[].ec_user_levelstring

Nível hierárquico, como texto. Vazio se não definido.

managers[].manager_discount_limitstring

Desconto máximo em percentual, duas casas ("7.50").

managers[].usersarray

Ids dos clientes da carteira. Na lista vem sempre vazio; use a consulta de um gerente para ver a carteira. users_count também só é preenchido na consulta.

managers[].orders_countinteger

Pedidos do gerente.

managers[].notifystring

Sempre "Y".

managers[].credit_balancestring

Saldo de crédito, string decimal.

searchobject

Paginação: page, items_per_page, total_items.

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

Consultar um gerente de vendas

Devolve o gerente com a carteira (users e users_count). Um gerente que não existe responde 200 com manager_data: null, não 404.

Parâmetros de caminho

idstringobrigatório

manager_id, inteiro. Outro formato responde 400 invalid manager_id.

200Gerente e carteira

json

{
  "manager_data": {
    "manager_id": "30",
    "user_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0",
    "name": "Ana Paula Ribeiro",
    "email": "ana.ribeiro@example.com",
    "phone": "11955554444",
    "status": "A",
    "internal_code": "GER-SUL-01",
    "ec_user_level": "1",
    "manager_discount_limit": "5.00",
    "users": ["3dc023ca-3746-4b6e-8afd-686a4a9af99f"],
    "users_count": 1,
    "orders_count": 0,
    "notify": "Y",
    "credit_balance": "0.00",
    "company_id": "",
    "company_name": "",
    "timestamp": 1791752276
  },
  "success": true,
  "message": ""
}

POST/api/v1.0/managersAdmin

Criar um gerente de vendas

Corpo da requisição

namestringobrigatório

Nome completo. Separado em nome e sobrenome pelo primeiro espaço.

emailstringobrigatório

E-mail de login. Precisa estar livre.

phonestringobrigatório

Telefone.

statusstringobrigatório

AD

Status inicial.

password1stringobrigatório

Senha.

password2stringobrigatório

Confirmação da senha. Diferente de password1: 400 error_passwords_dont_match.

company_idstring

Id do seller dono do gerente. 0 ou omitido, sem seller.

internal_codestring

Código no ERP.

manager_discount_limitstring

Desconto máximo em percentual ("5" ou "7.5").

ec_user_levelinteger

Nível hierárquico.

usersstring

Carteira: ids de clientes em lista (["uuid", "uuid"]) ou texto separado por vírgula.

200Gerente criado

json

{ "manager_id": 30, "message": "" }

Exemplo de requisição (criar)

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/managers" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Paula Ribeiro",
    "email": "ana.ribeiro@example.com",
    "phone": "11955554444",
    "status": "A",
    "password1": "Troque-Esta-Senha-9!",
    "password2": "Troque-Esta-Senha-9!",
    "internal_code": "GER-SUL-01",
    "manager_discount_limit": "5",
    "ec_user_level": 1
  }'

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

Atualizar um gerente de vendas

Parâmetros de caminho

idstringobrigatório

manager_id, inteiro.

Corpo da requisição

namestring

Nome.

emailstring

E-mail do gerente (o login do usuário não é alterado).

phonestring

Telefone.

statusstring

AD

Só A ativa; qualquer outro valor desativa, inclusive a palavra active. Mande sempre a letra.

company_idstring

Seller dono do gerente.

internal_codestring

Código no ERP.

manager_discount_limitstring

Desconto máximo, em percentual.

ec_user_levelinteger

Nível hierárquico.

usersstring

Nova carteira completa (lista ou texto com vírgulas). Omita para não mexer.

password1string

Se enviada, deve ser igual a password2. Não altera a senha.

password2string

Confirmação.

200Gerente alterado

json

{ "manager_id": 30, "message": "" }

DELETE/api/v1.0/managers/{id}Admin

Excluir um gerente de vendas (não suportado)

Não exclui. Responde sempre 404 com Delete not supported for managers, como o módulo original. Para desligar um gerente, use PUT com status: "D".

Parâmetros de caminho

idstringobrigatório

manager_id.

404Não suportado

json

{ "message": "Delete not supported for managers", "status": 404 }

Erros

Status	Quando	Corpo
200	Falta um campo obrigatório ao criar (não é erro HTTP)	`{"message":"email is required"}`
400	`password1` diferente de `password2`	`{"message":"error_passwords_dont_match","status":400}`
400	Corpo que não é JSON	`{"message":"Invalid JSON body","status":400}`
400	`id` que não é inteiro	`{"message":"invalid manager_id","status":400}`
400	E-mail já em uso, ao criar	`{"message":"email already registered","status":400}`
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	`DELETE`	`{"message":"Delete not supported for managers","status":404}`