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, inclusive as de devolução. Notas de serviço, complementares, avulsas e de entrada não entram no resultado, assim como notas canceladas e estornadas. Para trazer só as vendas, sem remessas, comodatos e devoluções, use o parâmetro somenteVenda.

/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&somenteVenda=true

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. Não pode ser usado junto com o codigoClasseTipo.
codigoClasseTipo	Inteiro	Não	Classe ou classe/tipo do item. Até 9999, é a classe inteira: 1111 traz todos os tipos da classe 1111. A partir de 10000, é a classe/tipo exata, a classe seguida do tipo com 4 dígitos: 11110001 traz só o tipo 1 da classe 1111. Sem ele, retorna todas as classes.
somenteVenda	Booleano (true ou false)	Não	Com true, traz só os itens de natureza de operação de venda e de Zona Franca, sem remessas, comodatos e devoluções. Sem ele, ou com false, traz todas as notas de produto.

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.

Os filtros opcionais também recusam a requisição com 400 quando o código não existe no cadastro, quando o valor não está no formato da tabela e quando o codigoItem e o codigoClasseTipo vêm juntos. Filtro enviado em branco (codigoCliente=) é desconsiderado.

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: 1 para os componentes diretos do item, 2 para os componentes deles, e assim por diante.
sequenciaEstrutura	Inteiro	Sequência do componente na ficha técnica. Vem 0 quando a estrutura não tem a sequência gravada.
quantidadeNecessaria	Decimal	Quantidade do componente para uma unidade do item.
ultimoNivel	Booleano	true quando o componente não tem ficha técnica abaixo dele, ou seja, é o fim daquele ramo da estrutura.
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
        }
      ]
    }
  ]
}

Requisição inválida

Retorna 400 com o motivo em mensagemFalha:

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

As outras mensagens de 400:

Situação	Mensagem
Filtro em formato inválido	O parâmetro codigoItem foi informado de forma inválida: deve ser um número inteiro.
somenteVenda diferente de true e false	O parâmetro somenteVenda foi informado de forma inválida: deve ser true ou false.
Cliente fora do cadastro	O cliente 10001 não existe.
Item fora do cadastro	O item 3041 não existe.
Classe ou classe/tipo fora do cadastro	A classe/tipo 1111 não existe.
codigoItem e codigoClasseTipo juntos	Informe o item ou a classe/tipo, não os dois.

Token ausente ou inválido

Retorna 401. Faça o Login de novo e envie o token devolvido, inteiro, no header auth.

Falha no processamento

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