Pular para o conteúdo principal

API - Clientes

Documentação da API de gerenciamento de clientes.

Autenticação​

Todos os endpoints requerem autenticação JWT. Veja Autenticação.

Endpoints​

GET /clients​

Lista todos os clientes (paginação).

Query Parameters:

  • page: Número da página (padrão: 1)
  • limit: Itens por página (padrão: 10)
  • search: Busca por nome, CNPJ ou email
  • status: Filtro por status (ativo, inativo, bloqueado)
  • sortBy: Campo para ordenação
  • sortOrder: Ordem (asc, desc)

Response (200 OK):

{
  "data": [
    {
      "id": "uuid",
      "razaoSocial": "Empresa Exemplo LTDA",
      "nomeFantasia": "Exemplo",
      "cnpj": "12.345.678/0001-90",
      "email": "contato@exemplo.com",
      "status": "ativo",
      "dataCadastro": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

GET /clients/:id​

Busca um cliente específico por ID.

Response (200 OK):

{
  "id": "uuid",
  "razaoSocial": "Empresa Exemplo LTDA",
  "nomeFantasia": "Exemplo",
  "cnpj": "12.345.678/0001-90",
  "email": "contato@exemplo.com",
  "telefone": "(11) 1234-5678",
  "endereco": {
    "logradouro": "Rua Exemplo",
    "numero": "123",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234-567"
  },
  "status": "ativo",
  "setores": [],
  "tecnicos": []
}

POST /clients​

Cria um novo cliente.

Request Body:

{
  "razaoSocial": "Empresa Exemplo LTDA",
  "nomeFantasia": "Exemplo",
  "cnpj": "12.345.678/0001-90",
  "email": "contato@exemplo.com",
  "telefone": "(11) 1234-5678",
  "logradouro": "Rua Exemplo",
  "numero": "123",
  "bairro": "Centro",
  "cidade": "São Paulo",
  "uf": "SP",
  "cep": "01234-567",
  "status": "ativo"
}

Response (201 Created):

{
  "id": "uuid",
  "razaoSocial": "Empresa Exemplo LTDA",
  ...
}

PUT /clients/:id​

Atualiza um cliente existente.

Request Body: (mesmos campos do POST, todos opcionais)

Response (200 OK):

{
  "id": "uuid",
  "razaoSocial": "Empresa Exemplo LTDA Atualizada",
  ...
}

DELETE /clients/:id​

Remove um cliente (soft delete).

Response (204 No Content)

Permissões​

  • ADMIN: Acesso total
  • RESPONSAVEL_TECNICO: Apenas seus clientes vinculados
  • CLIENT: Apenas seus próprios dados

Validações​

  • CNPJ deve ser válido (validado via Receita Federal)
  • Email deve ser único
  • Campos obrigatórios: razaoSocial, nomeFantasia, cnpj, email, endereço completo

Próximos Endpoints​