Saltar al contenido principal

📌 Introducción

🎯 Datos de interés​

  • Plan: Un conjunto de características, servicios y condiciones definidos que los usuarios pueden elegir para acceder a la plataforma. Un plan establece los límites y beneficios disponibles, como el número de usuarios permitidos, funcionalidades habilitadas y costos asociados.
  • Suscripción: El vínculo entre un usuario y un plan. Representa el compromiso del usuario con un plan específico, incluyendo la duración del acceso, el estado de pago y las condiciones de renovación o cancelación.

🎯 Definición​

La API de Gestión de Suscripciones permite la creación, administración y control de suscripciones de clientes de manera automatizada. Con esta API, podrás integrar un sistema de suscripciones en tu plataforma, facilitando la inscripción, renovación y cancelación de clientes en distintos planes de suscripción.

🎯 Funcionalidades Clave​

✅ Crear suscripciones para nuevos clientes.
✅ Administrar planes de suscripción (crear, actualizar o eliminar).
✅ Suscribir clientes a un plan específico.
✅ Gestionar cancelaciones y renovaciones de suscripciones.
✅ Consultar el estado de una suscripción en tiempo real.

Esta API está diseñada para ser segura, escalable y fácil de integrar con otros sistemas de pago y gestión de clientes.

1️⃣ Autenticación y Seguridad 🔑​

Para acceder a la API, es necesario autenticar cada petición mediante un token Bearer en el encabezado de la solicitud. Esto garantiza que solo los usuarios autorizados puedan interactuar con los endpoints.

✨ Autenticación mediante Bearer Token​

La API requiere que todas las solicitudes incluyan un token de autenticación en el encabezado Authorization.

📂 Formato del encabezado​

Authorization: Bearer {your_token}

🛡️ Manejo de Errores de Autenticación​

Si el token es inválido o no está presente, la API responderá con un código de estado HTTP 401 Unauthorized.

2️⃣ Endpoints y Métodos Disponibles 🌍​

Para realizar el proceso de suscripciones se tienen los siguientes métodos:

📌 Crear Plan​

  • URL base: https://api-sandbox.n1co.shop
  • Método: POST
  • Endpoint: /api/v2/Plans
  • Descripción: Crea una nueva suscripción para uno o más clientes.
  • Cabeceras necesarias:
    • Content-Type: application/json
    • Authorization: Bearer {your_token}
  • Cuerpo de la petición (JSON):
{
  "name": "nombre de la suscripción",
  "description": "descripción de la suscripción",
  "amount": 10,
  "ogTitle": "",
  "ogDescription": "",
  "ogImageBase64": null,
  "linkImageBase64": null,
  "customFields": [
    {
      "label": "CustomFields",
      "name": "customFields",
      "placeholder": "Este es un customField",
      "isRequired": false,
      "isVisible": true,
      "isEditable": true,
      "defaultValue": null
    }
  ],
  "successUrl": "https://pay.h4b.dev",
  "cancelUrl": "https://pay.h4b.dev",
  "billingCycleType": "WEEK",
  "billingCyclesNumber": 1,
  "cyclesToBillBeforeAllowCancelation": 2,
  "termsAndConditions": null,
  "subscriberLimit": 3,
  "enrollmentEndDate": "2025-12-30T18:00:00.000Z",
  "subscriptionEndDate": "2025-12-31T18:00:00.000Z",
  "billingDay": null,
  "locationId": 1
}
  • Respuesta esperada (200 OK):
    • Id del plan (suscripción) creado

⿲ Descripción:​

billingCyclesNumber: periodicidad de cobro (ejemplo 2 días, 1 mes, 1 semana, 1 año,etc.)

cyclesToBillBeforeAllowCancelation: Si se desea colocar periodos obligatorios antes de cancelar una suscripción, se puede configurar en este campo, de lo contrario debe enviarse null

subscriberLimit: Se puede configurar un límite de suscriptores que va a tener nuestro plan, de lo contrario se puede enviar null

enrollmentEndDate: Se puede indicar una fecha límite para aceptar suscriptores, después de esta fecha ya no se podrán agregar más suscriptores al plan

subscriptionEndDate: También es posible configurar una fecha de finalización para nuestra suscripción, llegada esta fecha la suscripción pasará a estar inactiva y ya no se realizarán más cobros a los usuarios, este campo puede ir null

billingDay: Para las suscripciones mensuales se puede configurar un día específico de cobro, este campo acepta null

locationId: El id de nuestra sucursal a la cual se asociará el plan/suscripción

{
  "name": "Nombre de la suscripción",
  "description": "Descripción de la suscripción",
  "amount": 10,
  "successUrl": "url hacia donde quieres redirigir en caso de éxito",
  "cancelUrl": "url hacia donde quieres redirigir en caso de error",
  "billingCycleType": "Los posibles valores son: DAY, WEEK, MONTH, YEAR",
  "billingCyclesNumber": 1,
  "cyclesToBillBeforeAllowCancelation": 2,
  "subscriberLimit": 3,
  "enrollmentEndDate": "2025-12-30T18:00:00.000Z",
  "subscriptionEndDate": "2025-12-31T18:00:00.000Z",
  "billingDay": null,
  "locationId": 1
}

📌 Consultar planes​

Este servicio utiliza el id del plan como **path parameter, **se puede obtener un plan en específico o consultar todos los planes.

Get plan by Id​

  • URL base: https://api-sandbox.n1co.shop
  • Método: GET
  • Endpoint: /api/v2/Plans/{planId}
  • Descripción: Obtiene la información de un plan.
  • Cabeceras necesarias:
    • Authorization: Bearer {your_token}

Get all plans​

  • URL base: https://api-sandbox.n1co.shop
  • Método: GET
  • Endpoint: /api/v2/Plans/all
  • Descripción: Obtiene la información de un plan.
  • Cabeceras necesarias:
    • Authorization: Bearer {your_token}

📌 Suscribir un usuario​

Subscriptions​

  • URL base: https://api-sandbox.n1co.shop
  • Método: GET
  • Endpoint: /api/v2/Subscriptions
  • Descripción: Obtiene la información de un plan.
  • Cabeceras necesarias:
    • Authorization: Bearer {your_token}
    • Content-Type: application/json
    • Request:
{
  "subscriptionLinkId": 424,
  "customer": {
    "name": "Rollffin",
    "email": "rolfin.guiroa@n1co.com",
    "phoneNumber": "+50377202044"
  },
  "paymentMethod": {
    "id": "67d9c7656d580a9ce2e41f17"
  },
  "backupPaymentMethod": {
    "id": "67dc46126d580a9ce2e41f23"
  },
  "locationCode": "SIGMA-01"
}

**Descripción **​

subscriptionLinkId: Id del plan que creamos en el paso anterior

Bloque customer: Datos del cliente

paymentMethod: Id devuelto en el servicio de tokenización de tarjeta

backupPaymentMethod: Id devuelto en el servicio de tokenización, debe ser diferente del paymentMethod principal

locationCode: Es el código de la sucursal a la cual asociamos la suscripción en el request de plans, no debe confundirse con el locationId, el location code se consigue ingresando a editar nuestra sucursal en el portal, lo encontramos justo debajo del número de teléfono

Response:

{
  "status": "SUCCEEDED",
  "message": "El pago fue realizado exitosamente",
  "error": null,
  "authentication": null,
  "subscription": {
    "id": 276,
    "status": "ACTIVE",
    "amount": 16.0000,
    "currency": "USD"
  }
}

📌 Consultar suscripciones​

Este servicio utiliza el id de la suscripción como **path parameter, **se puede obtener una suscripción en específico, también es posible cancelar la suscripción

Get subscription by Id​

  • URL base: https://api-sandbox.n1co.shop
  • Método: GET
  • Endpoint: /api/v2/Subscriptions/{subscriptionId}
  • Descripción: Obtiene la información de una suscripción.
  • Cabeceras necesarias:
    • Authorization: Bearer {your_token}

Cancel subscription​

  • URL base: https://api-sandbox.n1co.shop
  • Método: GET
  • Endpoint: /api/v2/Subscriptions/{subscriptionId}/cancel
  • Descripción: Cancelar una suscripción.
  • Cabeceras necesarias:
    • Authorization: Bearer {your_token}
{
  "reason": "Motivo de cancelación"
}