Item Service

Gerencia operações relacionadas aos itens de pedidos, permitindo cadastro, atualização completa e atualização parcial.

Visão Geral

O ItemService é responsável por:

• Cadastrar novos itens em pedidos
• Atualizar itens existentes completamente
• Atualizar itens parcialmente (PATCH)
• Gerenciar informações de produtos, preços e quantidades
• Controlar valores de descontos e impostos

Os itens representam os produtos dentro de um pedido, contendo informações de quantidade, preços, descontos e impostos.

Localização: services/item/item.service.ts

Endpoints Utilizados

Base URL

Todos os endpoints são relativos à base URL configurada em services/api.service.ts

Métodos

registerItem(data)

Cadastra um novo item em um pedido.

Endpoint: POST /item

Parâmetros:

type ItemRegisterSchema = {
  idCabecalhoPedido: string;
  idProduto: string;
  idUnidadeMedida: string;
  idLocal: string;
  idTabelaPreco: string;
  idExterno?: string | null;
  sequenciaDigitacao: string;
  controle: string;
  quantidade: number;
  precoBase: number;
  vlrUnit: number;
  vlrTot: number;
  vlrDesc: number;
  percDesc: number;
  vlrIpi: number;
  vlrRst: number;
};

Body: JSON com dados do item

Retorno:

Promise<ItemResponseSchema>;

Exemplo de uso:

import { itemServiceInstance } from "@/services/item/item.service.instance";

const newItem = await itemServiceInstance.registerItem({
  idCabecalhoPedido: "order-123",
  idProduto: "prod-456",
  idUnidadeMedida: "un-789",
  idLocal: "local-001",
  idTabelaPreco: "tab-001",
  sequenciaDigitacao: "1",
  controle: "controle-001",
  quantidade: 10,
  precoBase: 50.0,
  vlrUnit: 50.0,
  vlrTot: 500.0,
  vlrDesc: 50.0,
  percDesc: 10,
  vlrIpi: 10.0,
  vlrRst: 0,
});

console.log("Item criado:", newItem.id);

Tratamento de erros:

• Lança Error se o status da resposta não for 2xx
• Mensagem: ItemService.registerItem failed: {status}

---

updateItem(itemId, data)

Atualiza completamente um item existente.

Endpoint: PUT /item/{itemId}

Parâmetros:

• itemId (string): ID do item a ser atualizado
• data (ItemRegisterSchema): Dados completos do item

Body: JSON com todos os dados do item

Retorno:

Promise<ItemResponseSchema>;

Exemplo de uso:

const updatedItem = await itemServiceInstance.updateItem("item-123", {
  idCabecalhoPedido: "order-123",
  idProduto: "prod-456",
  idUnidadeMedida: "un-789",
  idLocal: "local-001",
  idTabelaPreco: "tab-001",
  sequenciaDigitacao: "1",
  controle: "controle-001",
  quantidade: 15,
  precoBase: 50.0,
  vlrUnit: 50.0,
  vlrTot: 750.0,
  vlrDesc: 0,
  percDesc: 0,
  vlrIpi: 15.0,
  vlrRst: 0,
});

Tratamento de erros:

• Lança Error se o status da resposta não for 2xx
• Mensagem: ItemService.updateItem failed: {status}

---

updatePartialItem(itemId, data)

Atualiza parcialmente um item existente (apenas campos especificados).

Endpoint: PATCH /item/{itemId}

Parâmetros:

• itemId (string): ID do item a ser atualizado
• data (Partial<ItemRegisterSchema>): Dados parciais do item

Body: JSON com apenas os campos a serem atualizados

Retorno:

Promise<ItemResponseSchema>;

Exemplo de uso:

// Atualizar apenas quantidade
const updated = await itemServiceInstance.updatePartialItem("item-123", {
  quantidade: 20,
});

// Atualizar quantidade e desconto
const updated2 = await itemServiceInstance.updatePartialItem("item-456", {
  quantidade: 5,
  vlrDesc: 25.0,
  percDesc: 5,
});

Tratamento de erros:

• Lança Error se o status da resposta não for 2xx
• Mensagem: ItemService.updatePartialItem failed: {status}

---

deleteItem(itemId)

Deleta um item específico.

Endpoint: DELETE /item/{itemId}

Parâmetros:

• itemId (string): ID do item a ser deletado

Retorno:

Promise<void>;

Exemplo de uso:

// Deletar item
await itemServiceInstance.deleteItem("item-123");
console.log("Item deletado com sucesso");

Tratamento de erros:

• Lança Error se o status da resposta não for 2xx
• Mensagem: ItemService.deleteItem failed: {status}

---

Estruturas de Dados

Interface ItemRegisterSchema

interface ItemRegisterSchema {
  idCabecalhoPedido: string;
  idProduto: string;
  idUnidadeMedida: string;
  idLocal: string;
  idTabelaPreco: string;
  idExterno?: string | null;
  sequenciaDigitacao: string;
  controle: string;
  quantidade: number;
  precoBase: number;
  vlrUnit: number;
  vlrTot: number;
  vlrDesc: number;
  percDesc: number;
  vlrIpi: number;
  vlrRst: number;
}

Interface ItemResponseSchema

interface ItemResponseSchema {
  id: string;
  idProduto: string;
  idUnidadeMedida: string;
  idOrderHeader: string;
  idExternoProd: string | null;
  idTabelaPreco: string;
  idLocal: string;
  nomeProduto: string;
  descricaoProduto: string;
  pesoLiquidoProd: number;
  pesoBrutoProd: number;
  nomeUnidadeMedida: string;
  nomeTabelaPreco: string;
  nomeLocal: string;
  quantidade: number;
  precobase: number;
  valorUnit: number;
  valorTotal: number;
  vlrDesc: number;
  percDesc: number;
  vlrIpi: number;
  vlrRst: number;
}

---

Casos de Uso

Adicionar Item a um Pedido

async function addItemToOrder(
  orderId: string,
  productId: string,
  quantity: number,
) {
  const item = await itemServiceInstance.registerItem({
    idCabecalhoPedido: orderId,
    idProduto: productId,
    idUnidadeMedida: "un-001",
    idLocal: "local-001",
    idTabelaPreco: "tab-001",
    sequenciaDigitacao: "1",
    controle: "ctrl-001",
    quantidade: quantity,
    precoBase: 100.0,
    vlrUnit: 100.0,
    vlrTot: 100.0 * quantity,
    vlrDesc: 0,
    percDesc: 0,
    vlrIpi: 0,
    vlrRst: 0,
  });

  console.log(`Item ${item.id} adicionado ao pedido`);
  return item;
}

Atualizar Quantidade de Item

async function updateItemQuantity(itemId: string, newQuantity: number) {
  const updated = await itemServiceInstance.updatePartialItem(itemId, {
    quantidade: newQuantity,
  });

  console.log(`Quantidade atualizada para ${updated.quantidade}`);
  return updated;
}

Aplicar Desconto a Item

async function applyDiscount(
  itemId: string,
  discountPercent: number,
  discountValue: number,
) {
  const updated = await itemServiceInstance.updatePartialItem(itemId, {
    percDesc: discountPercent,
    vlrDesc: discountValue,
  });

  console.log(`Desconto de ${discountPercent}% aplicado`);
  return updated;
}

---

Testes

Localização

services/item/item.service.test.ts

Executar Testes

# Teste específico do serviço
npx jest services/item/item.service.test.ts

# Modo watch
npx jest services/item/item.service.test.ts --watch

# Com coverage
npx jest services/item/item.service.test.ts --coverage

Casos de Teste

• ✅ registerItem: cadastro de item com sucesso
• ✅ registerItem: tratamento de erros para status não-2xx
• ✅ updateItem: atualização completa de item
• ✅ updateItem: tratamento de erros para status não-2xx
• ✅ updatePartialItem: atualização parcial de item
• ✅ updatePartialItem: tratamento de erros para status não-2xx
• ✅ deleteItem: deleção de item
• ✅ deleteItem: tratamento de erros para status não-2xx

---

Mocks

Localização

__mocks__/item.mock.ts

Dados Disponíveis

Mock com exemplo de item:

• Payload de cadastro/atualização
• Dados de produto, quantidade e valores
• Informações de desconto e impostos

Exemplo de uso em testes:

import { itemPayloadMock } from "@/__mocks__/item.mock";

// Mock registerItem
const apiWithoutAccessToken: any = {
  post: jest.fn(async () => ({
    status: 201,
    data: { id: "123", ...itemPayloadMock },
  })),
};

const service = new ItemService({ apiWithoutAccessToken });
const result = await service.registerItem(itemPayloadMock);

expect(result).toEqual({ id: "123", ...itemPayloadMock });

---