Cómo conectar tu propia app con planes y suscriptores que se cobran solos

Dos caminos para cobrar suscripciones desde tu app

Mercado Pago tiene su propia documentación para integrar suscripciones. Un plan tiene nombre, importe y frecuencia; la persona autoriza el débito una vez y los cobros siguientes son automáticos. Si integrás directo, todo lo que pasa alrededor de ese débito queda de tu lado:

• Crear y mantener los planes, y su precio cuando cambia.
• Armar el alta y guardar quién se suscribió a qué.
• Recibir los avisos de Mercado Pago por cada cobro, rechazo o baja, y traducirlos a un estado.
• Decidir cuándo una persona tiene acceso y cuándo no, y avisarle cuando algo cambia.

El otro camino es que Membresía haga esa parte y tu app solo pregunte. Los planes, el alta, la autorización en Mercado Pago, los estados y los mails al suscriptor viven en Membresía; tu app lee por API quién está suscripto y si tiene acceso. La plata cae igual en tu propia cuenta de Mercado Pago: Membresía no la retiene.

Qué resuelve Membresía y qué resuelve tu app

Conviene tener la frontera clara antes de escribir código, porque define qué tenés que construir:

• Membresía: conecta tu cuenta de Mercado Pago, guarda productos y planes de importe fijo, publica la página de alta, recibe los cambios de cada cobro y mantiene el estado de cada suscripción.
• Membresía también le manda mails al suscriptor: antes de cada débito, cuando se cobra la cuota y cuando un cobro rebota.
• Tu app: muestra los planes, lleva a cada usuario a su alta, guarda el identificador de su suscripción y decide qué puede hacer según el estado.
• Tu app, si medís uso: reporta el consumo de cada suscriptor, y decide qué hacer cuando supera el límite del plan.

La clave: una por producto

La API se autentica con una clave por producto. Se genera cuando creás el producto, se muestra una sola vez y después solo se puede rotar: si la perdés, rotás y la anterior deja de funcionar en el acto. Guardala como cualquier secreto, del lado del servidor y nunca en el navegador.

Cada pedido lleva la clave en la cabecera Authorization: Bearer, o en X-API-Key como alternativa. No hace falta mandar un identificador de empresa ni de producto: la clave ya dice de qué producto es, y con ella solo ves los planes y suscriptores de ese producto. Una suscripción de otro producto responde como si no existiera.

Las cinco rutas que vas a usar

• GET /api/partner/plans: los planes activos del producto, para tu página de precios.
• GET /api/partner/products: el producto de la clave.
• GET /api/partner/subscriptions: los suscriptores del producto, de a 50 por página por defecto y hasta 100, con filtros por estado y por plan.
• GET /api/partner/subscriptions/:externalId: una suscripción, con su estado, su uso y el veredicto de acceso.
• PUT /api/partner/subscriptions/:externalId/usage: fija el uso de esa suscripción con un número absoluto.

El detalle de cada respuesta, con ejemplos de pedido y de error, está en la página para desarrolladores.

La integración, paso a paso

1. En el panel, conectá tu cuenta de Mercado Pago, creá el producto y guardá su clave.
2. Armá los planes: importe fijo, frecuencia y, si querés, días de prueba.
3. En tu página de precios, leé los planes activos y mostralos con tu diseño.
4. Cuando un usuario elige un plan, mandalo a la página de alta de ese plan: pone nombre y mail y autoriza el débito en Mercado Pago, sin crear una cuenta.
5. Guardá en tu base el externalId de su suscripción junto a tu usuario: es el identificador estable con el que la vas a leer.
6. Cada vez que necesites decidir el acceso, pedí la suscripción por externalId y mirá el campo access.

El campo access vale allowed o blocked, y cuando es blocked, accessReason dice por qué: no es lo mismo «falta completar el alta» que «la cuota está pendiente» o «la suscripción está pausada». Leé ese veredicto en lugar de recalcularlo con el estado: así tu app y la página del suscriptor nunca se contradicen.

Lo que la API no hace, para que lo planifiques

• No hay webhooks hacia tu app. Tu app se entera leyendo: pedí la suscripción cuando la necesitás, o recorré la lista cada tanto.
• El uso no bloquea nada ni se reinicia por período. Es un contador acumulado; si tu ciclo necesita un corte, lo llevás vos y escribís el total que corresponda.
• Un plan pago es un importe fijo por período. No hay montos variables por uso ni precios por tramos.
• Hay una sola moneda, pesos argentinos, y un solo usuario dueño por empresa: no hay equipos ni roles.
• La clave no se crea por API: nace con el producto, en el panel.

Si nada de esto choca con tu caso, la integración es chica: una pantalla de precios, un link por plan y una lectura por usuario. Si tu modelo necesita cobrar por consumo, conviene saberlo ahora; la diferencia entre un cobro fijo y otros esquemas está en qué es un pago recurrente.