Leads

CRUD sobre prospectos del módulo de Prospección. El caso de uso más común es registrar leads desde un formulario público de tu sitio web.

El objeto Lead

{
  "id":                       "65a4b5c6d7e8f9012345abcd",
  "name":                     "Laura Méndez",
  "email":                    "laura@example.com",
  "phone":                    "+52 656 1234567",
  "company_name":             "Acme SA de CV",
  "job_title":                "Directora de operaciones",
  "source":                   "sitio_web",
  "preferred_contact_method": "email",
  "status":                   "new",
  "notes":                    "Pidió cotización vía formulario.",
  "metadata":                 { "utm_campaign": "primavera", "form_variant": "B" },
  "converted":                false,
  "created_at":               "2026-04-10T18:21:09Z",
  "updated_at":               "2026-04-10T18:21:09Z"
}

Campos

Campo	Tipo	Descripción
id	string	ObjectId.
name	string	Nombre del prospecto.
email	string	Email de contacto.
phone	string	Teléfono.
company_name	string	Empresa del prospecto.
job_title	string	Puesto.
source	string	Origen del lead. Libre (sitio_web, feria, referido, etc.).
preferred_contact_method	string	email, phone, whatsapp. Libre.
status	enum	new, qualified, disqualified, converted. Default new.
notes	string	Anotaciones libres.
metadata	object	Hasta 4 KB de metadata libre. Cualquier hash. Útil para UTM, A/B variant, custom fields.
converted	bool	Read-only. true cuando el lead se convirtió a Customer dentro de Finova.
created_at / updated_at	string	ISO 8601 UTC.

---

Listar leads

GET/api/v1/leadsread-leads

Query params: page, limit.

---

Obtener un lead

GET/api/v1/leads/:idread-leads

---

Crear un lead

POST/api/v1/leadscreate-leads

Campos aceptados en data: name, email, phone, company_name, job_title, source, preferred_contact_method, status, notes, metadata.

Idempotency-Key recomendado

Los formularios web típicamente generan doble-submit cuando el usuario hace doble-click o la red reintenta. Manda un Idempotency-Key derivado del form data (ej. hash del email + timestamp del primer intento) para evitar leads duplicados.

cURL

curl -X POST https://developers.fi-nova.com/api/v1/leads \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: form-abc-123' \
  -d '{
    "data": {
      "name":  "Laura Méndez",
      "email": "laura@example.com",
      "phone": "+52 656 1234567",
      "company_name": "Acme SA de CV",
      "source": "sitio_web",
      "metadata": { "utm_campaign": "primavera" }
    }
  }'

JavaScript

await fetch('https://developers.fi-nova.com/api/v1/leads', {
  method: 'POST',
  headers: {
    Authorization:    'Bearer finova_sk_TU_SECRETO',
    'Content-Type':   'application/json',
    'Idempotency-Key': 'form-abc-123',
  },
  body: JSON.stringify({
    data: {
      name:  'Laura Méndez',
      email: 'laura@example.com',
      phone: '+52 656 1234567',
      company_name: 'Acme SA de CV',
      source: 'sitio_web',
      metadata: { utm_campaign: 'primavera' },
    },
  }),
});

---

Actualizar un lead

PATCH/api/v1/leads/:idupdate-leads

Útil para actualizar el status cuando el lead se mueve por tu pipeline desde afuera (ej. tu sistema de marketing).

---

Eliminar un lead

DELETE/api/v1/leads/:iddelete-leads

204 No Content en éxito.

---

Sobre metadata

El campo es libre pero con dos reglas server-side:

1. Se serializa siempre como objeto. Si mandas algo que no es hash, lo coercemos a string-per-key.
2. El tamaño total serializado no puede exceder 4 KB. Si te pasas, recibes 400 metadata exceeds 4096 bytes.

Útil para guardar atributos custom que no caben en los campos estándar:

{
  "metadata": {
    "utm_source":   "google",
    "utm_campaign": "spring-2026",
    "form_variant": "B",
    "preferred_demo_slot": "tuesday-am"
  }
}

Cuando el lead se convierte a Customer, este metadata NO se copia automáticamente — sigue accesible vía GET del lead.

---

Errores específicos

error	Cuándo
validation_failed (422)	Faltan campos requeridos o formato inválido.
bad_request (400)	metadata excede 4 KB.
not_found (404)	El id no existe o pertenece a otra empresa.
insufficient_scope (403)	Falta el scope.