Consultando NF-e, itens e impostos pela API

A consulta completa de uma Nota Fiscal Eletrônica de produto (NF-e) utiliza três recursos da API FoxManager: o cabeçalho da nota, seus itens e os impostos calculados em cada item.

Antes de começar

Esta consulta exige autenticação. Consulte o artigo API FoxManager: Guia Completo de Integração com Swagger para aprender a obter o token e autorizar o acesso.

Endpoints utilizados

Etapa	Método	Endpoint	Finalidade
1	GET	/api/fox/nfe/	Listar e localizar a NF-e.
1	GET	/api/fox/nfe/{id}/	Consultar uma NF-e pelo identificador.
2	GET	/api/fox/nfe_item/?nfe={id}	Consultar os itens da NF-e.
2	GET	/api/fox/nfe_item/{id}/	Consultar um item pelo identificador.
3	GET	/api/fox/nfe_item_imposto/?nfe_item={id}	Consultar os impostos de um item.

Esses endpoints são somente para consulta e não alteram informações no FoxManager.

Empresa consultada

A empresa é definida automaticamente pelo token. Cada token permite consultar somente os dados da empresa à qual ele está associado.

O parâmetro company pode aparecer no Swagger, mas não é necessário informá-lo na URL. Para consultar outra empresa, use um token gerado para ela.

Segurança do token

Não coloque o token em documentos públicos, código-fonte, planilhas compartilhadas ou capturas de tela.

Etapa 1: consultar a NF-e

Listar notas

GET https://api.foxmanager.com.br/api/fox/nfe/?entrada_saida=1&limit=50
Authorization: Token SEU_TOKEN

Consultar pelo identificador

GET https://api.foxmanager.com.br/api/fox/nfe/67890/
Authorization: Token SEU_TOKEN

Filtros da listagem

Parâmetro	Obrigatório	Descrição	Exemplo
entrada_saida	Não	Tipo da nota: 0 para entrada ou 1 para saída.	1
ordering	Não	Campo usado para ordenar o resultado.	-issue_date
limit	Não	Quantidade por página. Padrão 500 e máximo 1000.	50
offset	Não	Posição inicial da página.	0

Campos da NF-e

Campo	Tipo	Descrição
id	Inteiro	Identificador interno da NF-e.
url	URI	Endereço da NF-e na API.
code	Inteiro ou nulo	Código interno no FoxManager.
created_at	Data	Data de cadastro.
issue_date	Data ou nulo	Data de emissão.
cancel_date	Data ou nulo	Data de cancelamento.
status	Texto	Situação: A aberta, F fechada ou C cancelada.
number	Texto	Número da NF-e.
serie	Texto	Série da NF-e.
total	Decimal ou nulo	Valor total.
protocolo	Texto	Protocolo de autorização.
chave_acesso	Texto	Chave de acesso da NF-e.
entrada_saida	Texto	0 para entrada ou 1 para saída.
company	URI	Empresa relacionada.
fiscal_operation	URI	Operação fiscal.
user_issued	URI ou nulo	Usuário responsável pela emissão.
person	URI ou nulo	Cliente ou fornecedor.
person_address	URI ou nulo	Endereço da pessoa.
person_seller	URI	Vendedor relacionado.

Etapa 2: consultar os itens da NF-e

O parâmetro nfe é obrigatório e recebe o identificador interno obtido na etapa anterior.

GET https://api.foxmanager.com.br/api/fox/nfe_item/?nfe=67890
Authorization: Token SEU_TOKEN

Parâmetros

Parâmetro	Obrigatório	Descrição	Exemplo
nfe	Sim	Identificador interno da NF-e.	67890
ordering	Não	Campo usado para ordenar o resultado. O padrão é -id.	id
limit	Não	Quantidade por página. Padrão 500 e máximo 1000.	100
offset	Não	Posição inicial da página.	0

Campos do item

Campo	Tipo	Descrição
id	Inteiro	Identificador interno do item.
url	URI	Endereço do item na API.
serial_number	Texto	Número de série relacionado ao item.
quantity	Decimal ou nulo	Quantidade.
unit_price	Decimal ou nulo	Valor unitário.
total_amount	Decimal ou nulo	Valor total do item.
nfe	URI	NF-e relacionada.
item	URI	Produto relacionado.
cfop	URI ou nulo	CFOP relacionado.
company	URI	Empresa relacionada.

O número final da URI do item será utilizado como nfe_item na consulta de impostos:

https://api.foxmanager.com.br/api/fox/nfe_item/98765/

Nesse exemplo, o identificador do item é 98765.

Etapa 3: consultar os impostos do item

O parâmetro nfe_item é obrigatório.

GET https://api.foxmanager.com.br/api/fox/nfe_item_imposto/?nfe_item=98765
Authorization: Token SEU_TOKEN

Parâmetros

Parâmetro	Obrigatório	Descrição	Exemplo
nfe_item	Sim	Identificador interno do item da NF-e.	98765
ordering	Não	Campo usado para ordenar o resultado. O padrão é -nfe_item.	tax
limit	Não	Quantidade por página. Padrão 500 e máximo 1000.	100
offset	Não	Posição inicial da página.	0

Exemplo de resposta

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 10001,
      "url": "https://api.foxmanager.com.br/api/fox/nfe_item_imposto/10001/",
      "tax": "CBS",
      "calculation_basis": 100.00,
      "aliquot": 0.90,
      "value": 0.90,
      "nfe_item": "https://api.foxmanager.com.br/api/fox/nfe_item/98765/",
      "company": "https://api.foxmanager.com.br/api/fox/company/100/"
    },
    {
      "id": 10002,
      "url": "https://api.foxmanager.com.br/api/fox/nfe_item_imposto/10002/",
      "tax": "IBS ESTADUAL",
      "calculation_basis": 100.00,
      "aliquot": 0.10,
      "value": 0.10,
      "nfe_item": "https://api.foxmanager.com.br/api/fox/nfe_item/98765/",
      "company": "https://api.foxmanager.com.br/api/fox/company/100/"
    },
    {
      "id": 10003,
      "url": "https://api.foxmanager.com.br/api/fox/nfe_item_imposto/10003/",
      "tax": "IBS MUNICIPAL",
      "calculation_basis": 100.00,
      "aliquot": 0.00,
      "value": 0.00,
      "nfe_item": "https://api.foxmanager.com.br/api/fox/nfe_item/98765/",
      "company": "https://api.foxmanager.com.br/api/fox/company/100/"
    }
  ]
}

Os identificadores, valores, alíquotas e URIs são apenas exemplos.

Campos do imposto

Campo	Tipo	Descrição
id	Inteiro	Identificador técnico do registro. Não deve ser usado como referência permanente.
url	URI	Endereço do imposto na API.
tax	Texto	Categoria do imposto.
calculation_basis	Decimal	Base de cálculo.
aliquot	Decimal	Alíquota aplicada.
value	Decimal	Valor calculado.
nfe_item	URI	Item da NF-e relacionado.
company	URI	Empresa relacionada.

IBS e CBS

O endpoint retorna todos os impostos vinculados ao item, não apenas os tributos da Reforma Tributária. Para identificar IBS e CBS, verifique o campo tax:

Valor	Imposto
CBS	Contribuição sobre Bens e Serviços.
IBS ESTADUAL	Parcela estadual do Imposto sobre Bens e Serviços.
IBS MUNICIPAL	Parcela municipal do Imposto sobre Bens e Serviços.

Um imposto pode ser retornado com alíquota ou valor zero quando estiver vinculado dessa forma ao item no FoxManager.

Paginação e resposta vazia

As listagens retornam count, next, previous e results. Quando não houver registros para os filtros informados, results será uma lista vazia.

Códigos de resposta

Código	Significado
200	Consulta realizada.
400	Parâmetro obrigatório ausente ou inválido.
401	Token ausente, inválido ou expirado.
403	Usuário sem permissão para o recurso.
404	Registro não encontrado.
500	Erro inesperado. Se persistir, contate o suporte técnico.

Boas práticas

• Siga a sequência NF-e, itens e impostos.
• Utilize o identificador interno, e não o número impresso da nota.
• Use fields quando precisar somente de alguns campos.
• Não use o id do imposto como vínculo permanente em outro sistema.
• Trate valores e alíquotas como números decimais.