Campos de cliente

Guarda datos extra de tus clientes (grado, código de alumno, sede…) y envíalos en custom_fields.

Cada negocio define sus propios campos en el panel (Ajustes → Clientes → Campos) o por API. Los valores viajan en custom_fields del cliente: en POST/PATCH /customers, en el customer de un cobro o de una checkout session, en los imports y en los webhooks customer.* y payment.*.

Las definiciones son las mismas en modo prueba y producción; los valores viven en cada cliente. La key y el tipo de un campo no se pueden cambiar después de crearlo. Máximo 20 campos activos.

Tipos

Tipo	Valor en custom_fields	Ejemplo
TEXT	texto	"2026-00781"
NUMBER	número como texto	"12.5"
DATE	YYYY-MM-DD	"2015-03-14"
HOUR	HH:mm	"09:30"
BOOLEAN	true / false (acepta "sí"/"no")	true
SELECT	key de la opción (acepta la etiqueta)	"quinto"
MULTISELECT	lista de keys (acepta texto separado por comas)	["math", "robotics"]
EMAIL	correo	"apoderado@example.com"
URL	http(s)	"https://drive.google.com/…"
PHONE_NUMBER	E.164	"+51987654321"

Endpoints

Método	Ruta	Qué hace
GET	/customer-fields	Lista los campos por posición (?include_archived=true para ver archivados).
POST	/customer-fields	Crea un campo: key, label, type, options (SELECT/MULTISELECT), required, help_text.
PATCH	/customer-fields/{id}	Edita label, options, required, help_text. Las opciones no se quitan: se desactivan (active: false).
PUT	/customer-fields/order	Reordena: { field_ids: [...] }.
POST	/customer-fields/{id}/archive	Archiva (deja de pedirse; los valores se conservan).
POST	/customer-fields/{id}/restore	Restaura un campo archivado.

Crear un campo SELECTbash

curl -s https://api.kuti.pe/v1/customer-fields \
  -H 'Authorization: Bearer kuti_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "grade",
    "label": "Grado",
    "type": "SELECT",
    "options": [
      { "key": "quinto", "label": "5to grado" },
      { "key": "sexto", "label": "6to grado" }
    ],
    "required": true
  }'

Usarlo al crear un cobrobash

curl -s https://api.kuti.pe/v1/payment-intents \
  -H 'Authorization: Bearer kuti_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pension-2026-03-45678912' \
  -d '{
    "amount": { "amount": "250.00", "currency": "PEN" },
    "payment_method_types": ["INTEROPERABLE_QR"],
    "description": "Pensión marzo",
    "customer": {
      "document": { "number": "45678912" },
      "custom_fields": { "grade": "quinto", "student_code": "2026-00781" }
    }
  }'

Reglas

Al editar un cliente solo cambian las keys enviadas; null borra ese valor.
Una key desconocida, un valor inválido o un campo archivado devuelve 422 con details[].field = custom_fields.<key>.
required se exige en el panel y en el checkout; la API no lo exige, para no romper integraciones cuando agregas un campo obligatorio.
ask_in_checkout: si el cobro se crea con requires_customer_info, el checkout también le pide al pagador los campos marcados así (GET /c/{code} los devuelve en checkout_customer_fields). Solo esos se aceptan desde el checkout.
El cobro congela los custom_fields del cliente al crearse (customer.custom_fields en GET /payment-intents/{id} y en payment.*).
Errores: CUSTOM_FIELD_KEY_TAKEN (409), CUSTOM_FIELD_LIMIT_REACHED (409), CUSTOM_FIELD_NOT_FOUND (404).