Criar fase

POST

/v1/flows/{id}/phases

Cria uma nova fase (etapa) dentro de um flow existente.

Os campos name, color, index, start e latenessTime são obrigatórios: a API exige start explicitamente no payload de criação (true para a fase inicial, false para as demais), retornando erro 400 caso o campo esteja ausente.

O campo latenessTime também é obrigatório — sua ausência pode comprometer operações futuras sobre os cards dessa fase, retornando um erro 500. Envie sempre um valor em minutos; o valor padrão recomendado é 2880 (48 horas).

O campo color aceita um conjunto fixo de 10 valores, não uma cor hexadecimal livre: start, lost, won, turquoise, blue, orange, violet, pink, purple e light_blue.

O campo doneType só é obrigatório quando done é true, devendo ser won ou lost.

O campo sortingPreference.field aceita apenas 5 valores; o valor createdAt não é aceito — utilize enteredCurrentPhaseAt.

O campo cardsCanBeMovedToPhase recebe um array com os identificadores das fases de origem permitidas. Trata-se de uma orientação de interface exibida no editor do flow, e não é validada pela API nem pelas automações de trigger.

Requisição

Parâmetros de Caminho

Parâmetros Bodyapplication/jsonNecessário

Examples

Respostas

🟢201Fase criada

application/json

A fase foi criada com sucesso.

Bodyapplication/json

🟠400Payload inválido

Request Example

Shell

JavaScript

Java

Swift

curl --location '/v1/flows//phases' \
--header 'Content-Type: application/json' \
--data '{
    "name": "string",
    "color": "start",
    "index": 0,
    "start": true,
    "done": false,
    "doneType": "won",
    "description": "string",
    "latenessTime": 2880,
    "sortingPreference": {
        "field": "name",
        "order": "asc"
    },
    "cardsCanBeMovedToPhase": [
        "string"
    ]
}'

Response Example

201 - Exemplo 1

{
    "id": "string",
    "name": "string",
    "color": "string",
    "index": 0,
    "start": true,
    "done": true,
    "doneType": "string",
    "latenessTime": 0,
    "sortingPreference": {},
    "cardsCanBeMovedToPhase": [
        "string"
    ],
    "flowId": "string"
}

Modificado em 2026-07-29 12:58:18