Registro de Cliente VLT

POST /api/clientes/register

Registra un cliente y asocia una tarjeta RFID. Si el cliente ya existe, actualiza su tarjeta vigente; si la tarjeta ya fue registrada, responde como duplicado.

Solicitud

Headers

Header	Valor	Requerido
Content-Type	application/json	Sí
Accept	application/json	Sí

Endpoint Público

Este endpoint es de acceso público (AllowAnonymous). No requiere X-Client-Secret ni token. Está protegido por rate limit (60 solicitudes por minuto por IP).

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
codigoClienteVLT	integer	Sí	Código interno único del cliente en el sistema VLT
correo	string	Sí	Dirección de correo electrónico del cliente
enviarWhatsApp	boolean	Sí	Consentimiento para comunicaciones por WhatsApp
enviarCorreo	boolean	Sí	Consentimiento para comunicaciones por correo
enviarSms	boolean	Sí	Consentimiento para comunicaciones por SMS
tarjeta	string	Sí	Identificador físico de la tarjeta RFID
tipoDocumento	integer	No	Identificador del tipo de documento de identidad
dni	string	No	Número de documento de identidad (máx. 20 chars)
nombre	string	No	Nombre(s) del cliente
apellidoPaterno	string	No	Apellido paterno
apellidoMaterno	string	No	Apellido materno
fechaNacimiento	string (ISO 8601)	No	Fecha de nacimiento (YYYY-MM-DDTHH:mm:ss.sssZ)
direccion	string	No	Dirección de residencia
telefono	string	No	Teléfono de contacto
ubigeo	string	No	Código de ubicación geográfica
sexo	integer	No	Identificador de sexo

Ejemplo de Solicitud

curl -X POST 'https://api.syssoft1.com/api/clientes/register' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "tipoDocumento": 1,
    "dni": "74658993",
    "nombre": "Brandon",
    "apellidoPaterno": "Mamani",
    "apellidoMaterno": "Ayala",
    "fechaNacimiento": "1995-04-23T13:47:04.200Z",
    "direccion": "Av. Bolognesi 123",
    "telefono": "928570056",
    "ubigeo": "230101",
    "sexo": 1,
    "codigoClienteVLT": 70,
    "correo": "cliente70@gmail.com",
    "enviarWhatsApp": true,
    "enviarCorreo": true,
    "enviarSms": true,
    "tarjeta": "A0C2BBCA"
  }'

Respuestas

La respuesta siempre devuelve los mismos cuatro campos. El status, mensaje y esDuplicado indican el resultado.

Cliente Nuevo — 201 Created

El cliente no existía previamente y la tarjeta tampoco había sido registrada.

{
  "id": 11,
  "tarjeta": "A0C2BBCA",
  "mensaje": "cliente nuevo",
  "esDuplicado": false
}

Tarjeta Agregada al Cliente Existente — 201 Created

El cliente ya existe (coincide por codigoClienteVLT o dni) y se le asigna una tarjeta nueva como vigente.

{
  "id": 11,
  "tarjeta": "B1D3CCDB",
  "mensaje": "tarjeta agregada al cliente existente",
  "esDuplicado": false
}

Registro Duplicado — 200 OK

La tarjeta enviada ya había sido registrada antes.

{
  "id": 11,
  "tarjeta": "A0C2BBCA",
  "mensaje": "registro duplicado",
  "esDuplicado": true
}

Campos de la Respuesta

Campo	Tipo	Descripción
id	integer	Identificador del cliente registrado
tarjeta	string	El identificador de tarjeta enviado en la solicitud
mensaje	string	Descripción del resultado: "cliente nuevo", "tarjeta agregada al cliente existente" o "registro duplicado"
esDuplicado	boolean	true cuando la tarjeta ya había sido registrada

Pruébelo

⚡API PlaygroundPOST

URL Base

Cuerpo de la petición

{ "tipoDocumento": 1, "dni": "74658993", "nombre": "Brandon", "apellidoPaterno": "Mamani", "apellidoMaterno": "Ayala", "fechaNacimiento": "1995-04-23T13:47:04.200Z", "direccion": "Av. Bolognesi 123", "telefono": "928570056", "ubigeo": "230101", "sexo": 1, "codigoClienteVLT": 70, "correo": "cliente70@gmail.com", "enviarWhatsApp": true, "enviarCorreo": true, "enviarSms": true, "tarjeta": "A0C2BBCA" }

URL de Petición

https://api.syssoft1.com/api/clientes/register

Respuestas de Error

Código	Descripción
422	Validación fallida. Revise que los campos obligatorios estén presentes y con el tipo correcto.
429	Rate limit excedido (60 solicitudes por minuto por IP).
503	El sistema no tiene configurado el cliente destino para registros VLT. Contacte a soporte.
500	Error interno procesando el registro.

Ejemplo 422 Unprocessable Entity

{
  "message": "The codigoClienteVLT field is required. (and 5 more errors)",
  "errors": {
    "codigoClienteVLT": ["The codigoClienteVLT field is required."],
    "tarjeta": ["The tarjeta field is required."],
    "enviarWhatsApp": ["The enviarWhatsApp field is required."],
    "enviarCorreo": ["The enviarCorreo field is required."],
    "enviarSms": ["The enviarSms field is required."]
  }
}

Notas para el Integrador VLT

• El endpoint es idempotente sobre la tarjeta: enviar el mismo tarjeta dos veces no crea ni modifica nada en la segunda llamada.
• El campo tarjeta debe corresponder al UID físico que devuelve el lector RFID. Es el mismo valor que el lobby enviará luego como cardIdentifier al endpoint de autenticación.