# Traer comercios a tu plataforma

> Cómo invita una plataforma a sus comercios en Lane: el enlace de registro por panel o por API, lo que hace el comercio, los documentos que adjunta y el paso de pruebas a cobros reales.

Cada comercio entra con un enlace de registro propio, de un solo uso. Tú lo creas; el comercio hace el resto.

## 1. Crea el enlace

Desde tu panel, en **Plataforma**, o por API. En el panel solo un administrador de tu empresa los crea y ve sus direcciones.

### POST /v1/platform/signup-links

Crea un enlace de registro para un comercio. Responde `201`.

**Cuerpo (todo es opcional)**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `reference` | texto | no | El id con el que tú conoces a ese comercio. Vuelve en el aviso `merchant.connected` y en la lista de tus comercios: con él sabes cuál de tus vendedores quedó como qué comercio de Lane. |
| `merchant_name` | texto | no | El nombre del negocio. Se le muestra a quien abre el enlace. |
| `email` | correo | no | Si lo pones, solo una cuenta con ese correo puede usar el enlace. Sin él, lo puede usar quien lo tenga. |
| `expires_in_days` | entero | no | Días de vida. Por defecto `30`, máximo `90`. |

**Crear un enlace de registro**

```bash
curl -X POST https://api.lane.money/v1/platform/signup-links \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: alta-vendedor-77" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "vendedor-77",
    "merchant_name": "Tienda de Ana",
    "email": "ana@tienda.co"
  }'
```

**Respuesta**
```json
{
  "object": "signup_link",
  "id": "5b0c1c5e-…",
  "url": "https://lane.money/unirse/0123456789abcdef0123456789abcdef",
  "status": "open",
  "reference": "vendedor-77",
  "merchant_name": "Tienda de Ana",
  "email": "ana@tienda.co",
  "taken_by": null,
  "merchant_id": null,
  "expires_at": "2026-11-09T15:00:00.000Z",
  "used_at": null,
  "created_at": "2026-10-10T15:00:00.000Z"
}
```

Le entregas `url` al comercio, por el canal que quieras. Con `Idempotency-Key`, un reintento no crea un segundo enlace para el mismo vendedor.

> **Cuidado: Un enlace sin correo es de quien lo tenga.** Quien abra primero un enlace sin `email` puede poner su comercio debajo de tu plataforma, con la `reference` que le diste a otro. Por eso es de un solo uso y vence. Revisa `taken_by` antes de darle servicio a un comercio que no reconoces.

## 2. Lo que hace el comercio

1. **Abre el enlace.** Ve quién lo invita y lo que pagaría por cobro con tu plataforma.
2. **Crea su cuenta en Lane,** o entra con la que ya tiene.
3. **Acepta la conexión** en su panel. Solo un administrador de esa empresa puede aceptarla.
4. **Activa su comercio:** llena los datos del negocio, elige en cuánto tiempo recibe su plata y adjunta sus documentos.
5. **Queda conectado** en el momento en que su comercio se activa. Si ya tenía un comercio activo, queda conectado al aceptar.

La tarifa no la elige el comercio: es la que tu plataforma acordó con Lane para sus comercios. Lo que sí elige es el plazo en que recibe su plata, a 7 días o al día siguiente, cada uno con su tarifa.

### Los documentos que adjunta

| Si el comercio es | Adjunta |
| --- | --- |
| Una empresa | Cámara de comercio, RUT, cédula del representante legal y certificación bancaria. |
| Una persona natural | Su cédula y la certificación bancaria. |

Cada documento va en PDF, JPG o PNG, de hasta 10 MB. Sin ellos el comercio no se activa. Avísales a tus vendedores para que los tengan a la mano: es lo que más demora un registro.

## 3. Sigue el enlace

| `status` | Qué significa |
| --- | --- |
| `open` | Nadie lo ha usado. |
| `claimed` | Una empresa lo aceptó y todavía no activa su comercio. `taken_by` trae su nombre. |
| `used` | El comercio quedó conectado. `merchant_id` es el que usas para cobrar a su nombre. |
| `revoked` | Lo anulaste, o el comercio lo descartó. |
| `expired` | Venció sin que nadie lo usara. |

### GET /v1/platform/signup-links

Tus enlaces, el más nuevo primero.

### DELETE /v1/platform/signup-links/{id}

Anula un enlace que todavía no conectó a nadie. Uno ya usado responde `409`.

- **Un enlace aceptado no vence.** El vencimiento es para aceptarlo. Si una empresa lo aceptó y nunca activa su comercio, se queda en `claimed` hasta que lo anules.
- **Una empresa tiene un enlace aceptado a la vez.** Si acepta otro antes de activar su comercio, el anterior se devuelve y pasa a `revoked`.
- **Si la activación del comercio no pasa, no hay aviso:** todavía no hay comercio. El enlace sigue en `claimed` y el comercio puede corregir y reenviar.

## 4. Conoce a tus comercios

### GET /v1/platform/merchants

Tus comercios conectados, el más nuevo primero.

**Cada comercio**

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `id` | UUID | no | El id del comercio. Es el que mandas en `Lane-On-Behalf-Of` para cobrar a su nombre. |
| `name` | texto | no | El nombre del comercio en Lane. |
| `reference` | texto | no | La que pusiste en su enlace de registro. |
| `status` | `active` · `revoked` | no | `revoked`: ya no está conectado contigo. |
| `can_charge` | booleano | no | Si ya puede cobrar en el modo de tu llave. Con una `sk_test_` dice si puede en prueba; con una `sk_live_`, si puede de verdad. |
| `connected_at` | fecha | no | Desde cuándo. |
| `disconnected_at` | fecha | no | Cuándo dejó de estarlo. `null` mientras siga conectado. |

Pagina como los demás listados, con `limit` y `starting_after` (ver [Convenciones](https://lane.money/docs/api/paginacion)).

## 5. De pruebas a cobros reales

Un comercio recién activado cobra en modo de prueba. Para cobrar de verdad pasa por una revisión, que hace el equipo de Lane con los datos y documentos que el comercio entregó. Ni tú ni el comercio tienen que pedirla por API.

| Qué pasa | Cómo te enteras | Qué cambia |
| --- | --- | --- |
| El comercio se activa | `merchant.connected` | Tu llave `sk_test_` ya cobra a su nombre. |
| Lo aprueban para cobros reales | `merchant.approved` | Tu llave `sk_live_` ya cobra a su nombre. `can_charge` pasa a `true` con esa llave. |
| La revisión no pasa | `merchant.rejected` | Sigue cobrando solo en prueba. El aviso no trae el motivo: escríbenos. |

Si creas un cobro real a nombre de un comercio que todavía no está aprobado, la API responde `409` y no se crea nada: lo sabes tú al crear, no tu comprador al pagar.

### Con qué medios cobra cada comercio

Cuando un comercio se activa, y otra vez cuando queda aprobado para cobros reales, Lane pide para él los cinco medios: tarjeta, PSE, Nequi, Daviplata y Bre-B. La página de pago ofrece solo los que el comercio tiene habilitados en ese modo. Si pides uno que no tiene, la API responde `422` con `code: payment_method_unavailable` y dice cuáles sí.

## Desconectar un comercio

- **La desconexión la hace el equipo de Lane.** El comercio no se desconecta solo desde su panel, y no hay una ruta de la API para hacerlo. Escríbenos.
- **Te llega `merchant.disconnected`** y el comercio aparece con `status: revoked`. Crear un cobro a su nombre responde `404`.
- **Sigues oyendo cómo terminan los cobros que ya habías creado** para ese comercio.
- **Si vuelve a conectarse,** es la misma conexión: conserva su `id` y, si el enlace nuevo no trae `reference`, la que tenía.

> **Cuidado: Una plataforma en pausa no recibe a nadie.** Si Lane pausa tu plataforma, tus enlaces se leen como anulados, no puedes crear ninguno ni cobrar a nombre de nadie, y no recibes avisos. En tu panel sigues viendo tus enlaces y tus comercios. Un comercio que había aceptado un enlace queda esperando y se conecta cuando la plataforma se reactiva.