Usuários (REST)

Os endpoints de Usuários gerenciam as contas de usuário da plataforma Venddor. Um usuário é uma pessoa que entra na loja, seja como administrador, seja como cliente. Você usa esses endpoints quando um sistema externo, como um ERP ou um CRM, precisa criar, ler, alterar ou remover contas sem que ninguém abra o painel administrativo.

Todos eles fazem parte da API REST genérica: o mesmo prefixo /api e as mesmas credenciais HTTP Basic (e-mail:chave_de_api de um administrador) do restante da Referência completa. Se você só precisa cadastrar um varejista que compra de um fornecedor, o Guia rápido tem um caminho mais curto, descrito em Clientes.

Como funciona

A API de Usuários permite criar contas, consultar informações de usuários, atualizar dados, gerenciar permissões e acessos e atribuir usuários a grupos.

1. Crie o usuário

   Envie POST /api/users com os dados da conta. Os campos obrigatórios estão em Campos de usuário.

2. Leia de volta

   Use GET /api/users/{id} para uma conta ou GET /api/users para uma página de contas. A lista é paginada, veja Paginação.

3. Altere ou remova

   Use PUT /api/users/{id} para alterar campos e DELETE /api/users/{id} para remover a conta.

4. Coloque em um grupo

   A participação em grupos é tratada pelos endpoints em /api/users/{id}/usergroups. Veja Usuários e grupos.

Status do usuário

O campo status do usuário recebe um destes códigos.

Conceitos-chave

Tipo de usuário

user_type é A para administrador e C para cliente. Nos administradores, is_root indica se a conta é de administrador raiz (Y) ou não (N). Ao criar um administrador, defina user_type como A e escolha is_root de acordo com o nível de permissões que quer conceder.

A loja a que o usuário pertence

company_id é o ID da loja ou do vendedor a que o usuário pertence. Se você omitir o campo, vale o ID da empresa padrão.

Senhas

O campo password leva o hash MD5 da senha, e não a senha em si. Ele só é usado ao criar e ao atualizar um usuário. Nunca envie a senha em texto puro. Para trocar uma senha, use o endpoint próprio de redefinição de senha, que é mais seguro.

Campos desconhecidos

Um campo que não está na tabela de campos é ignorado quando você o inclui em uma requisição.

Endpoints

Erros comuns

• Enviar a senha em texto puro. O campo espera o hash MD5.
• Enviar o usuário inteiro no PUT como se fosse uma substituição. Só os campos enviados mudam.
• Reutilizar na atualização um e-mail que já pertence a outra conta. A API responde 409 Conflict.
• Enviar campos que não estão na tabela e esperar que sejam salvos. Eles são ignorados.
• Chamar os endpoints com um usuário sem permissão para gerenciar usuários. A resposta é 403 Forbidden.
• Tratar page como começando em zero. As páginas começam em 1.

Próximos passos