API Version Policy
En Placetopay contamos con una única versión del api disponible hasta la fecha. Tal que si te vas a conectar o ya estas conectado con nuestro api, estás usando la única versión disponible.
Al tratarse de una única versión de API, todas las funcionalidades nuevas y ajustes se hacen en la misma versión del API y pretenden ser retro-compatibles.
Cambios Retro-compatibles
En Placetopay consideramos los siguientes cambios retro-compatibles:
Agregar nuevos recursos y endpoints.
Cuando se agrega una nueva funcionalidad, es muy probable que venga acompañada de un nuevo endpoint y/o recurso.
Ejemplo: Si se hiciera el lanzamiento de un nuevo API para obtener usuarios, la funcionalidad llevaría a un nuevo recurso User
y nuevo endpoint api.com/users
.
Agregar nuevos parámetros opcionales a las solicitudes de API existentes
Debido a la evolución de algunas funcionalidades, es probable que agreguemos nuevos parámetros opcionales en las solicitudes que pueden hacer los clientes integradores.
Ejemplo: En el api CreateRequest
se podría agrega un parámetro opcional notificationUrl
para aquellos clientes integradores que quieren definir la url de notificación de esa sesión.
// CreateRequest body
{
...
"payment": { ... }
"notificationUrl": "http://example.com" // new optional parameter
...
}
Este nuevo parámetro será opcional y no afectará las integraciones existentes.
Agregar nuevas propiedades en respuestas de API existentes
Debido a la evolución de algunas funcionalidades, es probable que algunas respuestas del api incluyan nuevas propiedades.
Ejemplo: En el api GetRequestInformation
la respuesta puede ser modificada para incluir una nueva propidad cancelled
dentro de la propiedad subscription
// GetRequestInformation Response
{
...
"subscription": {
...
"cancelled": true, // new property
...
}
...
}
Esta nueva propiedad será incluida y no afectará las integraciones existentes.
Cambiar el orden de propiedades en respuestas de API existentes
Debido a la evolución de algunas funcionalidades, es probable que algunas respuestas del api cambien el orden de sus propiedades.
Ejemplo: En el api GetRequestInformation
la respuesta puede ser modificada para que el orden de las propiedades sea diferente.
// current
{
"requestId": "123",
"status": { ... },
...
}
// changes to
{
"status": { ... }, // changed order
"requestId": "123",
...
}
Este cambio no afectará las integraciones existentes.
Cambiar parámetros requeridos a opcionales en las solicitudes de API existentes
Debido a la evolución de algunas funcionalidades, es probable que cambiemos un parámetro existente que es requerido a opcional en las solicitudes que pueden hacer los clientes integradores.
Ejemplo: En el api CreateRequest
el parámetro requerido ipAddress
se podría cambiar para que fuera opcional.
// CreateRequest body
{
...
"payment": { ... }
"ipAddress": "1.0.0.0.1" // changed to be optional
...
}
Este cambio no afectará las integraciones existentes.
No se podrá hacer lo contrario, es decir, un parámetro opcional no se podrá volver requerido.