Documenta el EP de ingesta y los webhooks salientes
api-docs/README.md: método/URL, auth Bearer, esquema del cuerpo (items foto/texto, zona, momento, flags), respuesta y errores (401/404/422), ejemplos curl de los 5 casos, y los payloads de los 3 webhooks salientes (perfil, entrega WhatsApp, arranque WhatsApp) con cómo el flujo externo devuelve las "después" por el mismo EP. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Carlos Narro
163
mvp/b2c/api-docs/README.md
Normal file
163
mvp/b2c/api-docs/README.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
# API — Ingesta del perfil del lead
|
||||||
|
|
||||||
|
Endpoint único y asíncrono para enriquecer el perfil de un lead del funnel B2C. Cada llamada puede
|
||||||
|
traer **imágenes, imagen+texto o solo texto**, etiquetado por **zona** y, en fotos, por **momento**
|
||||||
|
(antes/después). Lo usan tanto el formulario web como los flujos externos (agente de llamada, bot de
|
||||||
|
WhatsApp, generador de renders).
|
||||||
|
|
||||||
|
## Endpoint
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/leads/:id/ingesta
|
||||||
|
```
|
||||||
|
|
||||||
|
- `:id` = UUID del lead (el que crea el funnel al capturar nombre/teléfono/email).
|
||||||
|
- **Auth:** header `Authorization: Bearer <FUNNEL_API_KEY>`. Sin él, o con clave incorrecta → `401`.
|
||||||
|
- **Content-Type:** `application/json`.
|
||||||
|
|
||||||
|
## Cuerpo (JSON)
|
||||||
|
|
||||||
|
| Campo | Tipo | Notas |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `items` | array | Lista de items `foto` o `texto`. Por defecto `[]`. |
|
||||||
|
| `perfilCompleto` | boolean | Opcional. `true` señala al flujo externo que genere renders/agente. |
|
||||||
|
| `finalizar` | boolean | Opcional. `true` construye el PDF y lo entrega (email + señal WhatsApp). |
|
||||||
|
|
||||||
|
Debe llegar **al menos un item o un flag**; una llamada totalmente vacía → `422`.
|
||||||
|
|
||||||
|
### Item `foto`
|
||||||
|
|
||||||
|
| Campo | Tipo | Notas |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `tipo` | `"foto"` | Obligatorio. |
|
||||||
|
| `imagen` | string | Obligatorio. Data URI (`data:image/...;base64,...`) o URL `http(s)`. |
|
||||||
|
| `zona` | enum | Opcional: `cocina`,`bano`,`salon`,`comedor`,`integral`,`otro`. Si falta, se asume el tipo de reforma del lead. |
|
||||||
|
| `momento` | `"antes"`\|`"despues"` | Por defecto `"antes"`. Los renders del flujo externo se mandan como `despues`. |
|
||||||
|
| `orden` | number | Opcional. Si falta, continúa el máximo actual del lead. |
|
||||||
|
|
||||||
|
### Item `texto`
|
||||||
|
|
||||||
|
| Campo | Tipo | Notas |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `tipo` | `"texto"` | Obligatorio. |
|
||||||
|
| `texto` | string | Obligatorio, no vacío. Ej. `"suelo premium"`. |
|
||||||
|
| `zona` | enum | Opcional (mismo enum que en `foto`). |
|
||||||
|
|
||||||
|
## Respuesta
|
||||||
|
|
||||||
|
`200`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"ok": true,
|
||||||
|
"fotos": 1,
|
||||||
|
"notas": 1,
|
||||||
|
"perfilSenalado": false,
|
||||||
|
"finalizado": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `fotos` / `notas`: cuántos items de cada tipo se guardaron.
|
||||||
|
- `perfilSenalado`: `true` si `perfilCompleto` disparó el webhook y respondió ok.
|
||||||
|
- `finalizado`: `null` si no se pidió `finalizar`; si sí,
|
||||||
|
`{ ok, emailEnviado, whatsappSenal }`.
|
||||||
|
|
||||||
|
### Códigos de error
|
||||||
|
|
||||||
|
| Código | Cuándo |
|
||||||
|
| --- | --- |
|
||||||
|
| `401` | Falta `Authorization: Bearer`, o la clave no coincide con `FUNNEL_API_KEY`. |
|
||||||
|
| `404` | El lead `:id` no existe. |
|
||||||
|
| `422` | JSON inválido, item mal formado, o llamada vacía (sin items ni flag). |
|
||||||
|
|
||||||
|
## Ejemplos (curl)
|
||||||
|
|
||||||
|
Sustituye `LEAD`, `KEY` y el host según tu entorno.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1) Solo texto: añade un dato a la zona baño
|
||||||
|
curl -X POST "$HOST/api/leads/$LEAD/ingesta" \
|
||||||
|
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
|
||||||
|
-d '{"items":[{"tipo":"texto","zona":"bano","texto":"suelo premium"}]}'
|
||||||
|
|
||||||
|
# 2) Solo imagen (antes)
|
||||||
|
curl -X POST "$HOST/api/leads/$LEAD/ingesta" \
|
||||||
|
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
|
||||||
|
-d '{"items":[{"tipo":"foto","zona":"bano","imagen":"https://cdn/ejemplo/bano-antes.jpg"}]}'
|
||||||
|
|
||||||
|
# 3) Imagen + texto en la misma llamada
|
||||||
|
curl -X POST "$HOST/api/leads/$LEAD/ingesta" \
|
||||||
|
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
|
||||||
|
-d '{"items":[
|
||||||
|
{"tipo":"foto","zona":"cocina","imagen":"data:image/jpeg;base64,..."},
|
||||||
|
{"tipo":"texto","zona":"cocina","texto":"encimera de cuarzo"}
|
||||||
|
]}'
|
||||||
|
|
||||||
|
# 4) Perfil completo: que el flujo externo genere renders / corra el agente
|
||||||
|
curl -X POST "$HOST/api/leads/$LEAD/ingesta" \
|
||||||
|
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
|
||||||
|
-d '{"perfilCompleto":true}'
|
||||||
|
|
||||||
|
# 5) Devolver renders "después" y finalizar (genera PDF + email + señal WhatsApp)
|
||||||
|
curl -X POST "$HOST/api/leads/$LEAD/ingesta" \
|
||||||
|
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
|
||||||
|
-d '{"items":[{"tipo":"foto","zona":"cocina","momento":"despues","imagen":"https://cdn/render-cocina.jpg"}],"finalizar":true}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Webhooks salientes (hacia el flujo externo)
|
||||||
|
|
||||||
|
La app **emite** estas señales; el flujo externo (n8n/generador) las recibe y, cuando toca,
|
||||||
|
devuelve los resultados llamando de nuevo a este mismo EP (las "después" con `finalizar:true`).
|
||||||
|
Cada webhook es opcional: sin su URL en el entorno, la señal simplemente no se manda.
|
||||||
|
|
||||||
|
### `PERFIL_WEBHOOK_URL` — perfil completo
|
||||||
|
|
||||||
|
Disparado por `perfilCompleto:true`. Payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"leadId": "uuid",
|
||||||
|
"cliente": { "nombre": "...", "telefono": "...", "email": "...", "provincia": "..." },
|
||||||
|
"reforma": { "tipo": "cocina", "m2Suelo": 12, "calidad": "media",
|
||||||
|
"estructural": false, "urgencia": "media", "presupuestoTarget": 800000 },
|
||||||
|
"empresa": { "tenantId": "uuid", "nombre": "Reformas Ejemplo" },
|
||||||
|
"zonas": [
|
||||||
|
{ "zona": "cocina", "notas": ["encimera de cuarzo"],
|
||||||
|
"fotos": { "antes": ["url", "..."], "despues": [] } }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> El flujo externo genera los renders y los devuelve como items `foto` con `momento:"despues"`
|
||||||
|
> por `POST /api/leads/:id/ingesta`, y cierra con `finalizar:true`.
|
||||||
|
|
||||||
|
### `WHATSAPP_WEBHOOK_URL` — entrega del PDF
|
||||||
|
|
||||||
|
Disparado por `finalizar:true`. Payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"leadId": "uuid",
|
||||||
|
"telefono": "+34...",
|
||||||
|
"nombre": "...",
|
||||||
|
"empresa": "Reformas Ejemplo",
|
||||||
|
"pdfBase64": "JVBERi0xLj...",
|
||||||
|
"filename": "presupuesto-nombre.pdf"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `WHATSAPP_START_WEBHOOK_URL` — arranque de conversación
|
||||||
|
|
||||||
|
Disparado cuando el lead elige continuar por WhatsApp en el funnel. Payload:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "leadId": "uuid", "telefono": "+34...", "nombre": "...", "empresa": "Reformas Ejemplo" }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Notas
|
||||||
|
|
||||||
|
- **Storage:** las imágenes se guardan tal cual se reciben (data URI o URL) en `lead_fotos.url`;
|
||||||
|
las notas en `lead_notas`. Ver `mvp/b2c/db-schema/`.
|
||||||
|
- **Email:** la entrega por email es real vía SMTP (`SMTP_*` + `EMAIL_FROM`). Sin configurar,
|
||||||
|
`finalizado.emailEnviado` será `false` y el evento queda marcado como simulado.
|
||||||
|
- Variables de entorno: ver `mvp/b2c/.env.example`.
|
||||||
Reference in New Issue
Block a user