Documentação da API REST

Consulta pública das rotas. Autenticação nas integrações com Bearer (plano Prime).

Base URL

/public/api

Prefixo das rotas: /api/… · Métodos: GET e POST apenas (não há DELETE/PUT) · JSON em request e response · Headers: Accept: application/json · POST: Content-Type: application/json

Autenticação

Integrações (Prime): header Authorization: Bearer <token>
Sessão no navegador: cookie de login; POSTs exigem X-CSRF-Token quando não houver Bearer.

Erros no formato {"error":"…"} (opcionalmente message). Em GET clientes, dados pessoais seguem máscara LGPD conforme o perfil (token Bearer usa visão de integração).

Códigos HTTP

Código	Significado
200	Aceito — requisição OK (GET e POST bem-sucedidos retornam JSON com os dados; muitos POSTs incluem `ok: true`)
401	Não autorizado (sem sessão ou Bearer inválido)
403	Plano/permissão insuficiente (ex.: módulo fiscal)
404	Rota inexistente
405	Método HTTP não permitido na rota
422	Validação / regra de negócio
500	Erro interno

Documentação somente leitura. Para executar chamadas reais, abra o portal de testes.

Pessoas

Tela Pessoas (/clientes) e veículos do cadastro.

Implementation Notes

Busca clientes por texto ou placa. Resposta: id, nome, cpf_cnpj, telefones, cidade, preferências de pagamento; opcional placa_busca/veiculo_id_busca. Dados mascarados conforme LGPD (Bearer = visão integração).

HTTP: 200 401

Parameters

Parameter	Value	Description	Parameter Type	Data Type
`q`	`{joao`	Texto de busca (nome, documento ou placa).	`query`	`string` · {q}

Response Class (Status 200)

Example Value

{
  "items": [
    {
      "id": 1,
      "nome": "João Silva",
      "cpf_cnpj": "***.***.***-00",
      "telefone": "11999990000",
      "cidade": "São Paulo"
    }
  ]
}

Implementation Notes

Cadastra pessoa física ou jurídica. Campos principais: nome (ou nome_completo), tipo_pessoa (fisica|juridica), cpf_cnpj, telefone, whatsapp, email, endereço (cep, logradouro, numero, bairro, cidade, uf). PJ: razao_social, nome_fantasia. Sem DELETE na API — exclusões não estão expostas. Requer permissão clientes.criar (sessão) ou Bearer Prime.

HTTP: 200 401 403 422

Parameters — body

Parameter content type: application/json

Example Value

{"nome":"Maria Souza","tipo_pessoa":"fisica","cpf_cnpj":"529.982.247-25","telefone":"11988887777","email":"[email protected]","cidade":"São Paulo","uf":"SP"}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "cliente_id": 42,
  "item": { "id": 42, "nome": "Maria Souza", "cpf_cnpj": "529.982.247-25" }
}

Implementation Notes

Retorna veículos do cliente. Query obrigatória: cliente_id.

HTTP: 200 401 422

Parameters

Parameter	Value	Description	Parameter Type	Data Type
`cliente_id` *	`{1`	ID do cliente.	`query`	`integer` · {cliente_id}

Response Class (Status 200)

Example Value

{
  "items": [
    { "id": 10, "cliente_id": 1, "placa": "ABC1D23", "modelo": "Gol", "ano": 2018 }
  ]
}

Produtos

Tela Produtos (/produtos).

Implementation Notes

Busca por nome, código interno ou barras. Inclui preços, estoque, estoque_critico, sem_estoque, foto_url.

HTTP: 200 401

Parameters

Parameter	Value	Description	Parameter Type	Data Type
`q`	`{oleo`	Texto de busca.	`query`	`string` · {q}
`tipo_item`	`{produto`	Filtro: produto \| mao_obra \| hora_tecnica.	`query`	`string` · {tipo_item}

Response Class (Status 200)

Example Value

{
  "items": [
    {
      "id": 1,
      "nome": "Óleo 5W30",
      "preco": 45.9,
      "estoque": 12,
      "estoque_critico": false,
      "tipo_item": "produto"
    }
  ]
}

Implementation Notes

Cadastro essencial: nome (obrigatório), tipo_item (produto|mao_obra|hora_tecnica), preco ou preco_varejo, opcionais codigo_interno, codigo_barras, estoque, ativo, ncm, cest, cfop, estoque_critico. Sem DELETE na API. Requer produtos.criar (sessão) ou Bearer Prime.

HTTP: 200 401 403 422

Parameters — body

Parameter content type: application/json

Example Value

{"nome":"Óleo 5W30","tipo_item":"produto","preco":45.9,"codigo_interno":"OLEO5W30","estoque":10,"ativo":true}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "produto_id": 88,
  "nome": "Óleo 5W30",
  "tipo_item": "produto",
  "preco": 45.9
}

Relatórios · Pedidos

Listagem em Relatórios → Pedidos (/relatorios?tab=pedidos).

Implementation Notes

Lista documentos do período. Itens trazem entrega, cancelamento e meta fiscal.

HTTP: 200 401 422

Parameters

Parameter	Value	Description	Parameter Type	Data Type
`de` *	`{2026-01-01`	Data inicial (YYYY-MM-DD).	`query`	`string` · {de}
`ate` *	`{2026-12-31`	Data final (YYYY-MM-DD).	`query`	`string` · {ate}
`tipo`	`{os`	Filtro de tipo (ex.: os, pedido, orcamento).	`query`	`string` · {tipo}
`situacao`	`{pag_pendente`	Situação / status (ex.: pag_pendente).	`query`	`string` · {situacao}
`busca`	`{`	Busca por cliente / documento (aliases: q, cliente).	`query`	`string` · {busca}

Response Class (Status 200)

Example Value

{
  "items": [
    {
      "id": 1257,
      "cliente_id": 1,
      "data": "2026-05-01 10:00:00",
      "tipo": "os",
      "status": "em_atendimento",
      "status_label": "Em atendimento",
      "total": 350.0,
      "faturado": 0,
      "data_entrega": null,
      "motivo_cancelamento": null,
      "nota_fiscal_status": "sem_nota",
      "cliente_nome": "Cliente Mock"
    }
  ]
}

PDV / OS — Carrinho

Montagem do atendimento: cliente, itens, descontos e cupom.

PDV / OS — Criar / abrir

Criar OS/pedido, carregar, reabrir ou duplicar documento.

Implementation Notes

Cria um novo documento. Padrão: tipo=os (ordem de serviço). Também aceita pedido ou orcamento. Body: cliente_id, items[] (produto_id, qtd; preço/nome preenchidos do cadastro se omitidos), opcionais veiculo_id, observacao, motivo_entrada, data_inicio, data_fim, status (padrão aberto). Por padrão faturado=false (só grava). Para faturar na criação, envie faturado:true e pagamentos (como em pdv/finalizar). Requer plano com OS (para tipo os/orcamento) e permissão pdv.criar.

HTTP: 200 401 403 422

Parameters — body

Parameter content type: application/json

Example Value

{"cliente_id":1,"veiculo_id":null,"tipo":"os","status":"aberto","observacao":"Revisão 10 mil","items":[{"produto_id":1,"qtd":1},{"produto_id":2,"qtd":2,"valor_unitario":80}]}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "pedido_id": 1001,
  "tipo": "os",
  "status": "aberto",
  "total": 125.9,
  "faturado": false
}

PDV / OS — Fechamento

Finalização e faturamento do documento.

Implementation Notes

Finaliza pedido/OS/orçamento.

pedido_id — ao editar documento já aberto
faturado, concluir, concluir_sem_nota, concluir_pag_pendente
modo_fiscal: auto | somente_nfse | servico | produto
Pagamento único: forma, valor_recebido, parcelas
Vários: pagamentos[]

HTTP: 200 401 422

Parameters — body

Parameter content type: application/json

Example Value

{"cliente_id":1,"veiculo_id":null,"tipo":"pedido","status":"aberto","faturado":true,"concluir_pag_pendente":false,"modo_fiscal":"auto","forma":"cartao_credito","valor_recebido":91,"parcelas":3,"pagamentos":[{"forma":"cartao_credito","valor":91,"troco":0,"parcelas":3}]}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "pedido_id": 9999,
  "faturado": true,
  "total": 91.0,
  "status": "concluido_faturado",
  "status_label": "Concluído / faturado",
  "pagamentos": [{ "forma": "cartao_credito", "valor": 91.0, "parcelas": 3 }],
  "fiscal": { "modo": "auto", "faturar_sem_emissao": false }
}

PDV / OS — Entrega e cancelamento

Pós-venda: entrega e cancelamento com opções de estorno.

Implementation Notes

Registra entrega (pedido_id, data_entrega YYYY-MM-DD, opcional observacao_entrega).

HTTP: 200 401 422

Parameters — body

Parameter content type: application/json

Example Value

{"pedido_id":1,"data_entrega":"2026-07-15","observacao_entrega":"Entregue ao cliente"}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "pedido_id": 1,
  "data_entrega": "2026-07-15",
  "observacao_entrega": "Entregue ao cliente",
  "status": "concluido",
  "status_label": "Concluído"
}

Implementation Notes

Consulta estornos, NF e PIN disponíveis. Use antes de POST pdv/cancelar. Path efetivo: pdv/cancelar-opcoes?pedido_id={pedido_id}.

HTTP: 200 401 422

Parameters

Parameter	Value	Description	Parameter Type	Data Type
`pedido_id` *	`{1`	ID do pedido.	`query`	`integer` · {pedido_id}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "pedido_id": 1,
  "pode_estorno_financeiro": true,
  "pode_estorno_estoque": false,
  "pode_cancelar_nf": false,
  "exige_pin": false
}

Implementation Notes

Cancela documento.

pedido_id — obrigatório
motivo ou motivo_cancelamento — mínimo 5 caracteres
Opcionais: estorno_financeiro, estorno_estoque, cancelar_nf, pin_cancelamento

HTTP: 200 401 422

Parameters — body

Parameter content type: application/json

Example Value

{"pedido_id":1,"motivo":"Cliente desistiu do serviço","estorno_financeiro":true,"estorno_estoque":false,"cancelar_nf":false,"pin_cancelamento":""}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "pedido_id": 1,
  "status": "cancelado",
  "status_label": "Cancelado",
  "motivo_cancelamento": "Cliente desistiu do serviço",
  "cancelado_em": "2026-07-15 14:30:00",
  "efeitos": {
    "estorno_financeiro": true,
    "estorno_estoque": false,
    "cancelar_nf": false
  }
}

PDV / OS — Link / e-mail

Documento público: meta WhatsApp, e-mail e revogação/renovação de link.

Implementation Notes

Meta do pedido (link público, logo, limites fiscais) via query pedido_id.

HTTP: 200 401

Parameters

Parameter	Value	Description	Parameter Type	Data Type
`pedido_id` *	`{1`	ID do pedido.	`query`	`integer` · {pedido_id}

Response Class (Status 200)

Example Value

{
  "ok": true,
  "pedido_id": 1,
  "link_publico": "https://…",
  "expira_em": null
}

Fiscal

Módulo Fiscal (/fiscal) e encerramento de faturamento pendente.

Empresa · Plano

Contexto em Minha empresa / plano ativo.

Cookie	Duração	Descrição
`PHPSESSID`	até ~6 h	Identificador de sessão HTTP (PHP). Segurança, CSRF e estado da navegação. Expira em cerca de 6 horas ou no logout — não apenas ao fechar o navegador.
`oficina360_lgpd_consent`	12 meses	Registro do consentimento prestado quanto à Política de Cookies (HttpOnly), conforme LGPD.

Duração

Descrição

PHPSESSID

até ~6 h

Identificador de sessão HTTP (PHP). Segurança, CSRF e estado da navegação. Expira em cerca de 6 horas ou no logout — não apenas ao fechar o navegador.

oficina360_lgpd_consent

12 meses

Registro do consentimento prestado quanto à Política de Cookies (HttpOnly), conforme LGPD.

Chave	Duração	Descrição
`mecanicarSidebarDesktop`	persistente	Estado do menu lateral (expandido ou recolhido) na área autenticada.
`mecanicarValoresVisiveis`	persistente	Exibição ou mascaramento de valores monetários na interface.
`venda_pdv_perguntar_doc`	persistente	Preferência do PDV/venda rápida: se deve perguntar documento (CPF/CNPJ) ao abrir nova venda.
`pdv_kiosk`	aba / sessão	Modo kiosk/tela cheia do PDV nesta aba (`sessionStorage`); some ao fechar a aba.
`api-docs-tester-history`	aba / sessão	Histórico local de requisições no testador da documentação/portal da API (`sessionStorage`).

Chave

Duração

Descrição

mecanicarSidebarDesktop

persistente

Estado do menu lateral (expandido ou recolhido) na área autenticada.

mecanicarValoresVisiveis

persistente

Exibição ou mascaramento de valores monetários na interface.

venda_pdv_perguntar_doc

persistente

Preferência do PDV/venda rápida: se deve perguntar documento (CPF/CNPJ) ao abrir nova venda.

pdv_kiosk

aba / sessão

Modo kiosk/tela cheia do PDV nesta aba (sessionStorage); some ao fechar a aba.

api-docs-tester-history

aba / sessão

Histórico local de requisições no testador da documentação/portal da API (sessionStorage).