API atual/Referência completa/Venddor Intelligence: automações e canais

Rotinas agendadas

Cria, lista, lê, altera e exclui as rotinas: tarefas da VI que rodam em horário fixo.

Uma rotina é uma tarefa recorrente descrita em linguagem natural, por exemplo "toda segunda às 7h, liste os produtos com estoque abaixo de 5". A VI a transforma em um plano (lista de passos), que o administrador revisa antes de ativar. As rotinas são da loja: qualquer administrador com o privilégio as vê.

Listar rotinas

Devolve todas as rotinas não excluídas da loja, da mais nova para a mais antiga.

GET/api/v1/admin/intelligence/routinesAdmin

Listar rotinas

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/routines" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotinas

json

{
  "routines": [
    {
      "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "name": "Relatório matutino",
      "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
      "plan": [
        { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
      ],
      "schedule_kind": "daily",
      "schedule_dow": null,
      "schedule_dom": null,
      "schedule_hour": 8,
      "timezone": "America/Sao_Paulo",
      "status": "draft",
      "require_approval": true,
      "last_run_at": null
    }
  ],
  "total": 1
}

Campos da resposta

routinesarray

Rotinas, com os campos abaixo.

iduuid

Id da rotina.

user_iduuid

Administrador que a criou.

namestring

Nome.

prompt_textstring

Texto original, em linguagem natural.

planarray

Passos compilados: tool (identificador do passo), params (objeto), is_write (altera a loja) e description (frase para o administrador).

schedule_kindstring

dailyweeklymonthly

Periodicidade.

schedule_dowinteger

Dia da semana (0 = domingo ... 6 = sábado) em weekly. Nulo nos demais.

schedule_dominteger

Dia do mês (1 a 28) em monthly. Nulo nos demais.

schedule_hourinteger

Hora do dia, 0 a 23, no fuso timezone.

timezonestring

Fuso IANA. Padrão America/Sao_Paulo.

statusstring

draftactivepausedarchived

Estado.

require_approvalboolean

Se a execução para antes do primeiro passo que escreve.

last_run_atstring

RFC 3339 da última execução concluída. Nulo se nunca rodou.

totalinteger

Quantidade devolvida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`

Criar uma rotina

Grava a rotina como rascunho. Ela só roda sozinha depois de Ativar.

POST/api/v1/admin/intelligence/routinesAdmin

Criar uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

namestringobrigatório

Nome. Obrigatório na criação.

prompt_textstring

Texto original da rotina.

planarray

Passos, no formato devolvido por compile. Sem valor, a rotina fica com plano vazio.

schedule_kindstringobrigatório

dailyweeklymonthly

Periodicidade.

schedule_dowinteger

Obrigatório em weekly, de 0 a 6.

schedule_dominteger

Obrigatório em monthly, de 1 a 28.

schedule_hourintegerobrigatório

Hora, de 0 a 23.

timezonestring

Fuso IANA. Vazio usa America/Sao_Paulo na criação e mantém o atual na alteração.

require_approvalbooleanpadrão: false

Parar antes do primeiro passo que escreve.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/routines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Relatório matutino",
    "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
    "plan": [
      {
        "tool": "list_orders",
        "params": {
          "limit": 200
        },
        "is_write": false,
        "description": "Listar os pedidos de ontem."
      }
    ],
    "schedule_kind": "daily",
    "schedule_hour": 8,
    "require_approval": true
  }'

Resposta

201Rotina criada

json

{
  "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "name": "Relatório matutino",
  "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
  "plan": [
    { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
  ],
  "schedule_kind": "daily",
  "schedule_dow": null,
  "schedule_dom": null,
  "schedule_hour": 8,
  "timezone": "America/Sao_Paulo",
  "status": "draft",
  "require_approval": true,
  "last_run_at": null
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo ilegível.	`{"error":"invalid request body"}`
400	Agenda inválida ou nome vazio.	`{"error":"weekly routine requires schedule_dow 0..6"}`, `{"error":"monthly routine requires schedule_dom 1..28"}`, `{"error":"schedule_hour must be 0..23"}`, `{"error":"invalid schedule_kind \"x\""}`, `{"error":"name required"}`

Ler uma rotina

Devolve uma rotina com o plano completo.

GET/api/v1/admin/intelligence/routines/{id}Admin

Ler uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotina

json

{
  "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "name": "Relatório matutino",
  "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
  "plan": [
    { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
  ],
  "schedule_kind": "daily",
  "schedule_dow": null,
  "schedule_dom": null,
  "schedule_hour": 8,
  "timezone": "America/Sao_Paulo",
  "status": "draft",
  "require_approval": true,
  "last_run_at": null
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
404	Rotina inexistente.	`{"error":"..."}` (o texto da mensagem não é estável)

Alterar uma rotina

Apesar do método, substitui todos os campos: mande a rotina inteira, como na criação. A rotina volta para draft e precisa ser ativada de novo, para que um plano alterado passe pela revisão do administrador.

PATCH/api/v1/admin/intelligence/routines/{id}Admin

Alterar uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Corpo da requisição

namestringobrigatório

Nome. Obrigatório na criação.

prompt_textstring

Texto original da rotina.

planarray

Passos, no formato devolvido por compile. Sem valor, a rotina fica com plano vazio.

schedule_kindstringobrigatório

dailyweeklymonthly

Periodicidade.

schedule_dowinteger

Obrigatório em weekly, de 0 a 6.

schedule_dominteger

Obrigatório em monthly, de 1 a 28.

schedule_hourintegerobrigatório

Hora, de 0 a 23.

timezonestring

Fuso IANA. Vazio usa America/Sao_Paulo na criação e mantém o atual na alteração.

require_approvalbooleanpadrão: false

Parar antes do primeiro passo que escreve.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Relatório matutino",
    "prompt_text": "Todo dia às 9h, resuma os pedidos de ontem",
    "plan": [
      {
        "tool": "list_orders",
        "params": {
          "limit": 200
        },
        "is_write": false,
        "description": "Listar os pedidos de ontem."
      }
    ],
    "schedule_kind": "daily",
    "schedule_hour": 9,
    "require_approval": true
  }'

Resposta

200Rotina alterada

json

{
  "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "name": "Relatório matutino",
  "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
  "plan": [
    { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
  ],
  "schedule_kind": "daily",
  "schedule_dow": null,
  "schedule_dom": null,
  "schedule_hour": 8,
  "timezone": "America/Sao_Paulo",
  "status": "draft",
  "require_approval": true,
  "last_run_at": null
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Agenda inválida (o nome não é validado na alteração).	`{"error":"weekly routine requires schedule_dow 0..6"}`, `{"error":"monthly routine requires schedule_dom 1..28"}`, `{"error":"schedule_hour must be 0..23"}`, `{"error":"invalid schedule_kind \"x\""}`
400	Rotina inexistente (a rota responde 400, não 404).	`{"error":"..."}` (o texto da mensagem não é estável)

Excluir uma rotina

Exclui a rotina (exclusão lógica): ela deixa de aparecer nas listagens e não roda mais. As execuções passadas ficam guardadas.

DELETE/api/v1/admin/intelligence/routines/{id}Admin

Excluir uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída

json

{ "ok": true }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
500	`id` com formato inválido.	`{"error":"..."}`

Veja também

API atual/Referência completa/Venddor Intelligence: automações e canais

Rotinas agendadas

Cria, lista, lê, altera e exclui as rotinas: tarefas da VI que rodam em horário fixo.

Listar rotinas

Devolve todas as rotinas não excluídas da loja, da mais nova para a mais antiga.

GET/api/v1/admin/intelligence/routinesAdmin

Listar rotinas

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/routines" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotinas

json

{
  "routines": [
    {
      "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "name": "Relatório matutino",
      "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
      "plan": [
        { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
      ],
      "schedule_kind": "daily",
      "schedule_dow": null,
      "schedule_dom": null,
      "schedule_hour": 8,
      "timezone": "America/Sao_Paulo",
      "status": "draft",
      "require_approval": true,
      "last_run_at": null
    }
  ],
  "total": 1
}

Campos da resposta

routinesarray

Rotinas, com os campos abaixo.

iduuid

Id da rotina.

user_iduuid

Administrador que a criou.

namestring

Nome.

prompt_textstring

Texto original, em linguagem natural.

planarray

Passos compilados: tool (identificador do passo), params (objeto), is_write (altera a loja) e description (frase para o administrador).

schedule_kindstring

dailyweeklymonthly

Periodicidade.

schedule_dowinteger

Dia da semana (0 = domingo ... 6 = sábado) em weekly. Nulo nos demais.

schedule_dominteger

Dia do mês (1 a 28) em monthly. Nulo nos demais.

schedule_hourinteger

Hora do dia, 0 a 23, no fuso timezone.

timezonestring

Fuso IANA. Padrão America/Sao_Paulo.

statusstring

draftactivepausedarchived

Estado.

require_approvalboolean

Se a execução para antes do primeiro passo que escreve.

last_run_atstring

RFC 3339 da última execução concluída. Nulo se nunca rodou.

totalinteger

Quantidade devolvida.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`

Criar uma rotina

Grava a rotina como rascunho. Ela só roda sozinha depois de Ativar.

POST/api/v1/admin/intelligence/routinesAdmin

Criar uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

namestringobrigatório

Nome. Obrigatório na criação.

prompt_textstring

Texto original da rotina.

planarray

Passos, no formato devolvido por compile. Sem valor, a rotina fica com plano vazio.

schedule_kindstringobrigatório

dailyweeklymonthly

Periodicidade.

schedule_dowinteger

Obrigatório em weekly, de 0 a 6.

schedule_dominteger

Obrigatório em monthly, de 1 a 28.

schedule_hourintegerobrigatório

Hora, de 0 a 23.

timezonestring

Fuso IANA. Vazio usa America/Sao_Paulo na criação e mantém o atual na alteração.

require_approvalbooleanpadrão: false

Parar antes do primeiro passo que escreve.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/routines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Relatório matutino",
    "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
    "plan": [
      {
        "tool": "list_orders",
        "params": {
          "limit": 200
        },
        "is_write": false,
        "description": "Listar os pedidos de ontem."
      }
    ],
    "schedule_kind": "daily",
    "schedule_hour": 8,
    "require_approval": true
  }'

Resposta

201Rotina criada

json

{
  "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "name": "Relatório matutino",
  "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
  "plan": [
    { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
  ],
  "schedule_kind": "daily",
  "schedule_dow": null,
  "schedule_dom": null,
  "schedule_hour": 8,
  "timezone": "America/Sao_Paulo",
  "status": "draft",
  "require_approval": true,
  "last_run_at": null
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo ilegível.	`{"error":"invalid request body"}`
400	Agenda inválida ou nome vazio.	`{"error":"weekly routine requires schedule_dow 0..6"}`, `{"error":"monthly routine requires schedule_dom 1..28"}`, `{"error":"schedule_hour must be 0..23"}`, `{"error":"invalid schedule_kind \"x\""}`, `{"error":"name required"}`

Ler uma rotina

Devolve uma rotina com o plano completo.

GET/api/v1/admin/intelligence/routines/{id}Admin

Ler uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotina

json

{
  "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "name": "Relatório matutino",
  "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
  "plan": [
    { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
  ],
  "schedule_kind": "daily",
  "schedule_dow": null,
  "schedule_dom": null,
  "schedule_hour": 8,
  "timezone": "America/Sao_Paulo",
  "status": "draft",
  "require_approval": true,
  "last_run_at": null
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
404	Rotina inexistente.	`{"error":"..."}` (o texto da mensagem não é estável)

Alterar uma rotina

PATCH/api/v1/admin/intelligence/routines/{id}Admin

Alterar uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Corpo da requisição

namestringobrigatório

Nome. Obrigatório na criação.

prompt_textstring

Texto original da rotina.

planarray

Passos, no formato devolvido por compile. Sem valor, a rotina fica com plano vazio.

schedule_kindstringobrigatório

dailyweeklymonthly

Periodicidade.

schedule_dowinteger

Obrigatório em weekly, de 0 a 6.

schedule_dominteger

Obrigatório em monthly, de 1 a 28.

schedule_hourintegerobrigatório

Hora, de 0 a 23.

timezonestring

Fuso IANA. Vazio usa America/Sao_Paulo na criação e mantém o atual na alteração.

require_approvalbooleanpadrão: false

Parar antes do primeiro passo que escreve.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Relatório matutino",
    "prompt_text": "Todo dia às 9h, resuma os pedidos de ontem",
    "plan": [
      {
        "tool": "list_orders",
        "params": {
          "limit": 200
        },
        "is_write": false,
        "description": "Listar os pedidos de ontem."
      }
    ],
    "schedule_kind": "daily",
    "schedule_hour": 9,
    "require_approval": true
  }'

Resposta

200Rotina alterada

json

{
  "id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "name": "Relatório matutino",
  "prompt_text": "Todo dia às 8h, resuma os pedidos de ontem",
  "plan": [
    { "tool": "list_orders", "params": { "limit": 200 }, "is_write": false, "description": "Listar os pedidos de ontem." }
  ],
  "schedule_kind": "daily",
  "schedule_dow": null,
  "schedule_dom": null,
  "schedule_hour": 8,
  "timezone": "America/Sao_Paulo",
  "status": "draft",
  "require_approval": true,
  "last_run_at": null
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Agenda inválida (o nome não é validado na alteração).	`{"error":"weekly routine requires schedule_dow 0..6"}`, `{"error":"monthly routine requires schedule_dom 1..28"}`, `{"error":"schedule_hour must be 0..23"}`, `{"error":"invalid schedule_kind \"x\""}`
400	Rotina inexistente (a rota responde 400, não 404).	`{"error":"..."}` (o texto da mensagem não é estável)

Excluir uma rotina

Exclui a rotina (exclusão lógica): ela deixa de aparecer nas listagens e não roda mais. As execuções passadas ficam guardadas.

DELETE/api/v1/admin/intelligence/routines/{id}Admin

Excluir uma rotina

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída

json

{ "ok": true }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
500	`id` com formato inválido.	`{"error":"..."}`