Iniciar Execução de Playbook
POST/external/v1/playbooks/:id/runsInicia 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Identificador do playbook (UUID) |
Corpo da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contact_id | string | Não* | Contato de que trata a execução |
opportunity_id | string | Não* | Oportunidade de que trata a execução. O contato dela vem junto, e o responsável dela recebe as etapas owner |
conversation_id | string | Não* | Conversa vinculada à execução. Também é usada para descobrir quem atende o contato quando a oportunidade não tem responsável |
title | string | Não* | Título da execução (máx. 255). Obrigatório numa execução interna (sem contato, oportunidade nem conversa) |
start_date | string (ISO 8601) | Não | Quando a execução começa. O padrão é agora; uma data no passado deixa as primeiras etapas atrasadas na hora |
skip_weekends | boolean | Não | Prazos 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 |
timezone | string | Não | Fuso 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
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"
}'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);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.
{
"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
| Status | Código | Descrição |
|---|---|---|
| 400 | VALIDATION_ERROR | Nenhum 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 |
| 403 | INSUFFICIENT_PERMISSIONS | A chave não tem playbooks:run |
| 404 | NOT_FOUND | Playbook não encontrado, ou não visível para o criador da chave |