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

Compilar, ativar e executar rotinas

Transforma texto em plano, ativa, pausa, executa uma rotina na hora e lista suas execuções.

Estas cinco rotas cobrem o ciclo depois da criação. compile é independente de qualquer rotina salva; as demais agem sobre uma rotina existente.

Compilar

Interpreta o texto e devolve o plano de passos que a VI executaria, sem salvar nada. Mostre o plano ao administrador antes de criar a rotina. Os passos usam apenas ações que a plataforma permite em rotinas.

POST/api/v1/admin/intelligence/routines/compileAdmin

Compilar texto em plano

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

prompt_textstringobrigatório

O que a rotina deve fazer e quando, em linguagem natural.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/routines/compile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "Todo dia às 8h me mande um resumo dos pedidos de ontem"
  }'

Resposta

200Plano

json

{
  "plan": [
    {
      "tool": "list_orders",
      "params": { "limit": 50 },
      "is_write": false,
      "description": "Listar os pedidos mais recentes para identificar os de ontem."
    },
    {
      "tool": "send_summary",
      "params": { "text": "Resumo diário dos pedidos de ontem." },
      "is_write": false,
      "description": "Enviar ao lojista o resumo dos pedidos."
    }
  ],
  "warnings": []
}

Campos da resposta

planarray

Passos: tool, params, is_write, description.

warningsarray

Avisos de texto sobre o que não pôde ser compilado exatamente.

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	`prompt_text` vazio, corpo ilegível ou texto que não virou um plano válido.	`{"error":"prompt_text required"}` ou `{"error":"compilação inválida: ..."}` (devolvido em português)
503	Nenhum provedor de IA configurado.	`{"error":"provedor de IA não configurado ..."}` (devolvido em português)

Ativar ou retomar

Coloca a rotina em active: a partir daí ela roda no horário. Esta chamada também guarda o seu token para as execuções agendadas: os passos que escrevem na loja rodam depois com as permissões de quem ativou. Uma rotina nova (draft) precisa passar por aqui.

POST/api/v1/admin/intelligence/routines/{id}/resumeAdmin

Ativar ou retomar

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 POST "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/resume" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotina ativa

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": "active",
  "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"]}`
409	Já há 20 rotinas ativas.	`{"error":"intelligence: active routine limit reached (20)..."}`
400	Rotina inexistente.	`{"error":"sql: no rows in result set"}`

Pausar

Coloca a rotina em paused. Não apaga nada e pode ser retomada com resume.

POST/api/v1/admin/intelligence/routines/{id}/pauseAdmin

Pausar 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 POST "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotina pausada

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": "paused",
  "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	Rotina inexistente.	`{"error":"sql: no rows in result set"}`

Rodar agora

Executa a rotina uma vez, na hora, e devolve a execução. Funciona em qualquer estado (inclusive draft) e usa o seu token nos passos que escrevem. Se uma execução anterior ainda está em andamento, devolve uma execução skipped em vez de rodar em paralelo.

POST/api/v1/admin/intelligence/routines/{id}/runAdmin

Rodar agora

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 POST "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/run" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execução

json

{
  "id": "38a64aca-96eb-46bf-a832-ecea000bed08",
  "routine_id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "status": "completed",
  "steps": [
    { "tool": "list_orders", "is_write": false, "status": "ok", "detail": "leitura executada (3541 bytes)" }
  ],
  "summary": "Listar os pedidos de ontem.",
  "error": null,
  "started_at": "2026-10-11T21:07:50.627855Z",
  "finished_at": "2026-10-11T21:07:51.715311Z"
}

Campos da resposta

iduuid

Id da execução.

routine_iduuid

Rotina executada.

statusstring

runningcompletedfailedwaiting_approvalskipped

Resultado da execução.

stepsarray

Passos: tool, is_write, status (ok, skipped, failed ou waiting_approval) e detail.

summarystring

Resumo das ações concluídas.

errorstring

Motivo da falha. Nulo se não falhou.

started_atstring

RFC 3339.

finished_atstring

RFC 3339. Nulo enquanto roda ou em waiting_approval.

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	Rotina inexistente ou falha ao iniciar a execução.	`{"error":"..."}`

Listar execuções

Devolve as execuções da rotina, da mais recente para a mais antiga.

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

Listar execuções

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade. Padrão 50; valores acima de 200 ou menores que 1 voltam para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/runs?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execuções

json

{
  "runs": [
    {
      "id": "38a64aca-96eb-46bf-a832-ecea000bed08",
      "routine_id": "9ed7a252-c085-486a-8d0f-430a828e0681",
      "status": "completed",
      "steps": [
        { "tool": "list_orders", "is_write": false, "status": "ok", "detail": "leitura executada (3541 bytes)" }
      ],
      "summary": "Listar os pedidos de ontem.",
      "error": null,
      "started_at": "2026-10-11T21:07:50.627855Z",
      "finished_at": "2026-10-11T21:07:51.715311Z"
    }
  ],
  "total": 1
}

Campos da resposta

runsarray

Execuções, com os campos abaixo.

iduuid

Id da execução.

routine_iduuid

Rotina executada.

statusstring

runningcompletedfailedwaiting_approvalskipped

Resultado da execução.

stepsarray

Passos: tool, is_write, status (ok, skipped, failed ou waiting_approval) e detail.

summarystring

Resumo das ações concluídas.

errorstring

Motivo da falha. Nulo se não falhou.

started_atstring

RFC 3339.

finished_atstring

RFC 3339. Nulo enquanto roda ou em waiting_approval.

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"]}`
500	`id` com formato inválido.	`{"error":"..."}`

Veja também

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

Compilar, ativar e executar rotinas

Transforma texto em plano, ativa, pausa, executa uma rotina na hora e lista suas execuções.

Estas cinco rotas cobrem o ciclo depois da criação. compile é independente de qualquer rotina salva; as demais agem sobre uma rotina existente.

Compilar

POST/api/v1/admin/intelligence/routines/compileAdmin

Compilar texto em plano

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

prompt_textstringobrigatório

O que a rotina deve fazer e quando, em linguagem natural.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/routines/compile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "Todo dia às 8h me mande um resumo dos pedidos de ontem"
  }'

Resposta

200Plano

json

{
  "plan": [
    {
      "tool": "list_orders",
      "params": { "limit": 50 },
      "is_write": false,
      "description": "Listar os pedidos mais recentes para identificar os de ontem."
    },
    {
      "tool": "send_summary",
      "params": { "text": "Resumo diário dos pedidos de ontem." },
      "is_write": false,
      "description": "Enviar ao lojista o resumo dos pedidos."
    }
  ],
  "warnings": []
}

Campos da resposta

planarray

Passos: tool, params, is_write, description.

warningsarray

Avisos de texto sobre o que não pôde ser compilado exatamente.

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	`prompt_text` vazio, corpo ilegível ou texto que não virou um plano válido.	`{"error":"prompt_text required"}` ou `{"error":"compilação inválida: ..."}` (devolvido em português)
503	Nenhum provedor de IA configurado.	`{"error":"provedor de IA não configurado ..."}` (devolvido em português)

Ativar ou retomar

POST/api/v1/admin/intelligence/routines/{id}/resumeAdmin

Ativar ou retomar

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 POST "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/resume" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotina ativa

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": "active",
  "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"]}`
409	Já há 20 rotinas ativas.	`{"error":"intelligence: active routine limit reached (20)..."}`
400	Rotina inexistente.	`{"error":"sql: no rows in result set"}`

Pausar

Coloca a rotina em paused. Não apaga nada e pode ser retomada com resume.

POST/api/v1/admin/intelligence/routines/{id}/pauseAdmin

Pausar 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 POST "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/pause" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Rotina pausada

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": "paused",
  "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	Rotina inexistente.	`{"error":"sql: no rows in result set"}`

Rodar agora

POST/api/v1/admin/intelligence/routines/{id}/runAdmin

Rodar agora

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 POST "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/run" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execução

json

{
  "id": "38a64aca-96eb-46bf-a832-ecea000bed08",
  "routine_id": "9ed7a252-c085-486a-8d0f-430a828e0681",
  "status": "completed",
  "steps": [
    { "tool": "list_orders", "is_write": false, "status": "ok", "detail": "leitura executada (3541 bytes)" }
  ],
  "summary": "Listar os pedidos de ontem.",
  "error": null,
  "started_at": "2026-10-11T21:07:50.627855Z",
  "finished_at": "2026-10-11T21:07:51.715311Z"
}

Campos da resposta

iduuid

Id da execução.

routine_iduuid

Rotina executada.

statusstring

runningcompletedfailedwaiting_approvalskipped

Resultado da execução.

stepsarray

Passos: tool, is_write, status (ok, skipped, failed ou waiting_approval) e detail.

summarystring

Resumo das ações concluídas.

errorstring

Motivo da falha. Nulo se não falhou.

started_atstring

RFC 3339.

finished_atstring

RFC 3339. Nulo enquanto roda ou em waiting_approval.

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	Rotina inexistente ou falha ao iniciar a execução.	`{"error":"..."}`

Listar execuções

Devolve as execuções da rotina, da mais recente para a mais antiga.

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

Listar execuções

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da rotina.

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade. Padrão 50; valores acima de 200 ou menores que 1 voltam para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/routines/$ROUTINE_ID/runs?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execuções

json

{
  "runs": [
    {
      "id": "38a64aca-96eb-46bf-a832-ecea000bed08",
      "routine_id": "9ed7a252-c085-486a-8d0f-430a828e0681",
      "status": "completed",
      "steps": [
        { "tool": "list_orders", "is_write": false, "status": "ok", "detail": "leitura executada (3541 bytes)" }
      ],
      "summary": "Listar os pedidos de ontem.",
      "error": null,
      "started_at": "2026-10-11T21:07:50.627855Z",
      "finished_at": "2026-10-11T21:07:51.715311Z"
    }
  ],
  "total": 1
}

Campos da resposta

runsarray

Execuções, com os campos abaixo.

iduuid

Id da execução.

routine_iduuid

Rotina executada.

statusstring

runningcompletedfailedwaiting_approvalskipped

Resultado da execução.

stepsarray

Passos: tool, is_write, status (ok, skipped, failed ou waiting_approval) e detail.

summarystring

Resumo das ações concluídas.

errorstring

Motivo da falha. Nulo se não falhou.

started_atstring

RFC 3339.

finished_atstring

RFC 3339. Nulo enquanto roda ou em waiting_approval.

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"]}`
500	`id` com formato inválido.	`{"error":"..."}`