Generalidades

Esta API permite llamadas del tipo REST y utiliza JSON para el envío y recepción de información.

Convenciones utilizadas

Peticiones sobre SSL
Se usan sustantivos, no verbos.
Se utilizan dos urls base por recurso "/clients.json", "clients/1.json"
Siempre se usa el nombre del recurso en plural.
Se envía la url del recurso.
Respuesta en una estructura JSON con los atributos en camelCase.
todas las respuestas son en ingles (atributos y mensajes).
Manejo de versiones en la url.
Manejo de errores y estados en las respuestas.
Paginación de la respuesta JSON.
Permitir acceder a las relaciones de un recurso a través de la variable expand en una sola petición.
Permitir devolver solo los atributos requeridos a través de la variable fields.
Las fechas se trabaja como enteros, por ejemplo 1388545200 corresponde a la fecha 2014-01-01, la conversión es realizada utilizando el Tiempo Unix.

Seguridad

Para autenticar una petición se utiliza un token de acceso, el cual deberá acompañar cada llamada en la cabecera de la petición. El token deberá ser solicitado al equipo de Bsale (ayuda@bsale.app).

Es importante indicar que este token de acceso es único para cada empresa/usuario.

Enviar un Request

Las peticiones son HTTP REST por lo que se debe especificar el método que se va a utilizar, junto al método se debe enviar en la cabecera de la petición el token de acceso que permite la autenticación en la API.

GET, para obtener información de un recurso.
POST, para crear un recurso.
PUT, para modificar un recurso.
DELETE, para eliminar un recurso.

Un ejemplo de petición utilizando cURL seria:

curl -i -H "access_token: tuTokendeAcceso" -X GET https://api.bsale.com.pe/v1/clients.json

Herramientas útiles