VIN OCR

Una API para detectar números de bastidor de vehículos en imágenes, y documentos escaneados.

VIN, son las siglas para Vehicle Identification Number. Esta API permite detectar números VIN válidos dentro de imágenes y fotografías. La API de VinOcr proporciona además información extra sobre el VIN encontrado en el documento, como por ejemplo el fabricante, el año y el país de fabricación.

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-ocr/scan
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
image_file	fichero requerido Una imágen jpg o png a ser escaneada y que podría contener uno o mas códigos VIn Obligatorio si no se envía el parámetro image_url
image_url	string requerido Una dirección http / https donde esta disponible la imágen a ser escaneada y que podría contener uno o mas códigos VIn Obligatorio si no se envía el parámetro image
score_filters	array opcional Cuando la imágen no dispone de una buena calidad, es posible que haya confusiones entre diferentes códigos VIN válidos, 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. 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": "africa", "country": "", "manufacturer": "", "brand": "", "score": 1 }, { "zone": "", "country": "", "manufacturer": "motorcycle", "brand": "", "score": -20 }, { "zone": "", "country": "", "manufacturer": "truck", "brand": "", "score": -20 } ]` En este ejemplo se han aplicado tres filtros para alterar la puntuación, se desea dar prioridad a los vehículos fabricados en África, y penalizar los fabricados en America. Adicionalmente se desea filtrar fuera aquellos fabricantes de tractores, y motocicletas. Los vehículos fabricados en africa recibirán un extra de +1 en su puntuación Los vehículos fabricados en america 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 una lista de zonas países y fabricantes a través de nuestra API VehicleVIN, consulte: Obteniendo fabricantes, países, marcas.
wildcard_at_end	boolean opcional y por defecto a: false Si wildcard_at_end es especificado, el detector de VINS se permitirá añadir un asterisco* en aquellos VINS en los que se detecte que falta un caracter al final del código. Por ejemplo, dado el código VIN L6TCX2E70ME00515, dónde falta un carácter, la API determinará que el carácter faltante es el último, y retornará como VIN principal el código L6TCX2E70ME00515* Esta opción, puede ser usada para intentar determinar el código correcto en su propia base de datos de vehículos si dispone de ella.
include_considered_vins	boolean opcional y por defecto a: false Si se establece a true la respuesta contendrá un nuevo elemento considered_vins que contendrá array con todos los VINS considerados en el analisis de visión y sus puntuaciones.

Respuesta

Respuesta con éxito

Respuesta OK

{
   "success": true,
   "results": [
      {
         "vin_number": "VSSZZZ5F216532078",
         "dev_from_ocr": "SSZZZ5F216532078",
         "valid": true,
         "fixed": true,
         "quality": 1,
         "year": 2001,
         "wmi": "VSS",
         "vis": "16532078",
         "serial": "16532078",
         "manufacturer_name": "SEAT",
         "uses_manufacturation_plant_code": false,
         "manufacturation_plant_code": "6",
         "manufacturer_code": "VSS",
         "uses_check_digit": false,
         "provided_check_digit": "2",
         "expected_check_digit": "5",
         "valid_check_digit": false,
         "low_volume_manufacturer": false,
         "brands": [
            "seat"
         ],
         "country_name": "Spain",
         "country_zone": "Europe"
      }
   ],
   "costs": {
      "total_cost": 0.005
   }
}

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, dónde: total_cost: El coste total de esta solicitud.

Estructura del array *results*
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.
dev_from_ocr	string El número que fue leído por el OCR, sin procesar. Puede coincidir con vin_number si no fue necesaria ninguna corrección
valid	boleano Un boleano indicando si el VIN final se considera correcto o no. En aquellos fabricantes o países dónde se use un digito de control, este 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 mayoria 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 JSON con errores

Respuesta ERROR

{
	"success": false,
	"errors": [
		{
			"id": "MISSING_REQUIRED_PARAMETER",
			"image_file": "Specify an image with 'image_file' or 'image_url'",
			"on": "image_file"
		}
	]
}

Respuesta JSON sin errores ni VINs detectables

Respuesta SinDatos

{
	"results": [],
	"found_vins": 0,
	"success": true
}

Respuestas sin VINs, y facturación

Documentos sin VIN detectables

Cuando no se pueda encontrar ningún código VIN, la aplicación no enviará el array de errores, success será true, y el array results estará vacio.

Esto permite usar la API para asegurar que la imágen no contiene ningun VIN detectable.

Facturación de peticiones

Se facturarán como requests válidos todos aquellos en los que la imágen haya podido ser escaneada y no retorne errores en el array de errors

Un request cuya imágen no contenga VINS detectables tiene su coste habitual y será facturada.

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-ocr/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-ocr/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 paises

{
	"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-ocr/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 Vin OCR con el SDK en PHP

Instalando ZPK-PHP con composer

Terminal

composer require zpksystems/zpk-php

Ejemplo de request

Ejemplo SDK en PHP


<?php // Initialize ZPK application
$zpk = new PHPZPK(APPLICATION_ID,API_KEY);

// Initialize VinOcr
$vinOcr = new VinOcr($zpk);
$vinOcr->setImageFile('test_vin_image.png');

// Make a request
$response = $vinOcr->fetch();

// Dump the response as array
var_dump($response);

Precio

EUR 0,003 por imagen escaneada

1,00 Euro cada 333 imágenes

VinOCR tiene un coste por petición a la API, el precio por petición es de 0.003 € que será substraído de su crédito restante.

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

Regístrese para probar esta API

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

Registrarse Acceder

Filtro	Contra filtro
Zona
País
Fabricante
Marca
Puntuación