O quadro de ações: as etapas do funil com o trabalho dentro

GET

/v1/t/{tenantID}/plano/acoes

curl --request GET \
  --url https://dash.owiew.com/v1/t/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/plano/acoes \
  --header 'Authorization: Bearer <token>'

• Produção

As etapas do funil desenhado, em ordem, cada uma com o vocabulário declarado e as ações de marketing penduradas nela.

O eixo das colunas é a ETAPA, e não o estado do trabalho. É a diferença entre este quadro e o de tarefas: aqui o cliente redesenha as colunas quando redesenha o funil, e o estado (ideia/aprovado/rodando) é um selo dentro do cartão.

Nada aqui tem dinheiro. A ação é DECLARAÇÃO de trabalho a fazer; o gasto por etapa está em /plano/funil, e os dois não se somam nem se conferem — uma ação rodando pode não ter um real marcado.

Ordene as etapas por ordem e as ações por posicao; a ordem do array não é contrato.

Exige a permissão plano.read.

Authorizations

• tokenDeAcesso

Parameters

Path Parameters

tenantID

required

string format: uuid

O cliente. Vem SEMPRE do caminho — nunca de cabeçalho, nunca de cookie. Ele é conferido contra o token: um identificador que não bata com o do token devolve 403, e não uma resposta vazia.

Responses

200

OK

Media typeapplication/json

O quadro completo. Uma etapa sem ação continua vindo, porque ela continua sendo uma coluna do quadro — omiti-la faria a tela desenhar um funil com um buraco no meio.

object

etapas

Array<object>

nullable

Uma etapa do funil desenhado, com o que o cliente declarou sobre ela e as ações penduradas nela.

Apagar uma etapa que tem ação responde 409 ETAPA_COM_ACOES e não apaga nada. É ON DELETE RESTRICT de propósito: cascata sumiria com cartões em silêncio ao tirar uma caixa do desenho do funil. O caminho é mover ou apagar as ações primeiro.

object

id

string format: uuid

nome

string

ordem

A posição da etapa no funil, do topo para o fundo. Ordene por ela — a ordem do array não é contrato.

integer

verbo

O que a etapa FAZ com quem passa por ela, em texto livre até 40 caracteres («Atrair tutores»). Vazio = não declarado.

Os três campos declarados se gravam JUNTOS, e vazio APAGA: PUT /plano/etapas/{id} é substituição, não remendo.

string

objetivo

O resultado que a etapa persegue, em texto livre até 300 caracteres. Vazio = não declarado.

string

metrica

A métrica que o cliente DECLARA perseguir na etapa, em texto livre até 120 caracteres. Ela pode não existir na coleta — não a case com um campo de analytics sem conferir. Vazio = não declarado.

string

acoes

As ações desta etapa. Vem null quando não há nenhuma — e null aqui significa exatamente «nenhuma», nunca «não consegui ler».

Array<object>

nullable

Uma ação de marketing DECLARADA por uma pessoa e pendurada numa etapa do funil. Ela não tem gasto associado e não sai de plataforma nenhuma: é o trabalho que o cliente combinou fazer dentro daquela etapa.

object

id

string format: uuid

etapa_id

A etapa do funil onde ela está. É o eixo das COLUNAS do quadro — e não o estado do trabalho, que é status.

string format: uuid

titulo

Até 120 caracteres.

string

descricao

Até 1.200 caracteres. Pode vir vazia.

string

canal

O canal de EXECUÇÃO da ação, em texto livre até 60 caracteres — Instagram, WhatsApp, Kommo Salesbot, n8n + WhatsApp.

Não confunda com o canal de plano.marcacao, que é um enum de sete redes de anúncio e serve para conciliar gasto. Este aqui não concilia nada: metade dos valores reais não é rede de mídia.

string

unidade_de_negocio

A unidade FÍSICA ou comercial do cliente a que a ação se aplica (uma loja, uma filial, uma casa), em texto livre até 60 caracteres. Vazio significa «todas».

Não confunda com a unidade de ATRIBUIÇÃO — campanha, conjunto ou anúncio — das rotas de relatório. São dois sentidos da mesma palavra, e é por isso que o campo tem este nome comprido.

Ela NÃO reparte gasto: para um cliente com campanha unificada, investimento por unidade não existe, e declarar a intenção («quero trazer hóspede para a Serra») nunca vira rateio do realizado.

string

status

Em que pé a ação está. Não são os estados do quadro de tarefas (aberta/fazendo/feita/arquivada): lá o eixo das colunas é o estado; aqui o eixo é a etapa, e o estado é um selo dentro do cartão.

string

Allowed values: ideia aprovado rodando

posicao

A ordem dentro da coluna. É ponto flutuante DE PROPÓSITO: mover é gravar a média entre os dois vizinhos, o que escreve uma linha em vez de renumerar a coluna inteira. Não presuma que seja inteiro, nem que seja contíguo, nem que comece em zero — ordene por ele e ignore o valor.

number format: double

campos

Valores dos CAMPOS PERSONALIZADOS da ação (ADR-0040): {<id da definição>: valor}, sempre objeto (vazio quando não há nenhum). Escrita é mescla: chave presente troca, null apaga, ausente não toca. As definições vêm de GET /campos-personalizados.

object

key

additional properties

any

Example

{
  "etapas": [
    {
      "acoes": [
        {
          "status": "ideia"
        }
      ]
    }
  ]
}

401

Token ausente, malformado ou vencido.

Media typeapplication/json

object

error

object

code

Código estável, seguro para comparar.

string

message

Texto para pessoa. Pode mudar entre versões — não decida nada a partir dele.

string

trace_id

Identificador da ocorrência. Cite-o ao pedir suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "trace_id": "example"
  }
}

403

O token é válido, e o escopo não. Ou ele foi emitido para outro cliente, ou o papel não inclui a permissão da rota. NÃO é 404 de propósito: esconder um erro de escopo atrás de ‘não encontrado’ faz quem integra procurar o problema no lugar errado.

Media typeapplication/json

object

error

object

code

Código estável, seguro para comparar.

string

message

Texto para pessoa. Pode mudar entre versões — não decida nada a partir dele.

string

trace_id

Identificador da ocorrência. Cite-o ao pedir suporte.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "trace_id": "example"
  }
}