API Cuenta cliente

Sommaire

Introducción

Open Street es un servicio de optimización de itinerarios multipuntos accesible para los desarrolladores que desean incluir esta tecnología en sus propias aplicaciones. El servicio puede ser consumido, ya sea en la forma de un paquete que da derecho a cuotas optimizaciones por día (por ejemplo 30 optimizaciones por día de 50 puntos cada una), y también a través de la tarficación por uso, es decir es decir, cada optimización se descuenta de la cuenta de usuario hasta que se agote.

Es para este segundo caso que existe una API de gestión de cuenta usuario. Esta API permite crear cuentas de optimización y monitorear su consumo.

Descripción de la API Cuenta cliente

Protocolo utilizado

Al igual que todas las API del servicio de Open Street, se utiliza el protocolo HTTP 1.1, y se necesitan dos métodos para cubrir todas las funcionalidades de esta API: POST y GET. Siempre hay al menos un parámetro de URL en la petición, incluso en el caso de los métodos POST.

Esta API de optimización no recibe caracteres especiales o acentuados, pero las direcciones URL deben ser codificadas correctamente. Los navegadores recientes codifican automáticamente las direcciones URL, pero no siempre las bibliotecas HTTP. Con el lenguaje PHP podremos utilizar urlencode().

Todas nuestras API son compatibles con la compresión gzip, por lo que es muy recomendable activar esta funcionalidad en su cliente HTTP. Para verificar que la compresión está activao, el encabezado de la petición del cliente debe incluir Accept-Encoding : "gzip, deflate" y la cabecera de la respuesta del servidor debe incluir Content-Encoding : "gzip" .

El tiempo de respuesta de las peticiones es corto en la escala de una interfaz de usuario, típicamente menos de 300 ms.

Catálogo de los parámetros de entrada

Esta API acepta varios tipos de peticiones que producen resultados diferentes. Distinguimos los parámetros llamados «padres» que determinan el tipo de petición, y los parámetros denominados «niños» que son necesarios para el buen funcionamiento de la petición. Los parametros padres no esperan que un valor les sea atribuido, solo es suficiente su presencia. Los parámetros niños deben, sin embargo, contener un valor asociado, con una petición de tipo sea POST, o GET.

El asterisco * indica un parámetro necesario para iniciar un cálculo.

En la infraestructura de Open Street existen dos tipos de cuentas : la cuenta cliente que contiene los datos de facturación (coordenadas, tarifa aplicable) así como la cuenta de cálculo que es atribuida al cliente. Esta cuenta de cálculo permite efectuar las optimizaciones de itinerarios si necesidad de autenticarse en la cuenta cliente.

Una cuenta cliente se define por su identificador (correo electrónico) y la contraseña, mientras que una cuenta de cálculo se define por su clave de 32 carácteres (parámetro key a continuación).

La mayoría de las veces, un cliente tendrá una sola cuenta de cálculo. Sin embargo, si un cliente lo desea puede aperturar varias cuentas de cálculo, que puede ser útil sobre todo para fines estadísticos. En este caso, varias cuentas de cálculo serán capaces de cargar a la cuenta.

Parametro padre Parámetros niños Explicacion Método
deposits key* Lista de depósitos de crédito efectuados por el cliente que posee esta cuenta de cálculo. GET
credit key* Valor del crédito restante en la cuenta del cliente que posee esta cuenta de cálculo. GET
tsp_requests key*, date Lista de peticiones efectuadas por la cuenta de cálculo especificada. El parámetro fecha indica una fecha de inicio en formato YYYYMMDD/td> GET
tsp_rates key* Programa de tarifa aplicable para esta cuenta de cálculo. GET
tsp_quotas key* Cuotas aplicables al cliente que posee esta cuenta de cálculo. GET
create_key name*, description, email* Crea una cuenta de cálculo atribuida a la cuenta cliente especificada gracias al correo electrónico. GET
create_customer address_company*, address_person*, address_street*, address_street2, address_pc*, address_city*, address_cedex, email*, password_hashed_db* Crear una cuenta cliente con sus datos, su identificador (correo electrónico) y el hash MD5 de su contraseña. POST
salt null Reenvia un valor de 32 carácteres que cambian cada minuto, y es útil al proceso de autenticación para la petición query_customer. GET
query_customer email*, password_hashed_js* Lista de cuentas de cálculos atribuidas a la cuenta cliente. Esta petición es sensible. El paráametro password_hashed_js es calculado por md5(md5($password_typed).$salt) (sintaxis de PHP). POST

Métodos de autenticación

Para estas diferentes peticiones, distinguimos diferentes tipos de autenticación según la petición.

  • La mayoría de las veces, una clave de cuenta de cálculo es suficiente para efectuar una petición. Esta clave debe mantenerse absolutamente confidencial. Con una longitud de 32 caracteres, una persona con malas intenciones podría tener una oportunidad sobre 1,53 1054 a descubrir su clave, lo que parece ser un riesgo aceptable.
  • Para crear una cuenta, se requiere un nombre de usuario (correo electrónico) y contraseña. La contraseña debe ser hash MD5 y no transmitida sin cifrar al crear la cuenta.
  • Para consultar una cuenta de cliente y la lista de sus cuentas de cálculo, se requiere un proceso de autenticación más complicado. La contraseña nunca se transmite en claro o simplemente cifrada. El parámetro debe ser MD5 password_hashed_js (md5 ($ password_typed) $ sal.), O en otras palabras, el hash MD5: hash MD5 de la contraseña introducida, concatenada al salt obtenido a partir de la petición del mismo nombre. Esta seguridad incrementada es definida para proteger los valores de las claves.

Utilización de datos

Ejemplos

Por ejemplo, la petición crédito es un tipo GET, pasaremos entonces todos sus parámetros de URL. La petición completa sera : https://maps.open-street.com/api/account/?credit&key=clave .

El siguiente resultado indica que quedan 95,44 € en la cuenta cliente consultada.

La petición create_customer es tipo POST, pasaremos entonces parent a parámetros de URL, y todos los otros parámetros seran de tipo POST. El método HTTP empleado es POST. A continuación un script bash que crea una petición de este tipo. Podemos igualmente, utilizar javascript para crear esta petición (jQuery recomendado) o un simple formulario HTML sincronizado.

 

Ll resultado será :


 

Recomendaciones de uso

Cuando utilice este objeto JSON, debe imperativamente recuperar los valores gracias a su cadena asociada y por su posición en el documento o número de línea. De hecho, otros datos pueden ser insertados en el futuro y esta es la única manera de respetar la compatibilidad.

El resultado de la petición debe ser probado especialmente con el código de estado. Si indica algo diferente a «OK» entonces la petición ha fallado. Los siguientes códigos de error pueden evolucionar.

Códigos de error

A continuación el significado de los códigos de errores que podemos tener con esta API.

Codigo Explicaciones
SYNTAX_ERROR La petición esta incompleta o contiene un error.
REQUEST_TOO_LONG Los parámetros GET y POST son muy largos.
WRONG_KEY Su clave de autenticación es falsa.
TOO_MANY_PARENT_PARAMETERS Ha intentado dos parámetros parents en una mima petición mientras que el parámetro parent es unico y define el tipo de petición.
MISSING_CHILD_PARAMETER No ha indicado los parámetros requeridos para esta petición.
MISSING_PARAMETER No ha indicado un parámetro.
UNKNOWN_PARAMETER Uno de los parámetros es desconocido.
WRONG_METHOD No ha utilizado el método correcto de HTTP entre POST y GET.
WRONG_ADDRESS Uno de los campos de dirección es muy largo (limitado a 255 carácteres por campo salvo address_pc a 10 y address_cedex a 20).
WRONG_EMAIL El correo electrónico es invalido.
WRONG_PASSWORD La contraseña es invalida.