API de Wizerp

API de servidor a servidor de Wizerp. Todo va en JSON y todo está acotado a tu empresa.

La empresa sale de tu llave: no es un parámetro, no se puede pasar y no hay forma de leer datos de otra.

Esta API no se llama desde el navegador. Una petición con la cabecera Origin, con ?sid= o con x-csrf-mexerp se rechaza con 400.

Dirección base https://api.wizerp.com/api/v1

Colección de Postman OpenAPI (.yaml)

Autenticación

Van las dos cabeceras, en toda llamada.

Cabecera	Ejemplo	Qué es
`Authorization`	`Bearer wzk_live_…`	El secreto completo de la llave.
`X-Wizerp-Key-Id`	`208_a3f91c7d`	El identificador público. Van las dos: sin ésta la petición falla con 401 aunque el secreto sea correcto.

Términos de uso obligatorios. Toda llave debe tener aceptados los términos de uso de la API vigentes (versión 2026-10). Se aceptan al crear la llave o con el botón «Aceptar términos» en Configuración › Llaves de API; sin aceptarlos, cualquier llamada responde 403 terminos_pendientes.

Topes y reintentos

150 peticiones por minuto por llave, lecturas y escrituras juntas. Al pasarte recibes 429 limite_excedido con la cabecera Retry-After — espera esos segundos y reintenta, no de inmediato.

Cupo mensual de operaciones por empresa, compartido con el conector de IA y según las licencias de usuario que tengas pagadas: hasta 3 → 5,000; 4 a 5 → 10,000; 6 o más → 20,000. Cuenta toda petición autenticada, de lectura o de escritura; las respuestas 429 y 5xx no cuentan. El mes es calendario, en hora de México. Al agotarlo recibes 429 cupo_agotado.

Las consultas devuelven como máximo 30 registros por página. Cada llave pertenece al usuario que la creó: si ese usuario deja de tener acceso a la empresa, la llave deja de funcionar (401 llave_sin_titular). Sin plan Pro vigente la respuesta es 402 plan_requerido. Si tu empresa tiene demasiadas peticiones en curso a la vez recibes 503 ocupado, también con Retry-After.

Toda respuesta trae tu saldo en cabeceras, para que NUNCA tengas que chocar con el 429 para conocerlo:

Cabecera	Qué dice
`X-Rate-Limit-Limit` / `-Remaining` / `-Reset`	Peticiones por minuto de tu llave, cuántas te quedan en este minuto y en cuántos segundos se reinicia.
`X-Wizerp-Cupo-Limite` / `-Restante` / `-Reinicio`	Cupo del mes de tu empresa, cuántas operaciones le quedan y cuándo se reinicia (fecha ISO 8601 del día 1 siguiente).
`X-Wizerp-Aviso`	Sólo durante el periodo de transición: lo que pasará con esta petición cuando los límites se apliquen.

Periodo de transición. Mientras los límites estén en modo de aviso se cuentan y se anuncian en las cabeceras, pero no cortan: en lugar del 429 (o del 400 por pedir más de 30 registros, que mientras tanto siguen la regla anterior de hasta 500, del 401 por titular o del 402) la respuesta sale normal y trae X-Wizerp-Aviso. Revisa esa cabecera en tus registros antes de la fecha de aplicación.

Si vas a consultar seguido, no preguntes en bucle: pide que te avisemos. Hablar con soporte sale más barato que chocar contra el tope todos los días.

Errores

Todos tienen la misma forma. El campo peticion es lo que hay que pegar en un correo a soporte: con eso lo encontramos en el registro.

HTTP	Cuándo
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
405	Método equivocado para esta ruta. La respuesta trae la cabecera Allow
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

Servicio

Comprobar que la API responde

# Comprobar que la API responde

GET https://api.wizerp.com/api/v1/health

No necesita llave y no toca la base de datos: dice que el proceso está vivo y sirviendo, no que la base conteste.

GET https://api.wizerp.com/api/v1/health

https://api.wizerp.com/api/v1/health

No necesita llave y no toca la base de datos: dice que el proceso está vivo y sirviendo, no que la base conteste.

Respuestas

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

405 Método equivocado para esta ruta. La respuesta trae la cabecera Allow

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

Lenguaje

Petición · cURL

curl https://api.wizerp.com/api/v1/health

$ch = curl_init('https://api.wizerp.com/api/v1/health');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/health",
  {
  }
);
const datos = await r.json();

import requests

r = requests.get(
    "https://api.wizerp.com/api/v1/health",
)
datos = r.json()

Respuesta elige un ejemplo

{
    "ok": true,
    "version": "texto",
    "peticion": "texto"
}

Prospectos

Registrar un prospecto

# Registrar un prospecto

POST https://api.wizerp.com/api/v1/leads

Crea una ficha de prospecto en el CRM. Necesita nombre o empresa, y correo o teléfono. Los datos van en el cuerpo JSON, nunca en la URL.

Manda la cabecera Idempotency-Key para poder reintentar sin duplicar: con la misma clave y los mismos datos se devuelve la respuesta guardada, byte por byte.

Permiso: leads:write

## Cuerpo JSON
- `nombre` (texto): Máximo 100. Se necesita éste o «empresa».
- `empresa` (texto): Máximo 200.
- `correo` (texto): Máximo 50. Se necesita éste o «telefono».
- `telefono` (texto): Máximo 30.
- `mensaje` (texto): Máximo 2000.
- `vendedor` (entero): Clave del vendedor al que se asigna.

POST https://api.wizerp.com/api/v1/leads

https://api.wizerp.com/api/v1/leads

Crea una ficha de prospecto en el CRM. Necesita nombre o empresa, y correo o teléfono. Los datos van en el cuerpo JSON, nunca en la URL.

Manda la cabecera Idempotency-Key para poder reintentar sin duplicar: con la misma clave y los mismos datos se devuelve la respuesta guardada, byte por byte.

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

Cuerpo JSON

nombre texto

Máximo 100. Se necesita éste o «empresa».

empresa texto

Máximo 200.

correo texto

Máximo 50. Se necesita éste o «telefono».

telefono texto

Máximo 30.

mensaje texto

Máximo 2000.

vendedor entero

Clave del vendedor al que se asigna.

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

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/leads \
  -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 '{"nombre":"María Fernanda Olvera","correo":"mf.olvera@ejemplo.com.mx"}'

$ch = curl_init('https://api.wizerp.com/api/v1/leads');
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,
    '{"nombre":"María Fernanda Olvera","correo":"mf.olvera@ejemplo.com.mx"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/leads",
  {
    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({"nombre":"María Fernanda Olvera","correo":"mf.olvera@ejemplo.com.mx"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/leads",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"nombre":"María Fernanda Olvera","correo":"mf.olvera@ejemplo.com.mx"},
)
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,
    "prospecto": 184027,
    "creado": true,
    "folio": "texto"
}

{
    "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"
    }
}

Clientes

Lista de clientes

# Lista de clientes

GET https://api.wizerp.com/api/v1/clientes

Devuelve los registros de tu empresa, paginados por cursor.

Las consultas devuelven páginas, no listas completas. Pide la siguiente pasando
en `cursor` el valor que vino en `siguiente`, hasta que `hay_mas` sea false.

No hay conteo total: contar millones de filas cuesta lo mismo que traerlas.

Cada página trae hasta 30 registros (`limite`, de 1 a 30; 30 si no lo mandas).
Un `limite` mayor contesta 400 limite_invalido. Mientras los límites estén en
modo de aviso sigue la regla anterior (100 por omisión, hasta 500) y la
respuesta trae la cabecera `X-Wizerp-Aviso` con lo que cambiará.

Sólo se aceptan los filtros documentados. Cualquier otro parámetro contesta
400 filtro_no_permitido; no se ignora en silencio, porque un filtro ignorado
hace creer que filtraste.

El campo correo puede traer varias direcciones separadas por coma y recortadas: el filtro correo compara el campo completo, así que no encuentra a un cliente por su segunda dirección.

Permiso: clientes:read

## Query params
- `cursor` (texto): La clave que vino en «siguiente» de la página anterior. Sin él, empieza por el principio.
- `limite` (entero): Registros por página. Omisión 30, máximo 30.
- `clave` (entero): Número entero.
- `folio` (texto): Coincidencia exacta. No admite comodines.
- `correo` (texto): Correo exacto. Se compara normalizado: no distingue mayúsculas ni espacios de sobra.
- `telefono` (texto): Se comparan los últimos 10 caracteres tras quitar espacios, guiones, paréntesis y el signo de más. Manda el número como lo tengas.
- `movil` (texto): Se comparan los últimos 10 caracteres tras quitar espacios, guiones, paréntesis y el signo de más. Manda el número como lo tengas.
- `rfc` (texto): Coincidencia exacta. No admite comodines.
- `prospecto` (booleano): true o false.
- `publico` (booleano): true o false.
- `id_mercadolibre` (texto): Coincidencia exacta. No admite comodines.
- `id_shopify` (texto): Coincidencia exacta. No admite comodines.
- `id_woocommerce` (texto): Coincidencia exacta. No admite comodines.
- `id_tiendanube` (texto): Coincidencia exacta. No admite comodines.
- `id_walmart` (texto): Coincidencia exacta. No admite comodines.
- `uso_cfdi` (texto): La clave del SAT, por ejemplo G03. No el identificador interno de Wizerp.
- `modificado_desde` (texto): Fecha ISO 8601 en UTC, por ejemplo 2026-10-01T00:00:00Z. Devuelve lo que sea igual o posterior.
- `proximo_contacto_desde` (texto): Fecha ISO 8601 en UTC, por ejemplo 2026-10-01T00:00:00Z. Devuelve lo que sea igual o posterior.
- `proximo_contacto_hasta` (texto): Fecha ISO 8601 en UTC. Devuelve lo que sea igual o anterior.

GET https://api.wizerp.com/api/v1/clientes

https://api.wizerp.com/api/v1/clientes

Devuelve los registros de tu empresa, paginados por cursor.

Las consultas devuelven páginas, no listas completas. Pide la siguiente pasando en cursor el valor que vino en siguiente, hasta que hay_mas sea false.

No hay conteo total: contar millones de filas cuesta lo mismo que traerlas.

Cada página trae hasta 30 registros (limite, de 1 a 30; 30 si no lo mandas). Un limite mayor contesta 400 limite_invalido. Mientras los límites estén en modo de aviso sigue la regla anterior (100 por omisión, hasta 500) y la respuesta trae la cabecera X-Wizerp-Aviso con lo que cambiará.

Sólo se aceptan los filtros documentados. Cualquier otro parámetro contesta 400 filtro_no_permitido; no se ignora en silencio, porque un filtro ignorado hace creer que filtraste.

El campo correo puede traer varias direcciones separadas por coma y recortadas: el filtro correo compara el campo completo, así que no encuentra a un cliente por su segunda dirección.

Requiere el permiso clientes:read en la llave · contrato del 2026-10-12

Peticiones recientes · de esta consola, solo en esta pestaña

Hora	Estado	Duración	Acciones
Prueba esta consulta para ver aquí tu historial.

Query Params

cursor texto

La clave que vino en «siguiente» de la página anterior. Sin él, empieza por el principio.

limite entero

Registros por página. Omisión 30, máximo 30.

clave entero

Número entero.

folio texto

Coincidencia exacta. No admite comodines.

correo texto

Correo exacto. Se compara normalizado: no distingue mayúsculas ni espacios de sobra.

telefono texto

Se comparan los últimos 10 caracteres tras quitar espacios, guiones, paréntesis y el signo de más. Manda el número como lo tengas.

movil texto

Se comparan los últimos 10 caracteres tras quitar espacios, guiones, paréntesis y el signo de más. Manda el número como lo tengas.

rfc texto

Coincidencia exacta. No admite comodines.

prospecto booleano

true o false.

publico booleano

true o false.

id_mercadolibre texto

Coincidencia exacta. No admite comodines.

id_shopify texto

Coincidencia exacta. No admite comodines.

id_woocommerce texto

Coincidencia exacta. No admite comodines.

id_tiendanube texto

Coincidencia exacta. No admite comodines.

id_walmart texto

Coincidencia exacta. No admite comodines.

uso_cfdi texto

La clave del SAT, por ejemplo G03. No el identificador interno de Wizerp.

modificado_desde texto

Fecha ISO 8601 en UTC, por ejemplo 2026-10-01T00:00:00Z. Devuelve lo que sea igual o posterior.

proximo_contacto_desde texto

Fecha ISO 8601 en UTC, por ejemplo 2026-10-01T00:00:00Z. Devuelve lo que sea igual o posterior.

proximo_contacto_hasta texto

Fecha ISO 8601 en UTC. Devuelve lo que sea igual o anterior.