API de COBROSYA

Introducción

La API de CobrosYA permite integrar cualquier aplicación externa con la plataforma CobrosYA, para crear automáticamente talones.

Ejemplos de aplicaciones que pueden integrarse con CobrosYA son sitios web con un formulario de compra, sitios de comercio electrónico o cualquier otra aplicación desde la cual se pueda realizar un post.

Por ejemplo, un sitio web de un evento puede tener un formulario en el que pide los datos para que un participante se inscriba. Cuando una persona completa el formulario, se le envía automáticamente un talón de pago para que concurra al Abitab más cercano y lo pague. Una vez que lo paga, el organizador del evento es notificado instantáneamente. Una vez que el dinero está acreditado en su cuenta, el organizador del evento puede girarlo a su cuenta bancaria directamente desde CobrosYA.com.

Entendiendo CobrosYA

El primer paso es registrarte en CobrosYA.com. Sólo lleva un par de minutos, es muy sencillo y no tiene ningún costo.

Para familiarizarte con CobrosYA, podes dar de alta un talón de pago, y enviártelo a vos mismo. Si querés entender como funciona el ciclo completo, anda al Abitab más cercano, pagatelo, y mirá como el mismo automáticamente aparece cobrado en tu cuenta, y posteriormente acreditado cuando el dinero está disponible.

La API de CobroYA permite automatizar este proceso para poder crear talones de pago directamente desde tu propio sitio o aplicación, sin necesidad de ingresarlos uno a uno en la plataforma de CobrosYA.

¿Como empezar?

Lo primero que tenes que hacer es registrarte en CobrosYA, de la misma forma que lo harías para utilizar la plataforma “manualmente”.

Al registrarte, si vas al enlace Mis Datos verás que se habrá generado automáticamente un “token” o clave, (algo parecido a esto "b76adcc734b25a81ce1b5b37798a8af0"). Este “token” es un código único que te identifica como cliente de CobrosYA y que deberás incluir en todas las llamadas a la API, para que CobrosYA sepa que sos tu el que está haciendo la llamada y el sistema cree tus talones directamente en tu cuenta.

Para una fácil comprensión de la API se proveen a continuación distintos ejemplos.

Formulario Web Simple

Este ejemplo es la forma más fácil de entender como hacer una llamada a la API de CobrosYA desde un formulario.

La demo está disponible en: https://cobrosya.com/api/ejemplos/ej1

Este ejemplo es un simple formulario que pide el nombre y mail de una persona. Al enviar el formulario, invoca la API de CobrosYA para dar crear un talón de pago por 200 pesos, con concepto “Inscripcion Evento A”.

El código de este formulario es bien sencillo:




Analicemos el ejemplo línea por línea: La etiqueta < form > define un formulario cuya acción es invocar a la función crearNuevoTalon, mediante un post: Las

 

Estas líneas representan los campos del formulario. El formulario debe como mínimo incluir los siguientes campos para poder dar de alta el talón en CobrosYA:

En el campo Cobrosya[token] debe enviarse el token único asignado al usuario. Normalmente este campo es hidden para que no se despliegue en pantalla:

 

Los campos

identifican al talón que se va a crear. Los mismos pueden ser solicitados al usuario en el formulario, como en este ejemplo lo son el nombre y el mail:

  
    

o pueden ser ocultos y precargados con valores por defecto como en este caso el concepto, monto y fecha:

  
    

Una vez definidos los campos, el submit del formulario invoca mediante un post a la función crearNuevoTalon de la API.

Si interesa, es posible analizar si el talón fue exitosamente creado, analizando los codigos de respuesta de la llamada anterior:

Código Significado
0 El talón ha sido creado exitosamente y enviado por mail
1 El talón ha sido creado exitosamente
2 Ha habido un error al crear el talón.
3 El token no es correcto
4 Faltan campos obligatorios
5 El mail tiene un formato incorrecto
6 La fecha de vencimiento es incorrecta
7 La moneda no es valida (858 Pesos o 840 Dólares)
8 El monto no es numérico
9 El celular tiene un formato incorrecto

¿Querés agregar una Fecha de Vencimiento al talón que se crea?

Puede indicarle a la API que el talón que se crea incluya la fecha hasta la cual podrá ser pago

Es muy simplemente podrás agregar el campo "Cobrosya[fecha_vencimiento]" con el valor "dd/mm/aaaa"

    

¿Querés definir el monto que deberá pagar tu cliente después de vencido el talón?

Es muy fácil en caso que lo desees, podrás definir un segundo monto en tus talones, este corresponde al valor que dicho talón tendrá después de vencido.

Solamente se debe agregar el campo "Cobrosya[monto_vencido]" con el monto correspondiente.

    

¿Querés crear un talón en Dólares?

Podrás indicarle a la API la moneda en la que deseas crear tus talones, simplemente se deberá indicar el código correspondiente a la misma. En caso de ser Pesos = 858 y en caso de ser Dólares = 840.

Es importante destacar, que en caso que esta información no sea especificada, la API asumirá por defecto que todos los talones que se creen serán en Pesos.

Para incluir la moneda correspondiente al talón, se debe de agregar el campo "Cobrosya[moneda]" con el valor del código que corresponda, por ejemplo "840" para dólares

    

¿Querés que CobrosYA le envíe automáticamente el talón por email a tu cliente?

Si lo deseas, también puedes indicarle a la API que le envíe el talón por mail a tu cliente en el momento de crearlo. De esa forma, una vez que se completa el formulario, no solamente queda el talón en la grilla de CobrosYA, sino que lo envía a tu cliente y lo marca como enviado.

Para hacer esto, simplemente debes agregar el campo "Cobrosya[enviar]" con el valor "1"

    

Envío a través de SMS

Opcionalmente a utilizar el email, también puedes utilizar el campo Cobrosya[celular] para enviar el talón por SMS

Puedes usar una u otra opción (o ambas), pero al menos una opción de envío es obligatoria

En caso de usar envío por SMS el formulario sería así:

      
    

Formulario Web redireccionando el POST a un script propio

Una vez entendido el formulario simple, el siguiente ejemplo muestra como realizar llamada a la API de CobrosYA desde un formulario, y además poder ejecutar un script del usuario para realizar otra acción con los datos solicitados.

La demo está disponible en:

https://cobrosya.com/api/ejemplos/ej2

En este ejemplo se agrega un campo más al formulario donde se indica la url del usuario en la cual procesar el post del formulario. El campo utilizado para pasar la url es "Cobrosya[url]".

    

El código completo de este ejemplo es el siguiente:

  
    
    
    
    
    
    
    
    
    
     
    
    
    

Luego que hace POST a crearNuevoTalon, llama a comprar.php cuyo codigo es el siguiente:

  

Gracias por comprar con nosotros

Datos

Nombre:
Email:
Concepto:
Monto:
Respuesta:
Nro de talon:

Datos opcionales

Moneda:
Fecha de vencimiento:
Enviar por mail:

Como se ve en este ejemplo, crearNuevoTalon hace un post a comprar.php pasandole todos los campos del formulario, y además un id único que identifica al numero de talón creado en CobrosYA

La pagina de respuesta (en este ejemplo comprar.php) debe procesar los campos del POST (por ejemplo guardando los datos en una base de datos, enviando un mail, o cualquier otra acción) y luego DEBE redireccionar a otra página de tu sitio web (por ejemplo agradeciendo la compra), ya que si no, en la URL del navegador queda la url crearNuevoTalon.

¿Querés que CobrosYA le notifique automáticamente a tu aplicación cuando recibís un pago?

La API de CobrosYA tiene previsto un sencillo y potente sistema de notificación que funciona de la siguiente forma:

En el momento que tu cliente paga en Abitab, CobrosYA marca el talón como “Cobrado”, y si lo deseas también invoca una pagina en tu sitio mediante un POST pasándole todos los datos del talón.

En esa página podes, por ejemplo, enviarte un mail a ti o a tu cliente, grabar en una base de datos, cerrar el ciclo en tu eCommerce, o lo que tu quieras. Las posibilidades de integración son ilimitadas.

Los datos que recibe tu pagina mediante POST son los siguientes:

Campo Significado
[nombre] nombre de tu cliente
[email]email de tu cliente
[concepto]concepto del talón
[monto]monto del talón
[moneda]moneda del talón
[nroTalon]número de tu talón en CobrosYA
[nroTransaccion]número de transacción de Abitab. Este número lo imprime Abitab en el talón de tu cliente en el momento del pago
[FechaHoraTransaccion]fecha y hora en que tu cliente pagó en Abitab

A continuación incluimos un ejemplo muy sencillo en PHP que lo que hace es guardar los datos recibidos en un archivo de texto con el nombre “respuesta.txt”

  
 

La URL en la que deseas recibir la notificación, deberás indicarla accediendo a tu cuenta de CobrosYa ir a la opción Mis Datos solapa Opciones de Configuración en donde encontraras "URL para notificación de pago"