> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metricaas.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cria um fluxo completo (e, se pedido, publica)

> Exige `automations:manage`, um token `write` e o plano com automações. Numa
chamada só, faz o que a tela faz em seis passos: cria o fluxo no funil, dá o
nome, salva o desenho (com a mesma validação do editor), aplica a janela e o
teto, liga os posts e, com `publicar: true`, publica — e publicar **liga**: as
mensagens passam a sair para quem entrar a partir de agora.

**Comentário precisa de post (ou de `ligar_auto`) para publicar.** Um fluxo com o
gatilho "comentaram no post" (`comentou`) e nenhum post ligado responde a
**todos** os posts da conta. Por isso, com `publicar: true`, ele exige ao menos um
item em `posts` ou a regra `ligar_auto` — sem nenhum dos dois, `422` em `posts`
e nada é criado. Com `ligar_auto` e sem post, o fluxo espera o primeiro post novo
que bater a regra (não vale para todos).

**O gatilho `comentou` (ADR 0080)** aceita no `config`: `filtro`
(`qualquer` ou `data`; ausente = pelo `contem`/`exata`), `uma_entrada_horas`
(0 a 720; a mesma pessoa no mesmo post não entra de novo dentro da janela) e
`responder_repetidos` (o repetido ainda ganha a resposta pública). A peça
`esperar_resposta` aceita `aceita`: `botao` (padrão, pelo `contem`) ou
`qualquer` (a primeira mensagem de texto acorda e vira `{{resposta}}`).

**Idempotente pelo nome:** se esta empresa já tem um fluxo criado pela API com
o mesmo `nome`, a resposta é `409` com o `id` dele e nada é criado nem ligado.
Não precisa de `Idempotency-Key`. Um fluxo criado na tela com o mesmo nome não
conta.

**Nunca sobra fluxo pela metade:** se qualquer passo falhar (o grafo, o funil,
a validação de publicar), o que foi criado no caminho é desfeito.

`veredito` volta sempre: é a lista do que impede (ou só avisa) publicar,
a mesma da tela.




## OpenAPI

````yaml /openapi.yaml post /fluxos
openapi: 3.1.0
info:
  title: Metricaas API
  version: 1.0.0
  description: >
    API do Metricaas para automatizar o CRM de fora dele — registrar vendas de
    uma

    plataforma de pagamento, ler leads e conferir a atribuição de origem.


    **Base:** `https://app.metricaas.com.br/v1`


    Todo endpoint é server-to-server. Não há CORS: um token de API nunca deve ir

    para o navegador.
servers:
  - url: https://app.metricaas.com.br/v1
security:
  - bearerAuth: []
tags:
  - name: Sessão
  - name: Leads
  - name: Vendas
  - name: Atendimento
  - name: Agente de IA
    description: |
      Ler a conversa, responder ao lead e pedir um humano — para um agente de IA
      (no n8n, por exemplo) atender pelo número da empresa sem sair do
      MetricaaS. A mensagem do agente aparece no inbox com selo próprio, não
      assume a conversa e não conta como primeira resposta do time.

      Gere o token em **Configurações → Tokens de API** com a finalidade
      **"Agente de atendimento"**: ele só conversa (`inbox:view` e
      `inbox:operate`). O texto do lead vai para um modelo de linguagem, e um
      modelo pode ser manipulado pela própria mensagem — o token não pode
      permitir nada além de conversar.

      **Este token é do seu servidor (o n8n), não do modelo.** Nunca o entregue
      ao modelo de IA como ferramenta: uma mensagem do lead poderia mandar o
      modelo ler outras conversas.
  - name: Comentários
    description: >
      Os comentários dos posts do Instagram e a resposta EM PÚBLICO, como a
      conta

      da empresa — a mesma fila da caixa de comentários. Uso típico: o webhook

      `comment.received` chega, um agente escreve a resposta, uma pessoa aprova,
      e

      o seu servidor publica por `POST
      /v1/comentarios/{comentario_id}/respostas`.
  - name: Fluxos
    description: >
      Criar um fluxo completo e ligar um post do Instagram a um fluxo de

      comentário — a ponte para quem publica o post fora do MetricaaS (o Estúdio

      do Horus, ou um motor de Reels) e quer que o fluxo certo responda a quem

      comentar nele.


      Gere o token em **Configurações → Tokens de API** com a finalidade

      **"Acesso completo do papel"** e o modo de **escrita**, herdando alguém
      que pode montar

      fluxos (`automations:manage`).
  - name: Configuração do CRM
    description: |
      Funis, etapas, tags e campos personalizados — para montar a operação por
      script (ex.: o funil "Infoproduto": Comentou → Abriu material → Lead →
      Clicou comprar → Comprou → Entregue → Cliente recorrente · Perdido).

      **Criar é idempotente pelo nome** (no campo, pela chave): repetir o
      script devolve `200` com `criado: false` e não duplica nada. O que já
      existe com **outro tipo** é `409`, e nada muda. Renomear, reordenar o que
      existe e remover ficam na tela. Ler pede a tela correspondente (Funil,
      Leads); criar pede `funnel:config`.
paths:
  /fluxos:
    post:
      tags:
        - Fluxos
      summary: Cria um fluxo completo (e, se pedido, publica)
      description: >
        Exige `automations:manage`, um token `write` e o plano com automações.
        Numa

        chamada só, faz o que a tela faz em seis passos: cria o fluxo no funil,
        dá o

        nome, salva o desenho (com a mesma validação do editor), aplica a janela
        e o

        teto, liga os posts e, com `publicar: true`, publica — e publicar
        **liga**: as

        mensagens passam a sair para quem entrar a partir de agora.


        **Comentário precisa de post (ou de `ligar_auto`) para publicar.** Um
        fluxo com o

        gatilho "comentaram no post" (`comentou`) e nenhum post ligado responde
        a

        **todos** os posts da conta. Por isso, com `publicar: true`, ele exige
        ao menos um

        item em `posts` ou a regra `ligar_auto` — sem nenhum dos dois, `422` em
        `posts`

        e nada é criado. Com `ligar_auto` e sem post, o fluxo espera o primeiro
        post novo

        que bater a regra (não vale para todos).


        **O gatilho `comentou` (ADR 0080)** aceita no `config`: `filtro`

        (`qualquer` ou `data`; ausente = pelo `contem`/`exata`),
        `uma_entrada_horas`

        (0 a 720; a mesma pessoa no mesmo post não entra de novo dentro da
        janela) e

        `responder_repetidos` (o repetido ainda ganha a resposta pública). A
        peça

        `esperar_resposta` aceita `aceita`: `botao` (padrão, pelo `contem`) ou

        `qualquer` (a primeira mensagem de texto acorda e vira `{{resposta}}`).


        **Idempotente pelo nome:** se esta empresa já tem um fluxo criado pela
        API com

        o mesmo `nome`, a resposta é `409` com o `id` dele e nada é criado nem
        ligado.

        Não precisa de `Idempotency-Key`. Um fluxo criado na tela com o mesmo
        nome não

        conta.


        **Nunca sobra fluxo pela metade:** se qualquer passo falhar (o grafo, o
        funil,

        a validação de publicar), o que foi criado no caminho é desfeito.


        `veredito` volta sempre: é a lista do que impede (ou só avisa) publicar,

        a mesma da tela.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - nome
                - grafo
              properties:
                nome:
                  type: string
                  maxLength: 80
                  description: Espaços repetidos viram um. É a chave da idempotência.
                pipeline_id:
                  type: string
                  format: uuid
                  description: >-
                    O funil. Omitido, vale o principal da empresa (o primeiro da
                    lista).
                grafo:
                  type: object
                  required:
                    - nos
                    - arestas
                  description: >-
                    O desenho do fluxo, no formato do editor (até 60 peças e 120
                    ligações).
                  properties:
                    nos:
                      type: array
                      items:
                        type: object
                        required:
                          - key
                          - kind
                          - type
                        properties:
                          key:
                            type: string
                            pattern: ^[a-zA-Z0-9_-]{1,40}$
                          kind:
                            type: string
                            enum:
                              - trigger
                              - action
                              - condition
                              - wait
                              - exit
                          type:
                            type: string
                            example: comentou
                          config:
                            type: object
                            description: >-
                              A configuração da peça, a mesma do editor. Nas
                              mensagens para a pessoa (`send_message`,
                              `dm_instagram`, `responder_comentario` e os dois
                              textos do `portao_seguidor`), o `texto` aceita
                              variações separadas por uma linha com só `---` (no
                              JSON, `"Oi!\n---\nOlá!"`): cada pessoa recebe uma,
                              sempre a mesma.
                          x:
                            type: integer
                          'y':
                            type: integer
                    arestas:
                      type: array
                      items:
                        type: object
                        required:
                          - from
                          - to
                        properties:
                          from:
                            type: string
                          port:
                            type: string
                            default: out
                          to:
                            type: string
                ajustes:
                  type: object
                  required:
                    - send_window
                    - max_steps
                  properties:
                    send_window:
                      type: string
                      example: 08:00-20:00
                      description: HH:MM-HH:MM, horário de Brasília.
                    max_steps:
                      type: integer
                      minimum: 1
                      maximum: 200
                      description: Passos por lead por dia.
                posts:
                  type: array
                  maxItems: 20
                  description: >-
                    Ids de mídia da Graph, **como string** (com 17 dígitos ou
                    mais o número perde precisão). Só em fluxo com `comentou`.
                  items:
                    type: string
                    pattern: ^[0-9]{1,64}$
                ligar_auto:
                  $ref: '#/components/schemas/LigarAuto'
                publicar:
                  type: boolean
                  default: false
            example:
              nome: Reel 42 · link do material
              grafo:
                nos:
                  - key: g
                    kind: trigger
                    type: comentou
                    config:
                      contem: quero
                  - key: dm
                    kind: action
                    type: dm_instagram
                    config:
                      texto: Oi! Aqui está o link.
                arestas:
                  - from: g
                    port: out
                    to: dm
              ajustes:
                send_window: 00:00-23:59
                max_steps: 20
              posts:
                - '17895695668004550'
              publicar: true
      responses:
        '201':
          description: Criado (rascunho, ou publicado e ligado)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FluxoCriado'
        '401':
          $ref: '#/components/responses/NaoAutenticado'
        '403':
          $ref: '#/components/responses/SemPermissao'
        '409':
          description: >-
            Já existe um fluxo criado pela API com este nome nesta empresa. Nada
            foi criado.
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Problema'
                  - type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: O fluxo que já existe.
        '422':
          description: >
            Campo inválido (todos voltam juntos em `errors[]`), comentário sem
            post com

            `publicar: true` (`field = "posts"`), funil de outra empresa

            (`field = "pipeline_id"`), grafo inválido (`field = "grafo"`) ou
            publicar

            recusado — neste caso o corpo leva também o `veredito`. Em nenhum
            deles sobra

            fluxo.
          content:
            application/problem+json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Problema'
                  - type: object
                    properties:
                      veredito:
                        $ref: '#/components/schemas/Veredito'
components:
  schemas:
    LigarAuto:
      type: object
      description: >
        Ligar post automático (ADR 0080): liga sozinho, a este fluxo, os posts
        **novos** da

        conta (publicados depois de a regra ser ligada). Uma das duas regras:

        `legenda_contem` (a legenda tem um termo que começa com isto) ou

        `todo_reels_novo: true`. `codigo_prefixo` (opcional) escolhe o
        `{{post.codigo}}`:

        o 1º termo da legenda que começa com ele; sem ele, o termo que bateu,
        sem o `#`.
      properties:
        legenda_contem:
          type: string
          example: '#mcn-desenho'
          maxLength: 60
        todo_reels_novo:
          type: boolean
          enum:
            - true
        codigo_prefixo:
          type: string
          example: '#mcn-'
          maxLength: 60
    FluxoCriado:
      type: object
      properties:
        id:
          type: string
          format: uuid
        nome:
          type: string
        versao:
          type: integer
          description: A versão publicada
          ou a do rascunho quando não publicou.: null
        status:
          type: string
          enum:
            - draft
            - active
          description: '`active` = publicado e ligado.'
        veredito:
          $ref: '#/components/schemas/Veredito'
        vale_para:
          type:
            - string
            - 'null'
          enum:
            - todos
            - ligados
            - null
          description: >-
            Só em fluxo com o gatilho `comentou`. `todos` = nenhum post ligado
            (só possível em rascunho).
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PostLigado'
    Problema:
      type: object
      description: Erros seguem RFC 7807.
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    Veredito:
      type: object
      description: O que a validação de publicar achou — a mesma lista da tela.
      properties:
        pode_publicar:
          type: boolean
        achados:
          type: array
          items:
            type: object
            properties:
              gravidade:
                type: string
                enum:
                  - trava
                  - avisa
                description: '`trava` impede publicar; `avisa` só avisa.'
              node_key:
                type:
                  - string
                  - 'null'
                description: A peça do problema
                quando é de uma peça.: null
              texto:
                type: string
    PostLigado:
      type: object
      properties:
        media_id:
          type: string
          example: '17895695668004550'
        criado_em:
          type: string
          format: date-time
        criado_por:
          type: string
          enum:
            - user
            - api_token
            - ligar_auto
          description: >-
            `user` = ligado pela tela do fluxo; `api_token` = pela API ou pelo
            MCP; `ligar_auto` = ligado sozinho pela regra do fluxo (ADR 0080).
        codigo:
          type: string
          nullable: true
          description: >-
            O código achado na legenda (`{{post.codigo}}`). Só o ligar
            automático grava.
  responses:
    NaoAutenticado:
      description: Token ausente, inválido, expirado ou revogado
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problema'
    SemPermissao:
      description: O token não tem a capacidade exigida, ou é de leitura
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problema'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        `Authorization: Bearer mcp_…` — gere em **Configurações → Tokens de
        API**.


        O token de API tem modo `read` ou `write`. Um token `read` responde
        `403`

        a qualquer verbo que não seja `GET`. As capacidades do token são a

        **interseção** com as da pessoa de quem ele herda o papel: se ela perder

        acesso na grade de Equipe, o token perde junto, sem ninguém revogar
        nada.


        **Token de agência** (gerado no console da agência): vale para as

        empresas da agência, e a empresa de cada chamada vai no header

        **`X-Empresa: <slug da empresa>`**. Sem o header, `401`. Num token de

        empresa o header é opcional e, se vier, tem de ser a própria empresa. O

        modo `read` vale igual: um token de agência de leitura só faz `GET` —

        é o token para pôr numa função que só consulta.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.