API REST v1

Documentacion de la API

Integra Tu Decimo en tus aplicaciones mediante nuestra API REST.

Descargar Coleccion Postman

Requiere plan UNLIMITED

Las API Keys se gestionan desde tu dashboard en Configuracion > API Keys.

Inicio Rapido

URL Base

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

Autenticacion

Authorization: Bearer TU_API_KEY

Ejemplo de peticion

curl -X GET "https://api.tudecimo.es/api/v1/public/decimos" \
  -H "Authorization: Bearer tu_api_key_aqui" \
  -H "Content-Type: application/json"

Decimos

Gestiona tus decimos de loteria.

GET/decimosread:decimos

Lista todos los decimos del usuario.

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 decimo por ID.

POST/decimoswrite:decimos

Crea un nuevo decimo. Si no se proporciona sorteoId, se detecta automaticamente por fecha y tipo.

Request Body

{
  "numero": "12345",
  "tipoLoteria": "loteria_nacional",
  "fechaSorteo": "2024-12-22",
  "sorteoId": "507f1f77bcf86cd799439011",  // opcional
  "serie": "10",
  "fraccion": "5",
  "montoTotal": 20,
  "descripcion": "Decimo de Navidad"
}

PUT/decimos/:idwrite:decimos

Actualiza un decimo existente.

Request Body

{
  "numero": "12345",
  "descripcion": "Nuevo nombre"
}

DELETE/decimos/:idwrite:decimos

Elimina un decimo (soft delete).

Contratos

Gestiona contratos de participacion.

GET/contratosread:contratos

Lista todos los contratos del usuario.

GET/contratos/:idread:contratos

Obtiene un contrato por ID.

POST/contratoswrite:contratos

Crea un nuevo contrato.

Request Body

{
  "decimoId": "507f1f77bcf86cd799439011",
  "participantes": [
    {
      "email": "[email protected]",
      "nombre": "Juan Garcia",
      "porcentaje": 50,
      "monto": 10
    }
  ],
  "jurisdiccion": "Espana"
}

DELETE/contratos/:idwrite:contratos

Cancela un contrato pendiente.

Participaciones

Gestiona participaciones en decimos compartidos.

GET/participacionesread:participaciones

Lista todas las participaciones. Filtros: estado, 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 participacion por ID.

POST/participacioneswrite:participaciones

Crea una participacion (invita a alguien a tu decimo).

Request Body

{
  "decimoId": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "porcentaje": 25,
  "monto": 5,
  "mensaje": "Te invito a participar"
}

POST/participaciones/:id/responderwrite:participaciones

Acepta o rechaza una participacion recibida.

Request Body

{
  "accion": "aceptar",  // o "rechazar"
  "motivo": "No me interesa"  // solo si rechaza
}

DELETE/participaciones/:idwrite:participaciones

Cancela una participacion que enviaste.

Usuarios

Busca usuarios registrados.

GET/usuarios?email=read:usuarios

Busca un usuario por email. Util para validar antes de enviar participacion.

Response

{
  "id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "nombre": "Juan Garcia",
  "telefono": "+34612345678"
}

Sorteos

Consulta informacion de sorteos de loteria.

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

Estadisticas generales: decimos, contratos, inversion.

Response

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

Deudas

Gestiona deudas entre usuarios por participaciones.

GET/deudasread:deudas

Lista todas las deudas del usuario.

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
}

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 (busqueda).

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

Envia una solicitud de contacto.

Request Body

{
  "email": "[email protected]",
  "mensaje": "Hola, me gustaria añadirte"
}

POST/contactos/solicitud/:id/responderedit:contactos

Acepta o rechaza una solicitud de contacto.

Request Body

{
  "accion": "aceptar"  // o "rechazar"
}

DELETE/contactos/:iddelete:contactos

Elimina un contacto.

Penas

Gestiona grupos de loteria (penas).

GET/penasread:penas

Lista tus penas. Filtros: estado, miRol.

GET/penas/invitacionesread:penas

Lista invitaciones pendientes a penas.

GET/penas/:idread:penas

Obtiene detalle de una pena con miembros y decimos.

POST/penasedit:penas

Crea una nueva pena.

Request Body

{
  "nombre": "Mi Pena",
  "descripcion": "Grupo de amigos",
  "color": "#1B5E20"
}

PUT/penas/:idedit:penas

Actualiza una pena (solo admin).

DELETE/penas/:iddelete:penas

Elimina una pena (solo creador).

GET/penas/:id/miembrosread:penas

Lista miembros de una pena.

POST/penas/:id/miembrosedit:penas

Invita a un miembro por email.

Request Body

{
  "email": "[email protected]",
  "porcentaje": 10,
  "mensaje": "Te invito a mi pena"
}

POST/penas/invitaciones/:id/responderedit:penas

Acepta o rechaza una invitacion a pena.

Request Body

{
  "accion": "aceptar"  // o "rechazar"
}

GET/penas/:id/decimosread:penas

Lista decimos asignados a la pena.

POST/penas/:id/decimosedit:penas

Asigna un decimo a la pena.

Request Body

{
  "decimoId": "507f1f77bcf86cd799439011",
  "porcentajeAsignado": 100,
  "notas": "Decimo de Navidad"
}

DELETE/penas/:id/decimos/:decimoIdedit:penas

Quita un decimo de la pena.

POST/penas/:id/abandonaredit:penas

Abandona una pena (no disponible para creador).

GET/penas/:id/estadisticasread:penas

Estadisticas de la pena.

Estadisticas Globales

Obtiene estadisticas globales de tu cuenta.

GET/estadisticasread:estadisticas

Estadisticas completas: decimos, contratos, participaciones, deudas, penas, 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 que endpoints tiene acceso.

read:decimos

Leer decimos y resumen

edit:decimos

Crear y editar decimos

delete:decimos

Eliminar decimos

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 penas

edit:penas

Gestionar penas

delete:penas

Eliminar penas

read:sorteos

Leer sorteos y resultados

read:usuarios

Buscar usuarios por email

read:estadisticas

Estadisticas globales

full_access

Acceso completo a todos los endpoints

Limites de Uso

1000

Peticiones / hora

100

Peticiones / minuto

100

Items por pagina (max)