GET - Consulta de Faturamento

Este método retorna os itens faturados dentro de um período de emissão, um registro para cada item de nota fiscal, com a quantidade, o valor, as bases de cálculo dos impostos e a classificação fiscal do item. Quando o item vendido tem ficha técnica cadastrada, o registro traz também a relação dos componentes que formam esse item.

A consulta é feita sempre na filial conectada ao serviço e considera apenas notas de produto. Notas de serviço, complementares, avulsas, de devolução e de entrada não entram no resultado, assim como notas canceladas e estornadas.

/api/comercial/faturamento?dataEmissaoInicial=2026-01-01&dataEmissaoFinal=2026-01-31

Exemplo URL

localhost:8090/api/comercial/faturamento?dataEmissaoInicial=2026-01-01&dataEmissaoFinal=2026-01-31&codigoCliente=10001

Parâmetros do Header

auth	Token adquirido no Login.

Parâmetros (Query)

Nome	Tipo	Obrigatório	Descrição
dataEmissaoInicial	String (yyyy-MM-dd)	Sim	Data inicial de emissão das notas.
dataEmissaoFinal	String (yyyy-MM-dd)	Sim	Data final de emissão das notas.
codigoCliente	Inteiro	Não	Código interno do cliente. Sem ele, retorna todos os clientes.
codigoItem	Inteiro	Não	Código interno do item. Sem ele, retorna todos os itens.
codigoClasseTipo	Inteiro	Não	Classe/tipo do item. Sem ele, retorna todas as classes.

As duas datas são obrigatórias. Se faltar uma delas, ou se o formato estiver inválido, a requisição é recusada com 400. Não há limite para o tamanho do período.

Campos do Retorno

Cada registro da lista dados traz:

Campo	Tipo	Descrição
codigoEditavelItem	String	Código do item como o usuário o digita.
codigoInternoItem	Inteiro	Código interno do item.
descricaoItem	String	Descrição do item.
unidadeMedida	String	Unidade de medida do item.
codigoCliente	Inteiro	Código interno do cliente.
descricaoCliente	String	Nome do cliente.
quantidadeFaturada	Decimal	Quantidade faturada do item na nota.
precoBrutoTotal	Decimal	Valor total bruto do item na nota.
dataEmissao	Data	Data de emissão da nota.
serieNF	String	Série da nota fiscal.
numeroNF	Inteiro	Número da nota fiscal.
sequenciaItem	Inteiro	Sequência do item dentro da nota.
codigoCFOP	Inteiro	CFOP da operação.
descricaoCFOP	String	Descrição do CFOP.
codigoClasse / descricaoClasse	Inteiro / String	Classe do item.
codigoTipo / descricaoTipo	Inteiro / String	Tipo do item.
classificacaoTributaria	String	Classificação tributária de IBS/CBS.
baseICMS, baseICMSST, baseIPI, basePIS, baseCOFINS	Decimal	Bases de cálculo dos impostos.
valorICMS, valorICMSST, valorIPI, valorPIS, valorCOFINS, valorCBS	Decimal	Valores dos impostos.
componentes	Lista	Componentes da ficha técnica do item. Vazia quando o item não tem ficha técnica.

Componentes

Campo	Tipo	Descrição
codigoEditavelComponente	String	Código do componente como o usuário o digita.
codigoInternoComponente	Inteiro	Código interno do componente.
descricaoComponente	String	Descrição do componente.
unidadeMedida	String	Unidade de medida do componente.
nivel	Inteiro	Nível do componente dentro da ficha técnica.
sequenciaEstrutura	Inteiro	Sequência do componente na ficha técnica.
quantidadeNecessaria	Decimal	Quantidade do componente para uma unidade do item.
ultimoNivel	Booleano	Indica que o componente não se desdobra em outros.
custoUnitario	Decimal	Custo unitário do componente.
custoMaterial	Decimal	Custo do componente na quantidade necessária.

Exemplos de Retorno

Sucesso

{
  "bemSucedido": true,
  "dados": [
    {
      "codigoEditavelItem": "PA-1020",
      "codigoInternoItem": 3041,
      "unidadeMedida": "PC",
      "descricaoItem": "CONJUNTO MONTADO 1020",
      "codigoCliente": 10001,
      "descricaoCliente": "TESTE TECNOLOGIA LTDA",
      "quantidadeFaturada": 10.0,
      "precoBrutoTotal": 2500.00,
      "baseCOFINS": 2500.00,
      "basePIS": 2500.00,
      "baseICMS": 2500.00,
      "baseICMSST": 0.0,
      "baseIPI": 2500.00,
      "valorCBS": 0.0,
      "codigoCFOP": 5101,
      "descricaoCFOP": "VENDA DE PRODUCAO DO ESTABELECIMENTO",
      "codigoClasse": 1,
      "codigoTipo": 10,
      "descricaoClasse": "PRODUTO ACABADO",
      "descricaoTipo": "CONJUNTOS",
      "dataEmissao": "2026-01-15T00:00:00-03:00",
      "classificacaoTributaria": "000001",
      "valorPIS": 41.25,
      "valorCOFINS": 190.00,
      "valorIPI": 125.00,
      "valorICMS": 300.00,
      "valorICMSST": 0.0,
      "serieNF": "1",
      "numeroNF": 45877,
      "sequenciaItem": 1,
      "componentes": [
        {
          "codigoEditavelComponente": "MP-3001",
          "codigoInternoComponente": 1204,
          "descricaoComponente": "CHAPA ACO 2MM",
          "unidadeMedida": "KG",
          "nivel": 1,
          "sequenciaEstrutura": 1,
          "quantidadeNecessaria": 2.5,
          "ultimoNivel": true,
          "custoUnitario": 0.0,
          "custoMaterial": 0.0
        }
      ]
    }
  ]
}

Data inválida ou ausente

Retorna 400 com a mensagem de erro:

{
  "bemSucedido": false,
  "mensagemFalha": "A data de emissão inicial ou final foi informada de forma inválida (formato yyyy-MM-dd)."
}

Falha no processamento

Retorna 500 com o detalhamento da falha em mensagemFalha. A ocorrência fica registrada no log de integrações do ERP.