[GUIA] Integración básica Amplify SDK (Tienda única)
Última actualización
Última actualización
En esta guía vamos a aprender como integrar Amplify SDK a un proyecto en Next JS desde cero.
Si utilizan otra tecnología o framework algunas cosas de esta guía pueden no funcionar o requerir adaptación
Para poder utilizar Amplify SDK es requisito indispensable el tener una cuenta dentro de la plataforma ya que vamos a utilizar una serie de claves que se generan dentro de la misma. Las cuentas en la plataforma de Amplify son gratuitas y pueden ser creadas desde https://admin.getamplify.app/registro
Luego de crear tu cuenta, es necesario configurarla para acceder a todas las funcionalidades.
Para hacerlo podes ingresar https://admin.getamplify.app/configuracion en donde vas a encontrar que existen dos tipos de cuentas (tienda única y plataforma) las cuales están pensadas para distintos modelos de negocio
IMPORTANTE: Esta elección queda asociada a la cuenta y es permanente.
Elige esta opción si tu negocio se basa en la venta de bienes físicos o digitales. Ejemplo: Venta de cursos o indumentaria.
Elige esta opción si tu negocio es una plataforma que cobra una comisión por el uso de la misma. Ejemplo: Cafecito, Uber, Rappi.
El código de esta guía utiliza como tipo de cuenta "Tienda única"
Para poder acceder a información sensible de tu cuentas vas a necesitar autenticarte. Amplify utiliza un sistema de API Keys el cual se tienen que enviar en cada request desde un entorno seguro (servidor).
Podes generar tus API Keys en https://admin.getamplify.app/api-keys.
IMPORTANTE: Las API Keys generadas solo son validas en el ambiente en donde fueron creadas por lo que vas a tener que generar una para prod y otra para dev.
Podes cambiar de ambiente utilizando el switch que esta al lado de tu nombre en la barra de navegación superior
Una vez que tengas tu API Key guardala en un lugar seguro. La misma solo se muestra al momento de la creación y no se puede recuperar (el equipo de Amplify tampoco puede hacerlo). Por lo que si pierdes tu API Key vas a tener que crear una nueva.
Versiones utilizadas en esta guía
Next: 14.1.4
Amplify: 0.0.67
En esta ocasión vamos a estar usando Next para la creación de nuestro proyecto pero Amplify es compatible con cualquier stack tecnológico mientras tengamos un frontend para mostrar el SDK y un backend para enviar los requests de forma segura.
A. Cloná el siguiente repositorio: https://github.com/Fundit-Finance/sdk-self-with-next
B. Crea en la raíz del proyecto un archivo que se llame .env.local
copiando el contenido de .env.example
C. Reemplaza las variables API_KEY y CLIENT_ID por las que generaste en el paso 3 de esta guía
D. Instala las dependencias del proyecto ejecutando npm install
E. Inicia el servidor con el comando npm run dev
F. Ingresa a http://localhost:3000
y si todo esta configurado correctamente deberías ver el SDK funcionando
Ahora que ya tenemos nuestra integración funcional, vamos a entender un poco mejor como funciona el repositorio que clonamos y como podemos personalizarlo para nuestras necesidades. Arranquemos con el frontend.
Para que Amplify se renderice correctamente tenemos que pasarles algunos parámetros:
URL a la cual el frontend le va a hacer la request HTTP de forma automática al renderizarse para crear la Intención de pago. Esta URL tiene que ser una API que admita el método POST. En el ejemplo es /api/amplify/intent
Si bien esta propiedad no es requerida para que Amplify funcione, en la gran mayoría de los casos vamos a querer guardar información en nuestro backend o enviar metadata a Amplify para poder relacionar pagos con compradores. Esta propiedad es un objeto el cual se va a inyectar automáticamente en el body
en el post que se hace a la URL que definimos en #createpaymentintenturl-less-than-string-greater-than
Admite los valores test
y production
. Los cuales sirven para identificar que tipo de API Key estamos utilizando. Esto va a determinar si a la hora de renderizar el SDK mostramos las redes y los tokens de prueba o los productivos.
Si queres conseguir tokens de prueba podes ver como hacerlo en Obteniendo tokens de prueba
Amplify soporta light y dark mode por lo que con la propiedad theme
podemos elegir que tema queremos para nuestra integración
Admite los valores EN
y ES
. Sirve para cambiar el idioma de todos los textos internos del SDK
Con estos parámetros ya vas a poder manejar todo el flujo básico de Amplify pero si queres personalizarlo un poco mas, podes encontrar mas información en las secciones Propiedades y Personalización
Para la parte del backend el archivo que hay que analizar es pages/api/amplify/intent.js
. En donde te vas a encontrar con lo siguiente:
A. Validamos que el request sea tipo POST
B. Leemos las variables API_KEY, CLIENT_ID y BASE_URL de nuestro archivo de configuración y en caso de que no exista alguna de las claves lanzamos un error
C. Hacemos un HTTP Request a /api/payment_intent
enviando nuestra API KEY y CLIENT ID. Este endpoint también admite cierta información adicional que podemos enviarle para personalizar nuestra experiencia, podes ver que campos se pueden mandar en Intención de pago
D. ¡IMPORTANTE! Retornamos a nuestro frontend la información que obtenemos como respuesta del HTTP Request que hicimos en el punto C
Ahora que ya tenemos nuestra integración funcional y que entendemos como es el flujo de la misma podemos hacer un pago de prueba para ver que todo este impactando correctamente.
No tenes tokens de prueba? Aprende como conseguirlos de forma gratuita en Obteniendo tokens de prueba
Si el pago se ejecuto de forma correcta, en https://admin.getamplify.app/ deberías ver la información del pago