Registrar un contacto con un cliente

Referencia › Registrar un contacto con un cliente

Clientes

Registrar un contacto con un cliente

# Registrar un contacto con un cliente

POST https://api.wizerp.com/api/v1/clientes/{clave}/interacciones

Anota en la bitácora del CRM (DBCTEINT) que contactaste a un cliente o prospecto, igual que el modal «Registrar contacto» de la ficha. La clave va en la URL (GET /clientes).

El próximo paso es el único dato realmente obligatorio además de canal y resultado: manda «proximo_fecha» (y opcionalmente «proximo_texto»), o cierra el seguimiento con «cierre» (un motivo de hasta 40 caracteres). Si no mandas ninguno de los dos, responde 400.

Un contacto nuevo SUSTITUYE el compromiso anterior de ese cliente: la tarea de seguimiento vieja se cierra sola.

Si la cuenta es de OTRO vendedor de tu empresa, el contacto SÍ se guarda, pero no se toca su agenda de seguimiento (la respuesta trae «solo_nota»: true) — ni «cierre» surte efecto en ese caso.

Clientes de una plataforma (marketplace) o sin ningún dato de contacto no se pueden anotar aquí: el CRM no les da seguimiento, igual que en pantalla.

QUIÉN QUEDA COMO AUTOR: manda «vendedor» con un usuario activo de tu empresa, o déjalo sin mandar para que quede el usuario que creó tu llave (si sigue activo en tu empresa; si no, responde 422 pidiendo «vendedor»).

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Permiso: actividades:write

## Cuerpo JSON
- `canal` (texto): Uno de: llamada, whatsapp, correo, visita, reunion, otro. Obligatorio.
- `resultado` (texto): Uno de: contactado, no_contesto, cotizo, pidio, rechazo, reagendo. Obligatorio.
- `sentido` (texto): "saliente" (lo iniciaste tú, por omisión) o "entrante" (lo inició el cliente).
- `nota` (texto): Nota libre. Máximo 5000.
- `fecha` (texto): Cuándo ocurrió, ISO 8601 en UTC con sufijo Z (2026-10-11T15:30:00Z). No puede ser futura. Por omisión, ahora.
- `duracion_min` (entero): Minutos que duró el contacto, 1 a 1440.
- `proximo_fecha` (texto): Fecha del próximo paso, AAAA-MM-DD, no en el pasado. Obligatoria salvo que mandes «cierre».
- `proximo_texto` (texto): Qué sigue (p. ej. "Llamar para cerrar"). Máximo 200.
- `cierre` (texto): Motivo para cerrar el seguimiento de este cliente (hasta 40 caracteres), en vez de programar un próximo paso.
- `vendedor` (entero): Clave de usuario (DBUSERS) que queda como autor del contacto. Debe ser un vendedor activo de tu empresa.

POST https://api.wizerp.com/api/v1/clientes/{clave}/interacciones

https://api.wizerp.com/api/v1/clientes/{clave}/interacciones

Anota en la bitácora del CRM (DBCTEINT) que contactaste a un cliente o prospecto, igual que el modal «Registrar contacto» de la ficha. La clave va en la URL (GET /clientes).

El próximo paso es el único dato realmente obligatorio además de canal y resultado: manda «proximo_fecha» (y opcionalmente «proximo_texto»), o cierra el seguimiento con «cierre» (un motivo de hasta 40 caracteres). Si no mandas ninguno de los dos, responde 400.

Un contacto nuevo SUSTITUYE el compromiso anterior de ese cliente: la tarea de seguimiento vieja se cierra sola.

Si la cuenta es de OTRO vendedor de tu empresa, el contacto SÍ se guarda, pero no se toca su agenda de seguimiento (la respuesta trae «solo_nota»: true) — ni «cierre» surte efecto en ese caso.

Clientes de una plataforma (marketplace) o sin ningún dato de contacto no se pueden anotar aquí: el CRM no les da seguimiento, igual que en pantalla.

QUIÉN QUEDA COMO AUTOR: manda «vendedor» con un usuario activo de tu empresa, o déjalo sin mandar para que quede el usuario que creó tu llave (si sigue activo en tu empresa; si no, responde 422 pidiendo «vendedor»).

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Requiere el permiso actividades:write en la llave · contrato del 2026-10-12

Parámetros de ruta

clave entero en la URL

La clave del cliente o prospecto (la de GET /clientes). Va en la URL.

Cuerpo JSON

Además, toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar.

canal texto obligatorio

Uno de: llamada, whatsapp, correo, visita, reunion, otro. Obligatorio.

resultado texto obligatorio

Uno de: contactado, no_contesto, cotizo, pidio, rechazo, reagendo. Obligatorio.

sentido texto

"saliente" (lo iniciaste tú, por omisión) o "entrante" (lo inició el cliente).

nota texto

Nota libre. Máximo 5000.

fecha texto

Cuándo ocurrió, ISO 8601 en UTC con sufijo Z (2026-10-11T15:30:00Z). No puede ser futura. Por omisión, ahora.

duracion_min entero

Minutos que duró el contacto, 1 a 1440.

proximo_fecha texto

Fecha del próximo paso, AAAA-MM-DD, no en el pasado. Obligatoria salvo que mandes «cierre».

proximo_texto texto

Qué sigue (p. ej. "Llamar para cerrar"). Máximo 200.

cierre texto

Motivo para cerrar el seguimiento de este cliente (hasta 40 caracteres), en vez de programar un próximo paso.

vendedor entero

Clave de usuario (DBUSERS) que queda como autor del contacto. Debe ser un vendedor activo de tu empresa.

Respuestas

400 Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador

401 La llave no es válida, está revocada o venció (llave_invalida), o el usuario dueño de la llave ya no tiene acceso a la empresa (llave_sin_titular)

402 Tu empresa no tiene un plan Pro vigente (plan_requerido). Mientras los límites estén en modo de aviso, esta situación sigue contestando 401 llave_invalida

403 La llave no tiene el permiso que pide esta operación (sin_permiso), o no tiene aceptados los términos de uso de la API vigentes (terminos_pendientes: acéptalos en Wizerp, Configuración › Llaves de API)

404 La ruta no existe, o tu empresa no tiene la API habilitada

409 Conflicto: misma Idempotency-Key con datos distintos, o ya existe un registro con ese identificador (RFC, SKU)

413 El cuerpo pasa del máximo

415 El cuerpo no va como JSON (falta Content-Type: application/json)

422 Un dato no es válido para tu empresa

429 Pasaste el ritmo de 150 peticiones por minuto de tu llave (limite_excedido) o el cupo mensual de tu empresa (cupo_agotado). La respuesta trae Retry-After

500 Falló de nuestro lado. Reintenta y reporta el valor de peticion

503 Tu empresa tiene demasiadas peticiones en curso, o la búsqueda no está disponible. Trae Retry-After

Lenguaje

Petición · cURL

curl -X POST https://api.wizerp.com/api/v1/clientes/{clave}/interacciones \
  -H "Authorization: Bearer wzk_live_…" \
  -H "X-Wizerp-Key-Id: 208_a3f91c7d" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -d '{"canal":"llamada","resultado":"cotizo","nota":"Pidió ajustar el precio del paquete anual","proximo_fecha":"2026-10-15","proximo_texto":"Llamar para cerrar"}'

$ch = curl_init('https://api.wizerp.com/api/v1/clientes/{clave}/interacciones');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wzk_live_…',
    'X-Wizerp-Key-Id: 208_a3f91c7d',
    'Content-Type: application/json',
    'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    '{"canal":"llamada","resultado":"cotizo","nota":"Pidió ajustar el precio del paquete anual","proximo_fecha":"2026-10-15","proximo_texto":"Llamar para cerrar"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/clientes/{clave}/interacciones",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer wzk_live_…",
      "X-Wizerp-Key-Id": "208_a3f91c7d",
      "Content-Type": "application/json",
      "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    body: JSON.stringify({"canal":"llamada","resultado":"cotizo","nota":"Pidió ajustar el precio del paquete anual","proximo_fecha":"2026-10-15","proximo_texto":"Llamar para cerrar"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/clientes/{clave}/interacciones",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"canal":"llamada","resultado":"cotizo","nota":"Pidió ajustar el precio del paquete anual","proximo_fecha":"2026-10-15","proximo_texto":"Llamar para cerrar"},
)
datos = r.json()

Las escrituras se prueban desde tu propio sistema con tu llave; la consola pública es solo para consultas. Copia el ejemplo de arriba: ya lleva el cuerpo y la cabecera Idempotency-Key.

Respuesta elige un ejemplo

{
    "ok": true,
    "interaccion": 184027,
    "cliente": 184027,
    "proximo_contacto": "texto",
    "solo_nota": true,
    "tarea": 184027
}

{
    "ok": false,
    "error": {
        "codigo": "json_invalido",
        "mensaje": "Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "llave_invalida",
        "mensaje": "La llave no es válida, está revocada o venció (llave_invalida), o el usuario dueño de la llave ya no tiene acceso a la empresa (llave_sin_titular)",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "limite_excedido",
        "mensaje": "Pasaste el ritmo de 150 peticiones por minuto de tu llave (limite_excedido) o el cupo mensual de tu empresa (cupo_agotado). La respuesta trae Retry-After",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

Ver la referencia completa