En este artículo se asume que actualmente dispones de una integración con nuestra API heredada.
Si no dispones de una integración existente o si ya estás utilizando la API actual, este artículo no es aplicable a tu caso. Puedes consultar la documentación de la API actual aquí.
Puede que te resulte útil leer el resumen de cambios antes de leer la guía.
Si tienes una integración de asociado o estás interesado en desarrollar una, esta guía te resultará relevante, pero también te recomendamos que te pongas en contacto con nosotros antes de comenzar.
¿Qué debo hacer primero?
Si todavía no lo has hecho, deberías crear una cuenta de pruebas aquí. Las cuentas de pruebas ya no están vinculadas a tu cuenta real, por lo que tendrás que crear una cuenta de pruebas independiente para desarrollar tu integración con la API nueva.
A continuación, crea un token de acceso. Tendrás que asignar un nombre a tu token de acceso y asegurarte de que tenga acceso de lectura y escritura. Haz clic en "Crear token de acceso" y copia el token en el portapapeles. Guárdalo en un lugar seguro, porque ya no podrás volver acceder a él. Si es necesario, puedes desactivar el token de acceso y crear uno nuevo.
Échale un vistazo a la Guía de introducción y a toda la documentación para desarrolladores para empezar la integración nueva. La guía y la documentación contienen ejemplos de código para todas las bibliotecas de cliente actuales (o las solicitudes HTTP si no tenemos una biblioteca apropiada para tu pila). Puedes ver la fuente de cada biblioteca a través de los enlaces de la documentación.
Realización de solicitudes a la API nueva
Si utilizas una de las bibliotecas de cliente, no tienes que preocuparse sobre este apartado, ya que las bibliotecas se encargan de desarrollar las solicitudes en el formato correcto para ti.
Las URL básicas de la API son las siguientes:
| Real | https://api.gocardless.com/ |
| Cuenta de pruebas | https://api-sandbox.gocardless.com/ |
Tendrás que utilizar el token de acceso creado anteriormente e indicarlo en un encabezado de solicitud de autorización al hacer solicitudes a la API:
Authorization: Bearer TOKEN_ACCESO_AQUÍ
También tendrás que especificar el encabezado de la versión de GoCardless (GoCardless-Version). La versión actualmente disponible en el momento de elaboración de este documento es 2015-07-06:
GoCardless-Version: 2015-07-06
Todas las solicitudes y las respuestas tienen formato JSON y codificación UTF-8. La provisión del encabezado Accept es opcional, pero recomendable. El encabezado Content-Type se tiene que proporcionar cuando se envían datos a la API (usando los extremos POST y PUT). Se puede pasar el tipo JSON MIME estándar (application/json), o la variante JSON-API (application/vnd.api+json).
Webhooks
Ahora los webhooks contienen mucha más información y se pueden enviar a varios extremos. Cuando un recurso cambia de estado, registramos un evento. Los eventos se agrupan en matrices y se envían como webhooks mediante POST.
Si quieres utilizar webhooks, tienes que agregar un extremo de webhooks aquí. En la cuenta de pruebas, puedes utilizar una URL HTTP para los webhooks, pero para utilizarlos en un entorno real, deben tener la seguridad de HTTPS. Puedes consultar información adicional acerca de cómo mantenerte al día con webhooks aquí.
¿Cómo sigo facturando a mis clientes?
Para crear pagos para tus clientes, tienes que utilizar el identificador de mandato del cliente. Sea cual sea el tipo de autorización que se haya utilizado en la API heredada, ahora vas a necesitar el identificador de mandato para crear pagos.
Los identificadores de recursos que hayas utilizado se pueden usar en la API actual, pero se asignarán a recursos ligeramente distintos. Por ejemplo, un identificador de autorización previa en la API heredada es ahora un identificador de mandato en la API actual. A continuación, se ofrece un listado de las asignaciones:
| Identificador anterior | Identificador nuevo |
| Identificador de la autorización previa | Identificador de mandato |
| Identificador de autorización de suscripción | Identificador de suscripción |
| Identificador de autorización ad hoc | Identificador de pago |
| Identificador de factura | Identificador de pago |
Restricciones de mandatos
La API heredada tenía facturas puntuales y suscripciones no editables, por lo que los clientes que hayan configurado esos mandatos de domiciliación bancaria tendrán que aprobar cualquier pago o suscripción nuevos que crees a partir de sus mandatos. A estos mandatos los denominamos "mandatos restringidos".
No se pueden crear mandatos restringidos a través de la API actual, pero existen para que haya una manera fácil de cargar esos tipos de autorización antiguos sin que los clientes tengan que volver a introducir su información bancaria.
| Tipo de autorización antiguo | Tipo de mandato |
| Autorización previa | Mandato sin restricciones |
| Autorización (puntual) ad hoc | Mandato restringido |
| Suscripción | Mandato restringido |
Por medio de un mandato sin restricciones puedes crear pagos y suscripciones para el cliente sin necesidad de una autorización adicional, pero enviaremos un correo electrónico al cliente para informarle que has creado un pago o suscripción en cumplimiento de las normas de esquemas de domiciliación bancaria.
Con un mandato restringido, le enviaremos un correo electrónico al cliente para pedir su autorización antes de aceptar pagos desde su cuenta. El cliente solo tendrá que hacer clic en un enlace del correo electrónico para autorizarlo. No será necesario que vuelva a rellenar las páginas de pago ni que proporcione ningún dato adicional.
Los mandatos con autorización previa no están restringidos, pero la cantidad máxima y el intervalo que se especificaron inicialmente siguen siendo aplicables.
¿Cómo se configuran ahora los pagos puntuales/suscripciones/autorizaciones previas?
En vez de necesitar crear enlaces distintos para cada tipo de autorización, solo tendrás que utilizar el concepto de un flujo de redirección.
En primer lugar, crearás un flujo de redirección para el cliente y lo enviarás a la URL de redirección proporcionada, por ejemplo, https://pay.gocardless.com/flow/RE123.
El cliente rellenará las páginas de pago nuevas y mejoradas de GoCardless, indicando su nombre, correo electrónico, dirección e información bancaria.
Una vez enviado el formulario, almacenaremos de manera segura sus datos y redirigiremos al cliente de vuelta a tu URL de redirección de proceso correcto, que se especifica al crear el flujo de redirección.
A continuación, tendrás que "completar" el flujo de redirección con una sola solicitud a la API, que creará el cliente, la cuenta bancaria del cliente y el mandato. Este proceso es similar al paso "confirmación del recurso" de la API heredada.
Con el mandato recién creado puedes crear pagos y suscripciones para el cliente. Es conveniente que almacenes el identificador de mandato para poder crear con él pagos futuros e identificar webhooks entrantes relacionados con el estado del mandato.
¿Cómo hago el cambio?
Cuando estés satisfecho con la integración con la API nueva en la cuenta de pruebas, te podemos ayudar a realizar el cambio en unas pocas fases:
- Actualizamos tu cuenta al panel de control nuevo. Dejarás de tener acceso al panel de control para desarrolladores antiguo, pero la integración antigua seguirá funcionando. Todos los datos existentes estarán disponibles en el panel de control nuevo.
- En ese momento, tu cuenta ya estará en el panel de control nuevo. Podrás crear un token de acceso y especificar un extremo de webhooks para la cuenta del entorno real.
- Por tu parte, puedes dejar de utilizar la API heredada y empezar a utilizar la nueva como más cómodo te resulte.
- Cuando te parezca que todo funciona correctamente, puedes desactivar el token de acceso y el extremo de webhooks antiguos.
Cosas que cabe destacar:
- Todo el historial de la cuenta seguirá estando disponible y tus clientes no tendrán que volver a darte su autorización.
- Los recursos que crees a través del panel de control o la API nuevos no estarán accesibles desde la integración antigua, pero los recursos que se hayan creado en la integración antigua sí estarán accesibles desde la API nueva.
- Tendrás que ponerte en contacto con nosotros para que actualicemos tu cuenta y, posteriormente, desactivemos tu integración antigua (o si te surge alguna duda durante el proceso).
- Si tienes una integración de asociado antigua, deberías ponerte en contacto con nosotros para asegurarte de que este proceso de transición sea adecuado para tu integración.