Crear un cliente

API de Wizerp › Crear un cliente

Clientes

# Crear un cliente

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

Da de alta un cliente en tu cartera. La empresa sale de tu llave.

Necesita nombre. El RFC es opcional, pero si lo mandas y no es genérico (XAXX010101000 / XEXX010101000), no se permite repetirlo: un RFC ya dado de alta responde 409.

Régimen y uso de CFDI se mandan con la clave del SAT (regimen=612, uso_cfdi=G03). Se valida que el uso sea compatible con el régimen y con el tipo de persona del RFC. Con RFC genérico y sin régimen/uso, se usan los del ERP.

No se pueden escribir la empresa, el folio, el vendedor ni los saldos: son datos de identidad y de dinero. Las empresas en esquema de franquicia no pueden usar esta operación aún.

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: clientes:write

## Cuerpo JSON
- `nombre` (texto): Nombre o razón social. Obligatorio. Máximo 100.
- `rfc` (texto): RFC válido. En el alta, un RFC no genérico no puede repetirse en tu empresa.
- `regimen` (entero): Clave del régimen fiscal del SAT, por ejemplo 612 o 601.
- `uso_cfdi` (texto): Clave del uso de CFDI del SAT, por ejemplo G03. Debe ser compatible con el régimen.
- `cp` (texto): Código postal de 5 dígitos, como texto ("01000").
- `correo` (texto): Correo. Máximo 50.
- `telefono` (texto): Teléfono. Máximo 30.
- `movil` (texto): Móvil. Máximo 14.
- `calle` (texto): Calle y número. Máximo 200.
- `colonia` (texto): Colonia. Máximo 50.
- `pais` (entero): Clave de país (172 = México por omisión).

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

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

Da de alta un cliente en tu cartera. La empresa sale de tu llave.

Necesita nombre. El RFC es opcional, pero si lo mandas y no es genérico (XAXX010101000 / XEXX010101000), no se permite repetirlo: un RFC ya dado de alta responde 409.

Régimen y uso de CFDI se mandan con la clave del SAT (regimen=612, uso_cfdi=G03). Se valida que el uso sea compatible con el régimen y con el tipo de persona del RFC. Con RFC genérico y sin régimen/uso, se usan los del ERP.

No se pueden escribir la empresa, el folio, el vendedor ni los saldos: son datos de identidad y de dinero. Las empresas en esquema de franquicia no pueden usar esta operación aún.

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 clientes:write en la llave · contrato del 2026-10-10

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.

nombre texto obligatorio

Nombre o razón social. Obligatorio. Máximo 100.

rfc texto

RFC válido. En el alta, un RFC no genérico no puede repetirse en tu empresa.

regimen entero

Clave del régimen fiscal del SAT, por ejemplo 612 o 601.

uso_cfdi texto

Clave del uso de CFDI del SAT, por ejemplo G03. Debe ser compatible con el régimen.

cp texto

Código postal de 5 dígitos, como texto ("01000").

correo texto

Correo. Máximo 50.

telefono texto

Teléfono. Máximo 30.

movil texto

Móvil. Máximo 14.

calle texto

Calle y número. Máximo 200.

colonia texto

Colonia. Máximo 50.

pais entero

Clave de país (172 = México por omisión).

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, venció, o la empresa dejó de ser PRO

403 La llave no tiene el permiso que pide esta operación

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 un tope. 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 \
  -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":"Distribuidora Olvera S.A. de C.V.","rfc":"DOL120305AB1","regimen":601,"uso_cfdi":"G03","cp":"44100","correo":"pagos@distolvera.mx","telefono":"33 1234 5678"}'

$ch = curl_init('https://api.wizerp.com/api/v1/clientes');
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":"Distribuidora Olvera S.A. de C.V.","rfc":"DOL120305AB1","regimen":601,"uso_cfdi":"G03","cp":"44100","correo":"pagos@distolvera.mx","telefono":"33 1234 5678"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/clientes",
  {
    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":"Distribuidora Olvera S.A. de C.V.","rfc":"DOL120305AB1","regimen":601,"uso_cfdi":"G03","cp":"44100","correo":"pagos@distolvera.mx","telefono":"33 1234 5678"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/clientes",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"nombre":"Distribuidora Olvera S.A. de C.V.","rfc":"DOL120305AB1","regimen":601,"uso_cfdi":"G03","cp":"44100","correo":"pagos@distolvera.mx","telefono":"33 1234 5678"},
)
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,
    "cliente": 184027,
    "folio": "texto",
    "rfc": "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, venció, o la empresa dejó de ser PRO",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "limite_excedido",
        "mensaje": "Pasaste un tope. La respuesta trae Retry-After",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

Ver la referencia completa