Ir al contenido
KUTI

Crear cliente

Crea un customer (pagador) para el merchant autenticado por tu API key.

POSThttps://api.kuti.pe/v1/customers
type es obligatorio: INDIVIDUAL (persona) o COMPANY (empresa). Persona usa first_name/last_name; empresa usa company_name. Idempotency-Key recomendada: un reintento no crea otro cliente. No se crean duplicados: si ya tienes un cliente con ese external_id, documento, correo o teléfono, responde 409 CUSTOMER_ALREADY_EXISTS con el id del existente en error.details. Excepción: dos clientes con documento distinto pueden compartir correo o teléfono.

Parámetros del body

Campo
Descripción
type
stringrequerido
INDIVIDUAL o COMPANY.Ej: INDIVIDUAL
external_id
stringopcional
Id en tu sistema (ERP, CRM, …).Ej: cust_erp_4821
first_name
stringopcional
Nombres (INDIVIDUAL).Ej: María
last_name
stringopcional
Apellidos (INDIVIDUAL).Ej: López
company_name
stringopcional
Razón social (COMPANY).
document
objectopcional
Documento de identidad: { type, number, country }. Si ya tienes un cliente con ese documento responde 409 con su id.
type
stringopcional
DNI, RUC, CE, PASSPORT, DIPLOMATIC_ID u OTHER. Opcional: se deduce del número (8 dígitos = DNI; 11 dígitos que empiezan en 10/15/17/20 = RUC).Ej: DNI
number
stringrequerido
Número del documento.Ej: 45678912
country
stringopcional
ISO 3166-1 alpha-2. Por defecto PE.Ej: PE
email
stringopcional
Correo. No puede repetirse entre tus clientes (no distingue mayúsculas).Ej: maria@example.com
phone
stringopcional
Teléfono. Un celular peruano se guarda siempre como +51 y sus 9 dígitos, lo envíes como lo envíes (999111222, 51999111222 o +51 999 111 222 quedan como +51999111222). No puede repetirse entre tus clientes.Ej: +51987654321
merchant_id
stringopcional
Opcional. Si se envía debe coincidir con el merchant de la key.Ej: mer_01J8Z3K4M5N6P7Q8R9S0T1U2V3
metadata
objectopcional
Pares string→string libres (para tu integración; no se muestran en el panel).
custom_fields
objectopcional
Campos personalizados que definiste en Ajustes → Clientes → Campos (ver Campos de cliente). Objeto { key: valor }: texto, número como texto ("12.5"), fecha "YYYY-MM-DD", hora "HH:mm", true/false, key de opción (SELECT; también acepta la etiqueta) o lista de keys (MULTISELECT). Una key desconocida o un valor inválido devuelve 422 con el detalle custom_fields.<key>.Ej: {"grade": "quinto", "student_code": "2026-00781"}

Language

Credentials

Header

Authorization

Secret key de developer · ejemplos con SDK oficial

API Request
$ npm install @kuti-pe/node
import { KutiClient } from "@kuti-pe/node";

const kuti = new KutiClient({ secretKey: process.env.KUTI_SECRET_KEY! });

const result = await kuti.customers.create({
  type: "INDIVIDUAL",
  firstName: "Ana",
  lastName: "Rojas",
  email: "ana@example.pe",
  document: { number: "45678912" },
}, { idempotencyKey: "alta-ana-rojas" });
console.log(result.id, result.code);
SDK oficial · guía en /sdks
Response

Elige un ejemplo de respuesta:

application/json
201Created
{
  "success": true,
  "message": "Customer created",
  "data": {
    "id": "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "merchant_id": "mer_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "external_id": "cust_erp_4821",
    "type": "INDIVIDUAL",
    "first_name": "María",
    "last_name": "López",
    "document": {
      "type": "DNI",
      "number": "45678912",
      "country": "PE"
    },
    "email": "maria@example.com",
    "phone": "+51987654321",
    "created_at": "2026-09-04T10:48:59.556906Z"
  }
}