API Oficina — Documentação

🔑

Autenticação

Toda requisição (exceto endpoints públicos) exige uma chave API de 64 caracteres

Método	Exemplo
Query string	`?api_key=SEU_TOKEN_64_CHARS`
Header HTTP	`X-API-Key: SEU_TOKEN_64_CHARS`

ℹ️ Respostas: 401 não autenticado · 403 sem permissão para o recurso

✅

auth.php

Valida uma chave e retorna permissões do agente

GET /auth.php?api_key=CHAVE

Exemplo cURL

curl -s ".../auth.php?api_key=CHAVE"

Resposta

{
  "status": "success",
  "nome_agente": "Agente WhatsApp",
  "permissoes": ["os", "clientes", "veiculos", "agendamentos"]
}

🔧

os.php — Ordens de Serviço

Busca por ID, placa ou CPF · 🔒 permissão: os

GET /os.php?api_key=CHAVE&os=345

Busca por ID

curl -s ".../os.php?api_key=CHAVE&os=345"

{
  "status": "success",
  "os": {
    "id": 345,
    "titulo_servico": "Revisão geral",
    "cliente": { ... },
    "veiculo": { ... },
    "financeiro": { ... }
  }
}

GET /os.php?api_key=CHAVE&placa=ABC1234

Busca por placa — retorna lista resumida de OS

curl -s ".../os.php?api_key=CHAVE&placa=ABC1234"

👤

clientes.php

Buscar e criar clientes · 🔒 permissão: clientes

GET /clientes.php?api_key=CHAVE&cpf=12345678900

{ "status": "found", "cliente": { ... }, "veiculos": [ ... ] }

POST /clientes.php?api_key=CHAVE

Body JSON — criar cliente

{
  "nome": "João Silva",
  "cpf": "12345678900",
  "telefone": "82999999999",
  "email": "joao@email.com",
  "cep": "57000000"
}

201 — cliente criado · 409 — CPF já cadastrado

🚗

veiculos.php

Buscar e criar veículos · 🔒 permissão: veiculos

GET /veiculos.php?api_key=CHAVE&placa=ABC1234

{ "status": "found", "veiculo": { ... }, "dono": { ... } }

POST /veiculos.php?api_key=CHAVE

Body JSON — criar veículo

{
  "cliente_id": 12,
  "placa": "ABC1234",
  "marca": "Chevrolet",
  "modelo": "Onix",
  "ano": "2019",
  "cor": "Branco",
  "tipo_veiculo": "carro"
}

📅

agendamentos.php

Criar, confirmar, cancelar e consultar · 🔒 permissão: agendamentos

POST /agendamentos.php?api_key=CHAVE

Criar agendamento

{
  "acao": "criar",
  "cliente": { "cpf": "12345678900" },
  "veiculo": { "placa": "ABC1234" },
  "agendamento": { "data": "2026-03-20", "motivo": "Revisão geral" }
}

Confirmar agendamento

{
  "acao": "confirmar",
  "agendamento_id": 84,
  "data_confirmada": "2026-03-21",
  "hora": "09:00"
}

Cancelar agendamento

{ "acao": "cancelar", "agendamento_id": 84 }

GET /agendamentos.php?api_key=CHAVE&agendamento_id=84

Consultar por ID ou CPF

GET .../agendamentos.php?api_key=CHAVE&agendamento_id=84
GET .../agendamentos.php?api_key=CHAVE&cpf=12345678900

💡

Exemplos práticos

cURL e JavaScript (fetch)

Buscar OS via cURL

curl -s "http://seusite/gestor/php/api/os.php?api_key=CHAVE&os=345"

Buscar cliente via JavaScript

fetch('/gestor/php/api/clientes.php?api_key=CHAVE&cpf=12345678900')
  .then(r => r.json())
  .then(data => console.log(data))

📋

Padrões e códigos de resposta

Todas as respostas JSON usam JSON_UNESCAPED_UNICODE

HTTP	status	Descrição
200	`success / found`	Operação bem sucedida
201	`created`	Recurso criado
401	`error`	Autenticação inválida ou ausente
403	`error`	Chave sem permissão
404	`not_found`	Recurso não encontrado
409	`conflict`	Duplicidade (ex: CPF)
500	`error`	Erro interno do servidor

🛡️ Use prepared statements e valide todas as entradas ao integrar com a API.

🎮

Playground

Teste interativo dos endpoints diretamente no navegador

O playground interativo está disponível em playground.php — requer sessão ativa no gestor.

Hi Auto API

Documentação de API Hi Auto - Oficinas