Primeros Pasos

La documentación de ApiPuntos le permitirá a nuestros clientes poder realizar todos los desarrollos e integraciónes necesarias para utilizar todas nuestras herramientas y servicios de valor agregado de forma segura y automatizada.

Introducción

API significa "Application Programming Interface". Una API proporciona un conjunto de comandos, funciones y protocolos para facilitar la programación de software. Estas funciones predefinidas simplifican la interacción del programador con el sistema operativo, ya que el hardware (monitor, datos en el disco duro, etc.) no tiene que ser direccionado directamente. En lo que se refiere a Internet, las APIs Web están a la vanguardia y también sirven como interfaz para permitir el uso de funciones existentes de terceros.

ApiPuntos entrega a las Empresas/Comercios una API REST HTTP con mensajeria de tipo JSON para trasparentar y acercar los datos y servicios a quien lo requiera.

Autenticación API

Ante la imparable evolución de aplicaciones, frameworks, lenguajes y alternativas para facilitarnos las tareas de Desarrollo Web en diferentes ámbitos, hablaremos a continuación sobre el modelo de autenticación para API REST de nuestra infraestructura. Las API REST que nuestro cloud entrega son uno de los mejores recursos actuales para cualquier desarrollador y en esta ocasión, queremos que conozcas mejor las características y el flujo de este modelo.
En el mundo de las API REST, se deben implementar flujos distintos de los habituales en cuanto a la autenticación de usuarios, ya que su arquitectura nos ofrece otro tipo de recursos que los tradicionales. Por lo general, en las aplicaciones web tradicionales, se utilizan las variables de sesión como soporte para memorizar el usuario. Esto viene a decir que en el momento de autenticar un usuario, el servidor genera las correspondientes variables de sesión y en las siguientes páginas consultadas por ese mismo cliente, es capaz de recordar al usuario.
Sin embargo, en las aplicaciones REST, esto no es posible, ya que una de las limitaciones de este sistema es que no se dispone de variables de sesión. Esto es debido a motivos de escalabilidad, ya que las API REST suelen estar alojadas en un cluster de servidores. La solución habitual para salvar este problema es la autenticación por token.

Flujo de autenticación por usuario y contraseña:

Para acceder a nuestras integraciones y utilizar nuestros servicios es necesario que cuente con una cuenta activa aprobada y tenga acceso a los siguientes datos clave de su cuenta:

- Empresa: Es el código único de empresa asignado por ApiPuntos en nuestros sistemas.
- Usuario y Contraseña: Es el usuario con el que ingresa al panel de acceso al sistema. Dicho usuario debe estar habilitado en el módulo de seguridad para utilizar las integraciones externas.
- ApiToken: Es el código token único para su empresa y que se obtiene desde el menú de configuraciones -> Datos de configuración.

Seguridad en la comunicaciones:

Si la Empresa/Negocio asi lo requiere la API de acceso puede estar alcanzada por los siguientes métodos de seguridad extra:

- Conexión VPN entre ApiPuntos y los servidores de la Empresa/Negocio.
- Filtrado IP de Origen para los llamados desde servidores específicos de una Empresa/Negocio.
- Mecanizmo de autenticación OAuth2

Probar Autenticación en Swagger

API CodSeg

Puede que dentro de alguno de los llamados/endpoint de nuestra API exista una variable esperada llamada "CodSeg".

Con el fin de incrementar la seguridad de nuestras transacciones la variable "CodSeg" permite realizar una firma de los datos enviados en el origen y que ApiPuntos se asegure de su lado que dicha transacción / datos no ha sido alterada en su camino.

Método para generar el "CodSeg":

Independientemente del lenguaje de programación con el cual se realice el llamado a la API, si el endpoint de la API así lo requiere el codseg se debe enviar mediante GET HTTP dentro de la variable "codseg" y será generado de la siguiente manera:

- Se copiará todo el json generado a enviar en una variable string.
- Se debe concatenar la variable JSON STING con la variable APIToken asignada por ApiPuntos para su empresa.
- Se debe generar un hash md5 del resultado concatenado.

$codseg = MD5(concat($json, $apitoken));

Entornos

Con el fin de separar logicamente los entornos, al momento de recibir acceso a nuestra API, las Empresas/Negocios recibirán acceso a diferentes entornos:

- Homologación: http://cont-test.certisend.com/
- Producción: https://cont1-virtual1.ApiPuntos.com/

Así mismo si el cliente asi lo requiere podra realizar independientemente llamados a los diferentes servidores de nuestra nube para autoadministrarse la contingencia ante fallos (Consultar a Soporte).

API

A continuación se detalla cada uno de los diferentes EndPoint/Servicios y el funcionamiento de cada uno de los mismos.

Publicar Oferta

La API de publicación de deuda permite a la Empresa/Comercio realizar el envio de una oferta de forma automatizada para ser publicada en el market place de ApiPuntos. A continuación se detalla el funcionamiento del endpoint de publicación de oferta / promoción:

El endpoint a utilizar es el "api\v1\ApiPuntos\core\create_promo" y dicho endpont recibira por medio de GET la variable CodSeg y por medio del body un JSON con las siguientes variables:

Atención

El uso de dicho servicio deberá ser coordinado con nuestro equipo de soporte para la correcta configuración del sistema.

emision -> VARCHAR(100) (Obligatorio): Indica una referencia de la emisión de la oferta.

Una vez llamada correctamente a la API, el sistema retornará una repuesta en JSON con las siguientes variables:

state -> tinyint(4): Estado del procesamiento de la llamada.
- 0-Pendiente
- 1-Exitoso
- 2-Error
message -> VARCHAR(200): Indica la descripción de la API.
codigo -> VARCHAR(200): Se retorna ante un estado exitoso e indica el codigo generado para la transacción.
date -> VARCHAR(100): Retorna la fecha y hora de la llamada en formato DD/MM/YYYY HH:II:SS
id_internal -> VARCHAR(200): Se retorna ante un estado exitoso e indica el ID generado para la transacción.

Validar Cupón

La API de Validar Cupón permite a la Empresa/Comercio realizar una validación sobre la vigencia y autenticidad de un código de cupón emitido por el sistema ApiPuntos.com. A continuación se detalla el funcionamiento del endpoint de validación de cupón:

El endpoint a utilizar es el "api\v1\ApiPuntos\core\validate_cupon" y dicho endpont recibira por medio de GET la variable CodSeg y por medio del body un JSON con las siguientes variables:

Atención

El uso de dicho servicio deberá ser coordinado con nuestro equipo de soporte para la correcta configuración del sistema.

El endpoint a utilizar es el "api\v1\ApiPuntos\core\create_tx" y dicho endpont recibira por medio de GET la variable CodSeg y por medio del body un JSON con las siguientes variables:

codigo -> VARCHAR(200) (Obligatorio): Código del cupón a validar.

Una vez llamada correctamente a la API, el sistema retornará una repuesta en JSON con las siguientes variables:

state -> tinyint(4): Estado del procesamiento de la llamada.
- 0-Pendiente
- 1-Validado
- 2-Invalido
- 3-Cancelado
- 4-Vencido
message -> VARCHAR(200): Indica la descripción de la API.
codigo -> VARCHAR(200): Se retorna ante un estado exitoso e indica el codigo generado para la transacción.
date -> VARCHAR(100): Retorna la fecha y hora de la llamada en formato DD/MM/YYYY HH:II:SS
id_internal -> VARCHAR(200): Se retorna ante un estado exitoso e indica el ID generado para la transacción.