API de CRM

Leads, contactos y empresas

Busca leads y contactos por id o por teléfono, actualiza su etapa y sus campos personalizados, y lee el historial de cada lead.

La API de CRM lee y actualiza los datos comerciales de tu cuenta. Todas las rutas empiezan con https://api.whapi.chat/openapi.

Los cambios que hagas por esta API no disparan el webhook lead.updated: así tu sistema no recibe de vuelta sus propios cambios. La confirmación es la respuesta del request.

Buscar por id o por teléfono

Cada recurso se puede ubicar por su id o por el teléfono de su contacto:

Recurso	Por id	Por teléfono
Lead	`/leads/{leadId}`	`/leads/by-phone/{number}`
Contacto	`/contacts/{contactId}`	`/contacts/by-phone/{number}`
Empresa	`/businesses/{businessId}`	—

El teléfono va con código de país y solo dígitos (51987654321). Si coincide con varios leads activos, la respuesta es 409 con sus ids en leadIds (o contactIds para contactos): elige uno y usa la ruta por id.

Leer un lead

curl https://api.whapi.chat/openapi/leads/by-phone/51987654321 \
  --header 'Authorization: Bearer TU_CLAVE'

La respuesta trae todo lo necesario para mostrar el lead en tu sistema:

Campo	Contenido
`lead`	Nombre, etapa (`stage`), estado, monto, responsable y campos personalizados.
`contacts`	Sus contactos, con canales y campos personalizados. `link.main` marca el principal.
`business`	La empresa vinculada, o `null`.
`user`	El usuario responsable, o `null`.
`companyCustomFields`	La definición de cada campo personalizado: nombre, tipo y opciones.

Dos detalles:

lead.price llega como texto con dos decimales ("1500.00").
La prioridad del lead se puede cambiar con PATCH, pero hoy no viene en la respuesta.

Es la misma forma que el campo data de los webhooks lead.created y lead.updated.

Actualizar un lead

Envía solo los campos que quieres cambiar:

curl --request PATCH https://api.whapi.chat/openapi/leads/9 \
  --header 'Authorization: Bearer TU_CLAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "stageId": 12,
    "status": "open",
    "priority": "high",
    "price": 1500,
    "customFields": [
      { "name": "Origen", "value": "Feria 2026" }
    ]
  }'

Campo	Valores
`stageId`	Id de una etapa del embudo, o `null`.
`status`	`pending`, `open`, `archived` o `closed`.
`priority`	`low`, `medium` o `high`.
`businessId`	Id de una empresa, o `null` para desvincularla.

Un campo que no existe, o un valor fuera de los permitidos, responde 400 con code: INVALID_REQUEST y el motivo en error.

Campos personalizados

Leads, contactos y empresas aceptan customFields, una lista de { name, value }:

El campo tiene que existir en Whapi para ese tipo de registro. Si no, la respuesta es 400.
En lugar de name puedes usar companyCustomFieldId, el id de la definición que viene en companyCustomFields.
En campos de selección, value puede ser el texto de la opción.
Los campos que no envías no cambian.

Contactos y empresas

PATCH /contacts/{contactId} acepta name, customName, number, email, birthday, countryCode, provinceCode, countryIdNumber, docType (national_id, residence_id, passport u other) y customFields.

PATCH /businesses/{businessId} acepta name, ruc, email, phone (de 6 a 15 dígitos), address, industry, anniversary y firstLegalRepresentativeSince (fechas YYYY-MM-DD), firstLegalRepresentative, countryCode (dos letras), averageTicket y customFields.

Historial del lead

curl 'https://api.whapi.chat/openapi/leads/9/events?type=message&pageSize=20' \
  --header 'Authorization: Bearer TU_CLAVE'

Devuelve los eventos del más reciente al más antiguo: mensajes, notas, tareas, citas, cotizaciones, ventas, llamadas y cambios de campos. Cada evento trae un summary legible y, según su tipo, el detalle en message, note, task, schedule, quote o call.

Parámetro	Uso
`pageNumber`, `pageSize`	Paginación. Máximo 50 por página. `hasMore` indica si hay más.
`type`	`message`, `note`, `task`, `schedule`, `quote`, `sell`, `tag`, `call`, `payment_link` o `snapshot`.
`action`	`create`, `update` o `delete`.
`category`	`entity` (algo creado en el lead), `snapshot` (cambio de un campo) o `log`.

Todos los campos y errores: referencia de la API de CRM.