Skip to content

API Design

Esta página se reemplazará por Swagger

Todos los endpoints excepto /auth/register y /auth/login requieren el header: Authorization: Bearer <JWT>

Auth

POST /auth/register

Registra un nuevo jugador. Devuelve el JWT directamente para no obligar a hacer login justo después.

Request:

{
  "username": "daniela",
  "email": "daniela@email.com",
  "password": "superSecreta123"
}

Response 201:

{
  "token": "eyJhbGci...",
  "username": "daniela"
}

POST /auth/login

Request:

{
  "username": "daniela",
  "password": "superSecreta123"
}

Response 200:

{
  "token": "eyJhbGci...",
  "username": "daniela"
}

Collection

GET /collection/{username}

Devuelve todas las cartas del jugador con sus stats reales (base + EVs).

Response 200:

{
  "username": "daniela",
  "coins": 120,
  "cards": [
    {
      "playerCardId": "uuid",
      "name": "Nebula Drake",
      "rarity": "RARE",
      "theme": "space",
      "imageUrl": "https://...",
      "stats": {
        "hp": 88,
        "atk": 74,
        "def": 60,
        "spd": 95
      },
      "evs": {
        "hp": 3,
        "atk": 10,
        "def": 0,
        "spd": 22,
        "remaining": 0
      },
      "obtainedAt": "2025-06-01T12:00:00Z"
    }
  ]
}

Packs

POST /packs/open

Abre un sobre. Llama al generador Rust internamente. Si es el primer sobre del jugador, o el primero del día, es gratis — en caso contrario descuenta monedas.

Request:

{
  "packTypeId": "uuid"
}

Response 200:

{
  "packTypeId": "uuid",
  "seed": 8472918374,
  "cards": [
    {
      "playerCardId": "uuid",
      "name": "Solar Fox",
      "rarity": "COMMON",
      "imageUrl": "https://...",
      "stats": {
        "hp": 55,
        "atk": 48,
        "def": 50,
        "spd": 62
      },
      "isNew": true
    }
  ],
  "coinsSpent": 50,
  "coinsRemaining": 70
}

GET /packs/pool/{packTypeId}

Devuelve las cartas más destacadas que pueden salir en este pack, con su probabilidad. Pensado como showcase — no expone stats, solo nombre, rareza, imagen y probabilidad aproximada.

Response 200:

{
  "packTypeId": "uuid",
  "packName": "Summer 2025",
  "highlights": [
    {
      "name": "Coral Leviathan",
      "rarity": "MYTHIC",
      "imageUrl": "https://...",
      "dropChance": 0.03
    },
    {
      "name": "Sandy Sphinx",
      "rarity": "LEGENDARY",
      "imageUrl": "https://...",
      "dropChance": 0.08
    }
  ]
}

Cards

POST /cards/recycle

Recicla una o varias cartas duplicadas a cambio de monedas.

Request:

{
  "playerCardIds": [
    "uuid-1",
    "uuid-2"
  ]
}

Response 200:

{
  "recycled": 2,
  "coinsEarned": 10,
  "coinsTotal": 130
}

Trade

GET /trade/board

Devuelve listings y requests abiertos. Soporta filtros opcionales por query params.

GET /trade/board?rarity=RARE&theme=space&type=listing

Response 200:

{
  "listings": [
    {
      "listingId": "uuid",
      "owner": "daniela",
      "offeredCard": {
        "name": "Nebula Drake",
        "rarity": "RARE",
        "imageUrl": "https://..."
      },
      "wantedCard": {
        "name": "Solar Fox",
        "rarity": "COMMON",
        "imageUrl": "https://..."
      },
      "createdAt": "2025-06-01T12:00:00Z"
    }
  ],
  "requests": [
    {
      "requestId": "uuid",
      "owner": "daniela",
      "wantedCard": {
        "name": "Coral Leviathan",
        "rarity": "MYTHIC",
        "imageUrl": "https://..."
      },
      "offerCount": 3,
      "createdAt": "2025-06-01T12:00:00Z"
    }
  ]
}

POST /trade/listing

Publica un listing: "ofrezco X, quiero Y".

Request:

{
  "offeredPlayerCardId": "uuid",
  "wantedBaseCardId": "uuid"
}

Response 201:

{
  "listingId": "uuid",
  "status": "OPEN"
}

DELETE /trade/listing/{listingId}

Cancela y elimina un listing propio. Solo el dueño puede eliminarlo.

Response 204:

{}

POST /trade/request

Publica un request: "quiero X, ¿qué me das?".

Request:

{
  "wantedBaseCardId": "uuid"
}

Response 201:

{
  "requestId": "uuid",
  "status": "OPEN"
}

POST /trade/offer

Responde a un request con una carta propia.

Request:

{
  "requestId": "uuid",
  "offeredPlayerCardId": "uuid"
}

Response 201:

{
  "offerId": "uuid",
  "status": "PENDING"
}

POST /trade/accept/{offerId}

El dueño del request acepta una oferta. Todas las demás ofertas del request pasan a REJECTED.

Response 200:

{
  "status": "COMPLETED",
  "cardReceived": {
    "name": "Coral Leviathan",
    "rarity": "MYTHIC",
    "imageUrl": "https://..."
  }
}

POST /trade/reject/{offerId}

El dueño del request rechaza una oferta concreta. La oferta pasa a REJECTED, el request sigue OPEN.

Response 200:

{
  "offerId": "uuid",
  "status": "REJECTED"
}