Documentação da API REST

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

Base URL

/public/api

Prefixo das rotas: /api/… · JSON em request e response · Headers: Accept: application/json · POST: Content-Type: application/json

Autenticação

Integrações (Premium): 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).

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

Rotas por módulo / tela do sistema

Pessoas

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

Método	Rota	Descrição
GET		Lista / busca clientes
GET		Veículos do cliente
POST		Cadastra veículo (JSON: `cliente_id`, `placa`, `modelo`, `ano`)

Produtos

Tela Produtos (/produtos).

Método	Rota	Descrição
GET		Busca produtos (nome, código interno ou barras)

Relatórios · Pedidos

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

Método	Rota	Descrição
GET		Lista pedidos/OS/orçamentos. Query: `de`, `ate`; opcional `tipo`, `situacao`/`status`, `busca`/`q`/`cliente` (nome ou Nº do documento). Itens trazem entrega, cancelamento e meta fiscal.

Response

{
  "items": [
    {
      "id": 1257,
      "cliente_id": 1,
      "data": "2026-05-01 10:00:00",
      "tipo": "os",
      "tipo_documento": 2,
      "status": "em_atendimento",
      "status_label": "Em atendimento",
      "total": 350.0,
      "faturado": 0,
      "gera_financeiro": false,
      "gera_estoque": false,
      "gera_nf": false,
      "origem_pedido_id": null,
      "faturamento_status": "editavel",
      "faturamento_status_label": "Editável",
      "data_entrega": null,
      "observacao_entrega": null,
      "motivo_cancelamento": null,
      "cancelado_em": null,
      "nota_fiscal_status": "sem_nota",
      "nota_fiscal_label": "Sem nota",
      "pode_faturar_standby": false,
      "pode_encerrar_faturamento": false,
      "cliente_nome": "Cliente Mock"
    }
  ]
}

PDV / OS

Tela PDV / OS (/pdv) — montagem, itens, fechamento e pós-venda.

Carrinho e atendimento

Método	Rota	Descrição
GET		Estado do carrinho, pagamentos, formas, naturezas, limites fiscais, `pdv_config`, `desconto_manual`, `desconto_cupom` e `cupom`
GET		Naturezas de operação permitidas no PDV (MEI incluído)
POST		Define cliente no carrinho (`cliente_id`)
POST		Define veículo no PDV (`veiculo_id`)
POST		Campos extras do pedido (JSON `campos`)
POST		Seleciona registro de campos do cliente
POST		Grava registro de campos personalizados
POST		Adiciona item (`produto_id`, `qtd`)
POST		Altera item: `index`; opcional `qtd`, `desconto`/`desconto_modo`, `nome`, `valor_unitario`
POST		Remove item (`index`)
POST		Desconto manual: `desconto`, `desconto_modo` (`reais`\|`percent`) — independente do cupom
POST		Aplica cupom de desconto (`codigo`; opcional `cpf_destinatario`). Resposta = carrinho atualizado
POST		Remove cupom do carrinho (body vazio `{}`). Resposta = carrinho atualizado
POST		Limpa o carrinho
POST		Remove pagamento do pedido em edição (`pagamento_id`)

Abrir / duplicar documento

Método	Rota	Descrição
POST		Carrega pedido no carrinho (`pedido_id`)
POST		Igual a carregar; use `intencao: "faturar"` para documentos concluídos com fat. pendente
POST		Duplica pedido (`pedido_id`)

Fechamento

Método	Rota	Descrição
POST		Finaliza pedido/OS/orçamento — ver detalhe abaixo

POST pdv/finalizar — corpo JSON

Conclusão / faturamento

pedido_id — ao editar documento já aberto (evita duplicar se a sessão perder o vínculo)
faturado — emite faturamento (com ou sem nota)
concluir — conclui com faturamento pendente
concluir_sem_nota — conclui sem emitir nota
concluir_pag_pendente — conclui com pagamento pendente
data_prevista_cobranca — opcional, YYYY-MM-DD
acao_orcamento_aprovado — ao aprovar orçamento: manter | pedido | os

Fiscal

modo_fiscal: auto | somente_nfse | servico | produto
servico = todos os itens na NFS-e; somente_nfse = só serviços; produto = somente NF-e
faturar_sem_emissao, natureza_operacao_id, nota_referencia_id

Pagamento

Único: forma, valor_recebido, parcelas (cartão)
Vários: pagamentos[] com forma, valor, troco, parcelas, conta_financeira_id

Resposta: fiscal, nfse, nfe, pagamentos, fiscal_limites_mes, empresa (quando aplicável).

Request

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

Response

{
  "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 },
  "fiscal_limites_mes": { "nfe": { "limite": 50, "usado": 4, "restante": 46 } }
}

Entrega e cancelamento

Método	Rota	Descrição
POST		Registra entrega (`pedido_id`, `data_entrega` YYYY-MM-DD, opcional `observacao_entrega`)
GET		Opções disponíveis (estornos, NF, PIN, mínimo do motivo) — consulte antes de cancelar
POST		Cancela documento — ver detalhe abaixo

POST pdv/cancelar — corpo JSON

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

Resposta: status, motivo_cancelamento, cancelado_em, efeitos.

Request

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

Response

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

Request

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

Response

{
  "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
  }
}

Documento público (e-mail / link)

Método	Rota	Descrição
GET / POST		Meta do pedido (link público, logo, limites fiscais). POST com `pedido_id`
POST		Envia link do documento por e-mail (`pedido_id`; renova se expirado)
POST		Revoga link público (`pedido_id`)
POST		Gera novo link (invalida o anterior) e envia e-mail se houver endereço

Fiscal

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

Método	Rota	Descrição
GET		Uso e limites mensais NF-e, NFS-e e NFC-e do plano
POST		Encerra fat. pendente sem emitir nota. Body: `pedido_id` ou `pedido_ids[]`; `modo` `conclusao`\|`cancelamento`; `motivo` se cancelamento

Empresa · Plano

Contexto em Minha empresa / plano ativo (também usado pelo PDV e integrações).

Método	Rota	Descrição
GET		Empresa (nome, logo, regime), plano, módulos habilitados e limites fiscais do mês

Response

{
  "ok": true,
  "empresa": { "id": 1, "nome": "Oficina Mock LTDA", "regime_fiscal": "mei" },
  "plano": "premium",
  "integracao": { "modulo_fiscal": true, "api_bearer": true },
  "fiscal_limites_mes": {
    "nfe": { "limite": 50, "usado": 3, "restante": 47 }
  }
}

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.

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`).

Documentação da API REST

Pessoas

Produtos

Relatórios · Pedidos

Exemplo — GET pedidos/buscar

PDV / OS

Carrinho e atendimento

Abrir / duplicar documento

Fechamento

Exemplo — POST pdv/finalizar

Entrega e cancelamento

Exemplo — POST pdv/marcar-entregue

Exemplo — POST pdv/cancelar

Documento público (e-mail / link)

Fiscal

Empresa · Plano

Exemplo — GET empresa/contexto