Ir para o conteúdo
Pipefácil

Substituir automação

Ver como MarkdownConfigurar agente
PUT/api/v1/automations/{id}

Substitui toda a definição. Campos ausentes são redefinidos, as ações recebem novos identificadores e version é incrementada. A exceção é enabled: omitir preserva o estado atual. Para alterar somente o estado, use PATCH /{id}/enabled. Exige automations.edit.

Exemplos

A URL usa o servidor de produção. Defina PIPEFACIL_API_KEY e as variáveis de caminho (como SEQ ou ID) com os identificadores reais. Ajuste o corpo antes de executar: requisições de escrita alteram dados do workspace.

cURL

curl --request PUT \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/automations/$ID" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Fluxo manual de exemplo",
  "triggerType": "manual",
  "scope": "global",
  "enabled": false,
  "graphDefinition": {
    "version": 2,
    "nodes": [
      {
        "id": "inicio",
        "type": "trigger"
      },
      {
        "id": "fim",
        "type": "end"
      }
    ],
    "edges": [
      {
        "id": "inicio-fim",
        "source": "inicio",
        "target": "fim",
        "sourceHandle": "next"
      }
    ]
  }
}'
JavaScript
const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/automations/${process.env.ID}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Fluxo manual de exemplo",
  "triggerType": "manual",
  "scope": "global",
  "enabled": false,
  "graphDefinition": {
    "version": 2,
    "nodes": [
      {
        "id": "inicio",
        "type": "trigger"
      },
      {
        "id": "fim",
        "type": "end"
      }
    ],
    "edges": [
      {
        "id": "inicio-fim",
        "source": "inicio",
        "target": "fim",
        "sourceHandle": "next"
      }
    ]
  }
}),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const text = await response.text();
const data = text ? JSON.parse(text) : null;
Python
import os
import json
import requests

response = requests.request(
    "PUT",
    f"https://pipefacil-server.matchsales.com.br/api/v1/automations/{os.environ['ID']}",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"name\": \"Fluxo manual de exemplo\",\n  \"triggerType\": \"manual\",\n  \"scope\": \"global\",\n  \"enabled\": false,\n  \"graphDefinition\": {\n    \"version\": 2,\n    \"nodes\": [\n      {\n        \"id\": \"inicio\",\n        \"type\": \"trigger\"\n      },\n      {\n        \"id\": \"fim\",\n        \"type\": \"end\"\n      }\n    ],\n    \"edges\": [\n      {\n        \"id\": \"inicio-fim\",\n        \"source\": \"inicio\",\n        \"target\": \"fim\",\n        \"sourceHandle\": \"next\"\n      }\n    ]\n  }\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Parâmetros

NomeLocalTipoObrigatórioDescrição
idpathstringSimIdentificador da automação.

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "name": "Fluxo manual de exemplo",
  "triggerType": "manual",
  "scope": "global",
  "enabled": false,
  "graphDefinition": {
    "version": 2,
    "nodes": [
      {
        "id": "inicio",
        "type": "trigger"
      },
      {
        "id": "fim",
        "type": "end"
      }
    ],
    "edges": [
      {
        "id": "inicio-fim",
        "source": "inicio",
        "target": "fim",
        "sourceHandle": "next"
      }
    ]
  }
}
CampoTipoObrigatório no objetoDescrição
namestringSimAté 255 caracteres.
triggerTypestringSimUm dos valores de GET /api/v1/automations/triggers. Valores: deal_created, deal_stage_changed, deal_won, deal_lost, deal_assigned, message_received, conversation_closed, contact_no_reply, team_no_reply, field_filled, timer, instagram_comment_received, manual, webhook.
scopestringSimValores: global, pipeline, stage.
pipelineIdstringNãoAceita null.
stageIdstringNãoAceita null.
outboundChannelIdstringNãoNão existe rota pública para listar canais; obtenha o identificador por outro meio. Aceita null.
graphDefinitionAutomationGraphNãoGrafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto.
graphDefinition.versionintegerSimValores: 2.
graphDefinition.nodesarraySim—
graphDefinition.nodes[].idstringSim—
graphDefinition.nodes[].typestringSimValores: trigger, action, condition, wait, round_robin, end.
graphDefinition.nodes[].actionTypestringNãoValores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null.
graphDefinition.nodes[].configobjectNãoAs propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5.
graphDefinition.nodes[].conditionobjectNãoAceita null.
graphDefinition.edgesarrayNão—
graphDefinition.edges[].idstringNão—
graphDefinition.edges[].sourcestringSim—
graphDefinition.edges[].targetstringSim—
graphDefinition.edges[].sourceHandlestringNãonext, fallback, branch_<id>, rr_<id>, btn_<id>, replied, timeout ou text_reply.
respectBusinessHoursbooleanNãoAceita null.
triggerWindowobjectNãoAceita null.
conditionsobjectNãoAceita null.
triggerConfigobjectNãoO formato depende de triggerType. field_filled usa {fieldSlug, fillMode}; timer aceita {mode: date_field, dateFieldSlug, offsetMinutes, onPastDate} ou {mode: recurring, cron}; contact_no_reply e team_no_reply usam {timeoutSeconds} entre 60 e 2592000; webhook usa {path, httpMethod, authentication e outras propriedades}. Aceita null.
enabledbooleanNãoNa criação, omitir significa true: o fluxo começa a reagir aos gatilhos. Na substituição, omitir preserva o estado atual. Aceita null.
actionsarrayNãoAções do formato legado. Para novos fluxos, use graphDefinition. Aceita null.
actions[].typestringNãoTipo de ação legado.
actions[].orderintegerNão—
actions[].configobjectNão—
webhookUrlstringNãoURL de webhook do formato legado. Aceita null.
webhookHeadersobjectNãoCabeçalhos de webhook do formato legado. Aceita null.
Esquema OpenAPI
{
  "type": "object",
  "description": "Corpo de criação ou substituição. `scope: pipeline` exige `pipelineId`; `scope: stage` exige `stageId`. Gatilhos manual e webhook usam obrigatoriamente o escopo global. `respectBusinessHours` e uma triggerWindow não vazia são incompatíveis. O gatilho manual não aceita conditions, triggerWindow nem respectBusinessHours.",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255
    },
    "triggerType": {
      "type": "string",
      "description": "Um dos valores de `GET /api/v1/automations/triggers`.",
      "enum": [
        "deal_created",
        "deal_stage_changed",
        "deal_won",
        "deal_lost",
        "deal_assigned",
        "message_received",
        "conversation_closed",
        "contact_no_reply",
        "team_no_reply",
        "field_filled",
        "timer",
        "instagram_comment_received",
        "manual",
        "webhook"
      ]
    },
    "scope": {
      "type": "string",
      "enum": [
        "global",
        "pipeline",
        "stage"
      ]
    },
    "pipelineId": {
      "type": "string",
      "nullable": true
    },
    "stageId": {
      "type": "string",
      "nullable": true
    },
    "outboundChannelId": {
      "type": "string",
      "nullable": true,
      "description": "Não existe rota pública para listar canais; obtenha o identificador por outro meio."
    },
    "graphDefinition": {
      "$ref": "#/components/schemas/AutomationGraph"
    },
    "respectBusinessHours": {
      "type": "boolean",
      "nullable": true
    },
    "triggerWindow": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "conditions": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    },
    "triggerConfig": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "O formato depende de triggerType. field_filled usa {fieldSlug, fillMode}; timer aceita {mode: date_field, dateFieldSlug, offsetMinutes, onPastDate} ou {mode: recurring, cron}; contact_no_reply e team_no_reply usam {timeoutSeconds} entre 60 e 2592000; webhook usa {path, httpMethod, authentication e outras propriedades}."
    },
    "enabled": {
      "type": "boolean",
      "nullable": true,
      "description": "Na criação, omitir significa **true**: o fluxo começa a reagir aos gatilhos. Na substituição, omitir preserva o estado atual."
    },
    "actions": {
      "type": "array",
      "nullable": true,
      "items": {
        "$ref": "#/components/schemas/AutomationActionRequest"
      },
      "description": "Ações do formato legado. Para novos fluxos, use graphDefinition."
    },
    "webhookUrl": {
      "type": "string",
      "description": "URL de webhook do formato legado.",
      "nullable": true
    },
    "webhookHeaders": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true,
      "description": "Cabeçalhos de webhook do formato legado."
    }
  },
  "required": [
    "name",
    "triggerType",
    "scope"
  ],
  "example": {
    "name": "Fluxo manual de exemplo",
    "triggerType": "manual",
    "scope": "global",
    "enabled": false,
    "graphDefinition": {
      "version": 2,
      "nodes": [
        {
          "id": "inicio",
          "type": "trigger"
        },
        {
          "id": "fim",
          "type": "end"
        }
      ],
      "edges": [
        {
          "id": "inicio-fim",
          "source": "inicio",
          "target": "fim",
          "sourceHandle": "next"
        }
      ]
    }
  }
}

Respostas

200Sucesso
CampoTipoDescrição
dataAutomation—
data.idstring—
data.namestring—
data.versionintegerVersão da definição. A troca de enabled não incrementa a versão.
data.enabledboolean—
data.triggerTypestring—
data.scopestringValores: global, pipeline, stage.
data.pipelineIdstringAceita null.
data.stageIdstringAceita null.
data.outboundChannelIdstringAceita null.
data.respectBusinessHoursboolean—
data.triggerWindowobjectAceita null.
data.conditionsobjectAceita null.
data.triggerConfigobjectAs credenciais de webhook (headerValue, password) são removidas. Aceita null.
data.graphDefinitionAutomationGraphGrafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto.
data.graphDefinition.versionintegerValores: 2.
data.graphDefinition.nodesarray—
data.graphDefinition.nodes[].idstring—
data.graphDefinition.nodes[].typestringValores: trigger, action, condition, wait, round_robin, end.
data.graphDefinition.nodes[].actionTypestringValores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null.
data.graphDefinition.nodes[].configobjectAs propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5.
data.graphDefinition.nodes[].conditionobjectAceita null.
data.graphDefinition.edgesarray—
data.graphDefinition.edges[].idstring—
data.graphDefinition.edges[].sourcestring—
data.graphDefinition.edges[].targetstring—
data.graphDefinition.edges[].sourceHandlestringnext, fallback, branch_<id>, rr_<id>, btn_<id>, replied, timeout ou text_reply.
data.actionsarray—
data.actions[].idstringID da ação. As ações são substituídas na atualização, não alteradas individualmente.
data.actions[].typestring—
data.actions[].orderinteger—
data.actions[].configobjectO secret do webhook é removido.
data.createdAtstringFormato: date-time.
data.updatedAtstringFormato: date-time.
data.secretstringPresente somente na resposta de criação ou substituição que gerou o segredo. Nunca aparece na leitura. Salve-o: assina X-PipeFacil-Signature-256 e não pode ser consultado depois. Aceita null.
messagestringAceita null.
Esquema OpenAPI
{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Automation"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
400Falha de validação dos campos; `fieldErrors` contém os erros.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
401Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
403Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
404Recurso não encontrado ou fora da visibilidade do membro.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
422Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
429Limite de requisições excedido por workspace ou IP.
CampoTipoDescrição
errorstring—
codestringValores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
requestIdstring—
detailsstringAceita null.
fieldErrorsarrayAceita null.
fieldErrors[].fieldstring—
fieldErrors[].messagestring—
Esquema OpenAPI
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
OpenAPI JSONMarkdown desta operação

Precisa de ajuda?

Encontrou um problema ou ficou com uma dúvida? Fale com a equipe pelo WhatsApp.

Chamar no WhatsApp
Pipefácil