Executar tarefa de cadência

POST/api/v1/deals/{seq}/cadence/tasks/{taskId}/execute

Envia a tarefa ao provedor do canal e retorna o resultado. Esta operação envia de fato WhatsApp, e-mail ou chamada externa e pode gerar cobrança no workspace. idempotencyKey é obrigatória; repetir a mesma chave retorna duplicated: true, sem novo envio.

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 POST \
  --url "https://pipefacil-server.matchsales.com.br/api/v1/deals/$SEQ/cadence/tasks/$TASKID/execute" \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "idempotencyKey": "envio-negocio-123-tarefa-456-v1",
  "message": "Olá, Ana. Podemos retomar a proposta?"
}'

JavaScript

const response = await fetch(`https://pipefacil-server.matchsales.com.br/api/v1/deals/${process.env.SEQ}/cadence/tasks/${process.env.TASKID}/execute`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PIPEFACIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "idempotencyKey": "envio-negocio-123-tarefa-456-v1",
  "message": "Olá, Ana. Podemos retomar a proposta?"
}),
});

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(
    "POST",
    f"https://pipefacil-server.matchsales.com.br/api/v1/deals/{os.environ['SEQ']}/cadence/tasks/{os.environ['TASKID']}/execute",
    headers={"Authorization": f"Bearer {os.environ['PIPEFACIL_API_KEY']}"},
    json=json.loads("{\n  \"idempotencyKey\": \"envio-negocio-123-tarefa-456-v1\",\n  \"message\": \"Olá, Ana. Podemos retomar a proposta?\"\n}"),
)
response.raise_for_status()
data = response.json() if response.content else None

Parâmetros

Nome	Local	Tipo	Obrigatório	Descrição
`seq`	`path`	`integer`	Sim	—
`taskId`	`path`	`string`	Sim	Identificador da tarefa de cadência.

Corpo da requisição

Content-Type: application/json · obrigatório

{
  "idempotencyKey": "envio-negocio-123-tarefa-456-v1",
  "message": "Olá, Ana. Podemos retomar a proposta?"
}

Campo	Tipo	Obrigatório no objeto	Descrição
`idempotencyKey`	`string`	Sim	Chave escolhida pelo cliente para repetir o envio com segurança. Repetir a mesma chave retorna `duplicated: true`, sem novo envio. Informe-a em toda chamada, inclusive na primeira tentativa. Até 120 caracteres.
`message`	`string`	Não	Corpo de uma etapa de WhatsApp. Aceita null. Até 4000 caracteres.
`subject`	`string`	Não	Assunto de uma etapa de e-mail. Aceita null. Até 160 caracteres.
`htmlBody`	`string`	Não	Corpo HTML de uma etapa de e-mail. Aceita null. Até 10000 caracteres.
`textBody`	`string`	Não	Corpo em texto simples de uma etapa de e-mail. Aceita null. Até 4000 caracteres.
`manualReferenceId`	`string`	Não	Referência da tentativa definida pelo cliente. Aceita null. Até 120 caracteres.

Esquema OpenAPI

{
  "type": "object",
  "required": [
    "idempotencyKey"
  ],
  "properties": {
    "idempotencyKey": {
      "type": "string",
      "maxLength": 120,
      "description": "Chave escolhida pelo cliente para repetir o envio com segurança. Repetir a mesma chave retorna `duplicated: true`, sem novo envio. Informe-a em toda chamada, inclusive na primeira tentativa."
    },
    "message": {
      "type": "string",
      "maxLength": 4000,
      "nullable": true,
      "description": "Corpo de uma etapa de WhatsApp."
    },
    "subject": {
      "type": "string",
      "maxLength": 160,
      "nullable": true,
      "description": "Assunto de uma etapa de e-mail."
    },
    "htmlBody": {
      "type": "string",
      "maxLength": 10000,
      "nullable": true,
      "description": "Corpo HTML de uma etapa de e-mail."
    },
    "textBody": {
      "type": "string",
      "maxLength": 4000,
      "nullable": true,
      "description": "Corpo em texto simples de uma etapa de e-mail."
    },
    "manualReferenceId": {
      "type": "string",
      "maxLength": 120,
      "nullable": true,
      "description": "Referência da tentativa definida pelo cliente."
    }
  },
  "example": {
    "idempotencyKey": "envio-negocio-123-tarefa-456-v1",
    "message": "Olá, Ana. Podemos retomar a proposta?"
  }
}

Respostas

200Sucesso

Campo	Tipo	Descrição
`data`	`TaskExecution`	—
`data.ok`	`boolean`	—
`data.duplicated`	`boolean`	Verdadeiro quando a mesma execução já estava registrada.
`data.taskStatus`	`string`	—
`data.attemptNumber`	`integer`	—
`data.attemptId`	`string`	Aceita null.
`data.providerMessageId`	`string`	Aceita null.
`data.voiceCallId`	`string`	Aceita null.
`data.emailMessageId`	`string`	Aceita null.
`data.idempotencyKey`	`string`	Aceita null.
`data.executedAt`	`string`	Formato: date-time.
`message`	`string`	Aceita null.

Esquema OpenAPI

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/TaskExecution"
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}

400Falha de validação dos campos; `fieldErrors` contém os erros.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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"
  ]
}

409Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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.

Campo	Tipo	Descrição
`error`	`string`	—
`code`	`string`	Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE.
`requestId`	`string`	—
`details`	`string`	Aceita null.
`fieldErrors`	`array`	Aceita null.
`fieldErrors[].field`	`string`	—
`fieldErrors[].message`	`string`	—

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 JSON Markdown desta operação

Executar tarefa de cadência

Exemplos

cURL

Parâmetros

Corpo da requisição

Respostas

Precisa de ajuda?