Itens e Insumos

A API de itens e insumos disponibiliza métodos eficientes para gerenciar o inventário de itens e insumos da empresa, incorporando recursos avançados de filtragem e pesquisa detalhada. Essas funcionalidades aprimoram a gestão dos dados, apoiando decisões mais informadas sobre controle de estoque e disponibilidade.

Introdução

Nesta documentação, detalhamos os campos que você pode esperar manipular ao interagir com a API. Cada campo é descrito para esclarecer sua função e o tipo de dado esperado, como informações técnicas, valores, estoque e fornecedores, garantindo que você possa fornecer ou obter informações precisas.

As URLs da API são especificadas para cada operação possível, desde a listagem de todos os equipamentos até a criação de novos registros. Ao seguir as URLs e métodos HTTP detalhados, você será capaz de realizar operações de forma intuitiva e eficaz.

Veja abaixo:

URLs

Método	URL	Ação	Descrição
GET	/api/v1/equipment	Listar	Lista todos os itens e insumos
GET	/api/v1/equipment/{id}	Visualizar	Exibe um determinado item/insumo pelo ID
POST	/api/v1/equipment	Criar	Cria um novo item/insumo

Campos

Abaixo estão os campos disponíveis na API:

Campo	Tipo	Descrição	Obrigatório
categoria	integer	ID da categoria	Sim
nome	string	Nome do item/insumo	Sim
medida_em_estoque	integer	ID da unidade de medida	Sim
total_em_estoque	decimal	Quantidade em estoque	Sim
codigo	string	Código do item/insumo	Sim
ncm	string	Código NCM (Nomenclatura Comum do Mercosul)	Não
marca	string	Marca do item/insumo	Não
modelo	string	Modelo do item/insumo	Não
item_de_composicao	integer	Item de composição (0 ou 1)	Não
valor_da_reposicao	decimal	Valor de reposição	Não
valor_de_custo	decimal	Valor de custo	Não
valor_da_venda	decimal	Valor de venda	Não
modelo_estoque	string	Modelo de controle de estoque	Não
lembrete_estoque_minimo	decimal	Quantidade mínima para lembrete	Não
descricao	text	Descrição detalhada	Não
fornecedores	array	Array de IDs dos fornecedores	Não

Listar

Endpoint: /api/v1/equipment

Método: GET

Retorna uma lista de todos os itens e insumos. Suporta busca e paginação para gerenciar grandes volumes de dados.

Filtros Específicos

Além das funcionalidades básicas, oferecemos filtros específicos para itens e insumos:

Parâmetros:

• idcategoria: Filtra itens e insumos por categoria específica

Exemplo de Uso: Para filtrar itens e insumos de uma categoria específica: /api/v1/equipment?idcategoria=5

Ordenação

Para melhorar a experiência de visualização dos dados, oferecemos suporte à ordenação de registros. Você pode especificar a ordenação dos dados através de dois parâmetros:

Parâmetros:

• sort: Define a direção da ordenação. Valores permitidos: asc para ascendente, desc para descendente.
• field_sort: Especifica o campo pelo qual os registros devem ser ordenados, você pode consultar os campos disponíveis clicando aqui.

Exemplo de Uso: Para ordenar os itens e insumos pelo nome em ordem ascendente: /api/v1/equipment?field_sort=nome&sort=asc

Paginação

A paginação é essencial para o gerenciamento eficiente dos dados, especialmente quando lidamos com grandes volumes. Cada página pode conter um número definido de registros, reduzindo o tempo de carregamento e melhorando a usabilidade.

Parâmetro:

• page: Número da página desejada.
• limit (opcional): Número de registros por página, o limite é de até 200 registros.

Exemplo de Uso: Para acessar a segunda página de registros: /api/v1/equipment?page=2&limit=10

Buscar

Nossa API oferece buscas detalhadas no cadastro de itens e insumos, permitindo a fácil localização de registros específicos. A busca é realizada nos campos listados na tabela abaixo, otimizando o processo de consulta sem necessidade de especificar os campos manualmente.

Parâmetro:

• search: Valor a ser pesquisado.

Tipos de Busca:

• Campos Pesquisados: Nome, Código, Marca

Exemplo de Uso: Para buscar itens e insumos pelos campos acima: /api/v1/equipment?search=Cadeira

Resumo

Utilizar as funcionalidades de Filtros, Ordenação, Paginação e Buscar em conjunto permite uma manipulação eficiente e precisa dos dados na nossa API. Por exemplo, para listar itens e insumos de uma categoria específica, buscando por nome, ordenados pelo código, e exibir apenas os primeiros 10 resultados, você pode usar a seguinte URL:

/api/v1/equipment?idcategoria=5&search=Cadeira&field_sort=codigo&sort=asc&page=1&limit=10

Response:

{
  "data": [
    {
      "id": "1",
      "categoria": "5",
      "nome": "Cadeira Plástica Branca",
      "medida_em_estoque": "1",
      "total_em_estoque": "100",
      "codigo": "CAD001",
      "ncm": "94011000",
      "marca": "Tramontina",
      "modelo": "Modelo Standard",
      "item_de_composicao": "0",
      "valor_da_reposicao": "25.00",
      "valor_de_custo": "20.00",
      "valor_da_venda": "30.00",
      "modelo_estoque": "notificar",
      "lembrete_estoque_minimo": "10",
      "descricao": "Cadeira plástica resistente, ideal para eventos"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 200,
    "total_page": 1,
    "total_data": 1
  }
}

Visualizar

Endpoint: /api/v1/equipment/{id}

Método: GET

Para visualizar as informações de um item/insumo, você pode fazer uma solicitação GET para endpoint acima. Não é necessário fornecer informações no corpo da solicitação, já que você estará apenas recuperando dados. O ID do item/insumo a ser consultado deve ser especificado no endpoint.

Response:

{
  "id": "1",
  "categoria": "5",
  "nome": "Cadeira Plástica Branca",
  "medida_em_estoque": "1",
  "total_em_estoque": "100",
  "codigo": "CAD001",
  "ncm": "94011000",
  "marca": "Tramontina",
  "modelo": "Modelo Standard",
  "item_de_composicao": "0",
  "valor_da_reposicao": "25.00",
  "valor_de_custo": "20.00",
  "valor_da_venda": "30.00",
  "modelo_estoque": "notificar",
  "lembrete_estoque_minimo": "10",
  "descricao": "Cadeira plástica resistente, ideal para eventos"
}

Criar

Endpoint: /api/v1/equipment

Método: POST

Para criar um novo item/insumo, você deve fazer uma solicitação POST para o endpoint acima. Os dados devem ser enviados no corpo da requisição em formato JSON.

Campos Obrigatórios:

• nome: Nome do item/insumo
• codigo: Código único do item/insumo
• categoria: ID da categoria
• medida_em_estoque: ID da unidade de medida
• total_em_estoque: Quantidade em estoque

Campos Opcionais:

• ncm: Código NCM
• marca: Marca do item/insumo
• modelo: Modelo do item/insumo
• item_de_composicao: Item de composição (0 ou 1)
• valor_da_reposicao: Valor de reposição (formato: "25.00" ou "25,00")
• valor_de_custo: Valor de custo
• valor_da_venda: Valor de venda
• modelo_estoque: Tipo de controle de estoque ("", "aoinserir", "aposevento", "notificar")
• lembrete_estoque_minimo: Quantidade mínima para lembrete
• descricao: Descrição detalhada
• fornecedores: Array de IDs dos fornecedores

Exemplo de Requisição:

{
  "nome": "Mesa Redonda 1,60m",
  "codigo": "MES001",
  "categoria": 3,
  "medida_em_estoque": 1,
  "total_em_estoque": 50,
  "ncm": "94036000",
  "marca": "Móveis & Cia",
  "modelo": "Premium",
  "item_de_composicao": 0,
  "valor_da_reposicao": "120,00",
  "valor_de_custo": 80.00,
  "valor_da_venda": 150.00,
  "modelo_estoque": "notificar",
  "lembrete_estoque_minimo": 5,
  "descricao": "Mesa redonda de 1,60m para 8 pessoas",
  "fornecedores": [10, 15, 22]
}

Response de Sucesso:

{
  "status": "success",
  "message": "Item/insumo cadastrado com sucesso.",
  "data": {
    "id": "25",
    "categoria": "3",
    "nome": "Mesa Redonda 1,60m",
    "medida_em_estoque": "1",
    "total_em_estoque": "50",
    "codigo": "MES001",
    "ncm": "94036000",
    "marca": "Móveis & Cia",
    "modelo": "Premium",
    "item_de_composicao": "0",
    "valor_da_reposicao": "120.00",
    "valor_de_custo": "80",
    "valor_da_venda": "150",
    "modelo_estoque": "notificar",
    "lembrete_estoque_minimo": "5",
    "descricao": "Mesa redonda de 1,60m para 8 pessoas"
  }
}

Observações:

• A API verifica se a categoria e medida existem antes de criar o item/insumo
• Valores de modelo_estoque aceitos: vazio, "aoinserir", "aposevento", "notificar"