Guía del usuario del sistema de extracción de enlace de datos

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.

RESUMEN

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.

Parámetros de entrada

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:

NUEVONuevas suscripciones; esto incluye facturación única y recurrente.
REFACTURARSuscripciones que se han vuelto a facturar correctamente.
REEMBOLSOSuscripciones reembolsadas o reembolsos. *
VACÍOSuscripciones o Refacturaciones que hayan sido declaradas nulas.
EXPIRARLas 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ÓNSuscripciones o refacturaciones que se han devuelto.
CANCELACIÓNSuscripciones canceladas. Tenga en cuenta que CCBill Management debe aprobar el uso de esta función.
CDSLas 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.
AFILIADOMuestra la proporción de afiliados de transacciones referidas completadas durante el período de tiempo especificado.
MIEMBROS ACTIVOSEnumera 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.

Variables base

clienteAccnumEsta variable especifica el número de cuenta comercial de seis dígitos de la cuenta para la que se solicitan los datos.
clienteSubaccEste 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 usuarioEl 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ñaEl 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 pruebaEste 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.

Respuesta

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:

  1. Inicie sesión en el Portal de administración y navegue hasta el Info de Cuenta mega menú.
  2. Haga clic en Conjunto de servicios de enlace de datos enlace.
  3. Haga clic en Ver formatos de datos para ver una lista de posibles tipos de transacciones.
  4. Haga clic en Personalizar enlace junto al tipo de transacción para seleccionar qué campos le gustaría recibir para ese tipo de transacción. Serás llevado al Seleccionar campo de la pantalla
  5. Los programas Campos disponibles El cuadro muestra una lista de campos disponibles que están disponibles pero que no se devuelven actualmente. los Campos seleccionados El cuadro muestra todos los campos que se están devolviendo actualmente.
  6. Para agregar un campo al conjunto de datos para el tipo de transacción seleccionado, selecciónelo de la Campos disponibles cuadro y haga clic en el Añada (puede seleccionar más de un campo manteniendo presionada la tecla Control mientras selecciona campos individuales).
  7. Los valores de campo se devuelven en el orden en que aparecen en el Campos seleccionados caja. Para cambiar el orden, seleccione un valor en la lista y haga clic en las flechas hacia arriba y hacia abajo a la derecha del cuadro para mover el elemento seleccionado hacia arriba o hacia abajo en la lista.

Para eliminar un campo del conjunto de datos, selecciónelo en el Campos seleccionados cuadro y haga clic en el Elimine (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 

Definiciones de campo

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 reservaEl 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.

Valores predeterminados del tipo de transacció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:

NUEVOSubcuenta 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
REFACTURARSubcuenta 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
REEMBOLSOSubcuenta comercial, ID de suscripción, marca de tiempo de la transacción, monto contable
DEVOLUCIÓNSubcuenta comercial, ID de suscripción, marca de tiempo de la transacción, monto contable
EXPIRARSubcuenta comercial, ID de suscripción, Fecha de vencimiento, Fecha de cancelación, Transacción por lotes
CANCELACIÓNSubcuenta comercial, ID de suscripción, Fecha de vencimiento, Fecha de cancelación, Transacción por lotes
VACÍOSubcuenta comercial, ID de suscripción, marca de tiempo de la transacción, monto contable
CDSSubcuenta 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
AFILIADOSubcuenta comercial, tiempo de transacción, ID de suscripción, monto
MIEMBROS ACTIVOSSubcuenta 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

Autenticación

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á.

Solicitar datos de transacciones

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:

NUEVA solicitud de transacción sin número de subcuenta comercial:

https://datalink.ccbill.com/data/main.cgi?startTime=20050115010305&endTime=20050115102334&transactionTypes=NEW&clientAccnum=900100&username=user1234&password=passwd12

Varias solicitudes de transacciones sin número de subcuenta comercial:

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

NUEVA solicitud de transacción con número de subcuenta de comerciante opcional:

https://datalink.ccbill.com/data/main.cgi?startTime=20050101000000&endTime=20050101235959&transactionTypes=EXPIRE&clientAccnum=900100&clientSubacc=0000&username=user1234&password=passwd12

Solicitud de transacciones múltiples con número de subcuenta de comerciante opcional:

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

NUEVO Modo de prueba * solicitud de transacción sin número de subcuenta de comerciante:

https://datalink.ccbill.com/data/main.cgi?startTime=20050115010305&endTime=20050115102334&transactionTypes=NEW&clientAccnum=900100&username=user1234&password=passwd12&testMode=1

Modo de prueba múltiple * solicitudes de transacciones sin número de subcuenta de comerciante:

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

Modo de prueba*

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.

Códigos de error

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:

  • Formato de campo no válido o valor ausente.
  • El período seleccionado es superior a 24 horas.
  • La fecha de inicio es mayor que la fecha de finalización.
  • La autenticación falló debido a un nombre de usuario y / o contraseña incorrectos.
  • Dirección IP bloqueada debido a varios intentos fallidos de inicio de sesión.
  • El sistema está fuera de servicio por mantenimiento.
  • Se ha realizado una solicitud en los últimos 60 minutos.
Código de errorDescripción
01Demasiados ingresos fallidos
02Error de sesión
03Nombre de usuario inactivo
04Verificació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.