---
title: "Adicionar passo"
method: POST
path: "/v1/tours/{id}/steps"
---

# Adicionar passo

`POST /v1/tours/{id}/steps`

## Request

- Base URL: `https://app.guiaflow.pro`
- URL: `https://app.guiaflow.pro/v1/tours/{id}/steps`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `title` string: Título do balão.
  - `text` string: Texto do balão (curto, 1–2 frases).
  - `label` string: Nome do passo na lista do editor (padrão: o título).
  - `narrationScript` string: Roteiro da narração/legenda deste passo (opcional).
  - `alt` string: Texto alternativo da captura para leitor de tela (WCAG 1.1.1). Vazio: o player usa título + texto do balão.
  - `altDecorative` boolean: true = captura decorativa (alt vazio). Use só quando a imagem não traz informação.
  - `type` 'screen' | 'slide': screen = captura com destaque (padrão); slide = cartão de texto sem imagem.
  - `scene` integer: Cena (agrupa passos no editor).
  - `highlight` object: Retângulo do destaque em fração da imagem (0..1): x,y = canto superior esquerdo; width,height = tamanho. Ex.: botão em (0.62, 0.08) com 0.12×0.05.
    - `x` number, required
    - `y` number, required
    - `width` number, required
    - `height` number, required
  - `click` object: Ponto do clique em fração da imagem (0..1). Fica sempre dentro do destaque (é ajustado se cair fora). Só com click (sem highlight) o destaque vira 14%×8% em volta.
    - `x` number, required
    - `y` number, required
  - `popoverSide` 'top' | 'bottom' | 'left' | 'right' | 'over': Lado do balão em relação ao destaque.
  - `popoverAlign` 'start' | 'center' | 'end'
  - `simulateClick` boolean: Mostra a animação de clique no player (padrão true).
  - `position` integer: Índice onde inserir/mover (0 = primeiro). Padrão: no fim.
  - `image` object: A captura de tela: exatamente um de mediaId (de upload_media), url (https pública) ou base64 (PNG/JPEG/WebP/GIF, até 15 MB). Prefira upload_media + mediaId para arquivos locais.
    - `mediaId` string: sha256 devolvido por upload_media.
    - `url` string: URL https pública da imagem.
    - `base64` string: Imagem em base64 (ou data:image/...;base64,...).
    - `name` string: Nome do arquivo (opcional).

## Response `201`

Criado

- object
  - `ok` true

## Other responses

- `400`: Erro
- `401`: Erro
- `402`: Erro
- `403`: Erro
- `404`: Erro
- `429`: Erro

---

[API](https://skmtc.dev/guiaflow/apis/guiaflow-api.md) · [All operations](https://skmtc.dev/guiaflow/apis/guiaflow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/guiaflow/apis/guiaflow-api/revisions/1405464b8a2a?raw)