Ejemplo de integración con Contasimple API.

La API de Contasimple funciona usando un sistema estándar de Oauth2, lo que significa que para utilizar cualquier funcionalidad se debe disponer previamente de 2 claves, "Client Id" y "Client Secret".

Estas claves serán necesarias para realizar cualquier acción e identifican el partner de Contasimple que está realizando la petición.

Deberán ser proporcionados por el equipo de soporte de Contasimple, si no dispones de ellas, contacta con tu agente comercial o envíanos un mensaje a través del correo: soporte@contasimple.com.

Los diferentes servicios proporcionados para partners son:

Creación de usuarios: Permite crear usuarios de forma automática en el dominio que realiza la petición.
Modificación de la contraseña: Permite modificar la contraseña de un usuario. Requiere disponer de la contraseña antigua. Requiere realizar un login previo con los datos del usuario al que se desea modificar la contraseña.
Acceso automático a la plataforma: Permite generar un token a acceso automático a la plataforma. Requiere realizar un login previo con los datos del usuario al que se desea modificar la contraseña.

Para los servicios que requieren un login previo se puede realizar una llamada al servicio

POST "/oauth/token"

enviando los siguientes datos via "form-data":

"grant_type": "password"
"client_id": "Clave proporcionada por Contasimple"
"client_secret": "Clave proporcionada por Contasimple"
"username": "Email del usuario"
"password": "Contraseña del usuario"

Si los datos son correctos esta llamada retorna una estructura que contiene un campo "access_token" que deberá añadirse como cabecera en las llamadas siguientes.

Authorization = Bearer "access_token"

Ejemplos de código:

Javascript

var settings = {
'async': true,
'crossDomain': true,
'url': 'URL API/oauth/token',
'method': 'POST',
'headers': {
'content-type': 'application/x-www-form-urlencoded'
},
'processData': false,
'data':'{"grant_type":"password","client_id":ClientId,"client_secret":ClientSecret,"username":Email,"password":Contraseña}'
}

$.ajax(settings).done(function (response) {
console.log(response);
});

PHP

$request = new HttpRequest();
$request->setUrl('URL API/oauth/token');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'content-type' => 'application/x-www-form-urlencoded'
));
$request->setContentType('application/x-www-form-urlencoded');
$request->setPostFields(array(
'grant_type' => 'password',
'username' => Email,
'password' => Contraseña,
'client_id' => ClientId,
'client_secret' => Contraseña
));
$response = $request->send();

El servicio de creación de usuarios requiere realizar una llamada al servicio

POST "/users/create"

enviando los siguientes datos:

{
"clientId": "Clave proporcionada por Contasimple",
"clientSecret": "Clave proporcionada por Contasimple",
"username": "Email del nuevo usuario",
"password": "Contraseña para el nuevo usuario",
"promoCode": "Código de promoción para crear el usuario"
"userInvitation": {
"invitationId": "Id de la invitación a la empresa"
"invitationToken": "Token de la invitación a la empresa"
}
}

Puedes testear el acceso al servicio con el siguiente formulario (requiere introducir previamente tu "Client Id" y "Client Secret").

Email de acceso:
Contraseña:

Ejemplos de código:

Javascript

var settings = {
'async': true,
'crossDomain': true,
'url': 'URL API/users/create',
'method': 'POST',
'headers': {
'content-type': 'application/json'
},
'processData': false,
'data':'{"clientId":ClientId,"clientSecret":ClientSecret,"username":Email,"password":Contraseña}'
}

$.ajax(settings).done(function (response) {
console.log(response);
});

PHP

$request = new HttpRequest();
$request->setUrl('URL API/users/create');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$request->setBody('{
"clientId": ClientId,
"clientSecret": ClientSecret,
"username": Email,
"password": Contraseña
}');
$response = $request->send();

El servicio para modificar la contraseña de un usuario requiere realizar una llamada al servicio

POST "/me/password"

enviando la cabecera de autorización:

Authorization = Bearer "access_token"

y los siguientes datos:

{
"currentPassword": "Contraseña actual del usuario",
"newPassword": "Nueva contraseña para el usuario"
}

Puedes testear el acceso al servicio con el siguiente formulario (requiere introducir previamente tu "Client Id" y "Client Secret").

Email del usuario:
Contraseña actual:
Nueva contraseña:

Ejemplos de código:

Javascript

var settings = {
'async': true,
'crossDomain': true,
'url': 'URL API/me/password',
'method': 'PATCH',
'headers': {
'content-type': 'application/json',
'authorization': 'Bearer Access token'
},
'processData': false,
'data':'{"currentPassword":Contraseña actual,"newPassword":Nueva contraseña}'
}

$.ajax(settings).done(function (response) {
console.log(response);
});

PHP

HttpRequest::methodRegister('PATCH');
$request = new HttpRequest();
$request->setUrl('URL API/me/password');
$request->setMethod(HttpRequest::HTTP_METH_PATCH);
$request->setHeaders(array(
'authorization' => 'Bearer Access token',
'content-type' => 'application/json'
));
$request->setBody('{
"currentPassword": Contraseña actual,
"newPassword": Nueva contraseña
}');
$response = $request->send();

El servicio para generar un token de acceso automático requiere realizar una llamada al servicio

POST "/me/token"

enviando la cabecera de autorización:

Authorization = Bearer "access_token"

Esta llamada retorna un objeto con un campo "data" que contiene un campo "token" que se debe añadir como parámetro a la página de login de Contasimple.

https://URL-DE-TU-PORTAL/login.aspx?token=token

Puedes testear el acceso al servicio con el siguiente formulario (requiere introducir previamente tu "Client Id" y "Client Secret").

Email del usuario:
Contraseña actual:

Ejemplos de código:

Javascript

var settings = {
'async': true,
'crossDomain': true,
'url': 'URL API/me/token',
'method': 'POST',
'headers': {
'content-type': 'application/json',
'authorization': 'Bearer Access token'
},
'processData': false,
'data':''
}

$.ajax(settings).done(function (response) {
console.log(response);
});

PHP

$request = new HttpRequest();
$request->setUrl('URL API/me/token');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'authorization' => 'Bearer Access token',
'content-type' => 'application/json'
));
$response = $request->send();

La API de Contasimple permite integración mediante Authorization Code Grant. De esta forma el integrador no es responsable de capturar el usuario y la contraseña del usuario.
Para ello será necesario redirigir al usuario a la página de login de Contasimple para solicitar el authorization code. El formato de la URL es el siguiente:

https://[SITE-URL]/login.aspx?response_type=code&client_id=[CLIENT-ID]&redirect_uri=[REDIRECT-URL]&scope=offline_access

Dónde:

SITE-URL: Corresponde a la URL de la plataforma web en el entorno deseado.
CLIENT-ID: El identificador de cliente asociado a la integración.
REDIRECT-URL: La URL a la que se redirigirá al usuario una vez el usuario ha completado el login.
SCOPE: Añadir el valor "offline_access" si es necesario obtener un "refresh token" y poder acceder a la información del usuario en segundo plano. En caso de no necesitar "refresh token" es posible no indicar este parámetro. En ese caso, una vez caducado el "auth token"será necesario que el usuario vuelva a introducir sus credenciales.

Una vez el usuario haya completado la autorización, se reenviará al mismo a la URL proporcionada como REDIRECT-URL añadiendo un parámetro "code" con el código necesario para completar la autorización.

Para ello se deberá realizar una llamada a:

POST "/oauth/token"

enviando los siguientes datos via "form-data":

"grant_type": "authorization_code"
"client_id": "Clave proporcionada por Contasimple"
"client_secret": "Clave proporcionada por Contasimple"
"code": "El valor obtenido en el paso anterior"

Si los datos son correctos esta llamada retorna una estructura que contiene un campo "access_token" que deberá añadirse como cabecera en las llamadas siguientes.

Authorization = Bearer "access_token"

En la respuesta se obtendrá también un campo "refresh_token" que puede usarse para obtener un nuevo "access_token" con una llamada a

POST "/oauth/token"

enviando los siguientes datos via "form-data":

"grant_type": "refresh_token"
"client_id": "Clave proporcionada por Contasimple"
"client_secret": "Clave proporcionada por Contasimple"
"refresh_token": "El valor obtenido en el paso anterior"

PRODUCCIÓN PRE-PRODUCCIÓN
URL de tu portal:
URL API:
Client Id:
Client Secret: