Financeiro

Gerencie registros financeiros da sua loja ou shopping automotivo: comissões de venda, despesas operacionais, custos de preparação de veículos e receitas.

GET /v1/financial

Lista todos os registros financeiros.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Página atual
`limit`	number	20	Itens por página (máx: 100)
`type`	string	-	Filtrar por tipo: `revenue`, `expense`, `cost`
`status`	string	-	Filtrar por status: `pending`, `paid`, `cancelled`
`category`	string	-	Filtrar por categoria
`vehicle_id`	string	-	Filtrar por veículo
`client_id`	string	-	Filtrar por cliente
`from`	string	-	Data inicial (YYYY-MM-DD)
`to`	string	-	Data final (YYYY-MM-DD)
`sort`	string	`-date`	Ordenação

Request

curl -X GET "https://api.shopcar.com.br/v1/financial?type=revenue&status=pending" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "fin_abc123def456",
      "type": "revenue",
      "category": "venda-veiculo",
      "description": "Venda Honda Civic EXL 2024",
      "amount": 142900.00,
      "currency": "BRL",
      "date": "2026-02-15",
      "due_date": "2026-02-28",
      "status": "pending",
      "vehicle": {
        "id": "veh_xyz789",
        "title": "Honda Civic EXL 2.0 2024",
        "plate": "ABC1D23"
      },
      "client": {
        "id": "cli_abc123",
        "name": "João da Silva"
      },
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

POST /v1/financial

Cria um novo registro financeiro.

Request Body

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Tipo: `revenue`, `expense`, `cost`
`category`	string	Sim	Categoria do registro
`description`	string	Sim	Descrição
`amount`	number	Sim	Valor
`currency`	string	Não	Moeda (padrão: `BRL`)
`date`	string	Sim	Data do registro (YYYY-MM-DD)
`due_date`	string	Não	Data de vencimento (YYYY-MM-DD)
`paid_date`	string	Não	Data do pagamento (YYYY-MM-DD)
`status`	string	Não	Status: `pending`, `paid` (padrão: `pending`)
`vehicle_id`	string	Não	ID do veículo vinculado
`client_id`	string	Não	ID do cliente vinculado
`payment_method`	string	Não	Método de pagamento
`invoice_number`	string	Não	Número da nota fiscal
`notes`	string	Não	Observações
`metadata`	object	Não	Dados customizados

Tipos de Registro

Tipo	Descrição
`revenue`	Receita (vendas de veículos, comissões, etc.)
`expense`	Despesa operacional
`cost`	Custo de preparação de veículo (funilaria, mecânica, etc.)

Categorias Sugeridas

Receitas (revenue):

venda-veiculo - Venda de veículo
comissao - Comissão de venda
financiamento - Comissão de financiamento
seguro - Comissão de seguro

Despesas (expense):

aluguel - Aluguel da loja/pátio
pessoal - Folha de pagamento
marketing - Marketing e publicidade
tecnologia - Software e tecnologia

Custos (cost):

funilaria - Funilaria e pintura
mecanica - Revisão mecânica
higienizacao - Higienização e polimento
documentacao - Documentação e transferência

Request

curl -X POST https://api.shopcar.com.br/v1/financial \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "revenue",
    "category": "venda-veiculo",
    "description": "Venda Honda Civic EXL 2024 - Parcela 1/3",
    "amount": 47633.33,
    "date": "2026-02-15",
    "due_date": "2026-02-28",
    "vehicle_id": "veh_xyz789ghi012",
    "client_id": "cli_abc123def456",
    "notes": "Primeira parcela conforme contrato de venda"
  }'

Response

{
  "success": true,
  "data": {
    "id": "fin_new123abc456",
    "type": "revenue",
    "category": "venda-veiculo",
    "description": "Venda Honda Civic EXL 2024 - Parcela 1/3",
    "amount": 47633.33,
    "currency": "BRL",
    "date": "2026-02-15",
    "due_date": "2026-02-28",
    "status": "pending",
    "vehicle_id": "veh_xyz789ghi012",
    "client_id": "cli_abc123def456",
    "notes": "Primeira parcela conforme contrato de venda",
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

GET /v1/financial/:id

Busca um registro específico.

Request

curl -X GET https://api.shopcar.com.br/v1/financial/fin_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "fin_abc123def456",
    "type": "revenue",
    "category": "venda-veiculo",
    "description": "Venda Honda Civic EXL 2024",
    "amount": 142900.00,
    "currency": "BRL",
    "date": "2026-02-15",
    "due_date": "2026-02-28",
    "paid_date": null,
    "status": "pending",
    "vehicle": {
      "id": "veh_xyz789",
      "title": "Honda Civic EXL 2.0 2024",
      "plate": "ABC1D23"
    },
    "client": {
      "id": "cli_abc123",
      "name": "João da Silva",
      "email": "joao@email.com"
    },
    "payment_method": null,
    "invoice_number": null,
    "notes": "Primeira parcela conforme contrato de venda",
    "metadata": {},
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-04T14:00:00Z"
  }
}

PUT /v1/financial/:id

Atualiza um registro financeiro.

Request

curl -X PUT https://api.shopcar.com.br/v1/financial/fin_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paid",
    "paid_date": "2026-02-25",
    "payment_method": "pix",
    "invoice_number": "NF-2026-0001"
  }'

Response

{
  "success": true,
  "data": {
    "id": "fin_abc123def456",
    "status": "paid",
    "paid_date": "2026-02-25",
    "payment_method": "pix",
    "invoice_number": "NF-2026-0001",
    "updated_at": "2026-02-25T10:00:00Z"
  }
}

DELETE /v1/financial/:id

Cancela um registro financeiro.

Registros pagos não podem ser cancelados. Crie um registro de estorno se necessário.

Request

curl -X DELETE https://api.shopcar.com.br/v1/financial/fin_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "fin_abc123def456",
    "status": "cancelled",
    "cancelled_at": "2026-02-04T15:00:00Z"
  }
}

GET /v1/financial/summary

Retorna um resumo financeiro do período.

Query Parameters

Parâmetro	Tipo	Descrição
`from`	string	Data inicial (YYYY-MM-DD)
`to`	string	Data final (YYYY-MM-DD)
`group_by`	string	Agrupar por: `day`, `week`, `month` (padrão: `month`)

Request

curl -X GET "https://api.shopcar.com.br/v1/financial/summary?from=2026-01-01&to=2026-12-31" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "period": {
      "from": "2026-01-01",
      "to": "2026-12-31"
    },
    "totals": {
      "revenue": 4500000.00,
      "expense": 320000.00,
      "cost": 185000.00,
      "profit": 3995000.00
    },
    "pending": {
      "revenue": 750000.00,
      "expense": 15000.00,
      "cost": 25000.00
    },
    "by_category": {
      "venda-veiculo": 3800000.00,
      "comissao": 500000.00,
      "financiamento": 200000.00
    },
    "by_month": [
      {
        "month": "2026-01",
        "revenue": 350000.00,
        "expense": 25000.00,
        "cost": 15000.00,
        "profit": 310000.00
      },
      {
        "month": "2026-02",
        "revenue": 420000.00,
        "expense": 28000.00,
        "cost": 18000.00,
        "profit": 374000.00
      }
    ],
    "top_clients": [
      {
        "client_id": "cli_abc123",
        "name": "AutoPeças ABC Ltda",
        "total_revenue": 850000.00
      },
      {
        "client_id": "cli_def456",
        "name": "João da Silva",
        "total_revenue": 450000.00
      }
    ]
  }
}

GET /v1/financial/overdue

Lista registros financeiros em atraso.

Request

curl -X GET https://api.shopcar.com.br/v1/financial/overdue \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "fin_overdue123",
      "type": "revenue",
      "category": "venda-veiculo",
      "description": "Venda Toyota Corolla - Parcela 2/3",
      "amount": 45000.00,
      "due_date": "2026-01-31",
      "days_overdue": 4,
      "client": {
        "id": "cli_abc123",
        "name": "João da Silva"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "pages": 1
  }
}

Status dos Registros

Status	Descrição
`pending`	Pendente de pagamento
`paid`	Pago/Recebido
`cancelled`	Cancelado

Métodos de Pagamento

Método	Descrição
`pix`	PIX
`boleto`	Boleto bancário
`cartao`	Cartão de crédito/débito
`transferencia`	Transferência bancária
`financiamento`	Financiamento bancário
`dinheiro`	Dinheiro
`cheque`	Cheque

Erros Comuns

Código	Erro	Solução
`400`	`Invalid type`	Use: `revenue`, `expense` ou `cost`
`400`	`Invalid amount`	Valor deve ser maior que zero
`400`	`Invalid date format`	Use formato YYYY-MM-DD
`404`	`Record not found`	Verifique o ID
`422`	`Cannot cancel paid record`	Registros pagos não podem ser cancelados

Financeiro

On this page