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
PUT	/api/v1/equipment/`{id}`	Editar	Atualiza um item/insumo pelo ID

Campos

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

💡 Nota: o campo categoria retorna o ID da categoria. Para obter o nome, consulte GET /api/v1/categories, que lista o ID e o nome de todas as categorias de Itens e Insumos.

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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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"

Editar

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

Método: PUT

Atualiza parcialmente um item/insumo existente. O parâmetro {id} deve ser o ID numérico do item/insumo e o corpo da solicitação deve conter pelo menos um campo válido. Os campos que não forem enviados permanecem inalterados.

Campos aceitos

Todos os campos são opcionais, mas pelo menos um deve ser informado.

Campo	Tipo	Descrição
nome	string	Nome do item/insumo. Não pode ser vazio
codigo	string	Código do item/insumo. Não pode ser vazio
categoria	integer	ID de uma categoria de Itens e Insumos existente
medida_em_estoque	integer	ID de uma unidade de medida existente
total_em_estoque	decimal	Saldo em estoque, na mesma unidade retornada pelo GET. Aceita `0` e valores fracionados, mas não valores negativos
ncm	string	Código NCM
marca	string	Marca do item/insumo
modelo	string	Modelo do item/insumo
item_de_composicao	integer	Item de composição (`0` ou `1`)
valor_da_reposicao	string	Valor de reposição (formato: "25.00" ou "25,00"), igual ao cadastro
valor_de_custo	decimal	Valor de custo. Não aceita valores negativos
valor_da_venda	decimal	Valor de venda. Não aceita valores negativos
modelo_estoque	string	Tipo de controle de estoque ("", "aoinserir", "aposevento", "notificar")
lembrete_estoque_minimo	decimal	Quantidade mínima para lembrete. Não aceita valores negativos
descricao	string	Descrição detalhada

O campo total_em_estoque substitui o saldo atual pelo valor enviado: ele não soma nem subtrai da quantidade existente.

Exemplo de Requisição:

json

{
  "total_em_estoque": 42.5
}

Response de Sucesso:

json

{
  "status": "success",
  "message": "Equipamento atualizado com sucesso.",
  "data": {
    "id": "25",
    "categoria": "3",
    "nome": "Mesa Redonda 1,60m",
    "medida_em_estoque": "1",
    "total_em_estoque": "42.500",
    "codigo": "MES001",
    "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.000",
    "descricao": "Mesa redonda de 1,60m para 8 pessoas"
  }
}

Possíveis erros

Status HTTP	Situação
`400`	ID inválido, corpo sem campos válidos ou algum campo fora do formato aceito
`404`	Item/insumo, categoria de Itens e Insumos ou unidade de medida não encontrada
`500`	Erro interno ao executar a atualização

Itens e Insumos ​

Introdução ​

URLs ​

Campos ​

Listar ​

Filtros Específicos ​

Ordenação ​

Paginação ​

Buscar ​

Resumo ​

Visualizar ​

Criar ​

Editar ​

Campos aceitos ​

Possíveis erros ​

Itens e Insumos

Introdução

URLs

Campos

Listar

Filtros Específicos

Ordenação

Paginação

Buscar

Resumo

Visualizar

Criar

Editar

Campos aceitos

Possíveis erros