Registro de Cliente VLT

POST /api/clientes/register

Da de alta al cliente con su información esencial. No pide tarjeta, correo, teléfono ni dirección: eso llega después por sus propios endpoints, Datos Complementarios y Asignación de Tarjeta.

Dos contratos conviviendo

El endpoint acepta el contrato desacoplado (este documento) y el anterior (payload en español con codigoClienteVLT), que sigue operativo mientras VLT migra. La presencia de playerId decide cuál se aplica; los dos nunca se mezclan. Ver Contrato anterior.

Solicitud

Headers

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

Endpoint Público

Acceso público. No requiere X-Client-Secret ni token. Protegido por rate limit (60 solicitudes por minuto por IP).

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
playerId	integer	Sí	Identificador del jugador en el sistema de la contraparte. Único
documentType	integer	Sí	1 = DNI · 2 = Carné de Extranjería · 3 = Pasaporte
documentNumber	string	Sí	Número de documento (máx. 20 caracteres)
firstName	string	Sí	Nombre(s)
paternalLastName	string	Sí	Apellido paterno
maternalLastName	string | null	Presente	Apellido materno. Debe enviarse, puede ir vacío o null
birthDate	string (fecha)	Sí	Fecha de nacimiento (YYYY-MM-DD o ISO 8601)
gender	integer	Sí	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 '{
    "documentType": 1,
    "documentNumber": "87654321",
    "firstName": "John",
    "paternalLastName": "Doe",
    "maternalLastName": "Smith",
    "birthDate": "1985-05-15",
    "gender": 1,
    "playerId": 1
  }'

Reglas de identidad

Regla	Detalle
Documento único	El par documentType + documentNumber identifica a una persona. El mismo número con otro tipo es otra persona
playerId único	Dos perfiles distintos no pueden compartirlo
Idempotencia	Si documento y playerId ya existen y apuntan al mismo registro, la petición responde 200 sin crear nada
Cruce de identidades	Si cada identificador apunta a un perfil distinto, la petición se aborta sin escribir

Respuestas

Ambos escenarios de éxito devuelven los mismos dos identificadores: id es el nuestro y playerId el de la contraparte.

Cliente Nuevo — 201 Created

{
  "id": 1024,
  "playerId": 1
}

Cliente Preexistente / Idempotencia — 200 OK

El documento y el playerId enviados ya existen y coinciden con un mismo registro.

{
  "id": 1024,
  "playerId": 1
}

Respuestas de Error

Ramifique por code, no por message

code es la parte estable del contrato: no cambia. message es informativo y puede reformularse sin previo aviso — de hecho ERR_MISSING_REQUIRED_FIELDS comparte un único texto en los tres endpoints. Cuando la respuesta trae errors, ahí está el detalle por campo.

HTTP	code	Cuándo
400	ERR_MISSING_REQUIRED_FIELDS	Falta un campo obligatorio o no cumple el formato
409	ERR_DUPLICATE_DOCUMENT	El documento ya está registrado bajo otro playerId
409	ERR_DUPLICATE_PLAYER_ID	El playerId ya está en uso por otro documento
409	ERR_IDENTITY_COLLISION	El documento pertenece a un perfil y el playerId a otro
429	—	Rate limit excedido (60 por minuto por IP)
503	—	El sistema no tiene configurado el operador destino. Contacte a soporte
500	—	Error interno procesando el registro

Ejemplo 409 Conflict

{
  "code": "ERR_DUPLICATE_DOCUMENT",
  "message": "El documento ingresado ya se encuentra registrado."
}

Ejemplo 400 Bad Request

errors detalla exactamente qué campo falló.

{
  "code": "ERR_MISSING_REQUIRED_FIELDS",
  "message": "Faltan campos obligatorios para actualizar el perfil",
  "errors": {
    "documentNumber": ["The document number field is required."]
  }
}

Pruébelo

⚡API PlaygroundPOST

URL Base

Cuerpo de la petición

{ "documentType": 1, "documentNumber": "87654321", "firstName": "John", "paternalLastName": "Doe", "maternalLastName": "Smith", "birthDate": "1985-05-15", "gender": 1, "playerId": 1 }

URL de Petición

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

Flujo recomendado

1. POST /api/clientes/register → guarde el id que devuelve.
2. PUT /api/clientes/contact-info → complete contacto, ubicación y preferencias.
3. PUT /api/clientes/card → vincule la tarjeta RFID cuando el cliente la reciba.

Los pasos 2 y 3 son independientes entre sí y pueden repetirse cuantas veces haga falta.

---

Contrato anterior

En proceso de reemplazo

Se mantiene únicamente para no interrumpir la integración vigente. Los registros nuevos deben usar el contrato desacoplado descrito arriba.

Se activa cuando el body incluye codigoClienteVLT. En ese caso el endpoint exige correo, las tres preferencias y tarjeta, y responde con la forma antigua ({ id, tarjeta, mensaje, esDuplicado }) y con 422 de Laravel ante un error de validación.

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
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
dni	string	No	Número de documento (máx. 20 caracteres)
password	string	No	Contraseña de acceso al lobby: 4 a 8 caracteres, sin espacios
pin	string	No	Alias de password. Nombre anterior del mismo campo
nombre	string	No	Nombre(s)
apellidoPaterno	string	No	Apellido paterno
apellidoMaterno	string	No	Apellido materno
fechaNacimiento	string (ISO 8601)	No	Fecha de nacimiento
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
currency	string (ISO 4217)	No	Moneda del jugador. Por defecto PEN

Contraseña de acceso

La contraseña es la segunda vía de entrada al terminal, para el jugador que llega sin su tarjeta. Queda asociada a la tarjeta que quede vigente.

En el terminal el jugador escribe su documento y después su contraseña: la contraseña por sí sola no identifica a nadie, porque no es única, y es el par documento + contraseña el que resuelve la cuenta. Para poder usar esta vía el jugador debe tener dni registrado.

Regla	Detalle
Formato	De 4 a 8 caracteres, sin espacios. Admite letras y distingue mayúsculas: "Ab12" no es "ab12"
Longitud en sala	El terminal teclea exactamente 4, que es lo que emite el sistema de identidad. El registro admite más para no rechazar ningún alta
Tipo	Envíela como string. Como número, una contraseña con cero inicial ("0421") perdería el cero
Unicidad	No es única. Una contraseña repetida por otro jugador se registra con normalidad
Opcional	Un registro sin password conserva la que el jugador ya tuviera
Tarjeta nueva	Si la tarjeta nueva no trae password, hereda la del jugador

El campo se llamaba pin

pin se sigue aceptando como alias, así que una integración existente no necesita cambiar nada. Si llegan los dos, manda password. El error de validación se reporta siempre sobre password.

Cambiar o quitar una contraseña

Para cambiarla, envíe un registro nuevo con la password deseada. No hay forma de borrarla por API: omitir el campo conserva la existente, no la elimina.

Respuestas

Escenario	HTTP	mensaje	esDuplicado
Cliente nuevo	201	"cliente nuevo"	false
Tarjeta agregada a un cliente existente	201	"tarjeta agregada al cliente existente"	false
Tarjeta ya registrada	200	"registro duplicado"	true

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

Errores

Código	Descripción
422	Validación fallida, con el detalle en errors
429	Rate limit excedido
503	Operador destino sin configurar
500	Error interno

Notas para el Integrador VLT

• El endpoint nunca duplica un jugador. Con el contrato nuevo, repetir la misma identidad responde 200; con el anterior, repetir la misma tarjeta responde 200 registro duplicado.
• El identificador de tarjeta debe ser el UID físico que devuelve el lector RFID. Es el mismo valor que el lobby enviará luego como cardIdentifier al autenticar.
• La password nunca viaja de vuelta: no aparece en la respuesta de este endpoint ni en ningún otro. Tampoco se escribe en los registros de actividad.