Account

Cuenta de usuario: es lo que permite registrarse, iniciar sesión e identificarse en la API. Cada cuenta es de un solo tipo y tiene exactamente un perfil asociado según ese tipo: Client, Provider o Admin (relación user).

Tipo (type)

type codifica el rol como un valor de bits crecientes: client (0x00), provider (0x0f), seller_admin (0x30), low_admin (0x70), high_admin (0x77), owner_admin (0x7f) y super_admin (0xff). type_name (client / provider / admin) resume el grupo y se calcula al crear. accessLevel() va de 0 (cliente/repartidor) a 5 (super admin).

Estado (status, bitmask)

El ide-helper expone los bits de status como propiedades; ojo con los invertidos:

  • is_status_disabled: cuenta deshabilitada por un administrador.
  • is_status_blocked: cuenta bloqueada (por ejemplo por fraude).
  • is_phone_verified / is_email_verified: invertidos — el bit puesto significa "sin verificar"; la propiedad devuelve true cuando SÍ está verificado.
  • is_identity_verified: identidad (documento) verificada.
  • is_active: true si el grupo de bits de estado (0xf00) está a cero, es decir sin restricciones. El accesor is_restricted es lo contrario (disabled o blocked).

status_info es el resumen legible (disabled, blocked, unverified, unconfirmed, active). Los endpoints disable / block / activate cambian estos bits.

Balance

La cuenta es "balance owner": balance_e2 y derivados (todos en céntimos) son su monedero; available_balance_e2 suma el crédito setting_balance_credit_e2.

Ajustes (settings)

Casi todos los setting_* son tokens internos (Firebase, sesión, sockets, verificación) y no se editan por la API. El sub-recurso accounts/{id}/settings sólo expone last_seen (lectura) y permite editar telegram_id y telegram_actions.

Notas y gotchas

  • password se cifra automáticamente al asignarlo; nunca se devuelve.
  • Deshabilitar/eliminar/restaurar la cuenta hace lo mismo con su perfil asociado; cambiar el email lo propaga al perfil.

Estructura de Datos

Atributo Tipo Descripción
id int
email string Correo de la cuenta; único por compañía.
password string Contraseña cifrada (bcrypt); oculta en la respuesta.
type int Rol de la cuenta como valor de bits (ver la lista de tipos arriba).
status int Estado de la cuenta como bitmask; ver los bits is_status_* / is_*_verified arriba.
remember_token string\|null Token "recordarme" de sesión; oculto en la respuesta.
created_at datetime\|null Fecha de creación.
updated_at datetime\|null Fecha de última modificación.
deleted_at datetime\|null Fecha de borrado lógico.
company_id int Compañía dueña de la cuenta (oculto en la respuesta).
type_name string\|null Grupo del tipo: client, provider o admin.
is_status_disabled bool BitMask (({@link self::status} & 0x100) !== 0)
is_status_blocked bool BitMask (({@link self::status} & 0x200) !== 0)
is_phone_verified bool BitMask (({@link self::status} & 0x400) === 0)
is_email_verified bool BitMask (({@link self::status} & 0x800) === 0)
is_identity_verified bool BitMask (({@link self::status} & 0x2000) !== 0)
is_active bool BitMask ((({@link self::status} & 0xf00) >> 8) === 0)
setting_last_notification_id int Atajo del ajuste last_notification_id: última notificación entregada a la cuenta.
setting_firebase_token Token\|null Atajo del ajuste firebase_token: token de push de Firebase.
setting_confirmation_token array\|null Atajo del ajuste confirmation_token: token de confirmación de correo.
setting_phone_token Token\|null Atajo del ajuste phone_token: token de verificación de teléfono.
setting_email_token Token\|null Atajo del ajuste email_token: token de verificación de correo.
setting_session_token array\|null Atajo del ajuste session_token: token de la sesión activa.
setting_socket_token array\|null Atajo del ajuste socket_token: token para el canal de sockets.
setting_last_seen datetime\|null Atajo del ajuste last_seen: última conexión de la cuenta.
setting_telegram_id string\|null Atajo del ajuste telegram_id: id de Telegram enlazado (editable).
setting_telegram_actions array Atajo del ajuste telegram_actions: acciones pendientes del bot de Telegram (editable).
setting_sockette_token string\|null Atajo del ajuste sockette_token: token del servicio Sockette.
setting_sockette_channels array Atajo del ajuste sockette_channels: canales suscritos en Sockette.
setting_ignores_city_balance bool Atajo del ajuste ignores_city_balance: excluye el saldo de la cuenta del cómputo de deudas de la ciudad.
setting_confirmed_at datetime\|null Atajo del ajuste confirmed_at: fecha de confirmación del correo.
setting_balance_credit_e2 int\|null Atajo del ajuste balance_credit_e2: crédito adicional que suma al saldo disponible (céntimos).
setting_phone_verified_at datetime\|null Atajo del ajuste phone_verified_at: fecha de verificación del teléfono.
setting_identity_verified_at datetime\|null Atajo del ajuste identity_verified_at: fecha de verificación de la identidad.
activeBalanceModifiers BalanceModifier> Modificadores de saldo promocional vigentes de la cuenta.
admin Admin\|null Perfil de administrador, si type_name = admin.
allLogs ApiLog> Registros de auditoría de la API, incluidos los internos.
allSettings AccountSetting> Todos los ajustes de la cuenta (oculto en la respuesta).
allowed_settings array Claves de ajuste visibles para el rol actual.
available_balance_e2 int Saldo disponible incluyendo el crédito de la cuenta (céntimos).
available_for_withdrawal_balance_e2 int Saldo disponible para retiro (céntimos).
balance_e2 int Saldo del monedero de la cuenta (céntimos).
balanceModifiers BalanceModifier> Modificadores de saldo promocional de la cuenta.
balanceMovements BalanceMovement> Movimientos del monedero de la cuenta.
client Client\|null Perfil de cliente, si type_name = client.
company Company Compañía dueña de la cuenta.
editable_settings array Claves de ajuste editables por el rol actual.
is_email_valid bool true si el email tiene formato válido.
is_phone_user bool true si la cuenta se registró con teléfono (no correo real).
is_profile_completed bool true si el perfil asociado tiene los datos mínimos (por ejemplo teléfono del cliente).
is_restricted bool true si la cuenta está deshabilitada o bloqueada.
lastBalanceMovement BalanceMovement\|null Último movimiento del monedero de la cuenta.
locked_for_withdrawal_balance_e2 int Saldo bloqueado para retiro (céntimos).
logs ApiLog> Registros de auditoría de la API visibles.
notifications DatabaseNotification> Notificaciones de la cuenta.
provider Provider\|null Perfil de repartidor, si type_name = provider.
settings array Ajustes de la cuenta visibles para el rol actual.
settingsFirebaseToken AccountSetting\|null Ajuste con el token de Firebase de la cuenta.
settingsLastSeen AccountSetting\|null Ajuste con la última conexión de la cuenta.
status_info array Resumen legible del estado (disabled, blocked, unverified, unconfirmed, active).
tokens AccessToken> Tokens de acceso emitidos para la cuenta. 
{
    "id": 175,
    "email": "pedrop@manzanares.com.ve",
    "type": 255,
    "status": 37104,
    "created_at": "2020-04-20 15:24:38",
    "updated_at": "2023-11-14 17:15:59",
    "deleted_at": null,
    "type_name": "admin",
    "is_status_disabled": false,
    "is_status_blocked": false,
    "is_phone_verified": true,
    "is_email_verified": true,
    "is_identity_verified": false,
    "is_active": true,
    "status_info": {
        "disabled": false,
        "blocked": false,
        "unverified": false,
        "unconfirmed": false,
        "active": true
    }
}

Endpoints

Listar Account

{info} Soporta: Paginación Filters Carga dinámica

Listar cuentas

Devuelve las Account de la compañía, paginadas. El filtro de texto busca por correo y por los datos del perfil (cliente, repartidor o administrador).

Método URI Cabeceras
GET /companies/{companyId}/accounts Authorization

Ver los ajustes de una cuenta

Devuelve los settings de la Account visibles para el rol actual (last_seen).

Método URI Cabeceras
GET /companies/{companyId}/accounts/{accountId}/settings Authorization

Mostrar Account

Ver una cuenta

Devuelve la Account indicada con su status_info.

Método URI Cabeceras
GET /companies/{companyId}/accounts/{accountId} Authorization

Actualizar Account

Actualizar los ajustes de una cuenta

Modifica los settings editables de la Account (telegram_id, telegram_actions).

Método URI Cabeceras
PATCH /companies/{companyId}/accounts/{accountId}/settings Authorization 
{
    "telegram_id": "string",
    "telegram_actions": "array",
    "balance_credit_e2": "nullable|integer|min:0"
}

Eliminar Account

Eliminar una cuenta

Hace un borrado lógico de la Account y de su perfil asociado.

Método URI Cabeceras
DELETE /companies/{companyId}/accounts/{accountId} Authorization

Restaurar Account

Restaurar una cuenta

Revierte el borrado lógico de la Account y de su perfil asociado.

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/restore Authorization

Acciones de Account

Verificar el teléfono de una cuenta

Valida el code enviado por SMS y marca el teléfono de la Account como verificado (is_phone_verified).

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/verify-phone/{code} N/A 
{
    "phone": "required|string"
}

Errores de negocio

Código HTTP Cuándo ocurre
EB107 403 El código de verificación ha caducado.
EB108 403 El código de verificación no coincide.
EB109 403 El token de verificación es incorrecto.
EB121 409 El teléfono ya está en uso por otra cuenta.

Enviar el código de verificación de teléfono

Envía por SMS un código para verificar el teléfono de la Account.

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/send-phone-code N/A 
{
    "phone": "required|string"
}

Errores de negocio

Código HTTP Cuándo ocurre
EB110 400 Hay que esperar antes de volver a solicitar un código para ese teléfono.
EB121 409 El teléfono ya está en uso por otra cuenta.

Ver mi cuenta

Devuelve la Account autenticada.

Método URI Cabeceras
GET /companies/{companyId}/accounts/me Authorization

Deshabilitar una cuenta

Pone is_status_disabled en la Account; la cuenta queda restringida y no puede operar.

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/disable Authorization

Bloquear una cuenta

Pone is_status_blocked en la Account (bloqueo por fraude u otra causa grave).

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/block Authorization

Reactivar una cuenta

Quita los bits is_status_disabled / is_status_blocked de la Account.

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/activate Authorization

Cambiar la contraseña de una cuenta

Fija una nueva contraseña de la Account tras comprobar la anterior.

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/update-password Authorization 
{
    "new_password": "required|min:5"
}

Errores de negocio

Código HTTP Cuándo ocurre
EB111 401 La contraseña actual (old_password) no coincide.

Cambiar el correo de una cuenta

Cambia el email de la Account; el cambio se propaga al perfil asociado.

Método URI Cabeceras
POST /companies/{companyId}/accounts/{accountId}/update-email Authorization 
{
    "email": "required|email:rfc,filter"
}

Ver los ajustes editables de una cuenta

Devuelve las claves de settings que el rol actual puede modificar (telegram_id, telegram_actions), con sus reglas.

Método URI Cabeceras
GET /companies/{companyId}/accounts/{accountId}/allowed-settings Authorization

Relaciones