VIN Analyzer

Una api para analizar números VIN (Números de bastidor) en vehículos retornar datos asociados, y además detectar posibles errores de escritura.

VIN, son las siglas para Vehicle Identification Number. Esta API permite analizar números VIN válidos y extraer los datos asociados a ese VIN.

Esta API permite además, detectar posibles errores de escritura en los VINS y proponer posibles VINS validos cercanos.

Conectando a la API

Servidor y protocolos para la conexión

Conexión a la API
Servidor:	https://zpk.systems
Esquema:	HTTPS, solo conexiones seguras SSL.
Protocolo:	JSON recomendado Enviando un JSON en el body del request, y especificando una cabecera Content-Type: application/json en el request Si envia ficheros como imágenes o documentos, estos deberán estar codificados en base64. Form-Data no recomendado Formato usado en los formularios web, no recomendado. Al enviar una solicitud tipo form_data puede enviar todos los campos como parámetros POST separados. Sin embargo si la solicitud es muy grande recomendamos que envie el contenido de la peticion en un único campo de texto llamado _json (con un guión bajo). Este parametro especial sera procesado por nuestro backend como si se tratase de una solicitud JSON habitual.

El servidor dónde enviar las solicitudes es https://zpk.systems mediante una conexión HTTPS segura.

El tipo de comunicación recomendado es JSON, en cuyo caso especificaremos en la conexión un Content-Type: application/json, y enviaremos el body de la solicitud como un string JSON válido.

Endpoint y parámetros

POST /api/vin-analyzer/analyze
Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
vins	array de strings requerido Uno o más códigos VIN de vehículo.
score_filters	array opcional Cuando se facilite un VIN no válido esa API intentará proponer los VINS correctos que considere mas cercanos al VIN incorrecto facilitado. El array score_filters le permite alterar la puntuación interna que reciben diferentes códigos VIN a partir de datos como zona de fabricación, país de fabricación, nombre del fabricante, o la marca. Permitiendo por ejemplo priorizar VINs de un fabricante o de un país concreto. score_filters debe contener un array de elementos, cada uno de ellos indicando un filtro y una puntuación en caso de que ese filtro se cumpla Ejemplo de score_filters `[ { "zone": "America", "country": "", "manufacturer": "", "brand": "", "score": "0.3" }, { "zone": "Europe", "country": "", "manufacturer": "", "brand": "", "score": "-0.3" } ]` En este ejemplo se han aplicado tres filtros para alterar la puntuación, se quiere dar prioridad a los vehículos fabricados en África, y penalizar los fabricados en América. Adicionalmente se quiere filtrar fuera aquellos fabricantes de tractores, y motocicletas. Los vehículos fabricados en África recibirán un extra de +1 en su puntuación Los vehículos fabricados en América recibirán un penalizador de -1 en la puntuación Todos los fabricantes de motocicletas o tractores recibirán un penalizador -20 en su puntuación Zonas, Paises y Fabricantes Puede obtener estos datos con una llamada a la API, vea obteniendo otros datos.

Respuestas

Respuesta con éxito

Respuesta OK

{
  "success": true,
  "results": [
    {
      "sent": "L6TCX2E70ME005154",
      "vin": {
        "vin_number": "L6TCX2E70ME005154",
        "valid": true,
        "fixed": false,
        "year": 2021,
        "wmi": "L6T",
        "vis": "ME005154",
        "serial": "005154",
        "manufacturer_name": "Geely",
        "uses_manufacturation_plant_code": true,
        "manufacturation_plant_code": "E",
        "manufacturer_code": "L6T",
        "uses_check_digit": true,
        "provided_check_digit": "0",
        "expected_check_digit": "0",
        "valid_check_digit": true,
        "low_volume_manufacturer": false,
        "brands": [
          "geely"
        ],
        "country_name": "China (Mainland)",
        "country_zone": "Asia"
      },
      "considered_vins": [
        {
          "vin_code": "L6TCX2E70ME005154",
          "quality": 1
        }
      ]
    }
  ],
  "costs": {
    "base_request_cost": 0.007,
    "price_per_extra_vin": 0.003,
    "extra_vins": 0,
    "extra_vins_cost": 0,
    "total_cost": 0.007
  }
}

Estructura de respuesta

Estructura de respuesta
Parámetro	Descripción
success	boleano Un boleano con valor true si se pudo procesar su solicitud. O false, en caso de errores.
results	array Un array que contendrá todos los VINs que hayan sido enviados, junto a los datos extraídos y un análisis sobre la válidez de cada código VIN enviado. Consulte la siguiente tabla para detalles sobre los elementos de este array.
costs	array : asociativo Información detallada del coste de la solicitud enviada, donde: base_request_cost: El coste mínimo al realizar la petición para escanear un VIN. price_per_extra_vin: El coste de analizar un código VIN extra en la misma solicitud. extra_vins: El número de VINS enviados a parte del primero. Si envió tres códigos VIN, extra_vins será dos. extra_vins_cost: El coste de analizar los otrós códigos VIN, después del primero. total_cost: El coste total de esta solicitud.

Estructura del array results

Parámetro

Descripción

sent

string

El código VIN tal y como fue enviado en su solicitud, antes de que este sea corregido en caso de detectar errores.

vin

array : asociativo

Array con la información extraida de este VIN y las posibles correcciones en caso de detectar un VIN posiblemente erróneo.

Estructura del array *vins*
Parámetro	Descripción
vin_number	string El VIN que la API procesó finalmente, este VIN podría estar corregido si se detectó un posible error de escritura, o si faltaba algún carácter en el código enviado que pueda ser automáticamente deducido.
valid	boleano Un boleano indicando si el VIN final se considerá correcto o no. En aquellos fabricantes o países dónde se use un digito de control, éste es considerado a la hora de determinar si el VIN es correcto o no.
fixed	boleano En caso de que el VIN enviado haya sido corregido por la API al considerarse incorrecto, estará a true
year	númerico El año de fabricación del vehículo en caso de poder ser calculado.
wmi	string El código WMI (World Merchant Identifier) del VIN. Un identificador del fabricante.
vis	string Sección VIS (Vehicle Identification Section), el código que cada fabricante usa a su discreción internamente para determinar el vehículo y sus características.
serial	string El número de serie del fabricante, usado por los fabricantes internamente y a su discreción.
manufacturer_name	string El nombre del fabricante.
uses_manufacturation_plant_code	boleano Si hay constancia de que este fabricante usa internamente el código de planta de fabricación, true en caso afirmativo.
manufacturation_plant_code	string Código de un carácter que identifica la planta de fabricación del vehículo.
manufacturer_code	string Código del fabricante, habitualmente el mismo que WMI, con excepciones para algunos países y fabricantes.
uses_check_digit	boleano Si este fabricante usa un dígito de control o no. Dependiente de fabricantes, y zonas geográficas. true en caso afirmativo. Para vehículos que usan este dígito la API puede realizar comprobaciones extra para determinar mejor si el código VIN facilitado es correcto o no.
provided_check_digit	string El dígito de control extraido del VIN que se facilitó a la API. Antes de posibles correcciones.
expected_check_digit	string El dígito de control que se esperaba para este fabricante.
valid_check_digit	boleano Si el dígito de control facilitado es correcto o no. Para determinar el código vin final esta validación es ignorada en caso de que el fabricante no use dígito de control.
low_volume_manufacturer	boleano Indica si es un fabricante con un bajo volumen de producción. Suele indicar en la mayoría de casos que varios fabricantes con una cantidad baja de vehículos fabricados, operan bajo un mismo código de fabricante.
brands	array : strings Un array de strings que contiene los nombres de las marcas involucradas en la producción y/o fabricación del vehículo. En la mayoría de casos suele contener un solo elemento.
country_name	string El país donde el vehículo fue fabricado o ensamblado.
country_zone	string La zona geográfica donde el vehículo fue ensamblado o fabricado. Valores posibles: Africa, Asia, Europe, North America, South America y Oceania

considered_vins

array

Una lista de los VIN que fueron considerados durante la fase de autocorrección. En caso de que el VIN haya sido considerado como correcto tal y como fue proporcionado a la API contendrá un único elemento.

En caso de que la API haya considerado varios VINs esta lista, contendrá aquellos que haya contemplado junto a una puntuación quality).

Cada elemento del array considered_vins contiene:

vin_code: El código VIN considerado.

quality: La puntuación que la API otorgó a ese código vin, y que puede estar afectada por los filtros de puntuación si se han proporcionado.

Respuesta con errores

Respuesta ERROR

{
  "success": false,
  "errors": [
    {
      "id": "MISSING_REQUIRED_PARAMETER",
      "message": "Required parameter 'vins' not sent",
	  "on": "vins"
    }
  ]
}

Obtener todos los fabricantes

Si necesita obtener todos los fabricantes de vehículos que la API puede devolver para preparar su base de datos, o bien para crear filtros, puede usar el siguiente endpoint.

GET /api/vin-analyzer/manufacturers
Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación

Se retornará una lista con todos los fabricantes posibles:

Respuesta de fabricantes

{
	"success": true,
	"manufacturers": [
		{
			"code": "LDC",
			"name": "Dongfeng Peugeot-Citroën",
			"zone": "Europe",
			"country": "Slovenia",
			"brands": ["Peugeot","Citroën"]
		}
	]
}

Obtener todos los países

Si necesita obtener todos los países donde operan los fabricantes de vehículos que la API puede devolver para preparar su base de datos, o bien para crear filtros, puede usar el siguiente endpoint.

GET /api/vin-analyzer/countries
Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación

Se retornará una lista con todos los países posibles:

Listado de países

{
	"success": true,
	"countries": [
		{
			"code": "KA-KE",
			"name": "Sri Lanka",
			"zone": "Asia"
		}
	]
}

Obtener todas las marcas

Si necesita obtener todas las marcas comerciales de vehículo que la API puede devolver para preparar su base de datos, o bien para crear filtros, puede usar el siguiente endpoint.

GET /api/vin-analyzer/brands
Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación

Se retornará una lista con todas las marcas posibles:

Listado de marcas

{
	"success": true,
	"brands": [
		"opel","peugeot","sundiro","..."
	]
}

Integración con PHP

ZPK-PHP es una librería de código abierto instalable mediante composer que le permitirá integrar nuestras APIs en su proyecto PHP con un mínimo esfuerzo.

Integrar VinAnalyzer con el SDK en PHP

Instalando ZPK-PHP con composer

Terminal

composer require zpksystems/phpzpk

Ejemplo de request

Ejemplo SDK en PHP


<?php
// Initialize ZPK application
$app = new zpkApplication('appid','key');

$vinAnalyzer = new VinAnalyzer($app);
$vinAnalyzer->addVin('L6TCX2E70ME005154');
$vinAnalyzer->addVins(['L6TCX2E70ME005154','6TCX2E70ME005154']);

// Make a request
$response = $vinAnalyzer->analyze()

var_dump($response);

Precios

0,004 Euros por petición, 1 VIN

0,003 Euros por cada VIN extra en la misma petición.

VinAnalyzer tiene un coste por número de peticiones, el coste por petición es de 0,004 que se descontará de su crédito actual.

Sin embargo, en cada rerquest puede solicitar hasta 20 VINS, el precio por cada VIN extra es de solo 0,003

En caso de no disponer de crédito en su cuenta al realizar una petición la API de Vin Analyzer retornará un error.

Tabla de precios

Peticiones	VINS por petición	Precio petición	Precio por VIN
1	1	0,00	0,00
1	5	0,02	0,00
1	20	0,06	0,00
100	1	0,40	0,40
100	5	1,60	0,32
100	20	6,10	0,31
1.000	1	4,00	4,00
1.000	5	16,00	3,20
1.000	20	61,00	3,05
5.000	1	20,00	20,00
5.000	5	80,00	16,00
5.000	20	305,00	15,25
10.000	1	40,00	40,00
10.000	5	160,00	32,00
10.000	20	610,00	30,50
100.000	1	400,00	400,00
100.000	5	1.600,00	320,00
100.000	20	6.100,00	305,00

Regístrese para probar esta API

Regístrese para obtener crédito gratuito y probar esta y otras APIs de ZPK

Registrarse Acceder