Skip to content

Iniciar Execução de Playbook ​

POST /external/v1/playbooks/:id/runs

Inicia um playbook: cria uma execução e uma tarefa por etapa, com prazos encadeados a partir de start_date e responsáveis conforme configurado em cada etapa. É a mesma operação de Iniciar playbook no app, e os responsáveis são notificados da mesma forma.

Autenticação ​

Requer permissão playbooks:run. O playbook precisa estar ativo e visível para o usuário que criou a chave. A execução é iniciada por esse usuário.

Retentativas seguras

Envie um header Idempotency-Key para que uma retentativa não inicie o playbook duas vezes. Veja Idempotência.

Parâmetros de Caminho ​

ParâmetroTipoObrigatórioDescrição
idstringSimIdentificador do playbook (UUID)

Corpo da Requisição ​

CampoTipoObrigatórioDescrição
contact_idstringNão*Contato de que trata a execução
opportunity_idstringNão*Oportunidade de que trata a execução. O contato dela vem junto, e o responsável dela recebe as etapas owner
conversation_idstringNão*Conversa vinculada à execução. Também é usada para descobrir quem atende o contato quando a oportunidade não tem responsável
titlestringNão*Título da execução (máx. 255). Obrigatório numa execução interna (sem contato, oportunidade nem conversa)
start_datestring (ISO 8601)NãoQuando a execução começa. O padrão é agora; uma data no passado deixa as primeiras etapas atrasadas na hora
skip_weekendsbooleanNãoPrazos que caem no sábado ou no domingo passam para segunda-feira, no mesmo horário. As etapas seguintes contam a partir da data movida
timezonestringNãoFuso horário IANA que define o que é "sábado" para skip_weekends, por exemplo America/Sao_Paulo. O padrão é o fuso horário do criador da chave e, depois, UTC

* Envie pelo menos um entre contact_id, opportunity_id, conversation_id ou title. Quando mais de um é enviado, todos precisam apontar para o mesmo contato.

Quem recebe cada tarefa vem da configuração do playbook (veja Buscar Playbook); não dá para sobrescrever isso por execução.

Requisição ​

bash
curl --request POST \
  --url "https://app.getraze.com/external/v1/playbooks/9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62/runs" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Idempotency-Key: deal-won-e8a3b2c1" \
  --data '{
    "opportunity_id": "e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34",
    "skip_weekends": true,
    "timezone": "America/Sao_Paulo"
  }'
javascript
const axios = require('axios');

const playbookId = '9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62';

const response = await axios.post(
  `https://app.getraze.com/external/v1/playbooks/${playbookId}/runs`,
  {
    opportunity_id: 'e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34',
    skip_weekends: true,
    timezone: 'America/Sao_Paulo'
  },
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Idempotency-Key': 'deal-won-e8a3b2c1'
    }
  }
);

console.log(response.data);
python
import requests

playbook_id = '9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62'

response = requests.post(
    f'https://app.getraze.com/external/v1/playbooks/{playbook_id}/runs',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Idempotency-Key': 'deal-won-e8a3b2c1'
    },
    json={
        'opportunity_id': 'e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34',
        'skip_weekends': True,
        'timezone': 'America/Sao_Paulo'
    }
)

print(response.json())

Resposta ​

201 Created com a execução, no formato de Buscar Execução de Playbook. Cada etapa traz o task_id da tarefa que criou.

json
{
  "success": true,
  "data": {
    "id": "3ef8c1c3-c081-4187-a6aa-657fbf1a813b",
    "playbook": { "id": "9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62", "name": "Onboarding" },
    "status": "in_progress",
    "context": {
      "type": "contact",
      "name": "John Doe",
      "contact": { "id": "c2f9d1a4-5b7e-4c1a-9e0f-3a8b6d2c4e71", "name": "John Doe", "company": "Acme Inc" },
      "opportunity": { "id": "e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34", "title": "Acme Inc - Plano Pro" },
      "conversation_id": null
    },
    "progress": { "steps_done": 0, "steps_total": 3, "overdue_steps": 0 },
    "steps": [
      { "position": 1, "task_id": "97f785b0-d1ce-4a2b-8142-89c2fb88d501", "title": "Ligação de boas-vindas", "status": "pending", "due_date": "2026-10-23T22:00:00.000Z", "assignees": [{ "id": "2d19889d-6ff9-4782-8165-32e56bb593c0", "name": "Maria Silva" }] },
      { "position": 2, "task_id": "a8e9f0b1-c2d3-4e5f-8a9b-0c1d2e3f4a5b", "title": "Enviar o kit de onboarding", "status": "pending", "due_date": "2026-10-26T22:00:00.000Z", "assignees": [] }
    ]
  }
}

Erros ​

StatusCódigoDescrição
400VALIDATION_ERRORNenhum contato, oportunidade, conversa ou título; ids que não são desta conta ou que apontam para contatos diferentes; start_date ou timezone inválido; o playbook está inativo ou não tem etapas
403INSUFFICIENT_PERMISSIONSA chave não tem playbooks:run
404NOT_FOUNDPlaybook não encontrado, ou não visível para o criador da chave

GetRaze - AI-Powered Lead Generation