Pré-vendas e ordens de serviço pela API

O endpoint order permite consultar, cadastrar e atualizar o cabeçalho de pré-vendas e ordens de serviço do FoxManager.

Os itens e a prévia de pagamento são mantidos em endpoints próprios. Por isso, uma integração completa normalmente utiliza:

order: dados principais da pré-venda ou ordem de serviço;
order_item: produtos e serviços vinculados;
order_payment_preview: parcelas e valores da prévia de pagamento.

Antes de começar

Esta integração exige autenticação e permissões compatíveis com as operações utilizadas. Consulte o artigo API FoxManager: Guia Completo de Integração com Swagger para aprender a obter o token e autorizar o acesso.

Endpoints disponíveis

Método	Endpoint	Finalidade
`GET`	`/api/fox/order/`	Listar pré-vendas e ordens de serviço.
`POST`	`/api/fox/order/`	Cadastrar um registro.
`GET`	`/api/fox/order/{id}/`	Consultar um registro pelo identificador.
`PUT`	`/api/fox/order/{id}/`	Atualizar integralmente um registro.

O endpoint não oferece exclusão por DELETE.

Pré-venda ou ordem de serviço

O campo product_or_service identifica o tipo do registro:

Valor	Tipo
`P`	Produto. Utilizado principalmente no fluxo de pré-venda de produtos.
`S`	Serviço. Utilizado no fluxo de ordem de serviço.

O endpoint não possui um filtro específico para product_or_service. A integração deve verificar esse campo nos registros retornados.

Empresa consultada

Nas consultas, a empresa é definida pelo usuário associado ao token. Mesmo que o Swagger apresente o parâmetro company, a API restringe a listagem à empresa do usuário autenticado.

No cadastro, o campo company faz parte do corpo da requisição e recebe a URI da empresa.

Segurança do token

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

Parâmetros de consulta

Parâmetro	Obrigatório	Descrição	Exemplo
`contract`	Não	Identificador interno do contrato relacionado.	`1234`
`legacy_code`	Não	Código utilizado por um sistema externo. A correspondência é exata.	`OS-2026-001`
`ordering`	Não	Campo usado para ordenar o resultado. O padrão é `-id`.	`-date`
`limit`	Não	Quantidade por página. O padrão é 500 e o máximo é 1000.	`100`
`offset`	Não	Posição inicial da página. O padrão é zero.	`0`

O parâmetro company também aparece no Swagger, mas a empresa da consulta é definida pelo token.

Não existem filtros próprios para número de série, cliente, vendedor, status, período ou tipo de registro nesse endpoint.

Consulta básica

GET https://api.foxmanager.com.br/api/fox/order/?limit=100&offset=0
Authorization: Token SEU_TOKEN

Consultar pelo identificador

GET https://api.foxmanager.com.br/api/fox/order/12345/
Authorization: Token SEU_TOKEN

Filtrar pelo código legado

GET https://api.foxmanager.com.br/api/fox/order/?legacy_code=OS-2026-001
Authorization: Token SEU_TOKEN

Filtrar pelo contrato

GET https://api.foxmanager.com.br/api/fox/order/?contract=1234
Authorization: Token SEU_TOKEN

Estrutura da listagem

A listagem é paginada:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 12345,
      "url": "https://api.foxmanager.com.br/api/fox/order/12345/",
      "total_value": 850.0,
      "date": "2026-09-05T10:30:00-04:00",
      "initial_period_date": "2026-09-05",
      "final_period_date": "2026-09-10",
      "expiration_date": null,
      "total_discount": 0.0,
      "status": "A",
      "percent_discount": 0.0,
      "movement_stock": false,
      "note": "Instalação do equipamento",
      "note_document_service": null,
      "note_document_product": null,
      "order_code": 9876,
      "product_or_service": "S",
      "legacy_code": "OS-2026-001",
      "serial_number": "SERIE-000123",
      "company": "https://api.foxmanager.com.br/api/fox/company/100/",
      "salesman": "https://api.foxmanager.com.br/api/fox/person/200/",
      "condition_payment": "https://api.foxmanager.com.br/api/fox/condition_payment/10/",
      "person": "https://api.foxmanager.com.br/api/fox/person/300/",
      "contract": null
    }
  ]
}

Os identificadores e valores apresentados são apenas exemplos.

Campos retornados e aceitos

Campo	Tipo	Obrigatório no cadastro	Descrição
`id`	Inteiro	Gerado	Identificador interno do registro.
`url`	URI	Gerado	Endereço do registro na API.
`total_value`	Número	Sim	Valor total da pré-venda ou ordem de serviço.
`date`	Data e hora	Sim	Data e hora de cadastro.
`initial_period_date`	Data	Sim	Data inicial do prazo de entrega ou execução.
`final_period_date`	Data ou nulo	Não	Data final do prazo de entrega ou execução.
`expiration_date`	Data e hora ou nulo	Não	Data e hora de expiração da pré-venda.
`total_discount`	Número	Sim	Valor total do desconto.
`status`	Texto	Sim	Situação atual do registro.
`percent_discount`	Número ou nulo	Não	Percentual de desconto.
`movement_stock`	Booleano	Não	Indicador interno de movimentação de estoque.
`note`	Texto ou nulo	Não	Observação geral.
`note_document_service`	Texto ou nulo	Não	Observação destinada ao documento fiscal de serviço.
`note_document_product`	Texto ou nulo	Não	Observação destinada ao documento fiscal de produto.
`order_code`	Inteiro ou nulo	Não	Código da pré-venda ou ordem de serviço no FoxManager.
`product_or_service`	Texto	Sim	Tipo do registro: `P` para produto ou `S` para serviço.
`legacy_code`	Texto ou nulo	Não	Código do registro em sistema externo. Aceita até 64 caracteres.
`serial_number`	Texto ou nulo	Não	Número de série associado à ordem. Aceita até 100 caracteres.
`company`	URI	Sim	Empresa relacionada ao registro.
`salesman`	URI	Sim	Vendedor responsável.
`condition_payment`	URI ou nulo	Não	Condição de pagamento.
`person`	URI ou nulo	Não	Cliente relacionado.
`contract`	URI ou nulo	Não	Contrato relacionado.

Os campos id e url são somente para leitura e não devem ser enviados no cadastro.

Situações do registro

Valor	Situação
`A`	Aberto.
`C`	Cancelado.
`F`	Fechado.
`P`	Pendente.
`V`	Pré-ordem.
`R`	Reservado.

Valor V

O valor V faz parte do contrato da API, embora a descrição resumida do campo no Swagger possa não apresentá-lo junto aos demais valores.

Número de série

O campo serial_number corresponde ao número de série apresentado na ordem de serviço.

{
  "serial_number": "SERIE-000123"
}

Quando a ordem não possuir número de série, o campo poderá ser null:

{
  "serial_number": null
}

O campo aceita até 100 caracteres e não é um parâmetro de filtro. Para localizar uma ordem por número de série, a integração precisa percorrer os resultados disponíveis ou manter essa referência em sua própria base.

Relacionamentos por URI

Os campos relacionados recebem a URI completa do respectivo cadastro:

Campo	Endpoint relacionado
`company`	`/api/fox/company/{id}/`
`salesman`	`/api/fox/person/{id}/`
`person`	`/api/fox/person/{id}/`
`condition_payment`	`/api/fox/condition_payment/{id}/`
`contract`	`/api/fox/contract/{id}/`

Antes de cadastrar uma ordem, consulte os endpoints relacionados para obter as URIs válidas.

Exemplo de cadastro de pré-venda

POST https://api.foxmanager.com.br/api/fox/order/
Authorization: Token SEU_TOKEN
Content-Type: application/json

{
  "total_value": 1500.0,
  "date": "2026-09-05T10:30:00-04:00",
  "initial_period_date": "2026-09-05",
  "final_period_date": null,
  "expiration_date": "2026-09-15T23:59:59-04:00",
  "total_discount": 50.0,
  "status": "A",
  "percent_discount": 3.33,
  "movement_stock": false,
  "note": "Proposta válida até a data de expiração",
  "note_document_service": null,
  "note_document_product": null,
  "order_code": null,
  "product_or_service": "P",
  "legacy_code": "PV-EXTERNA-001",
  "serial_number": null,
  "company": "https://api.foxmanager.com.br/api/fox/company/100/",
  "salesman": "https://api.foxmanager.com.br/api/fox/person/200/",
  "condition_payment": "https://api.foxmanager.com.br/api/fox/condition_payment/10/",
  "person": "https://api.foxmanager.com.br/api/fox/person/300/",
  "contract": null
}

Exemplo de cadastro de ordem de serviço

POST https://api.foxmanager.com.br/api/fox/order/
Authorization: Token SEU_TOKEN
Content-Type: application/json

{
  "total_value": 850.0,
  "date": "2026-09-05T10:30:00-04:00",
  "initial_period_date": "2026-09-05",
  "final_period_date": "2026-09-10",
  "expiration_date": null,
  "total_discount": 0.0,
  "status": "A",
  "percent_discount": 0.0,
  "movement_stock": false,
  "note": "Instalação do equipamento",
  "note_document_service": "Informações complementares para a NFS-e",
  "note_document_product": null,
  "order_code": null,
  "product_or_service": "S",
  "legacy_code": "OS-2026-001",
  "serial_number": "SERIE-000123",
  "company": "https://api.foxmanager.com.br/api/fox/company/100/",
  "salesman": "https://api.foxmanager.com.br/api/fox/person/200/",
  "condition_payment": "https://api.foxmanager.com.br/api/fox/condition_payment/10/",
  "person": "https://api.foxmanager.com.br/api/fox/person/300/",
  "contract": null
}

Atualizar um registro

O método PUT substitui os dados do registro. Envie novamente todos os campos obrigatórios, mesmo que apenas um valor tenha sido alterado.

PUT https://api.foxmanager.com.br/api/fox/order/12345/
Authorization: Token SEU_TOKEN
Content-Type: application/json

Para evitar perda de informações:

consulte o registro atual com GET;
altere somente os valores necessários em sua aplicação;
envie o objeto completo com PUT;
confira a resposta retornada pela API.

Itens da pré-venda ou ordem de serviço

Os produtos e serviços não são retornados dentro do objeto order. Use o endpoint order_item e informe o identificador da ordem:

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

O parâmetro order é obrigatório nessa consulta.

Cada item possui os principais campos:

Campo	Descrição
`order`	URI da pré-venda ou ordem de serviço.
`company`	URI da empresa.
`product`	URI do produto ou serviço.
`unit_value`	Valor unitário.
`quantity`	Quantidade.
`discount`	Valor do desconto.
`total_value`	Valor total do item.
`percent_discount`	Percentual de desconto, quando informado.
`legacy_code`	Código do item no sistema externo.

Prévia de pagamento

Para consultar as parcelas e valores da prévia de pagamento, utilize:

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

O parâmetro order é obrigatório nessa consulta.

Funcionalidades que não pertencem ao endpoint

As telas do FoxManager oferecem operações adicionais, como aprovação, envio para venda, fechamento ou reabertura da ordem, geração de documentos fiscais, etapas, laudo técnico, solicitação de itens e histórico de eventos.

Essas operações não estão representadas pelos métodos publicados no endpoint order. Não considere que alterar apenas o campo status reproduz automaticamente os processos executados pelas telas do sistema.

Como percorrer todas as páginas

Faça a primeira consulta com offset=0.
Leia os registros do campo results.
Verifique o campo next.
Quando next contiver uma URI, consulte esse endereço.
Repita até next retornar null.

Paginação

O campo count informa o total de registros encontrados. O campo results contém somente os registros da página atual.

Respostas de erro mais comuns

Código	Significado	Como corrigir
`400`	Corpo ou parâmetro inválido.	Confira tipos, datas, campos obrigatórios e URIs relacionadas.
`401`	Token ausente ou inválido.	Confira o cabeçalho `Authorization` e utilize `Token` antes da chave.
`403`	Usuário sem permissão para a operação.	Solicite a revisão das permissões do usuário.
`404`	Registro ou URI relacionada não encontrada.	Confira o identificador e os endereços informados.
`500`	Erro inesperado no processamento.	Se persistir, entre em contato com o suporte do FoxManager.

Boas práticas

Utilize filtros e paginação para reduzir o volume retornado.
Percorra todas as páginas quando precisar de uma carga completa.
Trate campos opcionais como valores que podem retornar null.
Consulte as URIs relacionadas antes de cadastrar ou atualizar registros.
Use legacy_code para manter a correspondência com o sistema de origem.
Não tente localizar registros por serial_number diretamente, pois o campo não é um filtro.
Consulte order_item para obter os produtos e serviços vinculados.
Não altere status para simular ações funcionais que possuem regras próprias no FoxManager.
Não exponha o token em logs, exemplos, código-fonte ou arquivos compartilhados.

Documentações relacionadas

Para conferir o contrato técnico mais recente, consulte o Swagger da API FoxManager.

Endpoints disponíveis​

Pré-venda ou ordem de serviço​

Empresa consultada​

Parâmetros de consulta​

Consulta básica​

Consultar pelo identificador​

Filtrar pelo código legado​

Filtrar pelo contrato​

Estrutura da listagem​

Campos retornados e aceitos​

Situações do registro​

Número de série​

Relacionamentos por URI​

Exemplo de cadastro de pré-venda​

Exemplo de cadastro de ordem de serviço​

Atualizar um registro​

Itens da pré-venda ou ordem de serviço​

Prévia de pagamento​

Funcionalidades que não pertencem ao endpoint​

Como percorrer todas as páginas​

Respostas de erro mais comuns​

Boas práticas​

Documentações relacionadas​