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 PostmanLas API Keys se gestionan desde tu dashboard en Configuración > API Keys.
Inicio Rápido
URL Base
https://api.tudecimo.com/v1/publicAutenticación
X-API-Key: TU_API_KEYTambién se acepta Authorization: ApiKey TU_API_KEY. El esquema Bearer no es válido.
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.
/decimosread:decimosLista 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
}
}/decimos/:idread:decimosObtiene un décimo por ID.
/decimosedit:decimosCrea 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"
}/decimos/:idedit:decimosActualiza un décimo existente.
Request Body
{
"numero": "12345",
"descripcion": "Nuevo nombre"
}/decimos/:iddelete:decimosElimina un décimo (soft delete).
Contratos
Gestiona contratos de participación.
/contratosread:contratosLista todos los contratos del usuario. Filtros: status (pending, active, cancelled, expired), rol (creador, participante), fechaDesde, fechaHasta (ISO 8601).
/contratos/:idread:contratosObtiene un contrato por ID.
/contratosedit:contratosCrea un nuevo contrato.
Request Body
{
"decimoId": "507f1f77bcf86cd799439011",
"participantes": [
{
"email": "participante@ejemplo.com",
"nombre": "Juan Garcia",
"porcentaje": 50,
"monto": 10
}
],
"jurisdiccion": "España"
}/contratos/:iddelete:contratosCancela un contrato pendiente.
Participaciones
Gestiona participaciones en décimos compartidos.
/participacionesread:participacionesLista 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": { ... }
}/participaciones/:idread:participacionesObtiene una participación por ID.
/participacionesedit:participacionesCrea 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"
}/participaciones/:id/responderedit:participacionesAcepta 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"
}/participaciones/:iddelete:participacionesCancela una participación que enviaste.
Deudas
Gestiona deudas entre usuarios por participaciones.
/deudasread:deudasLista 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": { ... }
}/deudas/deboread:deudasLista lo que debo a otros.
/deudas/me-debenread:deudasLista lo que me deben otros.
/deudas/resumenread:deudasResumen de deudas: total debo, total me deben, balance.
Response
{
"totalDebo": 50,
"totalMeDeben": 100,
"balance": 50,
"deudasPendientes": 5,
"deudasPendienteConfirmacion": 1
}/deudas/:idread:deudasObtiene una deuda por ID.
/deudas/:id/marcar-pagadaedit:deudasMarca una deuda como pagada (como deudor).
Request Body
{
"notas": "Pagado por Bizum",
"metodoPago": "bizum"
}/deudas/:id/confirmar-pagoedit:deudasConfirma el pago de una deuda (como acreedor).
Contactos
Gestiona tu lista de contactos.
/contactosread:contactosLista todos los contactos. Filtro: q (búsqueda).
/contactos/solicitudes/pendientesread:contactosLista solicitudes de contacto pendientes recibidas.
/contactos/solicitudes/enviadasread:contactosLista solicitudes de contacto enviadas.
/contactos/solicitudedit:contactosEnvía una solicitud de contacto.
Request Body
{
"email": "usuario@ejemplo.com",
"mensaje": "Hola, me gustaria anadirte"
}/contactos/solicitud/:id/responderedit:contactosAcepta o rechaza una solicitud de contacto. accion: "aceptar" o "rechazar".
Request Body
{
"accion": "aceptar"
}/contactos/:iddelete:contactosElimina un contacto.
Peñas
Gestiona grupos de lotería (peñas).
/penasread:penasLista tus peñas. Filtros: estado (active, inactive, archived), miRol (admin, moderator, member).
/penas/invitacionesread:penasLista invitaciones pendientes a peñas.
/penas/:idread:penasObtiene detalle de una peña con miembros y décimos.
/penasedit:penasCrea una nueva peña.
Request Body
{
"nombre": "Mi Peña",
"descripcion": "Grupo de amigos",
"color": "#17663A"
}/penas/:idedit:penasActualiza una peña (solo admin).
/penas/:iddelete:penasElimina una peña (solo creador).
/penas/:id/miembrosread:penasLista miembros de una peña.
/penas/:id/miembrosedit:penasInvita a un miembro por email.
Request Body
{
"email": "usuario@ejemplo.com",
"porcentaje": 10,
"mensaje": "Te invito a mi peña"
}/penas/invitaciones/:id/responderedit:penasAcepta o rechaza una invitación a peña. accion: "aceptar" o "rechazar".
Request Body
{
"accion": "aceptar"
}/penas/:id/decimosread:penasLista décimos asignados a la peña.
/penas/:id/decimosedit:penasAsigna un décimo a la peña.
Request Body
{
"decimoId": "507f1f77bcf86cd799439011",
"porcentajeAsignado": 100,
"notas": "Décimo de Navidad"
}/penas/:id/decimos/:decimoIdedit:penasQuita un décimo de la peña.
/penas/:id/abandonaredit:penasAbandona una peña (no disponible para creador).
/penas/:id/estadisticasread:penasEstadísticas de la peña.
Usuarios
Busca usuarios registrados.
/usuarios?email=read:usuariosBusca 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.
/sorteosread:sorteosLista los sorteos disponibles.
/sorteos/:idread:sorteosObtiene detalles de un sorteo.
Resultados
Consulta resultados de sorteos finalizados.
/resultadosread:sorteosLista 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": { ... }
}/resultados/:idread:sorteosObtiene el resultado de un sorteo especifico.
Resumen
Obtiene un resumen de tu cuenta.
/resumenread:decimosEstadí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.
/estadisticasread:estadisticasEstadí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:decimosLeer décimos y resumen
edit:decimosCrear y editar décimos
delete:decimosEliminar décimos
read:contratosLeer contratos
edit:contratosCrear contratos
delete:contratosCancelar contratos
read:participacionesLeer participaciones
edit:participacionesCrear y responder participaciones
delete:participacionesCancelar participaciones
read:deudasLeer deudas
edit:deudasMarcar y confirmar pagos
read:contactosLeer contactos
edit:contactosGestionar solicitudes
delete:contactosEliminar contactos
read:penasLeer peñas
edit:penasGestionar peñas
delete:penasEliminar peñas
read:sorteosLeer sorteos y resultados
read:usuariosBuscar usuarios por email
read:estadisticasEstadísticas globales
full_accessAcceso 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ámetro | Descripción |
|---|---|
page | Entero ≥ 1. Por defecto 1. |
limit | Entero entre 1 y 100. Por defecto 20. |
cursor | Cursor 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).
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.
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ódigo | Cuándo |
|---|---|
400 | Validació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. |
403 | Cualquier 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. |
404 | El recurso no existe o no es tuyo. |
429 | Límite de peticiones por minuto, hora o día superado. |