Referência da API

Documentação completa de todos os endpoints disponíveis na API Ecosys Auto.

Base URL

https://api.shopcar.com.br/v1

Endpoints Disponíveis

Veículos (Vehicles)

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

GET /v1/vehicles - Listar veículos
POST /v1/vehicles - Cadastrar veículo
GET /v1/vehicles/:id - Buscar veículo
PUT /v1/vehicles/:id - Atualizar veículo
DELETE /v1/vehicles/:id - Remover veículo

Clientes

Gerenciar clientes Pessoa Física e Jurídica.

GET /v1/clients - Listar clientes
POST /v1/clients - Criar cliente
GET /v1/clients/:id - Buscar cliente
PUT /v1/clients/:id - Atualizar cliente
GET /v1/clients/:id/vehicles - Veículos do cliente

Atividades

Registrar e acompanhar atividades e tarefas.

GET /v1/activities - Listar atividades
POST /v1/activities - Criar atividade
PUT /v1/activities/:id - Atualizar atividade
DELETE /v1/activities/:id - Excluir atividade

Negócios (Deals)

Gerenciar pipeline de vendas de veículos.

GET /v1/deals - Listar negócios
POST /v1/deals - Criar negócio
PUT /v1/deals/:id - Atualizar negócio
PUT /v1/deals/:id/phase - Mover no pipeline

Financeiro

Controlar receitas, despesas e comissões.

GET /v1/financial - Listar registros
POST /v1/financial - Criar registro
PUT /v1/financial/:id - Atualizar registro
GET /v1/financial/summary - Resumo financeiro

Webhooks

Receber notificações de eventos em tempo real.

GET /v1/webhooks - Listar webhooks
POST /v1/webhooks - Criar webhook
DELETE /v1/webhooks/:id - Remover webhook

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",
    "details": {
      "field": "title",
      "type": "required"
    }
  }
}

Códigos HTTP

Código	Descrição	Quando Usar
`200`	OK	Requisição bem-sucedida
`201`	Created	Recurso criado com sucesso
`400`	Bad Request	Parâmetros inválidos
`401`	Unauthorized	Falha na autenticação
`403`	Forbidden	Sem permissão para o recurso
`404`	Not Found	Recurso não encontrado
`422`	Unprocessable Entity	Validação de negócio falhou
`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
`DUPLICATE_ENTRY`	Registro duplicado
`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 /v1/vehicles?page=2&limit=50

Filtros

Endpoints suportam filtros via query parameters:

# Filtrar veículos por status e marca
GET /v1/vehicles?status=disponivel&brand=Honda

# Filtrar clientes por tipo e segmento
GET /v1/clients?type=PF&segment=premium

# Filtrar atividades por período
GET /v1/activities?from=2026-01-01&to=2026-01-31

Ordenação

Use o parâmetro sort para ordenar resultados:

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

# Ordenar por título (alfabético)
GET /v1/vehicles?sort=title

Prefixo	Direção
(nenhum)	Ascendente (A-Z, 0-9)
`-`	Descendente (Z-A, 9-0)

Limites de Uso

Plano	Requisições/Minuto	Requisições/Dia
Starter	60	1.000
Professional	300	10.000
Enterprise	1.000	Ilimitado

Exceder os limites resultará em resposta 429 Too Many Requests. Implemente retry com backoff exponencial.

Datas e Horários

Todas as datas usam formato ISO 8601: YYYY-MM-DD
Timestamps incluem timezone: 2026-02-04T10:30:00Z
Sempre retornamos em UTC

Versionamento

A API usa versionamento na URL (/v1). Mudanças breaking serão lançadas em novas versões, garantindo compatibilidade com integrações existentes.

SDKs Oficiais

Estamos desenvolvendo SDKs oficiais:

Linguagem	Status
JavaScript/TypeScript	Em breve
Python	Em breve
PHP	Em breve

Suporte

Email: suporte@shopcar.com.br
Documentação: Você está aqui!