---
title: "Peças por Placa"
description: "Peças de reposição que servem num veículo, a partir da placa e da categoria (filtro de óleo, pastilha de freio, amortecedor, correia dentada...): a versão do veículo no catálogo (modelo, motor, potência e anos) e a lista de peças compatíveis, com marca, código e nome. Cobrada quando a base identifica a versão, inclusive se a categoria não tiver peça para ela; placa não encontrada, veículo fora do catálogo e placa com mais de uma versão possível não são cobrados."
lang: pt-BR
canonical: https://doc.apibrasil.io/apis/creditos/b3276393-de01-11f1-98bb-bc24118aba26
markdown: https://doc.apibrasil.io/apis/creditos/b3276393-de01-11f1-98bb-bc24118aba26.md
source: apibrasil-documentation
---

# Peças por Placa

> Peças de reposição que servem num veículo, a partir da placa e da categoria (filtro de óleo, pastilha de freio, amortecedor, correia dentada...): a versão do veículo no catálogo (modelo, motor, potência e anos) e a lista de peças compatíveis, com marca, código e nome. Cobrada quando a base identifica a versão, inclusive se a categoria não tiver peça para ela; placa não encontrada, veículo fora do catálogo e placa com mais de uma versão possível não são cobrados.

- **Categoria:** Histórico do Veículo
- **Cobrança:** por consulta, só com o Bearer Token
- **Preço:** R$ 2,90 por consulta
- **Limite:** 990.000 por mês
- **Cadastro:** exige CNPJ
- **Versão:** v2
- **Publicada por:** APIBrasil
- **Especificação OpenAPI:** https://doc.apibrasil.io/apis/creditos/b3276393-de01-11f1-98bb-bc24118aba26/openapi.json

## Como chamar

**Endereço base:** `https://gateway.apibrasil.io/api/v2`

Autenticação: cabeçalho `Authorization: Bearer <token>`. Nada além disso.

Com `homolog: true` no corpo, o gateway responde de uma base fixa, com a forma real da resposta, e não cobra. O CPF 00000000000 é dessa base e não é de ninguém: use-o nos testes, nunca em produção.

## Endpoints (1 endpoint)

### 1. POST /consulta/veiculos/credits

⚠️ Aviso: a consulta é cobrada quando a base identifica a versão do veículo, inclusive se a categoria não tiver peça para ela.

Envie um POST com tipo=pecas-por-placa e a placa (padrão antigo ABC1234 ou Mercosul ABC1D23) e a categoria. Categorias: filtro-oleo, filtro-ar, filtro-combustivel, filtro-cabine, pastilha-freio, disco-freio, freio-tambor, amortecedor, coxim-amortecedor, bandeja, pivo, bieleta, terminal-direcao, rolamento-roda, cubo-roda, homocinetica, coifa-homocinetica, kit-embreagem, rolamento-embreagem, correia-dentada, kit-correia-dentada, tensor-correia-dentada, correia-acessorios, bomba-agua, termostato, radiador, vela-ignicao, bobina-ignicao, bateria, alternador, motor-arranque, junta-cabecote e palheta. Opcionais: vehicle_id (a versão escolhida entre as candidatas, ou para repetir sem identificar a placa de novo) e pagina (1 a 50; cada página traz até 100 peças e é cobrada). O campo data traz veiculo (vehicle_id, marca, modelo, versao, combustivel, potencia_cv, cilindradas, fabricado_de, fabricado_ate e identificacao), categoria, total, pagina, paginas e pecas (id, marca, codigo, nome e imagem, que vem null), além da placa consultada. Placa inválida ou categoria fora da lista é recusada com HTTP 400, sem cobrança; placa não encontrada ou veículo fora do catálogo devolve HTTP 404, sem cobrança. Quando a placa corresponde a mais de uma versão, a resposta é HTTP 409, sem cobrança, com dados.candidatas (as versões, cada uma com vehicle_id): repita a consulta com o vehicle_id escolhido. Base de dados indisponível devolve HTTP 502, 503 ou 504, sem cobrança. Disponível para contas PJ. Em homologação (homolog=true), sem cobrança e com qualquer placa válida e uma categoria da lista, a resposta traz dados fictícios.

- **Método:** `POST`
- **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/veiculos/credits`
- **Versão da rota:** v2

**Cabeçalhos**

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer $APIBRASIL_TOKEN` |

**Corpo da requisição**

```json
{
  "tipo": "pecas-por-placa",
  "placa": "ABC1D23",
  "categoria": "filtro-oleo",
  "homolog": true
}
```

**Em cURL**

```bash
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/veiculos/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -d '{"tipo":"pecas-por-placa","placa":"ABC1D23","categoria":"filtro-oleo","homolog":true}'
```

Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação.

**Resposta de exemplo, do catálogo**

```json
{
  "user": {
    "first_name": "[omitido]",
    "email": "[omitido]",
    "cellphone": "[omitido]",
    "notification": "yes"
  },
  "balance": "397,100",
  "balance_before": "400,000",
  "tax": "2,900",
  "status_code": 200,
  "error": false,
  "message": "Dados validos! Voce foi tarifado em R$ 2,90.",
  "valor_consulta": 2.9,
  "api_limit_for": "credit",
  "homolog": false,
  "data": {
    "veiculo": {
      "vehicle_id": 113683,
      "marca": "PEUGEOT",
      "modelo": "2008 I (CU_)",
      "versao": "1.6 Flex",
      "combustivel": "Flex",
      "potencia_cv": 122,
      "cilindradas": 1587,
      "fabricado_de": 2015,
      "fabricado_ate": 2019,
      "identificacao": "exata"
    },
    "categoria": {
      "id": "filtro-oleo",
      "nome": "Filtro de óleo"
    },
    "total": 2,
    "pagina": 1,
    "paginas": 1,
    "pecas": [
      {
        "id": 8357511,
        "marca": "MARCA FICTICIA",
        "codigo": "AB 123/4",
        "nome": "Filtro de óleo",
        "imagem": null
      },
      {
        "id": 7499562,
        "marca": "MARCA FICTICIA",
        "codigo": "CD 567",
        "nome": "Filtro de óleo",
        "imagem": null
      }
    ],
    "placa": "ABC1D23"
  }
}
```

Nos exemplos de resposta, os campos da conta que gerou o exemplo (`user.first_name`, `user.email`, `user.cellphone`) saem como `[omitido]`. O resto é o que o catálogo publica.

## Armadilhas: o que uma integração erra sem avisar

Apuradas nas respostas que o próprio catálogo publica. Em todas elas o código funciona no caminho feliz e falha em silêncio no resto:

1. **O erro chega no CORPO, com HTTP 200.**
   A resposta traz um campo `error` booleano e uma `message`. Checar só `response.ok` ou o status HTTP deixa passar falha como sucesso. Confira SEMPRE `error === false` antes de ler `data`.

2. **`balance`, `tax` e `extra_charges.total` são STRING em formato brasileiro — e o formato varia entre APIs.**
   Valores observados no catálogo: `"154,380"`, `"497,84"`, `"0,000"` e `"0.19"`. Vírgula em umas, ponto em outra; três casas decimais em umas, duas em outra. Em JavaScript, `parseFloat("154,380")` devolve `154` e perde os centavos sem erro nenhum, e `Number("154,380")` devolve `NaN`. Escreva um conversor que trate os dois separadores, e nunca use esses campos numa decisão financeira sem convertê-los.

3. **Cada chamada custa dinheiro.**
   Retry cego multiplica a conta. Nunca repita automaticamente um 4xx: parâmetro errado repetido continua errado e continua cobrando. Repita só tempo esgotado e 5xx, com recuo exponencial e um teto pequeno de tentativas.

4. **HTTP 402 é saldo insuficiente, e repetir não resolve.**
   É o único status que exige ação humana — recarregar. Trate-o como erro terminal, com mensagem própria, e não o jogue no mesmo balde dos 4xx genéricos.

5. **`extra_charges` cobra à parte do preço da consulta.**
   Quando o corpo pede serviços adicionais, a resposta traz cada um com o preço e um `total` que NÃO está incluso no valor base. Se você mostra custo a quem usa, some os dois.

## Ver também

- Especificação OpenAPI: https://doc.apibrasil.io/apis/creditos/b3276393-de01-11f1-98bb-bc24118aba26/openapi.json
- Catálogo de APIs: [Catálogo de APIs](https://doc.apibrasil.io/apis.md)
- SDKs oficiais: [SDKs oficiais](https://doc.apibrasil.io/sdks.md)
- Índice da documentação: https://doc.apibrasil.io/llms.txt
- Versão HTML desta página: https://doc.apibrasil.io/apis/creditos/b3276393-de01-11f1-98bb-bc24118aba26