Esta es la documentación del API de Suscripciones.co, por medio de esta API tu equipo de desarrollo podrá integrarse con nuestra plataforma para generar links de pago y consultar el estado de tus suscripciones.
Primeros pasos
Antes de empezar a usar nuestro API, debés contactar a soporte para que te habiliten el acceso y te generen un conjunto de llaves para que puedas acceder a toda tu información.
Documentación del API
Toda la documentación de nuestro API la puedes encontrar vistando https://api.suscripciones.co/public/docs/, en este enlace encontrarás un Swagger con la descripción de cada endpoint y que provee la posibilidad de probar en línea todos los endpoints con tus propias llaves del API.
Autenticación
Llaves del API
La autenticación del API de Suscripciones.co se realiza por medio de llaves, estas llaves pueden ser de caracter público (operaciones realizadas desde el cliente) o privado (operaciones sensibles realizadas desde tu servidor) y además de esto pueden ser de prueba o producción. Todas nuestras llaves siguen el siguiente formato:
sus_<caracter>_<entorno>_<caracteres_aleatorios>
Donde
"caracter"es el caracter de la llave,"private"si es privada y"public"si es pública"entorno"es el entorno al que apunta la llave,"prod"si es de producción y"test"si es de prueba"caracteres_aleatorios"es una cadena de caracteres aleatorios que permiten distinguir tu llave de las de los otros comercios
Algunos ejemplos de estas llaves son:
sus_private_prod_jvetjPjhltOLIt70SxDqTOyJsus_private_test_IdxQEKv8khQCL8QxPeaegvYvsus_public_prod_hfqt6G9BX7N1ksR3W1Usgrxysus_public_test_PY5RkWoHTst1YPC4Hg04ZSWs
Autenticando las peticiones
Las autenticación de las peticiones se realiza por medio del header "x-sus-api-key", en el valor de este header se debe incluir la llave de API deseada. Por ejemplo, una petición con "fetch" se realiza de la siguiente manera:
const response = await fetch(
"https://api.suscripciones.co/public/v1/payments",
{
method: "post",
headers: {
"content-type": "application/json",
"x-sus-api-key": "sus_private_prod_jvetjPjhltOLIt70SxDqTOyJ",
},
body: JSON.stringify(body),
},
);
Webhook de eventos
Al usar nuestra integración a través del API, también te ofrecemos la posibilidad de configurar un webhook a través del cual recibirás eventos relevantes de tus suscripciones.
Configuración del webhook
Para configurar tu webhook de eventos debes contactar a soporte. Cuando tu webhook esté configurado soporte compartirá con tu equipo el valor del secreto que podrás usar para verificar la autenticidad de las peticiones que enviemos a tu endpoint.
Autenticación del webhook
Para que puedas verificar la autenticidad de las peticiones que llegan a tu endpoint nosotros incluímos el header "x-sus-webhook-secret" cuyo valor debe coincidir con el secreto que te envió soporte al realizar la configuración de tu webhook.
Estructura de la petición
Las peticiones a tu endpoint se realizarán usando el método POST y el cuerpo de la petición siempre sigue el siguiente schema:
{
"type": string,
"sandbox": boolean,
"data": object,
}
Donde
"type"es un string que indica el tipo de evento que ocurrió"sandbox"es un booleano que indica el entorno en el que ocurrió el evento,"true"para prueba y"false"para producción"data"es un objeto o arreglo que contiene la información relacionada al evento
Eventos
Suscripción creada (subscription.created)
Este evento lo recibirás cada vez que se cree una nueva suscripción. Con la petición vas a recibir la siguiente información en el cuerpo:
{
"type": "subscription.created",
"sandbox": true,
"data": [
{
"panelUrl": "https://go.suscripciones.co/subs/cK2fCMtMeunMq72ShIMeTH2z?token=tsub-42nbkxec9jl9wd783rr857ylzhzva596",
"id": "cK2fCMtMeunMq72ShIMeTH2z",
"site": "your-site",
"createdAt": "2024-04-10T20:27:43.039Z",
"cancelledAt": null,
"userData": {
"email": "[email protected]"
},
"frequency": "1m",
"status": "ACTIVE",
"hasIssues": false,
"externalReference": "",
"humanDescription": "",
"shippingAddress": {
"city": "BOGOTA (C/MARCA)",
"state": "Bogota D.C",
"country": "CO",
"street": "Calle 123 4-20"
},
"priceInCents": 10000000,
"currency": "COP",
"plans": [
{
"planId": "s6WzUiMwNiAzrWwrXZ0kABRF",
"name": "Plan 1",
"quantity": 1,
}
],
"bundles": [
{
"bundleId": "NrkIjxdV98ZTgrUylfWML1qD",
"name": "Bundle 1",
}
]
}
]
}