Card Assignment

PUT /api/clientes/card

Binds a physical card identifier (RFID) to an already created client profile. It is a step independent of the sign-up: the card may be assigned at any later moment, and replaced as often as needed.

Only one active card per client: assigning a new one automatically deactivates the previous one.

Request

Headers

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

Public Endpoint

Publicly accessible. It does not require X-Client-Secret or any token. Protected by rate limiting (60 requests per minute per IP).

Body Parameters

Parameter	Type	Required	Description
id	integer	Yes	Client identifier in our system
playerId	integer	Yes	Player identifier in the counterparty system
card	string	Yes	Physical card UID, as returned by the RFID reader

Request Example

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

Card lifecycle

Situation	Outcome
The client had no card	It is assigned and becomes active
The client had another card	The previous one becomes inactive and the new one active
The client's current card is sent again	Success with no changes (idempotent)
The card belongs to another profile, active or inactive	ERR_CARD_ALREADY_ASSIGNED
The card belongs to this client but was already replaced	ERR_CARD_DISABLED

A retired card is not reused

A card that has already been replaced reached a terminal state. It cannot be reactivated this way: issue a new card.

The client's PIN, if they had one, is kept across a card change: changing the card does not leave the player without their way in by document.

Responses

Assignment, Replacement or Resend — 200 OK

The response echoes the same identifiers that were sent, confirming the final state is identical to the requested one.

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

Error Responses

Branch on code, not on message

code is the stable part of the contract: it does not change. message is informative and may be reworded without notice — in fact ERR_MISSING_REQUIRED_FIELDS shares a single text across the three endpoints. When the response carries errors, the per-field detail is there.

HTTP	code	When
400	ERR_MISSING_REQUIRED_FIELDS	A field is missing or malformed
404	ERR_CUSTOMER_NOT_FOUND	The identifiers match no valid profile
409	ERR_IDENTITY_COLLISION	The id belongs to one profile and the playerId to another
409	ERR_CARD_ALREADY_ASSIGNED	The card is already bound to another profile
409	ERR_CARD_DISABLED	The card belongs to this profile but is disabled
429	—	Rate limit exceeded
503	—	The target operator is not configured
500	—	Internal error

409 Conflict Example

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

Try It

⚡API PlaygroundPUT

Base URL

Request Body

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

Request URL

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

Notes for the Integrator

• The card value must be the physical UID from the reader. It is the same one the lobby will later send as cardIdentifier when authenticating the player at the terminal.
• Card uniqueness is global, not per client: a UID may only belong to one profile, active or not.
• Retrying after a network timeout is safe: if the card is already assigned and active for that same client, the request answers 200 without altering anything.