VLT Client Registration

POST /api/clientes/register

Registers a client and binds an RFID card. If the client already exists, the active card is updated; if the card was registered before, the response is a duplicate.

Request

Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Public Endpoint

This endpoint is publicly accessible (AllowAnonymous). It does not require X-Client-Secret or any token. It is protected by rate limiting (60 requests per minute per IP).

Body Parameters

Parameter	Type	Required	Description
codigoClienteVLT	integer	Yes	Internal unique client identifier in the VLT system
correo	string	Yes	Client's email address
enviarWhatsApp	boolean	Yes	Consent to receive WhatsApp communications
enviarCorreo	boolean	Yes	Consent to receive email communications
enviarSms	boolean	Yes	Consent to receive SMS communications
tarjeta	string	Yes	Physical RFID card identifier
tipoDocumento	integer	No	Document type identifier
dni	string	No	National document number (max 20 chars)
nombre	string	No	Client's first name(s)
apellidoPaterno	string	No	Father's last name
apellidoMaterno	string	No	Mother's last name
fechaNacimiento	string (ISO 8601)	No	Birth date (YYYY-MM-DDTHH:mm:ss.sssZ)
direccion	string	No	Residential address
telefono	string	No	Contact phone number
ubigeo	string	No	Geographic location code
sexo	integer	No	Gender identifier

Request Example

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"
  }'

Responses

The response always returns the same four fields. The status, mensaje and esDuplicado describe the outcome.

New Client — 201 Created

The client did not exist and the card had not been registered before.

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

Card Added to Existing Client — 201 Created

The client already exists (matched by codigoClienteVLT or dni) and a new card is set as the active one.

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

Duplicate Registration — 200 OK

The submitted card had already been registered before.

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

Response Fields

Field	Type	Description
id	integer	Identifier of the registered client
tarjeta	string	The card identifier sent in the request
mensaje	string	Result description: "cliente nuevo", "tarjeta agregada al cliente existente", or "registro duplicado"
esDuplicado	boolean	true when the card had already been registered

Try It

⚡API PlaygroundPOST

Base URL

Request Body

{ "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" }

Request URL

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

Error Responses

Code	Description
422	Validation failed. Check that required fields are present and properly typed.
429	Rate limit exceeded (60 requests per minute per IP).
503	The system has no destination client configured for VLT registrations. Contact support.
500	Internal error processing the registration.

Example 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."]
  }
}

Notes for the VLT Integrator

• The endpoint is idempotent on the card: sending the same tarjeta twice neither creates nor modifies anything on the second call.
• The tarjeta field must contain the physical UID returned by the RFID reader. It is the same value the lobby will later send as cardIdentifier to the authentication endpoint.