Que es Colppy REST API?
REST es un estilo de arquitectura diseñada para aplicaciones Web's. La idea es de en vez de usar mecanismos complicados como SOAP para conexion entre computadoras, Simplemente usamos el protocolo HTTP para hacer las pegadas entre maquinas. Colppy REST API permite mediante una solicitud en formato json; iniciar sesión, realizar altas y bajas de facturas, leer datos de empresas o cliente.
Como empiezo?
El primer paso para empezar a desarrollar es registrar usuario y contraseña en la Web de desarrolladores de Colppy. Después para realizar una petición podemos o generar un script en php que utilice CUrl o utilizando alguna herramienta que puedan ejecutar HTTP POST Request (Por ej. httprequester para Firefox ò PostMan para Chrome).
Como realizo una petición?
La url de Colppy REST API para realizar pruebas es http://staging¿Cuáles son las URL?
Produccion: https://login.colppy.com/lib/frontera2/service.php. El punto de acceso a Colppy API en su versión Producción es
Staging: https://loginstaging.colppy.com/lib/frontera2/service.php. Para poder generar una petición debemos ejecutar HTTP POST Request a una de las urls en donde se encuentra el servicios, ya sea de produccion o testing con JSON que tiene el siguiente formato:
{"auth": {"usuario": "USUARIO_API","password": "USUARIO_PASSWORD"},"service": {"provision": "Nombre_del_Provisión","operacion": "Nombre_de_la_operación"},"parameters": {"sesion": {"usuario": "UsuariodeColppy","claveSesion": "ContraseñaDeColppy"},"otros parametros": {}}
}
(Demora 24 Hs desde la creación del usuario en la web de desarrolladores en estar disponible).
¿Cuál es el JSON de inicio de sesión?
Operación iniciar_sesion
| Code Block | ||
|---|---|---|
| ||
{
"auth": {
"usuario": "xxxx@colppy.com", // Usuario registrado en dev.colppy.com.
"password": "egewew6ewg6ew6363" // Contraseña del usuario registrado en dev.colppy.com en formato MD5.
},
"service": {
"provision": "Usuario",
"operacion": "iniciar_sesion"
},
"parameters": {
"usuario": "xxxx@colppy.com", // Usuario de Colppy.
"password": "egewew6ewg6ew6363" // Contraseña del usuario de Colppy en formato MD5.
}
} |
El JSON se divide en tres partes auth, service y parameters.
En auth van tus credenciales, es decir, tu usuario con las el que te registraste en la web de desarrolladores de colppy, tu usuario de colppy y el MD5 de la contraseña que utilizaste para registraste. por ejemplo si mi nombre usuario como desarrollador es SujetoDePrueba y mi contraseña SujetoDePruebaContraseña, el JSON quedaría de la siguiente forma:
{"auth": {"usuario": "SujetoDePrueba","password": "d0edfe89f30a78ef45ab9a22bd0f826b"},....}
El md5 de la cadena "SujetoDePruebaContraseña" es la cadena "d0edfe89f30a78ef45ab9a22bd0f826b".dev.colppy.com y la contraseña en formato MD5.
En service se especifica que es lo que deseo hacer con en la petición. Cada una alta, baja y modificación de colppy están en diferentes Provisiones y cada una de estas en diferentes operaciones. La Provisiones hacen referencia sobre cual de los modulo Colppy yo deseo trabajar, y la operacion hace referencia a lo que deseo hacer con ese modulo. Existe un Indice con las distintas Provisiones y Operaciones que soporta Colppy. Por ejemplo si lo que quiero hacer es iniciar sesion en Colppy lo que tengo que hacer es modificar el campo provision con el nombre del modulo al que quiero acceder en este caso Usuario, luego me fijo en el indice de provisiones y operaciones de colppy y verifico que exista la operaciones iniciar_sesion, Entonces en el campo operaciones lo cambio a iniciar_sesion. Entonces el JSON quedaría de la siguiente manera
{...
"service": {"provision": "Usuario","operacion": "iniciar_sesion"},
...
}
Una cosas con la que hay que tener mucho cuidado es que el la provisión y la operación que deseo hacer. Se pueden ver todas las opciones aquí. El nombre de las provisiones y operaciones son sensible sensibles a mayúsculas. Siempre tener el Indice de provisiones y operaciones a mano.
En parameters van los parametroslos parámetros que espera la operacion para operación para poderse ejecutar. Estos parámetros varían de provision en provision y de operacion en operacion. En este caso estamos tratando de iniciar sesion en colppy, si nos fijamos en el indice de provisiones y operaciones en la seccion de la provision sesion, podemos ver los parametros que espera la operacion en el JSON.
En el nuestro ejemplo el JSON final quedaría de la siguiente manera:
{"auth": {"usuario": "SujetoDePrueba","password": "SujetoDePruebaContraseña"},"service": {"provision": "Usuario","operacion": "iniciar_sesion"},"parameters": {"sesion": {"usuario": "UsuarioTest","claveSesion": "ContraseñaTest"},}
}
Una vez que ejecutamos la HTTP POST Request con nuestro JSON, Colppy REST API dependiendo la operación que necesitemos hacer.
Una vez que ejecutamos la petición POST con nuestro JSON, Colppy API nos va a responder con un mensaje informándonos si el requerimiento se realizo realizó con éxito o no.
Ejemplo de una respuesta de éxito:
Response
| Code Block | ||
|---|---|---|
| ||
{ |
...
"service":{ |
...
...
...
"provision":"Usuario", |
...
...
...
"operacion":"iniciar_sesion", |
...
...
...
"version":"1_0_0_0", |
...
...
...
"response_date":"2014-24-06 17:10:19" |
...
}, |
...
"result":{ |
...
...
...
"estado":0, |
...
...
...
"mensaje":"La operaci\u00f3n se realiz\u00f3 correctamente" |
...
}, |
...
"response":{ |
...
...
...
"success":true, |
...
...
...
"message":"La operacion se realizo con exito.", |
...
...
...
"data":{ |
...
...
"claveSesion":"b5a97564ad59e624a6ba545ecd3ca112" |
...
...
...
} |
...
} |
...
} |
Del response nos quedamos con la "claveSesion" que es obligatoria para realizar otras operaciones.