API CCBill: Tangibles

Introducción

Este documento es un anexo a la API de CCBill y analiza la configuración del comerciante de la API de CCBill para implementar las ventas de productos tangibles de suscripción.

Alcance

La API de CCBill se considera una característica avanzada del sistema de CCBill. Este documento asume lo siguiente:

  • El usuario ya ha habilitado la API de CCBill.
  • El usuario posee habilidades de programación de nivel intermedio a avanzado.
  • La empresa del usuario vende envíos únicos y / o recurrentes y ha completado todos los procesos necesarios para habilitar dicha función en la cuenta y / o subcuenta.
  • El usuario tiene acceso a los remitentes admitidos; UPS, USPS y / o FedEx.

RESUMEN

Se han agregado tres acciones a la API de CCBill, crearCumplimiento, actualizaciónCumplimiento y getFulfillmentStatus. Estas acciones permiten insertar y mantener la información del envío en nuestro sistema.

Estructura de acción

Cada acción realizada a través de la API de CCBill al sistema CCBill debe incluir los parámetros estándar de la API de CCBill aplicables (clienteAccnum, clienteSubacc, usandoSubacc, nombre de usuario, la contraseña, retornoXML- no todos son obligatorios. Ver el Guía de la API de CCBill para obtener más información sobre la estructura básica de la API de CCBill.

Acciones

Las acciones y sus respectivos parámetros se enumeran en esta sección. El sistema de CCBill enviará una respuesta a la acción; las posibles respuestas se definen en la sección Respuesta más adelante en este documento.

crearCumplimiento

Los programas crearCumplimiento La acción le permite insertar información de envío en nuestro sistema. La acción consta de los siguientes parámetros obligatorios:

ParámetroPropósitoDatos
ID de transacciónIdentifica la transacción con la que está asociado el envío.19-20 caracteres numéricos; subscriptionId o ID asociado con la refacturación.
compañía de enviosIdentifica el nombre de la empresa que realiza el envío físico.Los parámetros permitidos son: 1. UPS (United Parcel Service)
2. USPS (Servicio Postal de los Estados Unidos)
3. FedEx (Anteriormente Federal Express)
Estos parámetros distinguen entre mayúsculas y minúsculas.
ID de rastreoIdentifica el número de seguimiento de la empresa que realiza el envío físico.Para UPS: * 4-20 caracteres alfanuméricos. Para USPS
(Clase o servicio de correo (con número de identificación de etiqueta de muestra)): * Express Mail® EA 000 000 000 US
* Express Mail International® EC 000 000 000 US
* Priority Mail International® CP 000 000 000 US
* Global Express Guaranteed® 82 000 000 00
*Correo registrado RA 000 000 000 US
*Confirmacion de envio 0000 0000 0000 0000 0000 00 Para FedEx: * 12 dígitos numéricos

CreateFulfillment Ejemplo de acción

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=createFulfillment&transactionId=12345678987654321&shippingCompany=FedEx&trackingId=123456789987

actualizaciónCumplimiento

Los programas actualizaciónCumplimiento La acción le permite actualizar el remitente existente y / o el número de seguimiento para un ID de transacción. Cualquier dato que envíe usando esta acción reemplazará al enviado previamente compañía de envios y ID de rastreo parámetros del anterior crearCumplimiento or actualizaciónCumplimiento acciones y reemplazarlo con los datos que se envían.

Los siguientes parámetros son necesarios para actualizaciónCumplimiento acción:

ParámetroPropósitoDatos
ID de transacciónIdentifica la transacción con la que está asociado el envío.19-20 caracteres numéricos; subscriptionId o ID asociado con la refacturación.
Identificación del envíoGenerado por CCBill y enviado con la respuesta createFulfillment original y utilizado para identificar el envío.Caracteres numéricos de longitud variable, nunca más de 20 caracteres.
compañía de enviosIdentifica el nombre de la empresa que realiza el envío físico.Los parámetros permitidos son: 1. UPS (United Parcel Service)
2. USPS (Servicio Postal de los Estados Unidos)
3. FedEx (Anteriormente Federal Express)
Estos parámetros distinguen entre mayúsculas y minúsculas.
ID de rastreoIdentifica el número de seguimiento de la empresa que realiza el envío físico.Para UPS: * 4-20 caracteres alfanuméricos. Para USPS
(Clase o servicio de correo (con número de identificación de etiqueta de muestra)): * Express Mail® EA 000 000 000 US
* Express Mail International® EC 000 000 000 US
* Priority Mail International® CP 000 000 000 US
* Global Express Guaranteed® 82 000 000 00
*Correo registrado RA 000 000 000 US
*Confirmacion de envio 0000 0000 0000 0000 0000 00 Para FedEx: * 12 dígitos numéricos

updateFulfillment Ejemplo de acción

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=updateFulfillment&transactionId=12345678987654321&shipmentId=123456&shippingCompany=FedEx&trackingId=123456789887

getFulfillmentStatus

Los programas getFulfillmentStatus La acción le permite consultar el sistema CCBill para obtener datos de cumplimiento almacenados previamente para una transacción.

Los programas getFulfillmentStatus action utiliza los siguientes parámetros:

ParámetroPropósitoDatos
ID de transacciónIdentifica la transacción con la que está asociado el envío.19-20 caracteres numéricos; subscriptionId o ID asociado con la refacturación.
Identificación del envíoGenerado por CCBill y enviado con la respuesta createFulfillment original y utilizado para identificar el envío.Parámetro opcional. Caracteres numéricos de longitud variable, nunca más de 20 caracteres.

Acción de muestra getFulfillmentStatus

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=923590&username=testuser&password=testpassword&returnXML=1&clientSubacc=0005&action=getFulfillmentStatus&transactionId=12345678987654321&shipmentId=123456

Respuesta

Éxito

Las respuestas correctas se devolverán con algunos o todos los siguientes parámetros:

RespuestaPropósitoDatos
ID de rastreoIdentifica el número de seguimiento de la empresa que realiza el envío físico.Para UPS: * 4-20 caracteres alfanuméricos. Para USPS
(Clase o servicio de correo (con número de identificación de etiqueta de muestra)): * Express Mail® EA 000 000 000 US
* Express Mail International® EC 000 000 000 US
* Priority Mail International® CP 000 000 000 US
* Global Express Guaranteed® 82 000 000 00
*Correo registrado RA 000 000 000 US
*Confirmacion de envio 0000 0000 0000 0000 0000 00 Para FedEx: * 12 dígitos numéricos
Identificación del envíoGenerado por CCBill y enviado con la respuesta createFulfillment original y utilizado para identificar el envío.Parámetro opcional. Caracteres numéricos de longitud variable, nunca más de 20 caracteres.
fecha de creaciónLa fecha y hora en que se creó el registro.2010-06-01T15:27:11.529-07:00   AAAA-MM-DDTHH: mm: ss.lllooo: 00 * AAAA es el año de 4 dígitos $$$ * MM es el mes de 2 dígitos
* DD es el día de 2 dígitos
* HH es la hora de 2 dígitos
* mm es el minuto de 2 dígitos
* ss es el segundo de 2 dígitos
* lll son los milisegundos de 3 dígitos
* ooo: 00 es el desplazamiento GMT (IE -07: 00 es GMT-7)
nextCheckTimeLa próxima vez, el sistema CCBill comprobará el estado del envío.2010-06-01T15:27:11.529-07:00   AAAA-MM-DDTHH: mm: ss.lllooo: 00 * AAAA es el año de 4 dígitos $$$ * MM es el mes de 2 dígitos
* DD es el día de 2 dígitos
* HH es la hora de 2 dígitos
* mm es el minuto de 2 dígitos
* ss es el segundo de 2 dígitos
* lll son los milisegundos de 3 dígitos
* ooo: 00 es el desplazamiento GMT (IE -07: 00 es GMT-7)
anteriorEnvíoIdPermite a los clientes recuperar información de envío almacenada previamente para una transacción; siempre el más reciente.Caracteres numéricos de longitud variable, nunca más de 20 caracteres.
checkStatusURLLa URL que utiliza CCBill para verificar el estado del envío.http://www.shipperurl.com/
ccbillEnvíoEstadoEl código de estado que utiliza CCBill para los envíos.*Mira la sección: Códigos de estado más adelante en este documento para obtener una lista de los códigos de estado de CCBill y sus significados.
compañía de enviosIdentifica el nombre de la empresa que realiza el envío físico.Los parámetros permitidos son: *UPS (United Parcel Service)

Muestra de respuesta exitosa

Respuesta delimitada por comas

"trackingId","shipmentId","creationDate","shipperStatus","nextCheckTime","prevShipmentId","checkStatusURL","ccbillShipmentStatus","shippingCompany"
"1","13","2010-06-01T15:27:11.529-07:00","ERROR RESPONSE","2010-06-01T23:27:23.326-07:00","0", "http://www.fedex.com/Tracking?language=english&cntry_code=&tracknumbers=1","SHIPPER_ERROR","FedEx"

Respuesta XML

Envío a SHIPPER_ERROR http://www.fedex.com/Tracking?language=english&cntry_code=&tracknumbers=1.0 1-2010-06T01: 15: 36-05.159: 07 00-2010-06T01: 23: 36-08.211: 07 00 13 RESPUESTA AL ERROR FedEx EA 14 000 000 EE. UU. 000 900000 0000-2010-06T01: 15: 27-10: 07 00 910130101000000003

Códigos de estado

CódigoDescripción
SIN DATOSEl estado inicial de cada Envío que aparece cuando la información de cumplimiento no se ha agregado o no se ha agregado correctamente.
PENDIENTEIndica que los datos de cumplimiento ingresados ​​por el cliente están esperando ser enviados al remitente para su primera verificación de estado; Se ingresaron los datos de cumplimiento, pero el período de espera de 8 horas para la verificación inicial del remitente aún no ha pasado.
ENVIADOEste es el estado que indica que un Envío está con el remitente pero aún no lo ha recibido el consumidor.
ENVÍO_ERRORLa empresa de envío ha devuelto un error similar a "estado no disponible" en nuestro sistema durante la verificación de estado más reciente.
DeliveredLa empresa de envío nos ha devuelto un estado que indica que el envío ha sido entregado al destinatario.
NO_ENTREGABLEIndica que un envío no se puede entregar al consumidor por algún motivo, incluidos errores de dirección y rechazos.
DESPEJADOUn miembro del personal de CCBill borró el estado y lo estableció como OK.

Error

Los errores pueden deberse a varios motivos, siendo los más habituales los errores de validación de datos. A continuación, se muestra una lista de la validación de datos realizada por las funciones de suscripción tangibles:

  • Se verifica la exactitud del número de cuenta del comerciante, el número de subcuenta, el ID de suscripción o el ID de transacción.
  • La identificación de seguimiento y el remitente deben estar presentes.
  • El ID de transacción proporcionado pertenece a la cuenta del comerciante (y la subcuenta, si corresponde).
  • La identificación de seguimiento proporcionada debe coincidir con uno de los formatos aceptados por el remitente (proporcionado arriba).

Una respuesta de error suele contener dos parámetros:

  • errorDesc: Esta es una descripción del error que recibió su acción de nuestro sistema.
  • código de error: Este es el número de código en el que se almacena el error en nuestro sistema.

Todos los posibles errores, junto con la información de solución de problemas, se incluyen en esta tabla:

errorDesccódigo de errorDescripción
ERROR_SERVICE_ERROR-200Este es un código de error genérico y generalmente indica que el servicio no está disponible temporalmente.
ERROR_MISSING_PARAM-201Uno de los parámetros necesarios para la función no se incluyó en la acción. Consulte el cuadro anterior para conocer los parámetros necesarios para la acción que está intentando realizar y verifique que el formato de su acción esté correctamente construido.
ERROR_NO_COINCIDIR_ENVÍO-202El parámetro shippingId contiene información de identificación de envío desconocida / no coincidente.
ERROR_INVALID_TRACKING_NUMBER-203El parámetro trackingId contiene información no válida. Verifique que el trackingId contenga todos los caracteres esperados, coincida con el formato esperado para el parámetro shippingCompany (consulte la tabla anterior) y verifique el trackingId en el recibo de envío proporcionado por su compañía de envío.
ERROR_NO_COINCIDIR_TRANSACCIÓN-204El transactionId proporcionado en la acción no coincide con ningún transactionId previamente conocido para su número de cuenta (y número de subcuenta, si corresponde). Verifique el transactionId y vuelva a enviarlo, si es necesario.