API FoxManager: Guia Completo de Integração com Swagger

FAQ - API FoxManager com Swagger

Aqui estão as perguntas mais frequentes para ajudar você a se autenticar, realizar consultas e resolver problemas comuns ao usar a API do FoxManager.

Perguntas Gerais e Primeiros Passos

P1: O que é a API FoxManager e para que serve?

A API FoxManager é uma interface que permite que outros sistemas e desenvolvedores se conectem diretamente aos dados do seu ERP FoxManager. Ela serve para automatizar tarefas, criar integrações com plataformas de e-commerce e CRM, ou extrair dados para relatórios personalizados. Você irá interagir com ela através do Swagger, uma ferramenta visual que documenta e permite testar todas as funcionalidades da API.

P2: Como faço para me autenticar e começar a usar a API?

A autenticação é o primeiro e mais importante passo. Nenhuma consulta funcionará sem ela. O processo é feito em duas etapas:

Parte 1: Obter seu Token de Acesso no Sistema FoxManager

1. Acesse sua conta no sistema FoxManager ERP.

2. Clique em "Minha conta", localizado no menu do seu perfil.

3. No menu lateral esquerdo, clique na opção API.

4. Na nova tela, selecione a EMPRESA no menu suspenso para a qual o token será válido.

5. Clique no botão Obter Token.

6. O sistema irá gerar sua chave de acesso. Copie a linha inteira, que terá o formato Token <caracteres_alfanuméricos>.

   

Parte 2: Autorizar o Acesso no Swagger

1. Acesse a página da API: https://api.foxmanager.com.br/swagger/

2. No topo da tela, clique no grande botão verde Authorize.

   

3. Uma janela chamada "Available authorizations" irá aparecer. No campo Value, cole a chave completa que você copiou do sistema (Token ...).

   

4. Clique no botão Authorize (dentro da janela) e depois em Close.

   

5. Se tudo deu certo, o ícone de cadeado no botão principal "Authorize" ficará fechado, indicando que você está autenticado e pronto para fazer consultas.

Navegando e Realizando Consultas

P3: Como navego e entendo a interface do Swagger?

A interface é dividida em três partes principais:

• Grupos de Recursos: É a lista principal que organiza as operações por funcionalidade (ex: nfe, person, product).

• Endpoints (Operações): Dentro de cada grupo, você encontra as ações que pode realizar (buscar, criar, deletar). Ao clicar em uma, ela se expande.

• Painel de Detalhes: Mostra a documentação, os parâmetros para a consulta, exemplos de resposta e o botão "Try it out" para testar a operação diretamente no navegador.

  

P4: O que significam os métodos GET, POST, PUT e DELETE?

Cada método representa um tipo de ação:

• 🔵 GET (Azul): Buscar/ler dados (não altera nada)
• 🟢 POST (Verde): Criar novos registros
• 🟠 PUT/PATCH (Laranja): Atualizar registros existentes
• 🔴 DELETE (Vermelho): Remover registros

P5: Como funciona a paginação? O que são limit e offset?

Paginação é essencial para lidar com muitos dados sem sobrecarregar o sistema.

• limit: Define o número máximo de itens que você quer receber por página. É importante conhecer as seguintes regras para este parâmetro:
  • Limite Padrão: Se você não informar um valor, a API retornará 500 itens por padrão.
  • Limite Máximo: O valor máximo que pode ser informado é 1000.
  • Comportamento Acima do Limite: Se você solicitar um valor maior que 1000 (ex: limit=5000), a API ainda assim retornará no máximo 1000 registros na resposta.
• offset: Define a partir de qual item a busca deve começar. É usado para "pular" para as próximas páginas.

limit	offset	O que retorna	Uso típico
10	0	Itens 1 a 10	Primeira página
10	10	Itens 11 a 20	Segunda página
5	15	Itens 16 a 20	Pula 15 primeiros, mostra 5 seguintes
20	0	Itens 1 a 20	Página inicial, maior volume por página

P6: Como posso ordenar os resultados (ex: do mais novo para o mais antigo)?

Use o parâmetro ordering.

1. Preencha com o nome exato do campo que deseja usar para ordenar (ex: issue_date, created_at, total).
2. Para inverter a ordem (decrescente, do maior para o menor), adicione um sinal de menos (-) na frente do nome do campo.

• Exemplo 1 (do mais antigo para o mais novo): ordering = issue_date
• Exemplo 2 (do mais novo para o mais antigo): ordering = -issue_date

P7: Como faço para filtrar os resultados da minha busca?

Após clicar em "Try it out" em um endpoint GET, você verá vários campos na seção "Parameters". Preencha-os para filtrar sua busca.

• Filtros de Igualdade: status = F (busca status Fechado).
• Filtros de Faixa: Para buscar valores "maior ou igual que" ou "menor ou igual que", use a sintaxe __gte e __lte. Exemplo: total__gte = 500 (busca notas com total maior ou igual a 500).

Interpretando os Resultados

P8: Como eu leio a resposta (response) que a API me retorna?

Após executar uma consulta, a resposta aparece na seção "Responses".

1. Código de Status: Verifique o código HTTP. 200 OK significa sucesso. Códigos 4xx indicam um erro na sua requisição (veja a P10).
2. Corpo da Resposta (Response Body): Os dados vêm no formato JSON e têm a seguinte estrutura:
   • count: O número total de registros encontrados com seus filtros.
   • next: O link para a próxima página de resultados (ou null se não houver).
   • previous: O link para a página anterior.
   • results: Uma lista contendo os dados dos registros da página atual.

P9: Exemplo completo de como buscar as 5 notas fiscais mais recentes de uma empresa?

Passo a passo:

1. Autentique-se (P2).
2. Na lista de recursos, encontre e expanda o endpoint GET /nfe/.
3. Clique no botão Try it out.
4. Preencha os seguintes parâmetros:
   • limit: 5
   • ordering: -issue_date (o - traz as mais recentes primeiro)
   • entrada_saida: 1
   • company: 317
5. Clique no botão Execute.
6. Analise a resposta na seção "Responses" para ver os dados das 5 notas encontradas.

P10: Recebi um erro. O que significam os códigos mais comuns?

• 400 Bad Request: Requisição mal formatada. Verifique se você não digitou texto em um campo numérico ou usou um valor inválido.
• 401 Unauthorized: Erro de autenticação. Seu token está errado, expirou ou você não o informou no botão "Authorize". Volte para a P2.
• 403 Forbidden: Erro de permissão. Você está autenticado, mas seu usuário não tem permissão para acessar aquele dado específico.
• 404 Not Found: Recurso não encontrado. Geralmente acontece ao buscar um item com um ID que não existe (ex: /nfe/999999/).
• 500 Internal Server Error: Um erro inesperado no servidor da API. Se persistir, contate o suporte técnico.

P11: Por que minha consulta não retorna nenhum resultado, mesmo sem dar erro?

Verifique os seguintes pontos:

1. O company ID está correto? Este filtro é fundamental.
2. Seus filtros (datas, etc.) não estão restritivos demais? Tente remover alguns para testar.
3. O parâmetro offset não é maior que o número total de resultados? Tente com offset = 0.
4. Confirme se realmente existem dados no sistema que correspondem aos seus filtros.

P12: Quais são as melhores práticas para usar a API de forma eficiente?

• Sempre use o parâmetro company.
• Mantenha o limit entre 10 e 50 para respostas mais rápidas. Lembre-se que o valor padrão, caso não seja informado, é 500 e o máximo permitido por requisição é 1000.
• Use filtros sempre que possível para reduzir o volume de dados.
• Evite fazer muitas consultas ao mesmo tempo sem necessidade.

P13: Onde posso encontrar mais ajuda ou suporte?

• Questões de acesso e permissões: Fale com a Equipe Técnica interna.

• Problemas técnicos e erros persistentes: Contate o Suporte do FoxManager.

• Documentação Oficial: O link está disponível no cabeçalho da própria página do Swagger.

📚 Glossário Rápido

Termo	Significado
API	Interface de Programação de Aplicações
Endpoint	URL específica que responde a requisições
JSON	Formato de dados estruturado das respostas
Query Parameter	Parâmetro na URL para filtrar consultas
Token	Chave de autenticação para acesso
Status Code	Código numérico do resultado da requisição
HTTP	Protocolo de comunicação web
Swagger	Ferramenta visual para documentação de APIs
Bearer Token	Tipo de autenticação usado pela API
Offset	Posição inicial para recuperação de dados
Limit	Quantidade máxima de itens por consulta
Ordering	Parâmetro para ordenação dos resultados