Autenticación

Endpoints para iniciar y cerrar sesión, refrescar el token de acceso y autenticarse contra el canal de sockets. Todos operan sobre el modelo Account: una cuenta identifica a un usuario y tiene un único perfil según su type (Client, Provider o Admin).

Modelo y tipos de cuenta

La respuesta de un inicio de sesión correcto es el perfil que inició sesión (Client, Provider o Admin), con su account embebido y un access_token:

{
    "…": "campos del perfil (Client / Provider / Admin)",
    "account": {
        "id": "int",
        "email": "string",
        "type": "int",
        "status": "int",
        "type_name": "client | provider | admin"
    },
    "access_token": {
        "token_type": "bearer",
        "access_token": "string (JWT)",
        "created_at": "datetime",
        "expires_at": "datetime",
        "expires_in": "int (segundos)"
    },
    "registered": "bool — true si la cuenta se creó en esta misma petición"
}

El access_token.access_token se envía en las siguientes peticiones como cabecera Authorization: Bearer <token> (ver Autenticación).

Tipo de cuenta (account.type) — valor de bits crecientes según el rol:

type Rol Descripción
0 (0x00) client Compra productos y servicios.
15 (0x0f) provider Realiza entregas o presta servicios.
48 (0x30) seller_admin Vendedor con app propia; puede crear órdenes para sus clientes, acceso limitado.
112 (0x70) low_admin Atiende al público (órdenes, pagos); no cambia la configuración.
119 (0x77) high_admin Gestiona configuración, productos, categorías y privilegios.
127 (0x7f) owner_admin Propietario de la compañía; todos los privilegios sobre ella.
255 (0xff) super_admin Acceso a todas las compañías (staff de DonDemand).

account.type_name (client / provider / admin) resume el grupo.

Estado de la cuenta (account.status) — bitmask; se detalla en Account. Resumen:

Bit Significado
is_status_disabled Deshabilitada por un administrador: no puede iniciar sesión.
is_status_blocked Bloqueada: puede iniciar sesión y consultar, pero no operar.
is_phone_verified (invertido) El bit puesto significa teléfono sin verificar.
is_email_verified (invertido) El bit puesto significa correo sin confirmar.
is_identity_verified Identidad (documento) verificada.

{info} Todos los endpoints de inicio de sesión están limitados a 5 intentos por email/teléfono + IP; superado el límite responden 423 con too_many_attempts {seconds}.

Búsqueda previa de compañías (admin)

Dado un correo de administrador, devuelve las compañías en las que ese correo tiene una cuenta de tipo admin, para que el cliente muestre un selector antes de pedir la contraseña.

Método URI Cabeceras
POST /companies/{companyId}/login-lookup N/A 
{
    "email": "required|email"
}

Respuesta

[
    {
        "id": "int (companyId)",
        "name": "string",
        "logo": "string|null",
        "country_iso": "string",
        "url": "string — URL del panel de esa compañía"
    }
]

Si el correo no corresponde a ningún administrador, la lista viene vacía.

Inicio de sesión nativo

Verifica correo y contraseña y genera un token de acceso. Opcionalmente actualiza la ubicación del usuario (latitude_e6 / longitude_e6) y el push_token para notificaciones push. Al iniciar sesión, un provider o un admin pasan a estado en línea.

Método URI Cabeceras
POST /companies/{companyId}/login-native N/A 
{
    "type": "required|string|in:admin,provider,client",
    "email": "required|email",
    "password": "required|string|min:5|max:1024",
    "latitude_e6": "integer",
    "longitude_e6": "integer",
    "push_token": "nullable|string|max:255"
}

{info} Para provider la cuenta se busca en la compañía y en sus compañías vinculadas, priorizando las cuentas sin restricciones de estado.

Respuesta

Código 200 — el perfil que inició sesión (Admin, Provider o Client) con account, access_token y registered (ver Modelo).

Errores de negocio

Código HTTP Cuándo ocurre
EB100 401 El correo no existe o la contraseña no coincide.

Inicio de sesión social

Inicia sesión (o registra un cliente) con un proveedor social (google, apple, facebook, ...). Para facebook y apple se envía el token del proveedor en code; para el resto, el código de autorización OAuth.

Método URI Cabeceras
POST /companies/{companyId}/login-social N/A 
{
    "method": "required|string|in:<drivers configurados>",
    "code": "required|string",
    "push_token": "string|max:255"
}

Respuesta

Código 200 si la cuenta ya existía, 201 si se creó en esta petición. Cuerpo igual que el inicio de sesión nativo (ver Modelo).

Errores de negocio

Código HTTP Cuándo ocurre
EB102 401 El token/código del proveedor social no es válido o fue rechazado.

Inicio de sesión con Facebook

Variante específica de Facebook que valida el user_token contra la app de Facebook configurada en la compañía. Sólo crea/usa cuentas de tipo client.

Método URI Cabeceras
POST /companies/{companyId}/login-facebook N/A 
{
    "user_token": "required|string",
    "push_token": "string|max:255"
}

{warning} Requiere que la compañía tenga configurados facebook_app_id y facebook_secret_token; si no, el endpoint responde que la función no está disponible. Responde 400 token_invalid si el token no pertenece a esa app de Facebook.

Enviar código de acceso

Envía un código de 4 dígitos al phone (por SMS) o al email (por correo) del cliente, que luego se usa como contraseña temporal en login-phone. Se debe enviar phone o email, uno de los dos.

Método URI Cabeceras
POST /companies/{companyId}/send-login-code N/A 
{
    "phone": "required_without:email|string",
    "email": "required_without:phone|email"
}

{info} El inicio de sesión por teléfono debe estar habilitado en la configuración de la compañía. Si aún hay un código vigente, se reutiliza y se renueva su tiempo de vida.

Errores de negocio

Código HTTP Cuándo ocurre
EB119 400 No hay ninguna cuenta con ese correo.
EB110 400 Hay que esperar unos segundos antes de volver a pedir un código.
ER011 403 La cuenta del cliente está bloqueada (eliminada).

Inicio de sesión por código (teléfono / correo)

Valida el código de 4 dígitos enviado con send-login-code e inicia sesión. Si el código era de teléfono marca el teléfono como verificado; si era de correo, marca el correo como confirmado.

Método URI Cabeceras
POST /companies/{companyId}/login-phone N/A 
{
    "phone": "required_without:email|string",
    "email": "required_without:phone|email",
    "code": "required|string"
}

Respuesta

Código 200 — el Client con account, access_token y registered (ver Modelo).

Errores de negocio

Código HTTP Cuándo ocurre
EB107 403 El código ha caducado.
EB108 403 El código no coincide.
EB119 400 No hay ninguna cuenta con ese correo.
ER011 403 La cuenta del cliente está bloqueada (eliminada).

Cerrar sesión

Invalida el token de acceso usado en la petición y borra el token de push de la cuenta.

Método URI Cabeceras
POST /logout Authorization

Respuesta 204 sin cuerpo.

Actualizar el token de notificaciones

Guarda el push_token (Firebase) de la cuenta autenticada para el envío de notificaciones push.

Método URI Cabeceras
POST /token Authorization 
{
    "push_token": "required|string|max:255"
}

Respuesta 204 sin cuerpo.

Refrescar el token de acceso

Devuelve un nuevo access_token para la cuenta autenticada, extendiendo la sesión sin volver a pedir credenciales.

Método URI Cabeceras
POST /token-refresh Authorization

Respuesta

{
    "token_type": "bearer",
    "access_token": "string (JWT)",
    "created_at": "datetime",
    "expires_at": "datetime",
    "expires_in": "int (segundos)"
}

Errores de negocio

Código HTTP Cuándo ocurre
EB105 404 El token no corresponde a ninguna cuenta.

Autenticación de sockets

Devuelve la información de autenticación de la cuenta contra el canal de sockets en tiempo real de la compañía. GET reutiliza el token vigente; POST fuerza generar uno nuevo.

Método URI Cabeceras
GET /companies/{companyId}/socket-auth Authorization
POST /companies/{companyId}/socket-auth Authorization

La respuesta se serializa con el recurso socketAuth de la cuenta.