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 o Swagger da API FoxManager.

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 ou ler dados sem alterá-los.
• POST (verde): criar registros.
• PUT ou PATCH (laranja): atualizar registros.
• DELETE (vermelho): remover registros.

Cada endpoint disponibiliza somente os métodos exibidos no Swagger. Nem todos permitem cadastro, atualização ou exclusão.

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, consulte os campos apresentados na seção Parameters. Somente os parâmetros publicados para aquele endpoint devem ser utilizados.

Os nomes e comportamentos dos filtros variam entre os endpoints. Não acrescente sufixos como __gte ou __lte quando eles não estiverem expressamente disponíveis no Swagger.

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: Como buscar as cinco notas fiscais mais recentes?

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
5. Clique no botão Execute.
6. Analise a resposta na seção "Responses" para ver os dados das 5 notas encontradas.

A empresa consultada é definida pelo usuário associado ao token. Embora alguns endpoints exibam company entre os parâmetros, a API pode preencher ou restringir esse valor automaticamente.

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 token pertence à empresa que você pretende consultar?
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?

• Confirme se o token pertence à empresa desejada. Quando o endpoint restringir a empresa automaticamente, não é necessário informar 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.

Otimizando a Resposta: Expand, Fields e Omit

P14: Como posso personalizar quais campos aparecem na minha resposta?

Para tornar as consultas mais rápidas e leves, você pode usar os parâmetros fields e omit. Eles controlam a "largura" dos dados retornados.

• fields: Use quando você quer receber apenas campos específicos. Separe os nomes por vírgula.
  • Exemplo: fields = id,name,code (A API retornará apenas esses três campos).
• omit: Use quando você quer todos os campos, exceto alguns que são muito grandes ou irrelevantes.
  • Exemplo: omit = observacao,logs (A API retornará tudo, menos as observações e logs).

P15: O que é o parâmetro expand e para que serve?

Por padrão, um relacionamento normalmente é retornado como uma URI para o registro relacionado. O parâmetro expand pode trazer os dados do relacionamento dentro da mesma resposta quando esse recurso estiver configurado para o endpoint.

• Sem expand: o campo relacionado retorna sua URI.
• Com expand: quando permitido, o campo relacionado retorna um objeto JSON.

Dica de Performance: Use o expand com moderação. Expandir muitos níveis de uma vez (ex: nota -> itens -> produto -> categoria) pode tornar a consulta lenta.

Nem todos os relacionamentos aceitam expand. Confira o comportamento do endpoint antes de depender desse parâmetro em uma integração.

P16: Posso combinar esses comandos?

Sim! É uma excelente prática. Você pode expandir um relacionamento e, ao mesmo tempo, filtrar quais campos quer ver tanto do objeto principal quanto do expandido.

• Exemplo prático:
  • expand = person
  • fields = id,issue_date,person.name,person.cpf_cnpj
  • Resultado: Você terá os dados da nota e apenas o nome e documento do cliente, sem carregar o endereço ou contatos desnecessários dele.

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
Token	Prefixo usado no cabeçalho de autenticação da API FoxManager
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
Omit	Oculta campos específicos da resposta JSON
Fields	Retorna apenas os campos selecionados
Expand	Traz dados completos de registros vinculados