Atividades
Criar Atividade
Criar uma nova atividade atribuída a um comércio.
POST /api/activities
Crie uma nova atividade TASK com atribuição de comércio.
Auth: Obrigatório — permissão activity:create
Corpo da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Sim | TASK |
reason | string | Sim | Código do motivo: apenas letras minúsculas, dígitos e _ (^[a-z0-9_]+$), máximo de 100 caracteres. Um código que não está no catálogo de motivos do tenant é adicionado a ele na hora, com um rótulo derivado do código (monthly_visit → Monthly visit) |
channel | string | Sim | SALESMAN, CALLCENTER |
commerce_id | UUID | Condicional | ID do comércio alvo. Envie este campo ou commerce_external_id: pelo menos um é obrigatório. Se você enviar os dois, commerce_id prevalece |
commerce_external_id | string | Condicional | Comércio alvo por ID externo (máximo de 255 caracteres). Se nenhum comércio o tiver, a API cria um comércio placeholder com esse ID externo |
idempotency_key | string | Sim | Chave única por tenant (evita duplicados) |
scheduled_at | ISO 8601 | Sim | Quando a atividade deve ser executada |
intent_category | string | Não | ONBOARDING, MARKETING, COLLECTION, RETENTION, NOTIFICATION, SURVEY ou VALIDATION. Padrão NOTIFICATION |
suggested_execution_time | ISO 8601 | Não | Horário sugerido para execução |
user_status | string | Não | Contexto de status do usuário |
score | integer | Não | Pontuação de prioridade |
assignment_reason | string | Não | Motivo da atribuição |
activity_details | object | Sim, para TASK | Detalhes específicos do tipo — o formato depende de type (ver abaixo) |
activity_details
Para type: "TASK", o objeto activity_details carrega a atribuição de rota/operador e é obrigatório. A rota e o operador são obrigatórios, cada um por ID ou por ID externo; se você enviar as duas formas, o ID prevalece. Um ID externo que nenhuma rota ou operador tem faz a API criar um placeholder com ele.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
assigned_route_id | UUID | Condicional | Rota atribuída. Envie este campo ou assigned_route_external_id |
assigned_route_external_id | string | Condicional | Rota atribuída por ID externo (máximo de 255 caracteres) |
assigned_operator_id | UUID | Condicional | Operador atribuído. Envie este campo ou assigned_operator_external_id |
assigned_operator_external_id | string | Condicional | Operador atribuído por ID externo (máximo de 255 caracteres) |
Exemplo
curl -X POST https://api.reten.ai/api/activities \
-H "Authorization: Bearer <token>" \
-H "x-tenant-id: <tenant-id>" \
-H "x-project-id: <project-id>" \
-H "Content-Type: application/json" \
-d '{
"type": "TASK",
"reason": "monthly_visit",
"channel": "SALESMAN",
"commerce_id": "880e8400-e29b-41d4-a716-446655440000",
"idempotency_key": "task-2025-01-15-001",
"scheduled_at": "2025-01-16T09:00:00.000Z",
"activity_details": {
"assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
"assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000"
}
}'const response = await fetch("https://api.reten.ai/api/activities", {
method: "POST",
headers: {
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
"x-project-id": "<project-id>",
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "TASK",
reason: "monthly_visit",
channel: "SALESMAN",
commerce_id: "880e8400-e29b-41d4-a716-446655440000",
idempotency_key: "task-2025-01-15-001",
scheduled_at: "2025-01-16T09:00:00.000Z",
activity_details: {
assigned_route_id: "dd0e8400-e29b-41d4-a716-446655440000",
assigned_operator_id: "cc0e8400-e29b-41d4-a716-446655440000",
},
}),
});
const activity = await response.json();import requests
response = requests.post(
"https://api.reten.ai/api/activities",
headers={
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
"x-project-id": "<project-id>",
},
json={
"type": "TASK",
"reason": "monthly_visit",
"channel": "SALESMAN",
"commerce_id": "880e8400-e29b-41d4-a716-446655440000",
"idempotency_key": "task-2025-01-15-001",
"scheduled_at": "2025-01-16T09:00:00.000Z",
"activity_details": {
"assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
"assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000",
},
},
)
activity = response.json()Resposta 201 Created
Uma atividade TASK nasce em READY e fica pronta para ser despachada imediatamente: a identidade do comércio atribuído é tudo o que o despacho precisa. Veja Activity States para o catálogo completo.
Se uma atividade do projeto ativo já tiver essa idempotency_key, a API não cria nada e responde 200 OK com a atividade existente.
{
"id": "ee0e8400-e29b-41d4-a716-446655440000",
"projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
"type": "TASK",
"reason": {
"code": "monthly_visit",
"label": "Visita Mensual"
},
"channel": "SALESMAN",
"status": "READY",
"userStatus": null,
"idempotencyKey": "task-2025-01-15-001",
"scheduledAt": "2025-01-16T09:00:00.000Z",
"commerceAssignment": {
"commerceId": "880e8400-e29b-41d4-a716-446655440000"
}
}Respostas de Erro
| Status | Descrição |
|---|---|
400 | Erro de validação: um campo ausente ou inválido, ou um campo que o endpoint não aceita |
400 | Nem commerce_id nem commerce_external_id — Se requiere al menos uno de los campos commerce_id o commerce_external_id. |
400 | TASK sem activity_details — TASK activities require activityDetails |
400 | activity_details sem rota ou sem operador — assigned_route_id is required for TASK activities / assigned_operator_id is required for TASK activities |
400 | A rota ou o operador atribuído está inativo — Assigned route is not active / Assigned operator is not active |
400 | user_status não é um código ativo do catálogo de status de retenção do tenant — User retention status "<code>" is not configured for this tenant |
404 | commerce_id, assigned_route_id ou assigned_operator_id não existe — Commerce not found / Route not found / Operator not found |
409 | A idempotency_key já é usada por uma atividade de outro projeto do tenant — La clave de idempotencia ya está en uso. |