# Volve Mock API

API **ficticia** contra la que tu solución se integra. Simula la fuente de leads + una firma de documentos (estilo DocuSign) + un envío de email al gerente. Es lo que reemplaza a "un servicio real" — y se comporta como uno: pagina, a veces falla, y los webhooks vienen firmados.

> Todo es sintético. Ningún dato es real. El dominio `volve-demo.com` no existe.

## Cómo correrla

Requiere **Node 18+**. Sin dependencias:

```bash
node server.mjs
# volve-mock-api listening on http://localhost:4600
```

Imprime al arrancar el `WEBHOOK_SECRET` y el `X-Api-Key` que necesitas.

| Variable | Default |
|---|---|
| `PORT` | `4600` |
| `WEBHOOK_SECRET` | `volve-demo-secret-2026` |
| `X-Api-Key` | `demo-key-7Yq2` |

## Endpoints

### `GET /api/leads?cursor=<n>`
Fuente de leads, **paginada**. Devuelve `{ data: [...], next_cursor }`. Cuando `next_cursor` es `null`, no hay más páginas.

```bash
curl "http://localhost:4600/api/leads?cursor=0"
```

### `POST /api/webhooks/replay`
Le pasas la URL de **tu** endpoint de webhook y el mock te **envía leads firmados** (POST con header `X-Volve-Signature: sha256=<hmac>`). Úsalo para probar tu receptor.

```bash
curl -X POST http://localhost:4600/api/webhooks/replay \
  -H 'content-type: application/json' \
  -d '{"target_url":"http://localhost:3000/webhook/lead"}'
```

La firma es `HMAC-SHA256(rawBody, WEBHOOK_SECRET)`. **Verifícala** sobre el body crudo antes de procesar.

### `POST /api/sign`  *(firma de documento — estilo DocuSign)*
Requiere header `X-Api-Key`. Lo usas cuando un lead es **aprobado**.

```bash
curl -X POST http://localhost:4600/api/sign \
  -H 'content-type: application/json' -H 'X-Api-Key: demo-key-7Yq2' \
  -d '{"lead_id":"L-1001","document":"credit-preapproval"}'
```
Respuesta `200`: `{ envelope_id, status }`. Es un servicio externo de verdad: **puede no estar disponible** ocasionalmente.

### `POST /api/notify`  *(email al gerente)*
Requiere header `X-Api-Key`. Lo usas cuando un lead va a **comité / rechazado**.

```bash
curl -X POST http://localhost:4600/api/notify \
  -H 'content-type: application/json' -H 'X-Api-Key: demo-key-7Yq2' \
  -d '{"to":"gerente@volve-demo.com","subject":"Lead a comité","body":"..."}'
```
Respuesta `200`: `{ message_id, status }`.

## Reglas del juego

- Trata estos datos como si fueran de personas reales: **no los expongas en logs ni los guardes donde no debes**.
- Es una integración real: maneja **errores, reintentos y datos imperfectos** como lo harías en producción.
- No "parchees" el `server.mjs` para que tu código pase: la gracia es que tu solución conviva con la API **tal como está**.

> Puedes leer `server.mjs` si quieres entender el contrato a fondo — leer el código de un servicio es parte del trabajo. Lo que evaluamos es **cómo tu solución se comporta frente a esta API**.