Documentación de Integración API Custom para Implementar Addi en E-commerce

a continuación, se describe el flujo de comunicación y las reglas de negocio para integrar addi como método de pago en un e commerce notas generales ambientes addi cuenta con entornos de staging y producción las credenciales de staging se solicitan a soporte aliados\@addi com mailto\ soporte aliados\@addi com las de producción son únicas e intransferibles y se entregan tras la certificación de la integración idempotencia los recursos http de la api son idempotentes (garantizan que un crédito se origina solo una vez) y permiten reintentos seguros en caso de fallos 5xx moneda y documento solo se opera en pesos colombianos (cop) y con personas naturales (tipo de documento cc) flujo de la integración 1\ verificación de montos y descuentos (config endpoint) en el checkout, al listar los métodos de pago, se debe consumir este endpoint para determinar si addi debe estar disponible y si aplica algún descuento visual endpoint get https //channels public api addi com/allies/ally slug/config?requestedamount=xxxx https //channels public api addi com/allies/ally slug/config?requestedamount=xxxx (reemplazar ally slug y xxxx con los datos correspondientes del comercio) ejemplo { "name" "get config", "method" "get", "url" "https //channels public api addi com/allies/ally slug/config?requestedamount=xxxx", "description" "obtener configuración del comercio con el ally slug y el monto para solicitar el crédito", "tab" "examples", "examples" { "languages" \[ { "id" "tyeivxpqzkuc2pmf0krk9", "language" "curl", "code" "curl location 'https //channels public api addi com/allies/miallyslug/config?requestedamount=80000' \\\\\n header 'accept application/json' \\\\\n header 'content type application/json'", "customlabel" "" } ], "selectedlanguageid" "tyeivxpqzkuc2pmf0krk9" }, "results" { "languages" \[ { "id" "duzmcyvr0xg2rcwfqkblv", "language" "200", "code" "{\n \\"minamount\\" 10000,\n \\"maxamount\\" 10000000,\n \\"policy\\" {\n \\"discount\\" 0 2,\n \\"producttype\\" \\"addi pago\\",\n \\"policymaxamount\\" 800001,\n \\"isvisible\\" true\n },\n \\"widgetconfig\\" {\n \\"widgetversion\\" \\"addi template flex\\",\n \\"widgetshowpreapproval\\" true\n },\n \\"checkoutconfig\\" {\n \\"version\\" \\"bnpl bnpn v1\\"\n },\n \\"isactiveally\\" true,\n \\"isactivepaynow\\" true\n}" }, { "id" "vb5gfxflde tujogx8vvx", "language" "404", "code" "{\n \\"code\\" \\"007 017\\",\n \\"message\\" \\"the ally does not exist \\"\n}" } ], "selectedlanguageid" "duzmcyvr0xg2rcwfqkblv" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "ally slug", "kind" "required", "type" "string", "description" "identificador del comercio proporcionado por addi ", "" "identificador del comercio proporcionado por addi " }, { "name" "requestedamount", "kind" "required", "type" "number", "description" "monto total de la compra para la solicitud del credito con addi ", "" "required" } ], "headerparameters" \[], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" false, "autogeneratedanchorslug" "get config", "legacyhash" "bumhkwhythp3ihhtktvxp" } manejo de topes si el monto del carrito está fuera del rango permitido (minamount y maxamount), no se recomienda ocultar el método de pago lo ideal es deshabilitarlo y mostrar un disclaimer (ej "aplica solo para compras entre x y y") esta práctica es directa, resuelve dudas y fomenta que el cliente agregue más productos al carrito para alcanzar el monto mínimo manejo de descuentos el valor de discount es puramente visual (ej 0 02 = 2%) no se debe modificar el valor total aplicando el descuento antes de enviar la petición se debe enviar el monto original en la solicitud de transacción; addi se encarga de aplicar el descuento internamente según la negociación 2\ autenticación la seguridad se maneja vía addi auth con autenticación oauth(idaas) se requiere obtener un json web token (jwt) antes de consumir los demás endpoints documentación api auth docs https //api docs addi staging com/auth/#/authentication mejor práctica se debe generar un token nuevo por cada intento de transacción reutilizar un mismo token para múltiples transacciones simultáneas puede causar errores debido a tiempos de expiración cruzados 3\ creación de la aplicación (transacción) este endpoint se utiliza para iniciar el proceso de pago la transacción se creará inicialmente en estado "pendiente" documentación create online loan application https //api docs addi staging com/integration/#/online%20application/createonlineloanapplication order id es posible usar cualquier formato (uuid, números, letras), pero debe ser único por cada intento de compra si una persona falla o abandona el proceso y vuelve a intentar con el mismo carrito, se debe generar y enviar un order id distinto redirección (status 301) el endpoint devuelve un estado http 301 (sin body) con un header location que contiene la url de addi 🛑 importante sobre la redirección muchos frameworks siguen el redireccionamiento 301 de manera automática, lo que suele resultar en pérdida de parámetros o en un falso status 200 para un comportamiento estable, se sugiere desactivar la redirección automática en el código, capturar el status 301 y usar la url provista para redirigir al cliente manualmente 4\ reporte de resultado (webhook / callback) y redirección addi notificará al servidor del comercio el estado final de la transacción de forma asíncrona, previo a devolver al cliente al e commerce los tiempos de decisión toman generalmente entre 20 segundos y 10 minutos (depende de cada usuario) configuración de urls tanto la url de respuesta para el webhook como la url de redirección del cliente no son estáticas ni se configuran en un panel global deben definirse dinámicamente por cada transacción enviando las llaves callbackurl y redirectionurl dentro del body (json) de la petición al momento de crear la transacción (descrito en el punto 3) documentación online application callback https //api docs addi staging com/integration/#/online%20application%20callback/ estados posibles (enum) approved, rejected, declined, abandoned redirección dinámica (redirectionurl) una vez finalizado el proceso en addi, el cliente es retornado a la tienda esta url debe ser dinámica si el estado fue approved, se debe dirigir al cliente a la página de agradecimiento ( thank you page ) para cualquier otro estado, se le debe redirigir a la página del carrito para permitir un nuevo intento de compra con addi o con otro método de pago monto aprobado addi no realiza aprobaciones parciales el campo approvedamount siempre será 0, a menos que la transacción sea aprobada; en dicho escenario, el monto será exactamente igual al valor solicitado tiempo máximo de expiración de una transacción 2 horas requisitos del webhook (callbackurl) debe contar con autenticación básica ( basic auth ) las credenciales deben ser entregadas al equipo de integraciones previo al paso a producción para que los sistemas de addi marquen la notificación de la transacción como exitosa, el endpoint del comercio debe responder con un status http 200 y retornar exactamente el mismo cuerpo (body) en formato json que recibió en la petición reintentos en caso de que el webhook falle o la comunicación no se pueda establecer, addi marcará el envío como incompleto y realizará reintentos cada 30 minutos durante 24 horas si el problema persiste, el equipo de soporte puede forzar el envío de forma semi automática 5\ cancelaciones / reembolsos proveemos un endpoint dedicado para reversar compras previamente aprobadas (requiere autenticación con jwt) documentación online application cancellation https //api docs addi staging com/integration/#/online%20application%20cancellation total vs parcial si se envía un monto que coincide con el valor original de la transacción, el sistema asumirá una cancelación total si el monto es menor, se procesará como una cancelación parcial límites solo se permite realizar una (1) solicitud de cancelación por transacción, ya sea total o parcial soporte en caso de requerir una corrección o necesitar más de una cancelación parcial sobre una misma orden, se debe realizar una solicitud formal contactando al equipo de soporte a través de soporte aliados\@addi com mailto\ soporte aliados\@addi com