Consultando NFS-e, itens e impostos pela API

A consulta completa de uma Nota Fiscal de Serviço Eletrônica (NFS-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/nfse/	Listar e localizar a NFS-e.
1	GET	/api/fox/nfse/{id}/	Consultar uma NFS-e pelo identificador.
2	GET	/api/fox/nfse_item/?nfse={id}	Consultar os itens da NFS-e.
2	GET	/api/fox/nfse_item/{id}/	Consultar um item pelo identificador.
3	GET	/api/fox/nfse_item_imposto/?nfse_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 NFS-e

Listar notas

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

Filtrar pelo código ou número

GET https://api.foxmanager.com.br/api/fox/nfse/?code=12345
Authorization: Token SEU_TOKEN

GET https://api.foxmanager.com.br/api/fox/nfse/?number=9876
Authorization: Token SEU_TOKEN

Consultar pelo identificador

GET https://api.foxmanager.com.br/api/fox/nfse/54321/
Authorization: Token SEU_TOKEN

Filtros da listagem

Parâmetro	Obrigatório	Descrição	Exemplo
entrada_saida	Não	Tipo da nota: E para entrada ou S para saída.	S
code	Não	Código interno da NFS-e no FoxManager.	12345
number	Não	Número da NFS-e.	9876
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 NFS-e

Campo	Tipo	Descrição
id	Inteiro	Identificador interno da NFS-e.
url	URI	Endereço da NFS-e na API.
code	Inteiro ou nulo	Código interno no FoxManager.
created_at	Data e hora	Data e hora de cadastro.
issue_date	Data e hora ou nulo	Data e hora de emissão.
cancel_date	Data e hora ou nulo	Data e hora de cancelamento.
status	Texto	Situação: A aberta, F fechada ou C cancelada.
number	Texto	Número da NFS-e.
total	Decimal ou nulo	Valor total.
iss	Decimal ou nulo	Valor do ISS.
verification_code	Texto	Código de verificação.
entrada_saida	Texto	E para entrada ou S para saída.
company	URI	Empresa relacionada.
fiscal_operation	URI	Operação fiscal.
user_created	URI	Usuário responsável pelo cadastro.
user_issued	URI ou nulo	Usuário responsável pela emissão.
user_canceled	URI ou nulo	Usuário responsável pelo cancelamento.
person	URI ou nulo	Tomador relacionado.
person_address	URI ou nulo	Endereço do tomador.
person_seller	URI	Vendedor ou agência relacionada.
contract	URI	Contrato relacionado.

Etapa 2: consultar os itens da NFS-e

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

GET https://api.foxmanager.com.br/api/fox/nfse_item/?nfse=54321
Authorization: Token SEU_TOKEN

Parâmetros

Parâmetro	Obrigatório	Descrição	Exemplo
nfse	Sim	Identificador interno da NFS-e.	54321
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.
service_description	Texto	Descrição do serviço.
quantity	Decimal ou nulo	Quantidade.
unit_price	Decimal ou nulo	Valor unitário.
total_amount	Decimal ou nulo	Valor total do item.
nfse	URI	NFS-e relacionada.
item	URI	Serviço relacionado.
company	URI	Empresa relacionada.

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

https://api.foxmanager.com.br/api/fox/nfse_item/45678/

Nesse exemplo, o identificador do item é 45678.

Etapa 3: consultar os impostos do item

O parâmetro nfse_item é obrigatório.

GET https://api.foxmanager.com.br/api/fox/nfse_item_imposto/?nfse_item=45678
Authorization: Token SEU_TOKEN

Parâmetros

Parâmetro	Obrigatório	Descrição	Exemplo
nfse_item	Sim	Identificador interno do item da NFS-e.	45678
ordering	Não	Campo usado para ordenar o resultado. O padrão é -nfse_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": 20001,
      "url": "https://api.foxmanager.com.br/api/fox/nfse_item_imposto/20001/",
      "tax": "CBS",
      "calculation_basis": 250.00,
      "aliquot": 0.90,
      "value": 2.25,
      "nfse_item": "https://api.foxmanager.com.br/api/fox/nfse_item/45678/",
      "company": "https://api.foxmanager.com.br/api/fox/company/100/"
    },
    {
      "id": 20002,
      "url": "https://api.foxmanager.com.br/api/fox/nfse_item_imposto/20002/",
      "tax": "IBS ESTADUAL",
      "calculation_basis": 250.00,
      "aliquot": 0.10,
      "value": 0.25,
      "nfse_item": "https://api.foxmanager.com.br/api/fox/nfse_item/45678/",
      "company": "https://api.foxmanager.com.br/api/fox/company/100/"
    },
    {
      "id": 20003,
      "url": "https://api.foxmanager.com.br/api/fox/nfse_item_imposto/20003/",
      "tax": "IBS MUNICIPAL",
      "calculation_basis": 250.00,
      "aliquot": 0.00,
      "value": 0.00,
      "nfse_item": "https://api.foxmanager.com.br/api/fox/nfse_item/45678/",
      "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.
nfse_item	URI	Item da NFS-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 NFS-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.