Para desenvolvedores

API pública de leitura

Leve os dados do seu carro para fora do Carllog: um sensor no Home Assistant, um painel na TV, uma planilha, um script. A API só lê — ela não destrava, não liga o ar e não acorda o carro — e cada token enxerga apenas os carros da sua conta, com as permissões que você escolheu.

Primeiros passos

Entre no Carllog e abra Conta › API.
Crie um token: dê um nome, escolha as permissões, os carros e a validade (até 1 ano).
Copie o token na hora — ele aparece uma única vez. Se perder, revogue e crie outro.
Mande o token no cabeçalho Authorization de cada chamada, como Bearer.

export CARLLOG_TOKEN="cole o token aqui"

curl https://carllog.com/api/public/v1/vehicles \
  -H "Authorization: Bearer $CARLLOG_TOKEN"

Endereço: https://carllog.com/api/public/v1
Método: Só GET. Toda resposta é JSON em UTF-8.
Datas: RFC 3339 em UTC, como 2026-10-26T14:05:12Z.
Unidades: km, km/h, %, kWh, kW e litros; o nome de cada campo diz qual.
Plano: A API faz parte da assinatura (o período de teste conta). Com o plano vencido ela responde 402, e o token volta a funcionar na renovação.

Integrar com IA

Vai pedir a integração para o ChatGPT, o Claude ou outra IA? Passe este endereço: ele tem esta referência inteira num texto só, em Markdown, pronto para a IA ler.

https://carllog.com/developers/api/llms.txt

Por exemplo: “Leia https://carllog.com/developers/api/llms.txt e crie no meu Home Assistant sensores de bateria, autonomia e carregamento do meu carro.” Não cole o token na conversa — deixe a IA usar um lugar para ele, como secrets.yaml ou uma variável de ambiente, e coloque o token você mesmo.

Permissões

Cada token tem uma ou mais permissões, escolhidas quando você o cria. Uma rota fora das permissões do token responde 403. Dê a cada uso só o que ele precisa — um painel de bateria não precisa saber onde o carro está.

Carros e estadovehicles:read

A lista dos carros e o estado atual de cada um: bateria, autonomia, odômetro, carga e travas. Nunca inclui coordenadas.

Localizaçãolocation:read

A última posição de GPS e, junto com o histórico, os pontos de início e fim e o trajeto de cada viagem. Dê só a quem precisa de saber onde o carro está.

Históricohistory:read

Viagens, recargas e abastecimentos. Sem a permissão de localização, os lugares vêm só pelo nome.

Um token também pode ser limitado a alguns carros. Pedir um carro da sua conta que ficou de fora responde 403; um VIN que não é da sua conta responde 404.

Limites e atualização

Por token: 60 chamadas por minuto, com picos de até 10 seguidas.
Por conta: 120 chamadas por minuto, somando todos os tokens.
Ao passar: Resposta 429 com o cabeçalho Retry-After, em segundos.
Atualização: A API devolve o que a coleta do Carllog já leu do carro: os dados mudam a cada poucos minutos, e o carro parado dorme. Toda resposta traz Cache-Control: private, max-age=60 — consultar mais de uma vez por minuto não traz nada novo. A cada 5 minutos é um bom ritmo.
Validade: Até 5 tokens ativos por conta, cada um com validade de 1 dia a 1 ano. Um token sem uso por 180 dias é revogado sozinho.

Paginação

Viagens, recargas e abastecimentos vêm do mais recente para o mais antigo, em páginas. Cada resposta traz items e next_cursor; para a página seguinte, repita a chamada com cursor igual a esse valor. Quando next_cursor vier null, acabou.

curl "https://carllog.com/api/public/v1/vehicles/SEU_VIN/trips?limit=20&from=2026-10-01T00:00:00-03:00" \
  -H "Authorization: Bearer $CARLLOG_TOKEN"

As datas na URL levam fuso; o + de um fuso positivo precisa ir como %2B.

Listar carros

GET/vehiclesvehicles:read

Os carros da sua conta que o token pode ler. Use o vin de cada um nas outras rotas.

Um token restrito a alguns carros só lista esses. Sem restrição, entram também os carros que você conectar depois.

Campos da resposta

itemslista: Um item por carro, com os campos abaixo.
vinstring: O chassi (VIN), que identifica o carro nas outras rotas.
namestring: O apelido que você deu no app da BYD, ou o modelo quando não há apelido.
modelstring | null: Modelo, como a BYD informa (ex.: DOLPHIN MINI).
brandstring | null: Marca.
platestring | null: Placa, em maiúsculas.
last_seen_atdata-hora: Última vez que a coleta encontrou o carro na sua conta da BYD.

Exemplo de resposta

{
  "items": [
    {
      "vin": "LC0EXAMPLE0000001",
      "name": "Dolphin Mini",
      "model": "DOLPHIN MINI",
      "brand": "BYD",
      "plate": "ABC1D23",
      "last_seen_at": "2026-10-26T14:05:12Z"
    }
  ]
}

Estado atual

GET/vehicles/{vin}/statevehicles:read

A leitura mais recente do carro: bateria, autonomia, odômetro, combustível nos híbridos, carga e travas. Nunca traz coordenadas — para isso, use /location.

Qualquer campo pode vir null quando o carro não informou aquele dado na última leitura (comum com o carro dormindo).

Os valores de texto podem ganhar novas opções no futuro; trate um valor desconhecido como "desconhecido". Um código que ainda não decodificamos vem como code=N.

Campos da resposta

vinstring: O chassi pedido.
captured_atdata-hora | null: Quando a leitura foi feita. null se o carro ainda não tem nenhuma.
soc_percentinteiro | null: Carga da bateria, em %.
range_kminteiro | null: Autonomia elétrica que o carro estima, em km.
odometer_kminteiro | null: Odômetro, em km.
fuel_percentinteiro | null: Tanque, em % (só híbridos).
fuel_range_kminteiro | null: Autonomia a combustão, em km (só híbridos).
chargingboolean | null: true quando charge_state é charging.
charge_statestring | null: not_connected (sem cabo), charging (carregando), scheduled (carga agendada), idle (cabo ligado, sem carregar) ou idle_asleep (idem, com o carro dormindo).
connectorstring | null: plugged_in (cabo conectado), not_connected ou unknown_asleep (o carro dormia e não respondeu).
power_statestring | null: on (ligado), off (desligado) ou unknown.
lockedboolean | null: true só quando todas as portas com leitura estão trancadas; null quando nenhuma porta informou.
doors_lockedobjeto: Uma trava por porta: front_left, front_right, rear_left e rear_right. Cada uma true (trancada), false (destrancada) ou null (sem leitura).
trunk_lockedboolean | null: Porta-malas trancado.

Exemplo de resposta

{
  "vin": "LC0EXAMPLE0000001",
  "captured_at": "2026-10-26T14:05:12Z",
  "soc_percent": 78,
  "range_km": 221,
  "odometer_km": 18342,
  "fuel_percent": null,
  "fuel_range_km": null,
  "charging": false,
  "charge_state": "not_connected",
  "connector": "not_connected",
  "power_state": "off",
  "locked": true,
  "doors_locked": {
    "front_left": true,
    "front_right": true,
    "rear_left": true,
    "rear_right": true
  },
  "trunk_locked": true
}

Localização

GET/vehicles/{vin}/locationlocation:read

A última posição de GPS que o carro informou. Parado, o carro costuma não responder ao GPS; aí vem a última posição conhecida, com a hora em que ela foi lida.

Campos da resposta

vinstring: O chassi pedido.
captured_atdata-hora | null: Quando essa posição foi lida.
latitudenúmero | null: Latitude, em graus decimais (WGS 84).
longitudenúmero | null: Longitude, em graus decimais (WGS 84).

Exemplo de resposta

{
  "vin": "LC0EXAMPLE0000001",
  "captured_at": "2026-10-26T13:58:40Z",
  "latitude": -23.5614,
  "longitude": -46.6559
}

Viagens

GET/vehicles/{vin}/tripshistory:read

As viagens do carro, da mais recente para a mais antiga, as mesmas que você vê no app: viagens removidas não aparecem e viagens juntadas vêm como uma só.

Parâmetros da URL (todos opcionais)

limit: Quantos itens por página, de 1 a 100. Padrão: 50.
cursor: O next_cursor da página anterior, para pedir a seguinte. Vazio na primeira chamada.
from: Só itens que começaram nesse instante ou depois. Data e hora RFC 3339, como 2026-10-01T00:00:00-03:00.
to: Só itens que começaram até esse instante, inclusive. Mesmo formato de from.

Campos da resposta

idstring: Identificador do evento: o início em segundos desde 1970 (Unix), em texto.
start_atdata-hora: Quando começou.
end_atdata-hora: Quando terminou, ou a última leitura se ainda está em andamento.
duration_secinteiro: Duração, em segundos.
is_openboolean: true enquanto o evento ainda está acontecendo; os números podem mudar até ele fechar.
distance_kminteiro | null: Distância pelo odômetro, em km.
start_socinteiro | null: Bateria na saída, em %.
end_socinteiro | null: Bateria na chegada, em %.
kwh_usednúmero | null: Energia gasta na viagem, em kWh, estimada pela bateria consumida e a capacidade do carro.
start_fuelinteiro | null: Tanque na saída, em % (híbridos).
end_fuelinteiro | null: Tanque na chegada, em % (híbridos).
liters_usednúmero | null: Combustível gasto, em litros (híbridos).
max_speed_kmhnúmero | null: Velocidade máxima registrada, em km/h.
avg_speed_kmhnúmero | null: Velocidade média, em km/h.
start_placestring | null: Nome do lugar de saída: um lugar seu (Casa, Trabalho) ou o endereço.
end_placestring | null: Nome do lugar de chegada.
start{ latitude, longitude }: Ponto de saída. Omitido quando não houve posição.só com Localização
end{ latitude, longitude }: Ponto de chegada. Omitido quando não houve posição.só com Localização
pathlista de [longitude, latitude]: O trajeto pelos pontos de GPS registrados, na ordem do GeoJSON (longitude primeiro). Não é a rua exata. Omitido quando a viagem não tem pontos.só com Localização
next_cursordata-hora | null: Passe em cursor para a próxima página. null na última.

Exemplo de resposta

{
  "items": [
    {
      "id": "1761483600",
      "start_at": "2026-10-26T13:00:00Z",
      "end_at": "2026-10-26T13:32:10Z",
      "duration_sec": 1930,
      "is_open": false,
      "distance_km": 18,
      "start_soc": 86,
      "end_soc": 78,
      "kwh_used": 2.4,
      "start_fuel": null,
      "end_fuel": null,
      "liters_used": null,
      "max_speed_kmh": 74,
      "avg_speed_kmh": 33.6,
      "start_place": "Casa",
      "end_place": "Trabalho"
    }
  ],
  "next_cursor": "2026-10-26T13:00:00Z"
}

Recargas

GET/vehicles/{vin}/chargeshistory:read

As recargas do carro, da mais recente para a mais antiga.

Parâmetros da URL (todos opcionais)

limit: Quantos itens por página, de 1 a 100. Padrão: 50.
cursor: O next_cursor da página anterior, para pedir a seguinte. Vazio na primeira chamada.
from: Só itens que começaram nesse instante ou depois. Data e hora RFC 3339, como 2026-10-01T00:00:00-03:00.
to: Só itens que começaram até esse instante, inclusive. Mesmo formato de from.

Campos da resposta

idstring: Identificador do evento: o início em segundos desde 1970 (Unix), em texto.
start_atdata-hora: Quando começou.
end_atdata-hora: Quando terminou, ou a última leitura se ainda está em andamento.
duration_secinteiro: Duração, em segundos.
is_openboolean: true enquanto o evento ainda está acontecendo; os números podem mudar até ele fechar.
start_socinteiro | null: Bateria no início, em %.
end_socinteiro | null: Bateria no fim, em %.
kwh_addednúmero | null: Energia que entrou na bateria, em kWh, estimada pela capacidade do carro.
avg_power_kwnúmero | null: Potência média, em kW.
placestring | null: O nome do carregador que você cadastrou ou, sem ele, o endereço.
location{ latitude, longitude }: Onde o carro carregou. Omitido quando não houve posição.só com Localização
next_cursordata-hora | null: Passe em cursor para a próxima página. null na última.

Exemplo de resposta

{
  "items": [
    {
      "id": "1761436800",
      "start_at": "2026-10-26T00:00:00Z",
      "end_at": "2026-10-26T04:12:00Z",
      "duration_sec": 15120,
      "is_open": false,
      "start_soc": 31,
      "end_soc": 100,
      "kwh_added": 26.5,
      "avg_power_kw": 6.3,
      "place": "Casa"
    }
  ],
  "next_cursor": null
}

Abastecimentos

GET/vehicles/{vin}/refuelshistory:read

Os abastecimentos dos híbridos, do mais recente para o mais antigo. Num carro só elétrico a lista vem vazia.

Parâmetros da URL (todos opcionais)

limit: Quantos itens por página, de 1 a 100. Padrão: 50.
cursor: O next_cursor da página anterior, para pedir a seguinte. Vazio na primeira chamada.
from: Só itens que começaram nesse instante ou depois. Data e hora RFC 3339, como 2026-10-01T00:00:00-03:00.
to: Só itens que começaram até esse instante, inclusive. Mesmo formato de from.

Campos da resposta

idstring: Identificador do evento: o início em segundos desde 1970 (Unix), em texto.
start_atdata-hora: Quando começou.
end_atdata-hora: Quando terminou, ou a última leitura se ainda está em andamento.
is_openboolean: true enquanto o evento ainda está acontecendo; os números podem mudar até ele fechar.
start_fuelinteiro | null: Tanque antes, em %.
end_fuelinteiro | null: Tanque depois, em %.
liters_addednúmero | null: Litros colocados, estimados pela capacidade do tanque.
placestring | null: O nome do lugar (um lugar que você nomeou ou o endereço).
location{ latitude, longitude }: Onde o carro abasteceu. Omitido quando não houve posição.só com Localização
next_cursordata-hora | null: Passe em cursor para a próxima página. null na última.

Exemplo de resposta

{
  "items": [
    {
      "id": "1761310800",
      "start_at": "2026-10-24T13:00:00Z",
      "end_at": "2026-10-24T13:06:00Z",
      "is_open": false,
      "start_fuel": 22,
      "end_fuel": 100,
      "liters_added": 37.4,
      "place": "Posto Shell Av. Paulista"
    }
  ],
  "next_cursor": null
}

Erros

Um erro vem com o status HTTP e um JSON com a mensagem, em inglês, no campo error:

{ "error": "invalid token" }

400	Um parâmetro inválido, como uma data fora do formato RFC 3339. A mensagem diz qual.
401	Token ausente, incorreto, revogado ou vencido. A resposta é sempre a mesma, de propósito; confira o token na tela Conta › API.
402	A assinatura da conta não está ativa. O token continua valendo e volta a funcionar quando o plano for renovado.
403	O token não tem a permissão que a rota pede, ou foi criado só para outros carros.
404	Esse VIN não é de um carro da sua conta (ou a rota não existe).
405	Método diferente de GET. A API só lê.
429	Passou do limite de chamadas. Espere os segundos do cabeçalho Retry-After.
503	A API está temporariamente desligada.

Exemplo: Home Assistant

Com a integração rest do Home Assistant, três sensores a partir do estado do carro. Troque SEU_VIN pelo vin que aparece em /vehicles. Basta a permissão Carros e estado.

# configuration.yaml
rest:
  - resource: https://carllog.com/api/public/v1/vehicles/SEU_VIN/state
    headers:
      Authorization: !secret carllog_authorization
    scan_interval: 300
    sensor:
      - name: "Bateria do carro"
        value_template: "{{ value_json.soc_percent }}"
        unit_of_measurement: "%"
        device_class: battery
      - name: "Autonomia do carro"
        value_template: "{{ value_json.range_km }}"
        unit_of_measurement: "km"
      - name: "Carro carregando"
        value_template: "{{ value_json.charging }}"

# secrets.yaml — a palavra Bearer, um espaço e o token
carllog_authorization: "Bearer cole o token aqui"