# Membresías

La API Memberships permite a los tenants inscribir usuarios en programas vinculados a un anuncio de tipo `membership`.

Cada membresía registra la inscripción del usuario en un anuncio (con un `membership_id` externo propio del tenant), las contribuciones de pago asociadas a pedidos de Tradly y el historial de precios usado para calcular las unidades acreditadas.

## ID de miembro externo

`membership_id` es la referencia de miembro o programa del tenant (por ejemplo, `GOLD-2026-00123`). No es el `id` de la base de datos ni el `user_id` de Tradly. Úsalo para relacionar la membresía con tu CRM o sistema de gestión. Debe ser único para cada tenant y anuncio, y puede tener hasta 128 caracteres.

## Funcionamiento

1. Crea un anuncio de tipo `membership` mediante Listings.
2. Inscribe al usuario con `POST /v1/memberships`.
3. Cuando pague mediante el checkout estándar de Tradly, la contribución se registra al confirmar el pedido.
4. Opcionalmente, registra el historial de precios con `POST /v1/memberships/price_logs` para seguir las unidades acreditadas.

## Estado inicial

| Valor | Descripción |
|---|---|
| `active` | Membresía activa (valor predeterminado) |
| `expired` | La fecha `end_date` ya pasó |
| `cancelled` | Membresía cancelada manualmente |

Omite `status` al crear para iniciar como `active`. El punto de conexión guarda el estado indicado; no cambia automáticamente el estado por vencimiento o cancelación, por lo que tu aplicación debe gestionar esos ciclos.

## Autenticación

Autentica con `Authorization: Bearer <token>`. El tenant y el usuario se obtienen del token o de la pasarela. No envíes los encabezados `tenant_id`, `user_id`, `admin` ni `X-Auth-Key`. Los usuarios no administradores solo pueden consultar y crear sus propias membresías; los administradores pueden gestionarlas para cualquier usuario.