Este documento se proporciona como recurso técnico para los comerciantes de CCBill. Está escrito para programadores, técnicos y otras personas con habilidades de programación avanzadas.
La información de este documento se refiere a la construcción de una interfaz de programa de aplicación (API) con el sistema de extracción de enlace de datos CCBill.
El sistema de extracción de enlace de datos (enlace de datos) permite a los comerciantes de CCBill acceder a datos de transacciones sin procesar mediante el envío de parámetros específicos al script CGI de enlace de datos. Luego, los datos se devuelven en forma de un conjunto de datos de valores separados por comas (CSV) que el script que solicita la información puede leer y mostrar a través de un motor de informes personalizado. Las solicitudes enviadas directamente a través de la barra de direcciones de un navegador web producirán un "volcado de datos" en pantalla dentro de la ventana del navegador. Se devolverá un error si la solicitud no es válida o se rechaza.
Los valores pasados al script CGI de enlace de datos actúan como parámetros de búsqueda para filtrar la información en el conjunto de datos devuelto. Puede buscar por rango de fechas, tipo de transacción, número de cuenta comercial y número de subcuenta. Se le pedirá que incluya un nombre de usuario y una contraseña en la cadena de solicitud y, opcionalmente, puede incluir el parámetro Modo de prueba para utilizarlo con fines de prueba.
Para evitar el abuso del sistema, las solicitudes de enlace de datos solo se pueden realizar una vez cada 60 minutos.
Data Link acepta parámetros de entrada enviados a la siguiente secuencia de comandos:
https://datalink.ccbill.com/data/main.cgi
Cada uno de los siguientes términos de búsqueda son variables que deben pasarse al script. Pueden pasarse en cualquier orden. La primera variable pasada debe ir precedida del signo de interrogación (?), y cada variable subsiguiente debe ir precedida por el signo comercial (&) personaje. Por ejemplo:
https://datalink.ccbill.com/data/main.cgi?var1=value&var2=value
Las siguientes variables deben pasarse a la cadena:
hora de inicio y hora de finalización
hora de inicio y hora de finalización son variables independientes que representan la fecha y la hora durante las cuales se realizaron las transacciones. Los valores deben pasarse en AAAAMMDDHHIISS formato con horas expresadas en formato militar de 24 horas. Los intervalos de fechas especificados no pueden exceder las 24 horas; las fechas ingresadas fuera de este rango producirán un error y terminarán el script.
tipos de transacciones
Se pueden solicitar varios tipos de transacciones: NUEVA, REFACTURACIÓN, REEMBOLSO, ANULACIÓN, VENCIMIENTO, REEMBOLSO, CANCELACIÓN y CDS (Liquidación impulsada por el comerciante). Separe varios tipos con una coma; por ejemplo, para mostrar nuevas suscripciones y refacturaciones, ingrese transactionTypes = NUEVO, REFACTURACIÓN.
La siguiente lista muestra todos los tipos de transacciones posibles que se pueden solicitar:
| NUEVO | Nuevas suscripciones; esto incluye facturación única y recurrente. |
| REFACTURAR | Suscripciones que se han vuelto a facturar correctamente. |
| REEMBOLSO | Suscripciones reembolsadas o reembolsos. * |
| VACÍO | Suscripciones o Refacturaciones que hayan sido declaradas nulas. |
| EXPIRAR | Las suscripciones caducadas han llegado al final de su período de suscripción o se han cancelado y alcanzado su fecha de renovación. |
| DEVOLUCIÓN | Suscripciones o refacturaciones que se han devuelto. |
| CANCELACIÓN | Suscripciones canceladas. Tenga en cuenta que CCBill Management debe aprobar el uso de esta función. |
| CDS | Las transacciones de Liquidación impulsada por el comerciante (CDS) han sido autorizadas previamente, pero los fondos no se recolectarán hasta que el consumidor inicie sesión en el área de Miembros por primera vez. |
| AFILIADO | Muestra la proporción de afiliados de transacciones referidas completadas durante el período de tiempo especificado. |
| MIEMBROS ACTIVOS | Enumera los miembros activos en el momento de la solicitud de enlace de datos para un número de cuenta o subcuenta. Si no se define ningún número de subcuenta, se devolverá una lista de todos los miembros activos para todas las subcuentas. Nota: los parámetros startTime y endTime no son necesarios para este transactionType. Los valores no reconocidos pasados a la variable transactionTypes producirán un error y provocarán la finalización del script. |
| clienteAccnum | Esta variable especifica el número de cuenta comercial de seis dígitos de la cuenta para la que se solicitan los datos. |
| clienteSubacc | Este parámetro es opcional y define la subcuenta para la que se solicitan datos. Si no se incluye este parámetro, se devolverán los datos de todas las subcuentas debajo de la cuenta del comerciante. |
| nombre de usuario | El parámetro de nombre de usuario se proporciona durante la configuración inicial de la cuenta y se usa solo para autenticar solicitudes de enlace de datos. Si se especifica el número de subcuenta, el nombre de usuario debe corresponder a esa subcuenta. |
| la contraseña | El parámetro de contraseña se proporciona durante la configuración inicial de la cuenta y se usa solo para autenticar solicitudes de enlace de datos. Si se especifica el número de subcuenta, la contraseña debe corresponder a esa subcuenta. |
| Modo de prueba | Este parámetro es opcional y se utiliza solo con fines de prueba para garantizar que su sistema se interconecta correctamente con Data Link. Pase un valor de "1" para este parámetro para habilitar el modo de prueba; de lo contrario, no lo incluya. |
Los datos solicitados se devolverán en formato de valores separados por comas (CSV). Los campos y sus valores dependerán de la información solicitada. Todos los campos se devuelven entre comillas y las comillas dentro de los valores se escapan.
Las solicitudes de enlace de datos se pueden personalizar utilizando el sistema CCBill Admin Portal:
Para eliminar un campo del conjunto de datos, selecciónelo en el Campos seleccionados cuadro y haga clic en el Eliminar (puede seleccionar más de un campo manteniendo presionada la tecla Control mientras selecciona campos individuales).
Cuando termine, haga clic en el Presentar cambios botón. Para cancelar sus cambios y volver a la lista de formatos de datos, haga clic en el Cancelar del botón.
Los valores de campo se devuelven en forma de un conjunto de registros de datos. Los siguientes campos se pueden leer de este conjunto de datos utilizando funciones de recuperación de datos (los tipos de datos están entre paréntesis):
| Tipo de transacción (cadena) | La categoría a la que pertenece la transacción. |
| Número de cuenta mercantil (entero) | Número de cuenta comercial CCBill de seis dígitos. |
| Subcuenta del comerciante (entero) | Número de subcuenta de cuatro dígitos. |
| ID de suscripción (entero) | Número de identificación único para la suscripción. |
| Marca de tiempo de la transacción (cadena) | Hora exacta en que se realizó la transacción. El valor se devuelve como un número entero de 14 dígitos en formato AAAAMMDDHHIISS. Para los tipos REBILL y EXPIRE, el valor se devolverá como una cadena en formato AAAA-MM-DD. |
| Nombre (cadena) | Nombre del consumidor. |
| Apellido (cadena) | Apellido del consumidor. |
| Nombre de usuario (cadena) | Nombre de usuario del consumidor. |
| Contraseña (cadena) | Contraseña del consumidor. |
| Dirección (cadena) | Dirección de facturación del consumidor. |
| Ciudad (cadena) | Ciudad del consumidor. |
| Estado (cadena) | Estado del consumidor. |
| Código postal (cadena) | Código postal del consumidor. |
| País (cadena) | País en el que reside el consumidor. |
| Dirección de correo electrónico (cadena) | Dirección de correo electrónico del consumidor. |
| ID de socio (cadena) | Identificador único que denota el socio que refirió la venta. El valor tendrá un carácter de asterisco (*) agregado si el socio no es un afiliado de CCBill. |
| Estado de suscripción (cadena) | Devuelve 'Y' o 'N' para mostrar si la suscripción está actualmente activa. |
| Importe contable (flotante) | Este valor representa la cantidad en dólares estadounidenses (USD) que se pagó, anuló, reembolsó o devolvió. Para transacciones NUEVAS y CDS, este valor representa el precio de facturación inicial (el primero). |
| Período inicial (entero) | Duración del primer período de facturación. El período inicial denota el período de prueba si la suscripción comenzó con una prueba. |
| Importe contable recurrente (flotante) | La cantidad que el comerciante recibe en USD por cada transacción recurrente. Esta cantidad puede variar debido a las tasas de conversión de moneda aplicables. |
| Periodo recurrente (entero) | Tiempo entre refacturaciones. Devolverá 0 (cero) para billetes individuales. |
| Estado recurrente (entero) | El número restante de facturas que quedan para la suscripción. Los billetes individuales devuelven 0; las suscripciones periódicas indefinidas devuelven 99. |
| Tipo de tarjeta (cadena) | El tipo de tarjeta de crédito utilizada (Visa, MasterCard, JCB, Discover, etc.) El valor aparecerá en blanco si no es una transacción con tarjeta de crédito. |
| Monto facturado (flotante) | Monto cobrado en la moneda del consumidor. |
| Moneda facturada (entero) | Código de moneda de 3 dígitos para indicar el tipo de moneda en que el consumidor pagó. |
| Precio inicial base (flotante) | Precio inicial fijado por el comerciante. Debe utilizarse junto con la moneda base; por ejemplo, si el precio inicial es 30 EUR, el precio inicial base es 30. Si el precio inicial es 20 USD, el precio inicial base es 20. |
| Moneda base (cadena) | Tipo de moneda en la que se basó la opción de pago. |
| Precio base recurrente (flotante) | Precio recurrente en el que se basó la opción de pago. |
| Fecha de vencimiento (cadena) | Fecha de vencimiento de la suscripción, devuelta en formato AAAA-MM-DD. |
| Fecha de cancelación (cadena) | Fecha en que se canceló la suscripción, se devolvió en formato AAAA-MM-DD. |
| ID de transacción de nueva factura (entero) | Número de identificación único para la transacción de refacturación. |
| Transacción por lotes (cadena) | Las transacciones por lotes se aprueban previamente debido a problemas técnicos durante el registro; esto puede suceder en el caso de una interrupción de la red o un retraso en la autorización bancaria. El campo devolverá 'Y' para una transacción por lotes fallida o 'N' para una transacción por lotes exitosa. |
| Tipo de términos de facturación (cadena) | Este valor devolverá uno de los siguientes para NUEVOS tipos de transacciones: 1. NIVELADO. Este valor se devolverá para las transacciones del Sistema de suscripción por niveles (TSS). 2. UNA VEZ. Este valor se devolverá para las transacciones estándar de facturación única que no sean de TSS. 3. PERIÓDICO. Este valor se devolverá para las transacciones recurrentes estándar que no son de TSS. Para los tipos de transacciones REBILL, el Tipo de términos de facturación devolverá uno de los siguientes: 1. NIVELADO. Este valor se devolverá para las transacciones de TSS. 2. REFACTURAR. Este valor se devolverá para las transacciones de recarga estándar que no son de TSS. |
| ID de contrato de facturación (entero) | Para las transacciones del sistema de suscripción por niveles, este campo contendrá el número de identificación del contrato. Para transacciones que no son de TSS, este campo devolverá un valor nulo. |
| Cantidad (flotante) | El monto pagado al Afiliado por la transacción referenciada. |
| Sistema de afiliados (cadena) | El sistema de afiliados utilizado para la transacción; WMS o Legacy. |
| ID de reserva | El ID de reserva es una variable que se corresponde con el Nombre de usuario con Gestión de usuarios para fines de registro. |
Una vez que se completa la personalización, puede editar o restablecer los valores deseados haciendo clic en el enlace correspondiente junto al tipo de transacción en la lista de formatos de datos. El restablecimiento establecerá los campos devueltos en el conjunto predeterminado, como se muestra en la sección Valores predeterminados del tipo de transacción a continuación.
Cada tipo de transacción devuelve un conjunto específico de campos por defecto que se pueden modificar para entregar solo la información deseada. La siguiente lista muestra los campos predeterminados que se devuelven para cada tipo de transacción; Estos campos se pueden eliminar y volver a agregar en cualquier momento:
| NUEVO | Subcuenta del comerciante, ID de suscripción, Marca de tiempo de la transacción, Nombre, Apellido, Nombre de usuario, Contraseña, Dirección, Ciudad, Estado, Código postal, País, Dirección de correo electrónico, ID de socio, Estado de suscripción, Importe contable, Período inicial, Importe contable recurrente, Período recurrente, estado recurrente, tipo de tarjeta, tipo de términos de facturación, identificación del contrato de facturación |
| REFACTURAR | Subcuenta del comerciante, Id. De suscripción, Marca de tiempo de la transacción, Id. De la transacción de nueva factura, Monto contable, Tipo de términos de facturación, Id. Del contrato de facturación |
| REEMBOLSO | Subcuenta comercial, ID de suscripción, marca de tiempo de la transacción, monto contable |
| DEVOLUCIÓN | Subcuenta comercial, ID de suscripción, marca de tiempo de la transacción, monto contable |
| EXPIRAR | Subcuenta comercial, ID de suscripción, Fecha de vencimiento, Fecha de cancelación, Transacción por lotes |
| CANCELACIÓN | Subcuenta comercial, ID de suscripción, Fecha de vencimiento, Fecha de cancelación, Transacción por lotes |
| VACÍO | Subcuenta comercial, ID de suscripción, marca de tiempo de la transacción, monto contable |
| CDS | Subcuenta del comerciante, ID de suscripción, Marca de tiempo de la transacción, Nombre, Apellido, Nombre de usuario, Contraseña, Dirección, Ciudad, Estado, Código postal, País, Dirección de correo electrónico, ID de socio, Estado de suscripción, Importe contable, Período inicial, Importe contable recurrente, Período recurrente, estado recurrente, tipo de tarjeta, fecha de cancelación |
| AFILIADO | Subcuenta comercial, tiempo de transacción, ID de suscripción, monto |
| MIEMBROS ACTIVOS | Subcuenta del comerciante, ID de suscripción, Marca de tiempo de la transacción, Nombre, Apellido, Nombre de usuario, Contraseña, Dirección, Ciudad, Estado, Código postal, País, Dirección de correo electrónico, ID de socio, Estado de suscripción, Importe contable, Período inicial, Importe contable recurrente, Período recurrente, estado recurrente, próxima fecha de renovación, tipo de tarjeta, tipo de términos de facturación, identificación del contrato de facturación, fecha de vencimiento, sistema de afiliados |
Los comerciantes deben llamar a CCBill Merchant Support para habilitar las conexiones de enlace de datos en una cuenta. El Soporte para comerciantes necesitará la siguiente información: número de cuenta comercial, número de subcuenta (si solo se desea para una subcuenta), un nombre de usuario nuevo y único, una contraseña nueva y única y la dirección IP del sistema solicitante. Se puede utilizar un rango de direcciones IP, pero todas deben ser propiedad del comerciante o la solicitud puede ser rechazada.
Si las credenciales de la solicitud de enlace de datos no coinciden, la autenticación fallará y el script terminará.
Para solicitar datos de transacciones de Data Link, envíe una solicitud HTTPS estándar a https://datalink.ccbill.com/data/main.cgi con los valores de variable apropiados adjuntos. Los siguientes son ejemplos de solicitudes de enlace de datos válidas:
https://datalink.ccbill.com/data/main.cgi?startTime=20050115010305&endTime=20050115102334&transactionTypes=NEW&clientAccnum=900100&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=NEW,REBILL,REFUND,EXPIRE,CHARGEBACK,VOID,CANCELLATION,CDS&clientAccnum=900100&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=EXPIRE&clientAccnum=900100&clientSubacc=0000&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=NEW,REBILL,REFUND,EXPIRE,CHARGEBACK,VOID,CANCELLATION,CDS&clientAccnum=900100&merchantSubacc=0000&username=user1234&password=passwd12
https://datalink.ccbill.com/data/main.cgi?startTime=20050115010305&endTime=20050115102334&transactionTypes=NEW&clientAccnum=900100&username=user1234&password=passwd12&testMode=1
https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=NEW,REBILL,REFUND,EXPIRE,CHARGEBACK,VOID,CANCELLATION,CDS&clientAccnum=900100&username=user1234&password=passwd12&testMode=1
La función Modo de prueba le permite probar el sistema de enlace de datos y asegurarse de que su software se interconecta correctamente con nuestro sistema. Los datos que se le devuelven son solo para fines de prueba y se devuelven en el mismo formato que durante el funcionamiento normal. Cuando está en el modo de prueba, no hay restricción de tiempo y, por lo tanto, se elimina el período de espera.
Data Link genera un error cuando el script no puede procesar su solicitud. Los errores están precedidos por una cadena "Error:" y se repiten como salida cuando se muestran en un navegador. La siguiente es una lista de algunos errores que pueden ocurrir:
| Código de error | Descripción |
|---|---|
| 01 | Demasiados ingresos fallidos |
| 02 | Error de sesión |
| 03 | Nombre de usuario inactivo |
| 04 | Verificación de IP fallida (lo más probable es que esté fuera de rango) |
Contacto Apoyo comercial si necesita ayuda para solucionar alguno de estos errores.