API de Verificacion de Autos Chinos por VIN — Documentacion, Ejemplos de Codigo e Integracion

China Vehicle History API es la unica interfaz programatica para obtener el historial de vehiculos chinos: accidentes, odometro, propietarios, registros de seguro y servicio. Los servicios tradicionales como Carfax o AutoCheck cubren vehiculos con historial en Norteamerica pero no tienen datos de China. Los servicios europeos como Vincario cubren especificaciones pero no historial. Nuestra API llena ese vacio para desarrolladores, concesionarios e importadores en Mexico, Chile y Colombia.

En esta guia encontraras la documentacion completa de la API: autenticacion, endpoints, ejemplos de solicitudes y respuestas en Python, Node.js y PHP, estructura de respuestas JSON y casos de integracion. Material tecnico para desarrolladores que integran verificacion de autos chinos por VIN en sus sistemas.

Inicio Rapido — Tu Primera Solicitud en 5 Minutos

La API usa protocolo REST estandar. Todas las solicitudes y respuestas son en formato JSON. La autenticacion es mediante API key en el encabezado Authorization.

URL Base y Autenticacion

Base URL: https://api.chinavehiclehistory.com/v1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

El API key se entrega al registrarse en el programa de socios. Para obtener tu clave, contactanos via WhatsApp — el acceso se proporciona a clientes B2B (concesionarios, importadores de vehiculos chinos, desarrolladores de plataformas automotrices).

Primera Solicitud — Decodificacion VIN (cURL)

curl -X POST https://api.chinavehiclehistory.com/v1/decode \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin": "LGXCE6CB9P0123456"}'

Ejemplo de Respuesta

{
  "success": true,
  "data": {
    "vin": "LGXCE6CB9P0123456",
    "brand": "BYD",
    "model": "Song Plus DM-i",
    "year": 2023,
    "plant": "Shenzhen",
    "engine": "BYD476ZQB",
    "engine_volume": "1.5L",
    "fuel_type": "PHEV",
    "transmission": "E-CVT",
    "body_type": "SUV",
    "color": "White",
    "power_kw": 81,
    "battery_capacity_kwh": 18.3,
    "curb_weight_kg": 1780,
    "made_in": "China"
  }
}

Referencia de Endpoints

La API proporciona 6 endpoints que cubren el ciclo completo de verificacion de un auto chino: desde la decodificacion del VIN hasta la obtencion del historial de servicio.

1. POST /v1/decode — Decodificacion VIN (Basic)

Retorna las especificaciones de fabrica del vehiculo por VIN: marca, modelo, ano, motor, transmision, tipo de carroceria, peso, tipo de combustible. Solicitud sincronica — la respuesta es instantanea.

// Solicitud
POST /v1/decode
{
  "vin": "LGXCE6CB9P0123456",
  "email": "partner@example.com",
  "plan": "basic"
}

// Respuesta
{
  "success": true,
  "data": {
    "brand": "BYD",
    "model": "Song Plus DM-i",
    "series": "Song Plus",
    "year": 2023,
    "price_cny": 159800,
    "engine": "BYD476ZQB 1.5L",
    "power_kw": 81,
    "transmission": "E-CVT",
    "fuel_type": "PHEV",
    "body_type": "SUV",
    "dimensions": "4705x1890x1680mm",
    "curb_weight_kg": 1780,
    "fuel_consumption_l100km": 4.4,
    "plant": "Shenzhen"
  },
  "fromCache": false
}

2. POST /v1/history — Historial Completo (Standard)

Retorna especificaciones + historial de seguro de bases de datos chinas: registros de accidentes, pagos de seguros (PICC, Ping An, CPIC), cronologia de odometro, cantidad de propietarios, estado de robo y gravamenes. Solicitud sincronica.

// Solicitud
POST /v1/history
{
  "vin": "LGXCE6CB9P0123456",
  "email": "partner@example.com",
  "plan": "standard"
}

// Respuesta (fragmento)
{
  "success": true,
  "data": {
    "vehicleInfo": { ... },
    "insuranceInfo": {
      "total_claims": 2,
      "claims": [
        {
          "date": "2024-03-15",
          "type": "collision",
          "amount_cny": 8500,
          "description": "Rear bumper damage",
          "insurer": "PICC"
        },
        {
          "date": "2024-09-22",
          "type": "minor_scratch",
          "amount_cny": 1200,
          "description": "Left door scratch",
          "insurer": "Ping An"
        }
      ],
      "mileage_records": [
        {"date": "2023-06-01", "km": 5200},
        {"date": "2024-01-15", "km": 18400},
        {"date": "2024-09-22", "km": 34100}
      ],
      "owners_count": 1,
      "theft_status": "clear",
      "lien_status": "clear"
    }
  }
}

3. POST /v1/premium — Reporte Completo con Historial de Servicio (Premium, asincrono)

Incluye todo del Standard + registros de mantenimiento de concesionarios autorizados y talleres independientes, estado de recalls. Solicitud asincrona — la API retorna un order_id con el cual consultas el estado y obtienes el resultado. Soporta webhook (callback_url) para notificacion cuando el reporte esta listo.

// Solicitud
POST /v1/premium
{
  "vin": "LGXCE6CB9P0123456",
  "email": "partner@example.com",
  "plan": "premium",
  "engine": "BYD476ZQB",
  "callback_url": "https://yoursite.com/webhook/report-ready"
}

// Respuesta
{
  "success": true,
  "order_id": "ord_abc123def456",
  "status": "processing",
  "message": "Report is being generated. Poll /v1/premium/status/ord_abc123def456 or wait for webhook."
}

4. GET /v1/premium/status/{orderId} — Estado del Reporte Premium

Verifica el estado de procesamiento del reporte premium asincrono. Retorna el estado (pending, processing, completed, failed) y el porcentaje de progreso.

// Solicitud
GET /v1/premium/status/ord_abc123def456?email=partner@example.com

// Respuesta
{
  "success": true,
  "status": "completed",
  "progress": 100
}

5. GET /v1/premium/results/{orderId} — Resultado del Reporte Premium

Obtiene el reporte premium una vez completado el procesamiento. Retorna vehicleInfo, insuranceInfo y el arreglo maintenanceRecords con registros de servicios autorizados.

// Solicitud
GET /v1/premium/results/ord_abc123def456?email=partner@example.com

// Respuesta (fragmento)
{
  "success": true,
  "data": {
    "vehicleInfo": { ... },
    "insuranceInfo": { ... },
    "maintenanceRecords": [
      {
        "date": "2023-08-10",
        "mileage_km": 10200,
        "service_type": "Scheduled maintenance",
        "items": ["Engine oil change", "Oil filter", "Air filter"],
        "dealer": "BYD Shenzhen Authorized Service",
        "oem_parts": true
      },
      {
        "date": "2024-05-20",
        "mileage_km": 25600,
        "service_type": "Scheduled maintenance",
        "items": ["Brake fluid replacement", "Cabin air filter", "Battery health check"],
        "dealer": "BYD Guangzhou Service Center",
        "oem_parts": true
      }
    ]
  }
}

6. POST /v1/lookup/plate — Buscar VIN por Placa China

Encuentra el VIN de un vehiculo usando su numero de placa chino. Util cuando el cliente tiene la placa pero no el VIN.

// Solicitud
POST /v1/lookup/plate
{
  "license_plate": "京A12345",
  "vehicle_type": "02"
}

// Respuesta
{
  "success": true,
  "vin": "LGXCE6CB9P0123456"
}

Ejemplos de Codigo — Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.chinavehiclehistory.com/v1"

def decode_vin(vin: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/decode",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "vin": vin,
            "email": "partner@example.com",
            "plan": "basic"
        }
    )
    response.raise_for_status()
    return response.json()

def get_history(vin: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/history",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "vin": vin,
            "email": "partner@example.com",
            "plan": "standard"
        }
    )
    response.raise_for_status()
    return response.json()

# Ejemplo de uso
result = decode_vin("LGXCE6CB9P0123456")
print(f"Marca: {result['data']['brand']}")
print(f"Modelo: {result['data']['model']}")
print(f"Ano: {result['data']['year']}")

Ejemplos de Codigo — Node.js

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.chinavehiclehistory.com/v1";

async function decodeVin(vin) {
  const response = await fetch(`${BASE_URL}/decode`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      vin,
      email: "partner@example.com",
      plan: "basic"
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

async function getHistory(vin) {
  const response = await fetch(`${BASE_URL}/history`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      vin,
      email: "partner@example.com",
      plan: "standard"
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Ejemplo de uso
const result = await decodeVin("LGXCE6CB9P0123456");
console.log(`Marca: ${result.data.brand}`);
console.log(`Modelo: ${result.data.model}`);

Ejemplos de Codigo — PHP

<?php

$apiKey = "YOUR_API_KEY";
$baseUrl = "https://api.chinavehiclehistory.com/v1";

function decodeVin(string $vin): array {
    global $apiKey, $baseUrl;

    $ch = curl_init("$baseUrl/decode");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer $apiKey",
            "Content-Type: application/json"
        ],
        CURLOPT_POSTFIELDS => json_encode([
            "vin" => $vin,
            "email" => "partner@example.com",
            "plan" => "basic"
        ])
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("API error: $httpCode");
    }

    return json_decode($response, true);
}

// Ejemplo de uso
$result = decodeVin("LGXCE6CB9P0123456");
echo "Marca: " . $result["data"]["brand"] . "\n";
echo "Modelo: " . $result["data"]["model"] . "\n";

Manejo de Errores

La API retorna codigos de estado HTTP estandar. Se recomienda manejar los siguientes codigos en tu aplicacion:

• 200 OK — solicitud exitosa, datos en el cuerpo de la respuesta
• 400 Bad Request — VIN incorrecto (no tiene 17 caracteres), faltan campos obligatorios (vin, email, plan)
• 401 Unauthorized — API key invalido o ausente en el encabezado Authorization
• 404 Not Found — vehiculo no encontrado en la base de datos con el VIN o placa proporcionado
• 429 Too Many Requests — limite de solicitudes excedido. Usa backoff exponencial antes de reintentar
• 500 Internal Server Error — error del servidor. Reintenta la solicitud despues de 5-10 segundos

Casos de Integracion en Latinoamerica

La API de verificacion de autos chinos por VIN se integra en varios tipos de sistemas de negocio en el mercado latinoamericano:

• Importadores de vehiculos chinos — verificacion automatica de cada vehiculo antes de la compra en China. El VIN llega del agente en origen, la API retorna el historial, el gerente decide si comprar
• Concesionarios de autos usados — integracion en el DMS (Dealer Management System). Al recibir un auto chino como parte de pago, el vendedor escanea el VIN y el sistema consulta automaticamente el reporte
• Marketplaces automotrices — enriquecimiento de anuncios con datos verificados. El vendedor ingresa el VIN en Mercado Libre, Kavak o tu plataforma propia, y el comprador ve el historial verificado
• Agentes aduanales — obtencion de especificaciones tecnicas exactas para calculo de aranceles. La API confirma cilindrada, peso, tipo de combustible y ano de fabricacion para la documentacion ante ANAM (Mexico), DIAN (Colombia) o Aduanas (Chile)
• Aseguradoras — evaluacion de riesgo al asegurar vehiculos importados. La API muestra el historial de accidentes y pagos de seguro en China, datos que no estan disponibles en las bases de datos de seguros latinoamericanas
• Plataformas de inspeccion vehicular — integracion con servicios de revision tecnica y peritaje que necesitan verificar las especificaciones originales de fabrica contra el vehiculo fisico

Comparacion con Otras API del Mercado

En el mercado latinoamericano e internacional existen varias API para verificacion vehicular. Ninguna de ellas proporciona historial de vehiculos chinos:

• Carfax / AutoCheck API — datos de vehiculos con historial en Estados Unidos y Canada. Excelente cobertura norteamericana pero cero datos de vehiculos fabricados o usados en China. Un BYD importado aparecera sin historial
• Vincario API — servicio europeo con buena documentacion. Cubre especificaciones de autos chinos pero NO historial (accidentes, odometro, propietarios)
• Autofact API (Chile) — datos de vehiculos registrados en Chile: multas, revision tecnica, duenos. No incluye historial previo a la importacion
• RUNT (Colombia) — historico vehicular colombiano. Solo cubre el periodo desde que el vehiculo fue registrado en Colombia
• China Vehicle History API — la unica API con historial de bases de datos chinas: accidentes, registros de seguro (PICC, Ping An, CPIC), cronologia de odometro, historial de servicio y datos de propietarios

Tarifas de la API

La API esta disponible en tres planes con credito prepagado:

• Basic ($20/reporte) — hasta 100 solicitudes mensuales, acceso completo a la API, soporte estandar
• Professional ($18/reporte) — 100-500 solicitudes mensuales, acceso completo, soporte prioritario
• Enterprise ($16/reporte) — 1000+ solicitudes mensuales, funcionalidad completa, gerente dedicado, condiciones personalizadas

Para volumenes mayoristas y condiciones personalizadas, contactanos directamente. Para verificaciones individuales sin integracion API, ofrecemos reportes desde $1.99 por vehiculo a traves de nuestra plataforma web.

Preguntas Frecuentes

¿Que marcas chinas son compatibles?

Todos los principales fabricantes chinos: BYD, Geely, Great Wall (Haval, Tank, Poer), Changan, Chery (Tiggo, Omoda, Jaecoo), GAC, SAIC (MG), Zeekr, NIO, Xpeng, Li Auto, Voyah, Dongfeng, FAW, BAIC, Jetour, Deepal, Avatr. Tambien se soportan vehiculos de marcas extranjeras fabricados en plantas chinas.

¿Se puede probar la API antes de contratar?

Si. Comienza con la decodificacion VIN gratuita en nuestro sitio web para evaluar la calidad de los datos. Para probar el acceso API, contactanos — proporcionamos solicitudes de prueba.

¿En que se diferencia la API de la consulta manual en el sitio?

Los datos son identicos. La diferencia es el metodo de acceso: a traves del sitio web — manualmente, un VIN a la vez. A traves de la API — programaticamente, integrado en tu sistema, automaticamente al recibir un nuevo vehiculo. La API es ideal para empresas que verifican mas de 50 vehiculos al mes.

¿Hay webhook para reportes asincronos?

Si. Al solicitar un reporte Premium, envia el parametro callback_url — la API enviara una solicitud POST a tu URL cuando el reporte este listo. Esto es mas eficiente que consultar el estado periodicamente.

Como Obtener Tu API Key

Contactanos via WhatsApp para obtener tu API key y discutir el plan adecuado. Indicanos tu tipo de negocio y el volumen estimado de solicitudes — te recomendaremos el plan optimo. Para verificaciones individuales sin integracion tecnica, puedes usar directamente nuestro decodificador VIN gratuito o solicitar reportes completos desde la plataforma web.