ScheduledTask

Trabajo diferido/programado. Cada fila es una tarea que se despachará en dispatch_at (o de inmediato) y cuyo resultado queda registrado en payload.task_result.

Tipos (type)

notification (envío masivo de notificaciones), batch_good_import (importación masiva de productos), bancamiga_report / bnc_pos_report (reportes bancarios), virtual_request_call (llamada a un endpoint externo diferida), send_sms.

Estados (status)

pending → dispatched (ya ejecutada). Alternativamente aborted (cancelada antes de despacharse) o error (falló). priority puede ser default, low, high o special.

Notas y gotchas

  • company_id/branch_id/branch_group_id fijan el ámbito; se usan para dirigir las notificaciones en tiempo real.
  • Sólo se puede abortar una tarea que siga programada y sin despachar.
  • El accesor action resuelve el modelo objetivo de un envío masivo a partir de payload.action_type (+ action_id): branch_group, good, branch_category o category.

Estructura de Datos

Atributo Tipo Descripción
id int
type string Tipo de tarea (ver lista arriba).
priority string Prioridad de ejecución: default, low, high o special.
payload array Parámetros de la tarea y, tras ejecutarse, su resultado (task_result).
status string Estado: pending, dispatched, aborted o error.
dispatch_at datetime\|null Momento en que debe despacharse la tarea.
dispatched_at datetime\|null Momento en que se despachó realmente.
aborted_at datetime\|null Momento en que se abortó, si aplica.
created_at datetime\|null Fecha de creación.
updated_at datetime\|null Fecha de última modificación.
company_id int Compañía dueña de la tarea (oculto en la respuesta).
branch_id int\|null Comercio al que aplica la tarea; null si no aplica a uno.
branch_group_id int\|null Grupo de comercios al que aplica la tarea; null si no aplica.
task_id bigint -
action object\|null Modelo objetivo del envío masivo, resuelto desde payload.action_type/action_id.
allLogs ApiLog> Registros de auditoría de la API, incluidos los internos.
branch Branch\|null Comercio al que aplica la tarea.
logs ApiLog> Registros de auditoría de la API visibles.
should_notify_creator bool true si al terminar debe notificarse a quien creó la tarea.
should_notify_via_push bool true si la notificación de progreso/fin debe enviarse también por push. 
{
    "id": 1453,
    "type": "notification",
    "priority": "default",
    "payload": {
        "title": "aaaaaaa",
        "body": "addddd",
        "target_type": "providers"
    },
    "status": "aborted",
    "dispatch_at": "2020-10-29 22:03:57",
    "dispatched_at": null,
    "aborted_at": "2020-10-20 22:06:58",
    "created_at": "2020-10-20 22:04:13",
    "updated_at": "2020-10-20 22:06:58",
    "branch_id": null,
    "branch_group_id": null,
    "task_id": null
}

Endpoints

Listar ScheduledTask

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

Listar tareas programadas

Devuelve las ScheduledTask de la compañía, ordenadas por dispatch_at descendente, paginadas.

Método URI Cabeceras
GET /companies/{companyId}/scheduled-tasks Authorization

Listar ScheduledTask de Branch

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

Listar tareas programadas de un comercio

Devuelve las ScheduledTask cuyo branch_id es el comercio indicado, paginadas.

Método URI Cabeceras
GET /companies/{companyId}/branches/{branchId}/scheduled-tasks Authorization

Mostrar ScheduledTask

{info} Soporta: Carga dinámica

Ver una tarea programada

Devuelve la ScheduledTask indicada. Con with_action=1 incluye el modelo objetivo resuelto (action).

Método URI Cabeceras
GET /companies/{companyId}/scheduled-tasks/{scheduledTaskId} Authorization

Acciones de ScheduledTask

Enviar una notificación masiva

Crea una ScheduledTask de tipo notification para enviar un push/aviso a la audiencia indicada (compañía, grupo, comercio, categoría o producto según action_type + action_id); admite una image adjunta.

Método URI Cabeceras
POST /companies/{companyId}/send-broadcast-message Authorization 
{
    "title": "required|string|max:80",
    "body": "required|string|max:200",
    "target_type": "required|string|in:everyone,clients,providers,branch_admins,custom,email",
    "target_ids": [
        "integer"
    ],
    "target_emails": [
        "email"
    ],
    "action_type": "string|in:branch_group,good,branch_category,category",
    "action_id": "required_with:action_type|integer",
    "image": "image|mimes:jpeg,png|max:1024|dimensions:width=1000,height=500",
    "segmentation": [
        {
            "string": true,
            "regex": "/^(geofence:[1-9][0-9]*)|(city:[1-9][0-9]*)|(company_geofence:(inside|outside))(,(geofence:[1-9][0-9]*)|(city:[1-9][0-9]*)|(company_geofence:(inside|outside)))*$/"
        }
    ],
    "send_at": "date|after:now",
    "send_at_timezone": {
        "string": true,
        "regex": "/^[\+\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    }
}

Programar una llamada a un endpoint

Crea una ScheduledTask de tipo virtual_request_call que llamará a la url indicada con el content dado en el momento programado.

Método URI Cabeceras
POST /companies/{companyId}/schedule-request Authorization 
{
    "name": "required|string|max:64",
    "url": "required|url|regex:#^http://127.0.0.1:8000/api/v\d+/.*$#",
    "method": "required|string|in:POST,PATCH,UPDATE,DELETE",
    "content": "array",
    "send_at": "required|date|after:now",
    "send_at_timezone": {
        "string": true,
        "regex": "/^[\+\-]([0-1][0-9]|2[0-3]):[0-5][0-9]$/"
    }
}

Errores de negocio

Código HTTP Cuándo ocurre
ER400 400 La url apunta al propio endpoint de programación.

Abortar una tarea programada

Cancela una ScheduledTask que siga programada y sin despachar; pasa a aborted.

Método URI Cabeceras
POST /companies/{companyId}/scheduled-tasks/{scheduledTaskId}/abort Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EF105 400 La tarea ya fue despachada.
EF106 400 La tarea no está programada.

Relaciones