Especificaciones de intercambios REST

Los servicios webs utilizan los principios comunes de las API REST. El formato de intercambio utilizado es JSON.

Autenticación

L’API REST utilise l’authentification basique : [Basic Authentication]https://en.wikipedia.org/wiki/Basic_access_authentication)

  • l’utilisateur est l’identifiant de la boutique : 28478261
  • le mot de passe est défini dans le backoffice marchand :testpassword_HDBz5YpANEajG4DwYSmkQDNM9lzGiuvrhY9f6G9HEm5do

Pour retrouvez vos clés. consultez l’article suivant: Prérequis (Clés)

Parámetros de la consulta

La aplicación espera un JSON válido como entrada de solicitud. Por ejemplo, Charge/SDKTest interpretará Type/String object como valor de entrada.

La llamada debe efectuarse de la siguiente forma:

{
    "value": "my testing value"
}
/** 
 * Initialize the SDK 
 * Please update your keys in keys.php
 */
$client = new Lyra\Client();  

/**
 * I send test data
 */
$store = array("value" => "my testing value");
$response = $client->post("V4/Charge/SDKTest", $store);

Parámetros de la respuesta

Cuando el Servicio Web responde, devuelve:

{
    "webService":"Charge/SDKTest",
    "version":"V4",
    "applicationVersion":"4.1.2",
    "status":"SUCCESS",
    "answer": {
        "value":"my testing value",
        "_type":"V4/Type/String"
    },
    "ticket":null,
    "serverDate":"2018-10-02T16:13:57+00:00",
    "applicationProvider":"PAYZEN",
    "metadata":null,
    "_type":"V4/WebService/Response"
}

El objeto solicitado se devuelve en un objeto de respuesta genérica donde:

CARACTERÍSTICAS TIPO DESCRIPCIÓN
webService cadena Servicio web llamado, formato: [namespace]/[web_service_name]
versión cadena versión de la API
status cadena estado de la respuesta: SUCCESS o ERROR
answer objeto la respuesta automática (if status is SUCCESS)
ticket cadena número de ticket para transmitir al soporte (no implementado)
applicationProvider cadena Plataforma que libera el servicio
applicationVersion cadena versión de la aplicación
metadata objeto reservado para uso interno
serverDateTime cadena fecha del servidor que ha respondido, en UTC
_type cadena tipo del objeto. Comienza siempre por el número de versión

Manejo de errores

En caso de error del Servicio Web:

{
    "amount": -1
}

La respuesta es:

{
  "webService": "Charge/CreatePayment",
  "version": "V4",
  "applicationVersion": "4.5.1",
  "status": "ERROR",
  "answer": {
    "errorCode": "INT_902",
    "errorMessage": "web-service input data validation error",
    "detailedErrorCode": null,
    "detailedErrorMessage": "can't decode JSON data : {\n    \"amount\":   -1,\n}",
    "ticket": "null",
    "_type": "V4/WebService/WebServiceError"
  },
  "ticket": null,
  "serverDate": "2018-12-10T19:27:32+00:00",
  "applicationProvider": "PAYZEN",
  "metadata": null,
  "_type": "V4/WebService/Response"
}

El Servicio Web se ha detenido y devuelve un objeto V3.1/WebService/WebServiceError:

CARACTERÍSTICAS TIPO DESCRIPCIÓN
errorCode cadena Código de error (en el formato [PREFIJO]_[CÓDIGO])
errorMessage cadena Mensaje de error
detailedErrorCode cadena Código de error detallado (o nulo)
detailedErrorMessage cadena Mensaje detallado (o nulo)

Para más detalles sobre errores, vaya a: Códigos de error.

¿Por qué la API no es 100% REST?

Hemos decidido desarrollar una API tan simple como sea posible para evitar los errores comunes:

Solo utilizamos el método POST.

Así nos evitamos las preguntas habituales sobre qué método utilizar: SIEMPRE POST.

Todos los parámetros de búsqueda se envían como un objeto JSON:

  • Solo hay una forma de enviar los parámetros (no se le agrega nada al URI).
  • Los registros son más simples.
  • La API responde siempre HTTP 200

Por lo que no hay necesidad de administrar varios códigos de estado HTTP, la respuesta es siempre 200. El estado del Servicio Web se puede consultar en el interior del objeto JSON.

Fecha y hora

El objeto datetime está en formato ISO 8601.

El servicio web acepta todos los husos horarios como:

  • 2015-11-19T16:56:57+00:00
  • 2015-11-19T16:56:57+01:00
  • 2015-11-19T16:56:57+Z

El servidor devuelve siempre el objeto datetime en hora UTC (GMT+00) :

  • 2015-11-19T16:56:57+00:00

El servidor nunca devuelve 2015-11-19T16:56:57+Z

Valores nulos

Los valores nulos no obligatorios se eliminan automáticamente de la respuesta. Es decir, una propiedad nula se incluye en la respuesta si y solo si la clave es obligatoria y nulo es un valor aceptable.