Referência da API

API REST v1. Erros em application/problem+json (RFC 9457). Paginação por cursor. Webhooks assinados com HMAC-SHA256.

Versão 0.1.0. Gerado de openapi.json — não edite à mão.

Sessão do painel web

Entrar (painel web)

http

POST /api/v1/auth/login

Corpo: LoginInput

Respostas: 200 Me — Define o cookie de sessão · 401 · 429

Sair

http

POST /api/v1/auth/logout

Respostas: 204

Usuário logado

http

GET /api/v1/auth/me

Autenticação: session

Respostas: 200 Me · 401

Clientes

Listar clientes

http

GET /api/v1/customers

Autenticação: api_key (customers:read) ou session

Parâmetro	Onde	Tipo	Descrição
`limit`	query	integer	1 a 100 (padrão 50).
`cursor`	query	string
`q`	query	string	Busca por parte do nome, telefone ou CPF/CNPJ.

Respostas: 200 CustomerPage · 400 · 401

Criar cliente

http

POST /api/v1/customers

Aceita Idempotency-Key.

Autenticação: api_key (customers:write) ou session

Parâmetro	Onde	Tipo	Descrição
`Idempotency-Key`	header	string (opcional)

Corpo: NewCustomer

Respostas: 201 Customer · 400 · 403

Buscar cliente

http

GET /api/v1/customers/{id}

Autenticação: api_key (customers:read) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 Customer · 404

Alterar cliente

http

PATCH /api/v1/customers/{id}

Autenticação: api_key (customers:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: CustomerPatch

Respostas: 200 Customer · 400 · 404

Veículos e histórico por placa

Listar veículos

http

GET /api/v1/vehicles

Filtre por plate para achar o veículo pela placa (check-in).

Autenticação: api_key (customers:read) ou session

Parâmetro	Onde	Tipo	Descrição
`limit`	query	integer
`cursor`	query	string
`plate`	query	string	Placa exata (com ou sem hífen).
`customer_id`	query	integer

Respostas: 200 VehiclePage · 400 · 401

Cadastrar veículo

http

POST /api/v1/vehicles

Aceita Idempotency-Key. Placa repetida na mesma empresa → 409.

Autenticação: api_key (customers:write) ou session

Parâmetro	Onde	Tipo	Descrição
`Idempotency-Key`	header	string (opcional)

Corpo: NewVehicle

Respostas: 201 Vehicle · 400 · 409

Buscar veículo

http

GET /api/v1/vehicles/{id}

Autenticação: api_key (customers:read) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 Vehicle · 404

Alterar veículo

http

PATCH /api/v1/vehicles/{id}

Autenticação: api_key (customers:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: VehiclePatch

Respostas: 200 Vehicle · 400 · 404 · 409

Ordens de serviço, orçamento, etapas e quadro do pátio

Quadro do pátio

http

GET /api/v1/board

Etapas e OS abertas. Técnico vê só as OS em que tem serviço.

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 Board

Regiões, assuntos e condições aceitos em fotos e itens

http

GET /api/v1/inspection/catalog

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 Catalog

Listar OS

http

GET /api/v1/service-orders

Autenticação: api_key (service_orders:read) ou session

Parâmetro	Onde	Tipo	Descrição
`limit`	query	integer
`cursor`	query	string
`stage_id`	query	integer
`vehicle_id`	query	integer
`customer_id`	query	integer	Todas as OS de um cliente (histórico na ficha do cliente).
`open`	query	boolean	`true`: só as que não foram entregues nem canceladas.

Respostas: 200 ServiceOrderPage · 400

Abrir OS (check-in)

http

POST /api/v1/service-orders

Aceita Idempotency-Key. O cliente vem do veículo.

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`Idempotency-Key`	header	string (opcional)

Corpo: NewServiceOrder

Respostas: 201 ServiceOrder · 400

Buscar OS com itens e serviços

http

GET /api/v1/service-orders/{id}

Autenticação: api_key (service_orders:read) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 ServiceOrderDetail · 404

Alterar OS

http

PATCH /api/v1/service-orders/{id}

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: ServiceOrderPatch

Respostas: 200 ServiceOrder · 400 · 404

Pedir aprovação do orçamento ao cliente

http

POST /api/v1/service-orders/{id}/approval-request

Gera um link expirável (revoga o anterior) e envia pelo WhatsApp da oficina (Falia) ou devolve o wa.me pronto. O cliente abre com os 4 últimos dígitos do telefone.

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: ApprovalRequest

Respostas: 201 ApprovalSent · 400 · 409 · 502

Cancelar o link de aprovação

http

DELETE /api/v1/service-orders/{id}/approval-request

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 204 · 404

Links e respostas do cliente

http

GET /api/v1/service-orders/{id}/approvals

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 ApprovalHistory · 404

Enviar foto da OS

http

POST /api/v1/service-orders/{id}/attachments

JSON com a imagem em base64 (JPEG ou PNG, até 8 MB). Os metadados (GPS etc.) são removidos.

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: NewAttachment

Respostas: 201 Attachment · 400 · 404

Baixar foto

http

GET /api/v1/service-orders/{id}/attachments/{attachment_id}

Autenticação: api_key (service_orders:read) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer
`attachment_id`	path	integer

Respostas: 200 — A imagem · 404

Apagar foto

http

DELETE /api/v1/service-orders/{id}/attachments/{attachment_id}

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer
`attachment_id`	path	integer

Respostas: 204 · 404

Legenda ou visibilidade da foto

http

PATCH /api/v1/service-orders/{id}/attachments/{attachment_id}

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer
`attachment_id`	path	integer

Corpo: AttachmentPatch

Respostas: 200 Attachment · 404

Acrescentar ao histórico da OS

http

POST /api/v1/service-orders/{id}/entries

Relato, diagnóstico ou anotação. O histórico não se edita nem se apaga: para corrigir, acrescente uma nova entrada.

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: NewEntry

Respostas: 201 Entry · 400 · 404

Adicionar item ao orçamento

http

POST /api/v1/service-orders/{id}/items

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: NewItem

Respostas: 201 ServiceOrderDetail · 400 · 404

Remover item

http

DELETE /api/v1/service-orders/{id}/items/{item_id}

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer
`item_id`	path	integer

Respostas: 204 · 404 · 409

Alterar ou aprovar item

http

PATCH /api/v1/service-orders/{id}/items/{item_id}

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer
`item_id`	path	integer

Corpo: ItemPatch

Respostas: 200 ServiceOrderDetail · 400 · 404

Mover OS de etapa

http

POST /api/v1/service-orders/{id}/stage

Gera service_order.stage_changed; etapas ready e delivered também geram service_order.ready / service_order.delivered.

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: MoveStage

Respostas: 200 ServiceOrder · 400 · 404

Etapas do quadro

http

GET /api/v1/stages

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 Stage[]

Criar etapa (dono)

http

POST /api/v1/stages

Autenticação: session

Corpo: NewStage

Respostas: 201 Stage · 400 · 403

Renomear ou mover etapa (dono)

http

PATCH /api/v1/stages/{id}

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: StagePatch

Respostas: 200 Stage · 400 · 404

Serviços dos técnicos e quadro por técnico

Atribuir técnico ou renomear serviço

http

PATCH /api/v1/jobs/{id}

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: JobPatch

Respostas: 200 Job · 400 · 404

Marcar serviço como travado (com motivo)

http

POST /api/v1/jobs/{id}/block

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: BlockInput

Respostas: 200 Job · 400 · 403 · 404

Concluir serviço

http

POST /api/v1/jobs/{id}/finish

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 Job · 403 · 404

Pausar serviço

http

POST /api/v1/jobs/{id}/pause

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 Job · 403 · 404

Iniciar serviço (pausa o que o técnico estava fazendo)

http

POST /api/v1/jobs/{id}/start

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 Job · 403 · 404 · 409

Criar serviço avulso na OS

http

POST /api/v1/service-orders/{id}/jobs

Autenticação: api_key (service_orders:write) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: NewJob

Respostas: 201 Job · 400 · 404

Quadro por técnico

http

GET /api/v1/technicians/board

Uma raia por técnico com o serviço em andamento (current: em qual carro está agora) e os demais. Técnico vê só a própria raia.

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 TechnicianBoard

Equipe

http

GET /api/v1/team

Nomes e papéis (para atribuir técnicos). E-mail só para o dono.

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 Member[]

Cadastrar pessoa na equipe (dono)

http

POST /api/v1/team

Autenticação: session

Corpo: NewMember

Respostas: 201 Member · 400 · 403 · 409

Alterar papel, ativar/desativar ou trocar senha (dono)

http

PATCH /api/v1/team/{id}

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: MemberPatch

Respostas: 200 Member · 400 · 404 · 409

Nome e logo da unidade

Nome e logo da oficina

http

GET /api/v1/tenant

Autenticação: api_key ou session

Respostas: 200 Brand

Trocar o nome de exibição (dono)

http

PATCH /api/v1/tenant

Autenticação: session

Corpo: BrandPatch

Respostas: 200 Brand · 400 · 403

Baixar a logo

http

GET /api/v1/tenant/logo

Autenticação: api_key ou session

Respostas: 200 — A imagem · 404

Enviar ou trocar a logo (dono)

http

PUT /api/v1/tenant/logo

JSON com a imagem em base64 (JPEG ou PNG, até 512 KB). Os metadados são removidos.

Autenticação: session

Corpo: LogoInput

Respostas: 200 Brand · 400 · 403

Remover a logo (dono)

http

DELETE /api/v1/tenant/logo

Autenticação: session

Respostas: 204 · 403

Unidades da empresa e troca de unidade

Abrir outra unidade

http

POST /api/v1/auth/unit

Autenticação: session

Corpo: SwitchUnit

Respostas: 200 Me · 404

Minhas unidades

http

GET /api/v1/units

Unidades da empresa em que a pessoa tem papel, com o resumo do pátio de cada uma.

Autenticação: session

Respostas: 200 Unit[]

Criar unidade (dono da empresa)

http

POST /api/v1/units

Autenticação: session

Corpo: NewUnit

Respostas: 201 Unit · 400 · 403

Lembretes de retorno (troca de óleo, revisão…)

Regras de retorno

http

GET /api/v1/reminder-rules

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 Rule[]

Criar regra (dono)

http

POST /api/v1/reminder-rules

Autenticação: session

Corpo: NewRule

Respostas: 201 Rule · 400

Alterar regra (dono)

http

PATCH /api/v1/reminder-rules/{id}

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Corpo: RulePatch

Respostas: 200 Rule · 400 · 404

Clientes para avisar (retorno)

http

GET /api/v1/reminders

Recurso contratado (403 sem ele). Quem passou do intervalo da regra desde o último serviço (ou vence em 14 dias) e ainda não foi avisado.

Autenticação: api_key (customers:read, service_orders:read) ou session

Respostas: 200 DueReminder[]

Avisar um cliente pelo Falia (ou marcar para não avisar)

http

POST /api/v1/reminders/send

Autenticação: api_key (customers:write) ou session

Corpo: SendReminder

Respostas: 200 ReminderResult · 409 · 502

WhatsApp da oficina pelo Falia

Situação da conexão com o Falia

http

GET /api/v1/integrations/falia

Autenticação: api_key (service_orders:read) ou session

Respostas: 200 FaliaStatus

Conectar o Falia (dono)

http

POST /api/v1/integrations/falia

Valida a chave no Falia (GET /api/v1/status) e guarda cifrada.

Autenticação: session

Corpo: ConnectInput

Respostas: 200 FaliaStatus · 400 · 502

Desconectar o Falia (dono)

http

DELETE /api/v1/integrations/falia

Autenticação: session

Respostas: 204

Página do cliente (link de aprovação)

Cliente: aprovar ou recusar itens

http

POST /api/public/approval/decide

Corpo: PublicDecision

Respostas: 200 PublicView · 400 · 403 · 409 · 410

Cliente: logo da oficina

http

POST /api/public/approval/logo

Corpo: PublicAccess

Respostas: 200 — A imagem · 403 · 404 · 410

Cliente: foto do orçamento

http

POST /api/public/approval/photo

Corpo: PublicPhoto

Respostas: 200 — A imagem · 403 · 404 · 410

Cliente: ver o orçamento

http

POST /api/public/approval/view

Corpo: PublicAccess

Respostas: 200 PublicView · 403 · 410 · 429

Chaves para integrações

Listar API keys ativas

http

GET /api/v1/api-keys

Autenticação: session

Respostas: 200 ApiKey[]

Criar API key

http

POST /api/v1/api-keys

Autenticação: session

Corpo: NewApiKey

Respostas: 201 CreatedApiKey · 400

Revogar API key

http

DELETE /api/v1/api-keys/{id}

Autenticação: session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 204 · 404

Notificações de eventos para sistemas externos

Reenviar uma entrega

http

POST /api/v1/webhook-deliveries/{id}/retry

Autenticação: api_key (webhooks:manage) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 202 · 404

Listar endpoints de webhook

http

GET /api/v1/webhooks

Autenticação: api_key (webhooks:manage) ou session

Respostas: 200 Endpoint[]

Cadastrar endpoint de webhook

http

POST /api/v1/webhooks

Autenticação: api_key (webhooks:manage) ou session

Corpo: NewEndpoint

Respostas: 201 CreatedEndpoint · 400

Remover endpoint de webhook

http

DELETE /api/v1/webhooks/{id}

Autenticação: api_key (webhooks:manage) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 204 · 404

Últimas 100 entregas de um endpoint

http

GET /api/v1/webhooks/{id}/deliveries

Autenticação: api_key (webhooks:manage) ou session

Parâmetro	Onde	Tipo	Descrição
`id`	path	integer

Respostas: 200 Delivery[] · 404

Modelos

ApiKey

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`prefix`	string	sim	Início da chave, para identificá-la (ex.: `pk_live_a1b2`).
`scopes`	string[]	sim
`created_at`	integer	sim
`last_used_at`	integer (opcional)	não

ApprovalHistory

Campo	Tipo	Obrigatório	Descrição
`links`	LinkInfo[]	sim
`approvals`	ApprovalRecord[]	sim

ApprovalRecord

Campo	Tipo	Obrigatório
`signer_name`	string	sim
`decisions`	objeto[]	sim
`ip`	string	sim
`created_at`	integer	sim

ApprovalRequest

Campo	Tipo	Obrigatório	Descrição
`channel`	string (opcional)	não	`falia` envia pelo WhatsApp da oficina; `link` só gera (o atendente envia pelo wa.me). Padrão: falia se conectado.
`days`	integer (opcional)	não	Validade do link em dias (1 a 30, padrão 7).
`message`	string (opcional)	não	Texto da mensagem; `{link}` é trocado pelo endereço. Padrão: mensagem pronta com total e validade.

ApprovalSent

Campo	Tipo	Obrigatório	Descrição
`url`	string	sim
`expires_at`	integer	sim
`message`	string	sim	Texto que foi (ou será) enviado.
`channel`	string	sim	`falia` (já enviado) ou `link` (abra `whatsapp_url` para enviar).
`whatsapp_url`	string	sim	`wa.me` com o texto pronto.

Attachment

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`category`	string	sim	entrada \| diagnostico \| antes \| depois \| outro
`caption`	string	sim
`region`	string (opcional)	não	Região do carro (`GET /api/v1/inspection/catalog`); `null` = geral.
`system`	string (opcional)	não	Assunto (sistema do carro); `null` = não informado.
`condition`	string (opcional)	não	ok \| atencao \| problema; `null` = sem avaliação.
`mime`	string	sim
`size`	integer	sim
`visible_to_customer`	boolean	sim
`created_at`	integer	sim

AttachmentPatch

Campo	Tipo	Obrigatório	Descrição
`caption`	string (opcional)	não
`visible_to_customer`	boolean (opcional)	não
`region`	string (opcional)	não	`null` limpa.
`system`	string (opcional)	não
`condition`	string (opcional)	não

BlockInput

Campo	Tipo	Obrigatório	Descrição
`reason`	string	sim	Motivo (ex.: "aguardando peça").

Board

Campo	Tipo	Obrigatório	Descrição
`stages`	Stage[]	sim
`cards`	ServiceOrder[]	sim	OS abertas (sem entregues/canceladas), mais antigas na etapa primeiro.

Brand

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim
`logo_url`	string (opcional)	não	URL da logo (muda quando a logo é trocada); `null` = sem logo.

BrandPatch

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim

Catalog

Campo	Tipo	Obrigatório
`regions`	CatalogOption[]	sim
`systems`	CatalogOption[]	sim
`conditions`	CatalogOption[]	sim

CatalogOption

Campo	Tipo	Obrigatório	Descrição
`key`	string	sim
`label`	string	sim

ConnectInput

Campo	Tipo	Obrigatório	Descrição
`api_key`	string	sim	API key do Falia com o escopo `messages:send`.

CreatedApiKey

CreatedEndpoint

Customer

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`phone`	string	sim	E.164 (`+5521999998888`) ou vazio.
`email`	string	sim
`document`	string	sim	CPF/CNPJ (só dígitos, dígitos verificadores conferidos) ou vazio.
`birth_date`	string	sim	`AAAA-MM-DD` ou vazio.
`zip`	string	sim	CEP com 8 dígitos ou vazio.
`street`	string	sim
`number`	string	sim
`complement`	string	sim
`district`	string	sim
`city`	string	sim
`state`	string	sim	UF (`RJ`) ou vazio.
`notes`	string	sim
`created_at`	integer	sim
`updated_at`	integer	sim

CustomerPage

Campo	Tipo	Obrigatório	Descrição
`data`	Customer[]	sim
`next_cursor`	string (opcional)	não

CustomerPatch

Campo	Tipo	Obrigatório
`name`	string (opcional)	não
`phone`	string (opcional)	não
`email`	string (opcional)	não
`document`	string (opcional)	não
`birth_date`	string (opcional)	não
`zip`	string (opcional)	não
`street`	string (opcional)	não
`number`	string (opcional)	não
`complement`	string (opcional)	não
`district`	string (opcional)	não
`city`	string (opcional)	não
`state`	string (opcional)	não
`notes`	string (opcional)	não

CustomerRef

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`phone`	string (opcional)	não	Oculto para técnicos.

Delivery

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`event_id`	string	sim
`event_type`	string	sim
`status`	string	sim	`pending`, `delivered` ou `failed`.
`attempts`	integer	sim
`last_status`	integer (opcional)	não
`last_error`	string (opcional)	não
`created_at`	integer	sim
`delivered_at`	integer (opcional)	não

DueReminder

Campo	Tipo	Obrigatório	Descrição
`rule_id`	integer	sim
`rule_name`	string	sim
`vehicle_id`	integer	sim
`plate`	string	sim
`vehicle`	string	sim
`customer_id`	integer	sim
`customer_name`	string	sim
`has_phone`	boolean	sim	Sem telefone não dá para avisar pelo WhatsApp.
`last_service`	string	sim	Descrição do último serviço que casou com a regra.
`last_service_at`	integer	sim
`due_at`	integer	sim
`months`	integer	sim	Meses desde o último serviço (arredondado para baixo).
`overdue`	boolean	sim
`message`	string	sim	Mensagem pronta (o atendente pode editar antes de enviar).

Endpoint

Campo	Tipo	Obrigatório
`id`	integer	sim
`url`	string	sim
`events`	string[]	sim
`active`	boolean	sim
`created_at`	integer	sim

Entry

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`kind`	string	sim	complaint (relato do cliente) \| diagnosis \| note (anotação interna)
`text`	string	sim
`author`	string	sim	Quem escreveu (nome da pessoa ou da chave de API).
`created_at`	integer	sim

FaliaStatus

Campo	Tipo	Obrigatório	Descrição
`available`	boolean	sim	A instalação tem SECRETS_KEY (sem ela não dá para guardar a chave).
`connected`	boolean	sim
`key_prefix`	string (opcional)	não	Início da chave (`fal_live_…`), para conferência.
`provider`	string (opcional)	não	`evolution` (QR code) ou `cloud` (API oficial).
`whatsapp_state`	string (opcional)	não	Estado do número no Falia agora (`open` = conectado).
`connected_at`	integer (opcional)	não

Item

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`kind`	string	sim	service \| part
`description`	string	sim
`qty`	number	sim
`unit_price_cents`	integer (opcional)	não	Oculto para técnicos.
`total_cents`	integer (opcional)	não
`status`	string	sim	proposed \| approved \| rejected
`region`	string (opcional)	não	Região do carro (`GET /api/v1/inspection/catalog`); `null` = geral.
`system`	string (opcional)	não	Assunto (sistema do carro).

ItemPatch

Campo	Tipo	Obrigatório	Descrição
`description`	string (opcional)	não
`qty`	number (opcional)	não
`unit_price_cents`	integer (opcional)	não
`status`	string (opcional)	não	proposed \| approved \| rejected
`region`	string (opcional)	não	`null` limpa.
`system`	string (opcional)	não

Job

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`service_order_id`	integer	sim
`service_order_number`	integer	sim
`item_id`	integer (opcional)	não
`title`	string	sim
`technician_id`	integer (opcional)	não
`technician_name`	string (opcional)	não
`status`	string	sim	pending \| in_progress \| paused \| blocked \| done
`blocked_reason`	string	sim
`plate`	string	sim
`vehicle`	string	sim
`started_at`	integer (opcional)	não
`done_at`	integer (opcional)	não
`worked_ms`	integer	sim	Tempo trabalhado somado (inclui o trecho em andamento), em ms.
`running_since`	integer (opcional)	não	Início do trecho em andamento (para o cronômetro na tela).

JobPatch

Campo	Tipo	Obrigatório	Descrição
`title`	string (opcional)	não
`technician_id`	integer (opcional)	não	Técnico responsável; `null` tira do técnico.

LinkInfo

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`created_at`	integer	sim
`expires_at`	integer	sim
`opened_at`	integer (opcional)	não
`decided_at`	integer (opcional)	não
`state`	string	sim	active \| expired \| revoked \| decided

LoginInput

Campo	Tipo	Obrigatório	Descrição
`email`	string	sim
`password`	string	sim

LogoInput

Campo	Tipo	Obrigatório	Descrição
`data_base64`	string	sim	Imagem JPEG ou PNG em base64 (até 512 KB depois de decodificada).

Me

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`email`	string	sim
`role`	string	sim	`owner`, `manager` ou `technician`.
`is_technician`	boolean	sim	Aparece no quadro dos técnicos.
`business_type`	string	sim	oficina \| estetica \| funilaria \| lava_rapido \| outro
`features`	string[]	sim	Recursos contratados ligados (ex.: `reminders`).
`tenant_id`	integer	sim	Unidade aberta nesta sessão.
`tenant_name`	string	sim
`group_id`	integer	sim	A empresa (grupo) da unidade.
`group_name`	string	sim
`group_owner`	boolean	sim	Dono do grupo: cria unidades e vê todas.
`unit_count`	integer	sim	Quantas unidades a pessoa pode abrir (mostra o seletor quando > 1).
`tenant_logo_url`	string (opcional)	não	URL da logo da oficina; `null` = sem logo (o painel mostra as iniciais).
`scopes`	string[]	sim

Member

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`email`	string (opcional)	não	Só aparece para o dono.
`role`	string	sim	owner (dono) \| unit_manager (gerente) \| manager (recepção) \| technician \| finance (financeiro)
`group_owner`	boolean	sim	Dono do grupo (todas as unidades): só outro dono do grupo altera.
`is_technician`	boolean	sim
`active`	boolean	sim

MemberPatch

Campo	Tipo	Obrigatório	Descrição
`name`	string (opcional)	não
`role`	string (opcional)	não
`is_technician`	boolean (opcional)	não
`active`	boolean (opcional)	não	`false` desativa e derruba as sessões.
`password`	string (opcional)	não	Nova senha (derruba as sessões).

MoveStage

Campo	Tipo	Obrigatório	Descrição
`stage_id`	integer	sim

NewApiKey

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim
`scopes`	string[]	sim

NewAttachment

Campo	Tipo	Obrigatório	Descrição
`category`	string	sim
`caption`	string (opcional)	não
`region`	string (opcional)	não
`system`	string (opcional)	não
`condition`	string (opcional)	não
`visible_to_customer`	boolean (opcional)	não	Padrão: aparece no link de aprovação.
`data_base64`	string	sim	Imagem JPEG ou PNG em base64 (até 8 MB depois de decodificada).

NewCustomer

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	1 a 120 caracteres.
`phone`	string (opcional)	não	DDD + número (Brasil) ou `+código do país`.
`email`	string (opcional)	não
`document`	string (opcional)	não	CPF (11) ou CNPJ (14) dígitos, com ou sem pontuação.
`birth_date`	string (opcional)	não
`zip`	string (opcional)	não
`street`	string (opcional)	não
`number`	string (opcional)	não
`complement`	string (opcional)	não
`district`	string (opcional)	não
`city`	string (opcional)	não
`state`	string (opcional)	não
`notes`	string (opcional)	não

NewEndpoint

Campo	Tipo	Obrigatório	Descrição
`url`	string	sim	URL https:// pública que receberá os eventos.
`events`	string[]	sim	Eventos assinados; `["*"]` para todos.

NewEntry

Campo	Tipo	Obrigatório	Descrição
`kind`	string	sim	complaint \| diagnosis \| note
`text`	string	sim	1 a 4000 caracteres.

NewItem

Campo	Tipo	Obrigatório	Descrição
`kind`	string	sim	service \| part. Serviço cria automaticamente um serviço no quadro dos técnicos.
`description`	string	sim
`qty`	number (opcional)	não	Até 3 casas decimais. Padrão 1.
`unit_price_cents`	integer	sim
`technician_id`	integer (opcional)	não	Técnico do serviço (só para `service`).
`region`	string (opcional)	não
`system`	string (opcional)	não

NewJob

Campo	Tipo	Obrigatório	Descrição
`title`	string	sim
`technician_id`	integer (opcional)	não

NewMember

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim
`email`	string	sim
`password`	string	sim	Senha inicial (mínimo 10 caracteres); a pessoa troca depois.
`role`	string	sim	unit_manager (gerente), manager (recepção), technician ou finance (financeiro).
`is_technician`	boolean	não	Recepção que também executa serviço.

NewRule

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim
`match_text`	string	sim
`interval_days`	integer	sim	7 a 1095 dias.
`message`	string	sim

NewServiceOrder

Campo	Tipo	Obrigatório	Descrição
`vehicle_id`	integer	sim
`stage_id`	integer (opcional)	não	Etapa inicial; padrão: a primeira de check-in (`intake`).
`km_in`	integer (opcional)	não
`complaint`	string (opcional)	não
`promised_at`	integer (opcional)	não

NewStage

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim
`kind`	string	sim
`position`	integer (opcional)	não	Posição no quadro (0 = primeira). Padrão: última.

NewUnit

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim
`business_type`	string (opcional)	não	oficina \| estetica \| funilaria \| lava_rapido \| outro (define as etapas iniciais).

NewVehicle

Campo	Tipo	Obrigatório	Descrição
`customer_id`	integer	sim
`plate`	string	sim	Aceita com ou sem hífen, maiúsculas ou minúsculas.
`brand`	string (opcional)	não
`model`	string (opcional)	não
`year`	integer (opcional)	não	1900 a ano atual + 1.
`color`	string (opcional)	não
`notes`	string (opcional)	não

PublicAccess

Campo	Tipo	Obrigatório	Descrição
`token`	string	sim
`digits`	string	sim	4 últimos dígitos do telefone do cliente.

PublicDecision

Campo	Tipo	Obrigatório	Descrição
`token`	string	sim
`digits`	string	sim
`name`	string	sim	Nome de quem aprova (fica registrado).
`decisions`	PublicDecisionItem[]	sim

PublicDecisionItem

Campo	Tipo	Obrigatório	Descrição
`item_id`	integer	sim
`approve`	boolean	sim

PublicItem

Campo	Tipo	Obrigatório
`id`	integer	sim
`kind`	string	sim
`description`	string	sim
`qty`	number	sim
`unit_price_cents`	integer	sim
`total_cents`	integer	sim
`status`	string	sim
`region`	string (opcional)	não
`system`	string (opcional)	não

PublicPhoto

Campo	Tipo	Obrigatório
`token`	string	sim
`digits`	string	sim
`id`	integer	sim

PublicView

Campo	Tipo	Obrigatório	Descrição
`company`	string	sim
`customer_first_name`	string	sim	Só o primeiro nome.
`order_number`	integer	sim
`vehicle`	string	sim
`plate`	string	sim
`complaint`	string	sim
`diagnosis`	string	sim
`items`	PublicItem[]	sim
`approved_cents`	integer	sim
`proposed_cents`	integer	sim
`photos`	Attachment[]	sim
`expires_at`	integer	sim
`decided`	boolean	sim
`has_logo`	boolean	sim	A oficina tem logo (buscar em `/api/public/approval/logo`).

ReminderResult

Campo	Tipo	Obrigatório	Descrição
`channel`	string	sim
`message`	string	sim

Rule

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`match_text`	string	sim	Texto procurado na descrição dos serviços (ex.: "óleo").
`interval_days`	integer	sim
`message`	string	sim	Variáveis: {cliente} {veiculo} {placa} {servico} {meses} {empresa}.
`active`	boolean	sim

RulePatch

Campo	Tipo	Obrigatório
`name`	string (opcional)	não
`match_text`	string (opcional)	não
`interval_days`	integer (opcional)	não
`message`	string (opcional)	não
`active`	boolean (opcional)	não

SendReminder

Campo	Tipo	Obrigatório	Descrição
`rule_id`	integer	sim
`vehicle_id`	integer	sim
`channel`	string (opcional)	não	`falia` (padrão) ou `dismiss` (não avisar desta vez).
`message`	string (opcional)	não	Texto editado; padrão = mensagem da regra.

ServiceOrder

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`number`	integer	sim	Número sequencial por empresa (o que aparece para o cliente).
`customer`	CustomerRef	sim
`vehicle`	VehicleRef	sim
`stage_id`	integer	sim
`stage_kind`	string	sim
`stage_since`	integer	sim	Desde quando está na etapa atual (ms UTC).
`km_in`	integer (opcional)	não
`complaint`	string	sim	Relato do cliente.
`diagnosis`	string	sim
`promised_at`	integer (opcional)	não
`delivered_at`	integer (opcional)	não
`totals`	null \| Totals	não
`jobs_total`	integer	sim
`jobs_done`	integer	sim
`customer_approval`	string (opcional)	não	Link de aprovação mais recente: `waiting` (cliente ainda não respondeu), `answered` ou null.
`customer_answered_at`	integer (opcional)	não	Quando o cliente respondeu pelo link (ms UTC).
`created_at`	integer	sim
`updated_at`	integer	sim

ServiceOrderDetail

ServiceOrderPage

Campo	Tipo	Obrigatório	Descrição
`data`	ServiceOrder[]	sim
`next_cursor`	string (opcional)	não

ServiceOrderPatch

Campo	Tipo	Obrigatório	Descrição
`km_in`	integer (opcional)	não
`promised_at`	integer (opcional)	não

Stage

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`kind`	string	sim	scheduled \| intake \| waiting_customer \| waiting_parts \| in_progress \| qa \| ready \| delivered \| cancelled
`position`	integer	sim

StagePatch

Campo	Tipo	Obrigatório	Descrição
`name`	string (opcional)	não
`position`	integer (opcional)	não

SwitchUnit

Campo	Tipo	Obrigatório	Descrição
`tenant_id`	integer	sim

TechnicianBoard

Campo	Tipo	Obrigatório	Descrição
`technicians`	TechnicianLane[]	sim
`unassigned`	Job[]	sim	Serviços abertos sem técnico (só para recepção e dono).

TechnicianLane

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`current`	null \| Job	não
`jobs`	Job[]	sim	Abertos e os concluídos nas últimas 24 h.

Totals

Campo	Tipo	Obrigatório	Descrição
`approved_cents`	integer	sim	Soma dos itens aprovados, em centavos.
`proposed_cents`	integer	sim	Soma dos itens ainda em orçamento, em centavos.

Unit

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`name`	string	sim
`logo_url`	string (opcional)	não
`business_type`	string	sim
`role`	string	sim	Papel da pessoa nesta unidade.
`current`	boolean	sim	É a unidade aberta agora.
`open_orders`	integer (opcional)	não	OS no pátio (fora de entregue/cancelada). Só para quem vê a operação da unidade.
`ready_orders`	integer (opcional)	não	OS prontas para retirada.

Vehicle

Campo	Tipo	Obrigatório	Descrição
`id`	integer	sim
`customer_id`	integer	sim
`plate`	string	sim	Maiúsculas, sem hífen: `ABC1234` ou `ABC1D23`.
`brand`	string	sim
`model`	string	sim
`year`	integer (opcional)	não
`color`	string	sim
`notes`	string	sim
`created_at`	integer	sim
`updated_at`	integer	sim

VehiclePage

Campo	Tipo	Obrigatório	Descrição
`data`	Vehicle[]	sim
`next_cursor`	string (opcional)	não

VehiclePatch

Campo	Tipo	Obrigatório	Descrição
`customer_id`	integer (opcional)	não	Troca o dono do veículo (venda do carro).
`plate`	string (opcional)	não
`brand`	string (opcional)	não
`model`	string (opcional)	não
`year`	integer (opcional)	não
`color`	string (opcional)	não
`notes`	string (opcional)	não

VehicleRef

Campo	Tipo	Obrigatório
`id`	integer	sim
`plate`	string	sim
`brand`	string	sim
`model`	string	sim
`color`	string	sim
`year`	integer (opcional)	não

Referência da API ​

Sessão do painel web ​

Entrar (painel web) ​

Sair ​

Usuário logado ​

Clientes ​

Listar clientes ​

Criar cliente ​

Buscar cliente ​

Alterar cliente ​

Veículos e histórico por placa ​

Listar veículos ​

Cadastrar veículo ​

Buscar veículo ​

Alterar veículo ​

Ordens de serviço, orçamento, etapas e quadro do pátio ​

Quadro do pátio ​

Regiões, assuntos e condições aceitos em fotos e itens ​

Listar OS ​

Abrir OS (check-in) ​

Buscar OS com itens e serviços ​

Alterar OS ​

Pedir aprovação do orçamento ao cliente ​

Cancelar o link de aprovação ​

Links e respostas do cliente ​

Enviar foto da OS ​

Baixar foto ​

Apagar foto ​

Legenda ou visibilidade da foto ​

Acrescentar ao histórico da OS ​

Adicionar item ao orçamento ​

Remover item ​

Alterar ou aprovar item ​

Mover OS de etapa ​

Etapas do quadro ​

Criar etapa (dono) ​

Renomear ou mover etapa (dono) ​

Serviços dos técnicos e quadro por técnico ​

Atribuir técnico ou renomear serviço ​

Marcar serviço como travado (com motivo) ​

Concluir serviço ​

Pausar serviço ​

Iniciar serviço (pausa o que o técnico estava fazendo) ​

Criar serviço avulso na OS ​

Quadro por técnico ​

Equipe ​

Equipe ​

Cadastrar pessoa na equipe (dono) ​

Alterar papel, ativar/desativar ou trocar senha (dono) ​

Nome e logo da unidade ​

Nome e logo da oficina ​

Trocar o nome de exibição (dono) ​

Baixar a logo ​

Enviar ou trocar a logo (dono) ​

Remover a logo (dono) ​

Unidades da empresa e troca de unidade ​

Abrir outra unidade ​

Minhas unidades ​

Criar unidade (dono da empresa) ​

Lembretes de retorno (troca de óleo, revisão…) ​

Regras de retorno ​

Criar regra (dono) ​

Alterar regra (dono) ​

Clientes para avisar (retorno) ​

Avisar um cliente pelo Falia (ou marcar para não avisar) ​

WhatsApp da oficina pelo Falia ​

Situação da conexão com o Falia ​

Conectar o Falia (dono) ​

Desconectar o Falia (dono) ​

Página do cliente (link de aprovação) ​

Cliente: aprovar ou recusar itens ​

Cliente: logo da oficina ​

Cliente: foto do orçamento ​

Cliente: ver o orçamento ​

Chaves para integrações ​

Listar API keys ativas ​

Criar API key ​

Revogar API key ​

Notificações de eventos para sistemas externos ​

Reenviar uma entrega ​

Referência da API

Sessão do painel web

Entrar (painel web)

Sair

Usuário logado

Clientes

Listar clientes

Criar cliente

Buscar cliente

Alterar cliente

Veículos e histórico por placa

Listar veículos

Cadastrar veículo

Buscar veículo

Alterar veículo

Ordens de serviço, orçamento, etapas e quadro do pátio

Quadro do pátio

Regiões, assuntos e condições aceitos em fotos e itens

Listar OS

Abrir OS (check-in)

Buscar OS com itens e serviços

Alterar OS

Pedir aprovação do orçamento ao cliente

Cancelar o link de aprovação

Links e respostas do cliente

Enviar foto da OS

Baixar foto

Apagar foto

Legenda ou visibilidade da foto

Acrescentar ao histórico da OS

Adicionar item ao orçamento

Remover item

Alterar ou aprovar item

Mover OS de etapa

Etapas do quadro

Criar etapa (dono)

Renomear ou mover etapa (dono)

Serviços dos técnicos e quadro por técnico

Atribuir técnico ou renomear serviço

Marcar serviço como travado (com motivo)

Concluir serviço

Pausar serviço

Iniciar serviço (pausa o que o técnico estava fazendo)

Criar serviço avulso na OS

Quadro por técnico

Equipe

Equipe

Cadastrar pessoa na equipe (dono)

Alterar papel, ativar/desativar ou trocar senha (dono)

Nome e logo da unidade

Nome e logo da oficina

Trocar o nome de exibição (dono)

Baixar a logo

Enviar ou trocar a logo (dono)

Remover a logo (dono)

Unidades da empresa e troca de unidade

Abrir outra unidade

Minhas unidades

Criar unidade (dono da empresa)

Lembretes de retorno (troca de óleo, revisão…)

Regras de retorno

Criar regra (dono)

Alterar regra (dono)

Clientes para avisar (retorno)

Avisar um cliente pelo Falia (ou marcar para não avisar)

WhatsApp da oficina pelo Falia

Situação da conexão com o Falia

Conectar o Falia (dono)

Desconectar o Falia (dono)

Página do cliente (link de aprovação)

Cliente: aprovar ou recusar itens

Cliente: logo da oficina

Cliente: foto do orçamento

Cliente: ver o orçamento

Chaves para integrações

Listar API keys ativas

Criar API key

Revogar API key

Notificações de eventos para sistemas externos

Reenviar uma entrega