Asignación de Tarjeta

PUT /api/clientes/card

Vincula un identificador físico de tarjeta (RFID) a un perfil de cliente ya creado. Es un paso independiente del alta: la tarjeta puede asignarse en cualquier momento posterior, y reemplazarse cuantas veces haga falta.

Sólo una tarjeta activa por cliente: asignar una nueva desactiva automáticamente la 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
id	integer	Sí	Identificador del cliente en nuestro sistema
playerId	integer	Sí	Identificador del jugador en el sistema de la contraparte
card	string	Sí	UID físico de la tarjeta, tal como lo devuelve el lector RFID

Ejemplo de Solicitud

curl -X PUT 'https://api.syssoft1.com/api/clientes/card' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "id": 1024,
    "playerId": 1,
    "card": "A0C2BBCA"
  }'

Ciclo de vida de la tarjeta

Situación	Resultado
El cliente no tenía tarjeta	Se asigna y queda activa
El cliente tenía otra tarjeta	La anterior pasa a inactiva y la nueva queda activa
Se reenvía la tarjeta vigente del mismo cliente	Éxito sin cambios (idempotente)
La tarjeta pertenece a otro perfil, activa o inactiva	ERR_CARD_ALREADY_ASSIGNED
La tarjeta es del mismo cliente pero ya fue reemplazada	ERR_CARD_DISABLED

Una tarjeta retirada no se reutiliza

Una tarjeta que ya fue reemplazada alcanzó un estado terminal. No puede reactivarse por esta vía: emita una tarjeta nueva.

El PIN del cliente, si lo tenía, se conserva al cambiar de tarjeta: cambiarla no deja al jugador sin su forma de entrar por documento.

Respuestas

Asignación, Reemplazo o Reenvío — 200 OK

La respuesta hace eco de los mismos identificadores enviados, confirmando que el estado final es idéntico al solicitado.

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

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 o no cumple el formato
404	ERR_CUSTOMER_NOT_FOUND	Los identificadores no corresponden a ningún perfil válido
409	ERR_IDENTITY_COLLISION	El id pertenece a un perfil y el playerId a otro
409	ERR_CARD_ALREADY_ASSIGNED	La tarjeta ya está vinculada a otro perfil
409	ERR_CARD_DISABLED	La tarjeta es del mismo perfil pero está inhabilitada
429	—	Rate limit excedido
503	—	El sistema no tiene configurado el operador destino
500	—	Error interno

Ejemplo 409 Conflict

{
  "code": "ERR_CARD_ALREADY_ASSIGNED",
  "message": "La tarjeta ingresada ya se encuentra vinculada a otro perfil."
}

Pruébelo

⚡API PlaygroundPUT

URL Base

Cuerpo de la petición

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

URL de Petición

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

Notas para el Integrador

• El valor de card debe ser el UID físico del lector. Es el mismo que el lobby enviará luego como cardIdentifier al autenticar al jugador en el terminal.
• La unicidad de la tarjeta es global, no por cliente: un UID sólo puede pertenecer a un perfil, esté activo o no.
• Reintentar tras un timeout de red es seguro: si la tarjeta ya quedó asignada y activa para ese mismo cliente, la petición responde 200 sin alterar nada.