Especificaciones de intercambios REST
Los Web Services utilizan los principios comunes de las API REST. El formato de intercambio utilizado es JSON.
autentificación
La API REST utiliza la autentificación básica: Para más información, consulte: Fase de autentificación. Para recordar su clave, consulte el siguiente artículo: Prerrequisitos.
Parámetros de la solicitud
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"
} Parámetros de la respuesta
Cuando el Web Service 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":"COIN",
"metadata":null,
"_type":"V4/WebService/Response"
}el objeto solicitado se devuelve en un objeto de respuesta genérica donde:
| parámetros | Tipo | Descripción |
|---|---|---|
| webService | Cadena | Web Service llamado, formato: [namespace]/[web_service_name] |
| version | Cadena | versión de la API |
| status | Cadena | estado de la respuesta: SUCCESS o ERROR |
| answer | Objeto | respuesta comercial |
| 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 Web Service:
{
"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": "",
"metadata": null,
"_type": "V4/WebService/Response"
}El Web Service ha fallado y devuelve un objeto 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 información sobre errores, consulte: 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 agrega nada a la URL).
- Los informes 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 Web Service se puede consultar en el interior del objeto JSON.
Fecha y hora
El objeto datetime está en formato ISO 8601.
El Web Service 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.