Referência da API

Documentação dos endpoints disponíveis na API pública v1 da Zyraq.

Base URL

https://app.zyraqgroup.com/api/v1

Endpoints Disponíveis

Veículos (Vehicles)

Criar, listar, atualizar e gerenciar veículos do inventário.

GET /api/v1/vehicles — Listar veículos
POST /api/v1/vehicles — Cadastrar veículo
GET /api/v1/vehicles/:id — Buscar veículo
PUT /api/v1/vehicles/:id — Atualizar veículo
DELETE /api/v1/vehicles/:id — Arquivar veículo

Clientes

Gerenciar clientes Pessoa Física e Jurídica.

GET /api/v1/clients — Listar clientes
POST /api/v1/clients — Criar cliente
GET /api/v1/clients/:id — Buscar cliente
PUT /api/v1/clients/:id — Atualizar cliente
DELETE /api/v1/clients/:id — Desativar cliente

Negócios (Deals)

Gerenciar pipeline de vendas de veículos.

GET /api/v1/deals — Listar negócios
POST /api/v1/deals — Criar negócio
GET /api/v1/deals/:id — Buscar negócio
PUT /api/v1/deals/:id — Atualizar/mover/fechar negócio
DELETE /api/v1/deals/:id — Arquivar negócio

Atividades (Em breve)

Registrar e acompanhar atividades e tarefas.

Disponível apenas no painel por enquanto.

Financeiro (Em breve)

Controlar receitas, despesas e comissões.

Disponível apenas no painel por enquanto.

Webhooks (Em breve)

Receber notificações de eventos em tempo real.

Configuração disponível no painel.

Formato das Respostas

Sucesso

{
  "success": true,
  "data": {
    // Dados da resposta
  }
}

Sucesso com Paginação

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'title' é obrigatório"
  }
}

Códigos HTTP

Código	Descrição	Quando Ocorre
`200`	OK	Requisição bem-sucedida
`201`	Created	Recurso criado com sucesso
`400`	Bad Request	Parâmetros inválidos ou campos obrigatórios ausentes
`401`	Unauthorized	API Key ausente ou inválida
`403`	Forbidden	Sem permissão para o recurso
`404`	Not Found	Recurso não encontrado
`422`	Unprocessable Entity	Validação de negócio falhou (ex: placa duplicada)
`429`	Too Many Requests	Limite de requisições excedido
`500`	Internal Server Error	Erro interno

Códigos de Erro

Código	Descrição
`UNAUTHORIZED`	Autenticação falhou
`FORBIDDEN`	Sem permissão
`NOT_FOUND`	Recurso não encontrado
`VALIDATION_ERROR`	Erro de validação (campo obrigatório, formato inválido, etc.)
`DUPLICATE_ENTRY`	Registro duplicado (CPF, CNPJ, placa)
`INTERNAL_ERROR`	Erro interno do servidor
`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido

Autenticação

Todas as requisições requerem autenticação via header Authorization:

Authorization: Bearer ea_live_sua_chave_aqui
Content-Type: application/json

Veja mais em Autenticação.

Paginação

Endpoints que retornam listas suportam paginação via query parameters:

Parâmetro	Padrão	Máximo	Descrição
`page`	1	—	Número da página
`limit`	20	100	Itens por página

GET /api/v1/vehicles?page=2&limit=50

Ordenação

Use o parâmetro sort para ordenar resultados:

# Ordenar por data de criação (mais recente primeiro)
GET /api/v1/vehicles?sort=-created_at

# Ordenar por preço (menor para maior)
GET /api/v1/vehicles?sort=price