API REST v1

Documentación de la API

Integra TuDécimo en tus aplicaciones mediante nuestra API REST. ¿Usas un asistente de IA? Conéctalo con el servidor MCP.

Descargar colección Postman
Requiere plan UNLIMITED

Las API Keys se gestionan desde tu dashboard en Configuración > API Keys.

Inicio Rápido

URL Base

https://api.tudecimo.com/v1/public

Autenticación

X-API-Key: TU_API_KEY

También se acepta Authorization: ApiKey TU_API_KEY. El esquema Bearer no es válido.

Ejemplo de petición
curl -X GET "https://api.tudecimo.com/v1/public/decimos" \
  -H "X-API-Key: tu_api_key_aqui" \
  -H "Content-Type: application/json"

Décimos

Gestiona tus décimos de lotería.

GET/decimosread:decimos

Lista todos los décimos del usuario. Filtros: estado (activo, compartido, finalizado, cancelado), tipoLoteria, numero (contiene, máx. 100), soloGanadores, fechaSorteoDesde, fechaSorteoHasta (ISO 8601).

Response
{
  "data": [{
    "id": "507f1f77bcf86cd799439011",
    "numero": "12345",
    "tipoLoteria": "loteria_nacional",
    "fechaSorteo": "2024-12-22T00:00:00Z",
    "montoTotal": 20,
    "estado": "activo"
  }],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
GET/decimos/:idread:decimos

Obtiene un décimo por ID.

POST/decimosedit:decimos

Crea un nuevo décimo. El campo sorteoId es opcional: si no se envía, se detecta por fecha y tipo. tipoLoteria admite: loteria_nacional, el_gordo, loteria_navidad, loteria_nino, quiniela, bonoloto, euromillones, primitiva, otro.

Request Body
{
  "numero": "12345",
  "tipoLoteria": "loteria_nacional",
  "fechaSorteo": "2024-12-22",
  "sorteoId": "507f1f77bcf86cd799439011",
  "serie": "10",
  "fraccion": "5",
  "montoTotal": 20,
  "descripcion": "Décimo de Navidad"
}
PUT/decimos/:idedit:decimos

Actualiza un décimo existente.

Request Body
{
  "numero": "12345",
  "descripcion": "Nuevo nombre"
}
DELETE/decimos/:iddelete:decimos

Elimina un décimo (soft delete).

Contratos

Gestiona contratos de participación.

GET/contratosread:contratos

Lista todos los contratos del usuario. Filtros: status (pending, active, cancelled, expired), rol (creador, participante), fechaDesde, fechaHasta (ISO 8601).

GET/contratos/:idread:contratos

Obtiene un contrato por ID.

POST/contratosedit:contratos

Crea un nuevo contrato.

Request Body
{
  "decimoId": "507f1f77bcf86cd799439011",
  "participantes": [
    {
      "email": "participante@ejemplo.com",
      "nombre": "Juan Garcia",
      "porcentaje": 50,
      "monto": 10
    }
  ],
  "jurisdiccion": "España"
}
DELETE/contratos/:iddelete:contratos

Cancela un contrato pendiente.

Participaciones

Gestiona participaciones en décimos compartidos.

GET/participacionesread:participaciones

Lista todas las participaciones. Filtros: estado (pendiente, aceptada, rechazada, cancelada, excluido_impago), rol (propietario, participante).

Response
{
  "data": [{
    "id": "507f1f77bcf86cd799439011",
    "decimoId": "507f1f77bcf86cd799439012",
    "decimoNumero": "12345",
    "porcentaje": 50,
    "monto": 10,
    "estado": "pendiente",
    "esComoPropietario": true
  }],
  "pagination": { ... }
}
GET/participaciones/:idread:participaciones

Obtiene una participación por ID.

POST/participacionesedit:participaciones

Crea una participación (invita a alguien a tu décimo).

Request Body
{
  "decimoId": "507f1f77bcf86cd799439011",
  "email": "invitado@ejemplo.com",
  "porcentaje": 25,
  "monto": 5,
  "mensaje": "Te invito a participar"
}
POST/participaciones/:id/responderedit:participaciones

Acepta o rechaza una participación recibida. accion: "aceptar" o "rechazar"; motivo (opcional, máx. 500) solo tiene sentido al rechazar.

Request Body
{
  "accion": "rechazar",
  "motivo": "No me interesa"
}
DELETE/participaciones/:iddelete:participaciones

Cancela una participación que enviaste.

Deudas

Gestiona deudas entre usuarios por participaciones.

GET/deudasread:deudas

Lista todas las deudas del usuario. Filtros: estado (pendiente, pendiente_confirmacion, pagado, cancelado, vencido, excluido), rol (deudor, acreedor), fechaDesde, fechaHasta (ISO 8601).

Response
{
  "data": [{
    "id": "507f1f77bcf86cd799439011",
    "monto": 10,
    "estado": "pendiente",
    "esDeudor": true,
    "deudor": { "id": "...", "nombre": "Juan", "email": "..." },
    "acreedor": { "id": "...", "nombre": "Maria", "email": "..." }
  }],
  "pagination": { ... }
}
GET/deudas/deboread:deudas

Lista lo que debo a otros.

GET/deudas/me-debenread:deudas

Lista lo que me deben otros.

GET/deudas/resumenread:deudas

Resumen de deudas: total debo, total me deben, balance.

Response
{
  "totalDebo": 50,
  "totalMeDeben": 100,
  "balance": 50,
  "deudasPendientes": 5,
  "deudasPendienteConfirmacion": 1
}
GET/deudas/:idread:deudas

Obtiene una deuda por ID.

PUT/deudas/:id/marcar-pagadaedit:deudas

Marca una deuda como pagada (como deudor).

Request Body
{
  "notas": "Pagado por Bizum",
  "metodoPago": "bizum"
}
POST/deudas/:id/confirmar-pagoedit:deudas

Confirma el pago de una deuda (como acreedor).

Contactos

Gestiona tu lista de contactos.

GET/contactosread:contactos

Lista todos los contactos. Filtro: q (búsqueda).

GET/contactos/solicitudes/pendientesread:contactos

Lista solicitudes de contacto pendientes recibidas.

GET/contactos/solicitudes/enviadasread:contactos

Lista solicitudes de contacto enviadas.

POST/contactos/solicitudedit:contactos

Envía una solicitud de contacto.

Request Body
{
  "email": "usuario@ejemplo.com",
  "mensaje": "Hola, me gustaria anadirte"
}
POST/contactos/solicitud/:id/responderedit:contactos

Acepta o rechaza una solicitud de contacto. accion: "aceptar" o "rechazar".

Request Body
{
  "accion": "aceptar"
}
DELETE/contactos/:iddelete:contactos

Elimina un contacto.

Peñas

Gestiona grupos de lotería (peñas).

GET/penasread:penas

Lista tus peñas. Filtros: estado (active, inactive, archived), miRol (admin, moderator, member).

GET/penas/invitacionesread:penas

Lista invitaciones pendientes a peñas.

GET/penas/:idread:penas

Obtiene detalle de una peña con miembros y décimos.

POST/penasedit:penas

Crea una nueva peña.

Request Body
{
  "nombre": "Mi Peña",
  "descripcion": "Grupo de amigos",
  "color": "#17663A"
}
PUT/penas/:idedit:penas

Actualiza una peña (solo admin).

DELETE/penas/:iddelete:penas

Elimina una peña (solo creador).

GET/penas/:id/miembrosread:penas

Lista miembros de una peña.

POST/penas/:id/miembrosedit:penas

Invita a un miembro por email.

Request Body
{
  "email": "usuario@ejemplo.com",
  "porcentaje": 10,
  "mensaje": "Te invito a mi peña"
}
POST/penas/invitaciones/:id/responderedit:penas

Acepta o rechaza una invitación a peña. accion: "aceptar" o "rechazar".

Request Body
{
  "accion": "aceptar"
}
GET/penas/:id/decimosread:penas

Lista décimos asignados a la peña.

POST/penas/:id/decimosedit:penas

Asigna un décimo a la peña.

Request Body
{
  "decimoId": "507f1f77bcf86cd799439011",
  "porcentajeAsignado": 100,
  "notas": "Décimo de Navidad"
}
DELETE/penas/:id/decimos/:decimoIdedit:penas

Quita un décimo de la peña.

POST/penas/:id/abandonaredit:penas

Abandona una peña (no disponible para creador).

GET/penas/:id/estadisticasread:penas

Estadísticas de la peña.

Usuarios

Busca usuarios registrados.

GET/usuarios?email=read:usuarios

Busca un usuario por email. Solo devuelve id y nombre, y únicamente si es un contacto aceptado; si no, responde 404.

Response
{
  "id": "507f1f77bcf86cd799439011",
  "nombre": "Juan Garcia"
}

Sorteos

Consulta información de sorteos de lotería.

GET/sorteosread:sorteos

Lista los sorteos disponibles.

GET/sorteos/:idread:sorteos

Obtiene detalles de un sorteo.

Resultados

Consulta resultados de sorteos finalizados.

GET/resultadosread:sorteos

Lista resultados de sorteos finalizados. Filtro: tipoLoteria.

Response
{
  "data": [{
    "id": "507f1f77bcf86cd799439011",
    "sorteoId": "1294202097",
    "nombre": "SORTEO DEL JUEVES",
    "tipoLoteria": "loteria_nacional",
    "fechaSorteo": "2024-12-19T21:00:00Z",
    "combinacion": "12345",
    "primerPremio": 300000,
    "estado": "finalizado"
  }],
  "pagination": { ... }
}
GET/resultados/:idread:sorteos

Obtiene el resultado de un sorteo especifico.

Resumen

Obtiene un resumen de tu cuenta.

GET/resumenread:decimos

Estadísticas generales: décimos, contratos, inversión.

Response
{
  "decimos": {
    "total": 15,
    "activos": 10,
    "ganadores": 2
  },
  "contratos": {
    "total": 8,
    "activos": 5,
    "pendientes": 3
  },
  "economico": {
    "inversionTotal": 300,
    "premiosGanados": 100,
    "balance": -200
  }
}

Estadísticas Globales

Obtiene estadísticas globales de tu cuenta.

GET/estadisticasread:estadisticas

Estadísticas completas: décimos, contratos, participaciones, deudas, peñas, contactos.

Response
{
  "decimos": {
    "total": 50,
    "activos": 30,
    "compartidos": 15,
    "finalizados": 5,
    "ganadores": 2,
    "inversionTotal": 1000,
    "premiosGanados": 200
  },
  "contratos": {
    "total": 10,
    "pendientes": 2,
    "activos": 8,
    "cancelados": 0
  },
  "participaciones": {
    "total": 25,
    "comoInvitador": 15,
    "comoParticipante": 10,
    "pendientes": 5,
    "aceptadas": 20
  },
  "deudas": {
    "totalDebo": 50,
    "totalMeDeben": 100,
    "balance": 50,
    "deudasPendientes": 5
  },
  "penas": {
    "total": 3,
    "comoAdmin": 1,
    "comoMiembro": 2,
    "decimosEnPenas": 10
  },
  "contactos": {
    "total": 20,
    "solicitudesPendientes": 3
  }
}

Scopes (Permisos)

Cada API Key puede tener uno o varios scopes que determinan a qué endpoints tiene acceso.

read:decimos

Leer décimos y resumen

edit:decimos

Crear y editar décimos

delete:decimos

Eliminar décimos

read:contratos

Leer contratos

edit:contratos

Crear contratos

delete:contratos

Cancelar contratos

read:participaciones

Leer participaciones

edit:participaciones

Crear y responder participaciones

delete:participaciones

Cancelar participaciones

read:deudas

Leer deudas

edit:deudas

Marcar y confirmar pagos

read:contactos

Leer contactos

edit:contactos

Gestionar solicitudes

delete:contactos

Eliminar contactos

read:penas

Leer peñas

edit:penas

Gestionar peñas

delete:penas

Eliminar peñas

read:sorteos

Leer sorteos y resultados

read:usuarios

Buscar usuarios por email

read:estadisticas

Estadísticas globales

full_access

Acceso completo a todos los endpoints

Paginación

Todos los listados aceptan estos parámetros y devuelven data y pagination (page, limit, total, totalPages, hasNext, hasPrev, nextCursor).

ParámetroDescripción
pageEntero ≥ 1. Por defecto 1.
limitEntero entre 1 y 100. Por defecto 20.
cursorCursor opaco (máx. 200 caracteres): usa el valor de pagination.nextCursor de la respuesta anterior. Sustituye a page.

Con page, si (page - 1) * limit supera 10 000 la API responde 400. Para recorrer más resultados usa cursor o acota con filtros (fechas, estado).

Paginación por cursor
curl "https://api.tudecimo.com/v1/public/decimos?limit=50" \
  -H "X-API-Key: tu_api_key_aqui"

curl "https://api.tudecimo.com/v1/public/decimos?limit=50&cursor=VALOR_DE_nextCursor" \
  -H "X-API-Key: tu_api_key_aqui"

Límites de Uso

La API solo está disponible con el plan UNLIMITED (FREE, BASIC y PRO no tienen acceso) y mientras la cuenta del dueño de la clave esté activa. Cada clave tiene sus límites, que no pueden superar el tope del plan.

300
Peticiones / minuto (máx. UNLIMITED)
5000
Peticiones / hora (máx. UNLIMITED)
50000
Peticiones / día (máx. UNLIMITED)
100
Ítems por página (máx.)

Los valores por defecto de una clave nueva son 100 por minuto, 1000 por hora y 10000 por día. Al superar un límite la API responde 429.

Restricciones de IP y dominio

Cada clave puede limitarse a una lista de IPs y a una lista de dominios. Si la clave tiene lista y la petición no coincide, la API responde 403. El dominio se toma de la cabecera Origin o, si no existe, de Referer.

Errores

CódigoCuándo
400Validación: JSON inválido, valor fuera de rango o de enum, campo desconocido en el body o en la query, salto superior a 10 000.
403Cualquier clave rechazada (no hay 401): ausente, inválida, caducada o revocada, IP o dominio no permitidos, plan sin acceso, dueño inactivo o scope insuficiente.
404El recurso no existe o no es tuyo.
429Límite de peticiones por minuto, hora o día superado.