{"openapi":"3.0.0","paths":{"/v1/public/decimos":{"get":{"description":"Scope requerido: read:decimos","operationId":"PublicApiController_listDecimos","parameters":[{"name":"estado","required":false,"in":"query","schema":{"type":"string"}},{"name":"tipoLoteria","required":false,"in":"query","schema":{"type":"string"}},{"name":"fechaSorteoDesde","required":false,"in":"query","schema":{"type":"string"}},{"name":"fechaSorteoHasta","required":false,"in":"query","schema":{"type":"string"}},{"name":"numero","required":false,"in":"query","schema":{"maxLength":100,"type":"string"}},{"name":"soloGanadores","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"premiado","required":false,"in":"query","description":"Filtro `premiado` (hito 7, herramienta `check_my_tickets`): true = solo\nganadores, false = solo no ganadores, ausente = sin filtrar. Usa el mismo\ncampo del esquema que `soloGanadores` (`esGanador`); se mantiene aparte\npara no romper el parámetro existente.","schema":{"type":"boolean"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor opaco (campo `nextCursor` de la respuesta anterior). Sustituye a `page`.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Lista decimos del usuario","tags":["API pública v1"]},"post":{"description":"Scope requerido: edit:decimos","operationId":"PublicApiController_createDecimo","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDecimoApiDto"}}}},"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Crea un nuevo decimo","tags":["API pública v1"]}},"/v1/public/decimos/{id}":{"get":{"description":"Scope requerido: read:decimos","operationId":"PublicApiController_getDecimo","parameters":[{"name":"id","required":true,"in":"path","description":"Identificador (id)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Obtiene un decimo por ID","tags":["API pública v1"]},"put":{"description":"Scope requerido: edit:decimos. Las claves de agente solo pueden cambiar alias/notas.","operationId":"PublicApiController_updateDecimo","parameters":[{"name":"id","required":true,"in":"path","description":"Identificador (id)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDecimoApiDto"}}}},"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Actualiza un decimo","tags":["API pública v1"]}},"/v1/public/decimos/{id}/enlace":{"get":{"description":"Scope requerido: read:decimos. Devuelve el enlace /d/:token, el importe por plaza y cuántas plazas llevan cogidas (solo el número), o null.","operationId":"PublicApiController_getEnlaceDecimo","parameters":[{"name":"id","required":true,"in":"path","description":"Identificador (id)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Enlace de grupo de un decimo","tags":["API pública v1"]},"put":{"description":"Scope requerido: edit:decimos. Idempotente. No avisa a nadie ni crea deudas: devuelve un enlace para que el usuario lo envíe; cada persona se apunta ella misma.","operationId":"PublicApiController_upsertEnlaceDecimo","parameters":[{"name":"id","required":true,"in":"path","description":"Identificador (id)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertEnlaceDTO"}}}},"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Crea o actualiza el enlace de grupo de un decimo","tags":["API pública v1"]}},"/v1/public/participaciones":{"get":{"description":"Scope requerido: read:participaciones","operationId":"PublicApiController_listParticipaciones","parameters":[{"name":"estado","required":false,"in":"query","schema":{"type":"string"}},{"name":"rol","required":false,"in":"query","schema":{"type":"string","enum":["participante","propietario"]}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor opaco (campo `nextCursor` de la respuesta anterior). Sustituye a `page`.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Lista participaciones del usuario","tags":["API pública v1"]}},"/v1/public/sorteos":{"get":{"description":"Scope requerido: read:sorteos","operationId":"PublicApiController_listSorteos","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor opaco (campo `nextCursor` de la respuesta anterior). Sustituye a `page`.","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Lista sorteos disponibles","tags":["API pública v1"]}},"/v1/public/sorteos/{id}/puntos-venta":{"get":{"description":"Scope requerido: read:sorteos","operationId":"PublicApiController_getPuntosVentaSorteo","parameters":[{"name":"id","required":true,"in":"path","description":"Identificador (id) del sorteo","schema":{"type":"string"}},{"name":"numero","required":true,"in":"query","description":"Número del décimo (5 cifras)","schema":{"maxLength":10,"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Administraciones donde se vende un número (Navidad y Niño)","tags":["API pública v1"]}},"/v1/public/resumen":{"get":{"description":"Scope requerido: read:decimos","operationId":"PublicApiController_getResumen","parameters":[],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Obtiene resumen general del usuario","tags":["API pública v1"]}},"/v1/public/resultados/{id}":{"get":{"description":"Scope requerido: read:sorteos","operationId":"PublicApiController_getResultado","parameters":[{"name":"id","required":true,"in":"path","description":"Identificador (id)","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Obtiene resultado de un sorteo especifico","tags":["API pública v1"]}},"/v1/public/comprobar":{"get":{"description":"Scope requerido: read:sorteos","operationId":"PublicApiController_comprobarNumero","parameters":[{"name":"sorteoId","required":true,"in":"query","schema":{"maxLength":100,"type":"string"}},{"name":"numero","required":true,"in":"query","description":"Número del décimo (LNAC), números principales (combinación) o 14 signos (quiniela).","schema":{"maxLength":50,"type":"string"}},{"name":"complementario","required":false,"in":"query","description":"Estrellas / reintegro / clave / número sueño. Solo aplica a juegos de combinación.","schema":{"maxLength":50,"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"400":{"description":"Parámetros o cuerpo inválidos"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"404":{"description":"Recurso no encontrado"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Comprueba si un número (o combinación) tiene premio en un sorteo","tags":["API pública v1"]}},"/v1/public/deudas/resumen":{"get":{"description":"Scope requerido: read:deudas","operationId":"PublicApiController_getDeudaResumen","parameters":[],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Obtiene resumen de deudas","tags":["API pública v1"]}},"/v1/public/penas":{"get":{"description":"Scope requerido: read:penas","operationId":"PublicApiController_listPenas","parameters":[{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor opaco (campo `nextCursor` de la respuesta anterior). Sustituye a `page`.","schema":{"maxLength":200,"type":"string"}},{"name":"estado","required":false,"in":"query","schema":{"type":"string"}},{"name":"miRol","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Operación correcta"},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido, plan insuficiente o dominio no permitido"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Lista peñas del usuario","tags":["API pública v1"]}},"/v1/me":{"get":{"description":"Herramienta whoami (contrato de agentes §2). No consume cuota.","operationId":"MeController_me","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponseDto"}}}},"401":{"description":"API key ausente, inválida o caducada"},"403":{"description":"La key no tiene el scope requerido o el plan no da acceso"},"429":{"description":"Límite de peticiones de la key superado"}},"security":[{"api-key":[]}],"summary":"Plan, scopes efectivos, entorno y límites restantes de esta clave","tags":["Agentes · v1"]}}},"info":{"title":"Tu Décimo · API para agentes","description":"API de solo lectura (y alta/nota de décimos propios) para agentes y asistentes IA. Autenticación con API Key: cabecera X-API-Key o Authorization: Bearer/ApiKey <clave>. Ver el contrato completo en https://tudecimo.com/api-docs.","version":"1.0","contact":{}},"tags":[],"servers":[{"url":"https://api.tudecimo.com","description":"Producción"}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"CreateDecimoApiDto":{"type":"object","properties":{"numero":{"type":"string"},"serie":{"type":"string"},"fraccion":{"type":"string"},"tipoLoteria":{"type":"string"},"fechaSorteo":{"type":"string"},"sorteoId":{"type":"string"},"descripcion":{"type":"string","maxLength":500},"descripcionPersonal":{"type":"string","maxLength":500},"montoTotal":{"type":"number","minimum":0}},"required":["numero","fechaSorteo","montoTotal"]},"UpdateDecimoApiDto":{"type":"object","properties":{"numero":{"type":"string"},"serie":{"type":"string"},"fraccion":{"type":"string"},"tipoLoteria":{"type":"string"},"fechaSorteo":{"type":"string"},"descripcion":{"type":"string","maxLength":500},"descripcionPersonal":{"type":"string","maxLength":500},"montoTotal":{"type":"number","minimum":0},"estado":{"type":"string"}}},"UpsertEnlaceDTO":{"type":"object","properties":{"importePlaza":{"type":"number","minimum":0.01,"maximum":100000},"mensaje":{"type":"string","maxLength":280}},"required":["importePlaza"]},"ApiParticipantDto":{"type":"object","properties":{"email":{"type":"string"},"nombre":{"type":"string"},"porcentaje":{"type":"number","minimum":0,"maximum":100},"monto":{"type":"number","minimum":0}},"required":["email","nombre","porcentaje","monto"]},"CreateContratoApiDto":{"type":"object","properties":{"decimoId":{"type":"string"},"participantes":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/ApiParticipantDto"}},"jurisdiccion":{"type":"string"}},"required":["decimoId","participantes"]},"CreateParticipacionApiDto":{"type":"object","properties":{"decimoId":{"type":"string"},"email":{"type":"string"},"porcentaje":{"type":"number","minimum":0,"maximum":100},"monto":{"type":"number","minimum":0},"mensaje":{"type":"string","maxLength":500}},"required":["decimoId","email","porcentaje","monto"]},"RespondParticipacionApiDto":{"type":"object","properties":{"accion":{"type":"string","enum":["aceptar","rechazar"]},"motivo":{"type":"string","maxLength":500}},"required":["accion"]},"MarcarPagadaApiDto":{"type":"object","properties":{"notas":{"type":"string","maxLength":500},"metodoPago":{"type":"string"}}},"EnviarSolicitudApiDto":{"type":"object","properties":{"email":{"type":"string"},"mensaje":{"type":"string","maxLength":200}},"required":["email"]},"ResponderSolicitudApiDto":{"type":"object","properties":{"accion":{"type":"string","enum":["aceptar","rechazar"]}},"required":["accion"]},"CreatePenaApiDto":{"type":"object","properties":{"nombre":{"type":"string","maxLength":100},"descripcion":{"type":"string","maxLength":1000},"color":{"type":"string"}},"required":["nombre"]},"UpdatePenaApiDto":{"type":"object","properties":{"nombre":{"type":"string","maxLength":100},"descripcion":{"type":"string","maxLength":1000},"color":{"type":"string"},"estado":{"type":"string"}}},"InvitarMiembroApiDto":{"type":"object","properties":{"email":{"type":"string"},"porcentaje":{"type":"number","minimum":0,"maximum":100},"mensaje":{"type":"string","maxLength":500}},"required":["email"]},"ResponderInvitacionApiDto":{"type":"object","properties":{"accion":{"type":"string","enum":["aceptar","rechazar"]}},"required":["accion"]},"AsignarDecimoApiDto":{"type":"object","properties":{"decimoId":{"type":"string"},"porcentajeAsignado":{"type":"number","minimum":0,"maximum":100},"notas":{"type":"string","maxLength":500}},"required":["decimoId"]},"RemainingWindowDto":{"type":"object","properties":{"limit":{"type":"number","description":"Tope de la ventana"},"remaining":{"type":"number","description":"Peticiones (en unidades de coste) que quedan"},"resetSeconds":{"type":"number","description":"Segundos hasta que la ventana se reinicia"}},"required":["limit","remaining","resetSeconds"]},"ConcurrencyLimitDto":{"type":"object","properties":{"limit":{"type":"number","description":"Peticiones de esta clave en vuelo a la vez"},"remaining":{"type":"number","description":"Huecos libres ahora mismo"}},"required":["limit","remaining"]},"MeLimitsDto":{"type":"object","properties":{"requestsPerMinute":{"description":"Por clave, ventana de minuto","allOf":[{"$ref":"#/components/schemas/RemainingWindowDto"}]},"requestsPerHour":{"description":"Por clave, ventana de hora","allOf":[{"$ref":"#/components/schemas/RemainingWindowDto"}]},"requestsPerDayPerKey":{"description":"Por clave, ventana de día (UTC)","allOf":[{"$ref":"#/components/schemas/RemainingWindowDto"}]},"requestsPerDayPerUser":{"description":"Por usuario (suma de todas sus API Keys), día UTC","allOf":[{"$ref":"#/components/schemas/RemainingWindowDto"}]},"concurrency":{"$ref":"#/components/schemas/ConcurrencyLimitDto"}},"required":["requestsPerMinute","requestsPerHour","requestsPerDayPerKey","requestsPerDayPerUser","concurrency"]},"MeResponseDto":{"type":"object","properties":{"plan":{"type":"string","description":"Plan del propietario de la clave","example":"UNLIMITED"},"limiteDecimosActivos":{"type":"number","nullable":true,"description":"Máximo de décimos activos que se pueden tener desde la IA con este plan (50 en Gratis) o null si es ilimitado","example":50},"decimosActivos":{"type":"number","description":"Décimos activos del usuario ahora mismo (web, app e IA)","example":12},"environment":{"enum":["live","test"],"type":"string","description":"Entorno de la clave usada en esta petición"},"scopes":{"type":"array","items":{"type":"string","enum":["read:decimos","read:contratos","read:participaciones","read:sorteos","read:usuarios","read:deudas","read:contactos","read:estadisticas","read:penas","edit:decimos","edit:contratos","edit:participaciones","edit:deudas","edit:contactos","edit:penas","delete:decimos","delete:contratos","delete:participaciones","delete:deudas","delete:contactos","delete:penas","full_access","agent:read","agent:write"]},"description":"Scopes efectivos de la clave (alias agent:read/agent:write ya expandidos a scopes finos)"},"limits":{"$ref":"#/components/schemas/MeLimitsDto"}},"required":["plan","limiteDecimosActivos","decimosActivos","environment","scopes","limits"]}}}}