Pular para o conteúdo
Maestron Maestron / Docs /

Pipelines & Estágios

Um pipeline representa um funil de vendas com uma sequência ordenada de estágios. Todo negócio pertence a um pipeline e ocupa exatamente um de seus estágios. Um pipeline recém-criado pela API pública já nasce com os catálogos padrão de status, origem, motivo de perda e tipo de atividade — ver Visão Geral do CRM.

Escopo: crm.view para leitura, crm.funnels.manage para escrita — ver Escopos & Permissões.

Esquema do pipeline

Seção intitulada “Esquema do pipeline”
CampoTipoObrigatórioDescrição
idstring (UUID)leituraIdentificador do pipeline.
namestringsimNome do pipeline.
colorstring | nullnãoCor de exibição, livre.
iconstring | nullnãoÍcone de exibição, livre.
cards_countintegerleituraQuantidade de negócios no pipeline.
total_valueintegerleituraSoma de prospected_value (centavos) de todos os negócios do pipeline.
stagesarrayleituraEstágios do pipeline, ordenados por sort_order.
archived_atstring (ISO-8601) | nullleituraData de arquivamento. null enquanto ativo.
created_atstring (ISO-8601)leituraData de criação.
updated_atstring (ISO-8601)leituraData da última atualização.

Esquema do estágio

Seção intitulada “Esquema do estágio”
CampoTipoObrigatórioDescrição
idstring (UUID)leituraIdentificador do estágio.
funnel_idstring (UUID)leituraPipeline ao qual o estágio pertence.
namestringsimNome do estágio.
colorstring | nullnãoCor de exibição, livre.
sort_orderintegernãoPosição do estágio no pipeline. Quando omitida na criação, segue a ordem do array enviado.
default_probabilityinteger | nullnãoProbabilidade (0–100) aplicada a um negócio quando ele entra neste estágio sem probability explícito.
sla_daysinteger | nullnãoPrazo em dias esperado no estágio. Entre 1 e 3650.
created_atstring (ISO-8601)leituraData de criação.
updated_atstring (ISO-8601)leituraData da última atualização.

Listar pipelines

Seção intitulada “Listar pipelines”

Retorna todos os pipelines da empresa — não paginado.

GET /crm/pipelines

Listar pipelines

Retorna os pipelines da empresa, com stages, cards_count e total_value.

Parâmetros de query

CampoTipoObrigatórioDescrição
archived boolean — Padrão false. true retorna apenas os pipelines arquivados. 
curl -X GET https://api.maestron.com.br/api/v1/crm/pipelines \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/v1/crm/pipelines', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/api/v1/crm/pipelines",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/api/v1/crm/pipelines", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/api/v1/crm/pipelines");
var data = await response.Content.ReadAsStringAsync();
GET /crm/pipelines HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Pipelines.",
  "data": [
    {
      "id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Funil Comercial",
      "color": "#3b82f6",
      "icon": null,
      "cards_count": 12,
      "total_value": 18500000,
      "stages": [
        {
          "id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
          "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
          "name": "Sem contato",
          "color": "#94a3b8",
          "sort_order": 0,
          "default_probability": 10,
          "sla_days": null,
          "created_at": "2026-01-10T09:00:00Z",
          "updated_at": "2026-01-10T09:00:00Z"
        }
      ],
      "archived_at": null,
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-06-18T14:30:00Z"
    }
  ]
}
{
  "message": "Não autenticado.",
  "data": null
}
{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

Obter um pipeline

Seção intitulada “Obter um pipeline”
GET /crm/pipelines/{id}

Obter pipeline

Retorna um pipeline pelo ID, incluindo seus estágios.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim ID do pipeline (UUID). 
curl -X GET https://api.maestron.com.br/api/v1/crm/pipelines/{id} \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/v1/crm/pipelines/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/api/v1/crm/pipelines/{id}",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/api/v1/crm/pipelines/{id}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/api/v1/crm/pipelines/{id}");
var data = await response.Content.ReadAsStringAsync();
GET /crm/pipelines/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Pipeline.",
  "data": {
    "id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Funil Comercial",
    "color": "#3b82f6",
    "icon": null,
    "cards_count": 12,
    "total_value": 18500000,
    "stages": [],
    "archived_at": null,
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-06-18T14:30:00Z"
  }
}
{
  "message": "Não autenticado.",
  "data": null
}
{
  "message": "Recurso não encontrado.",
  "data": null
}

Listar estágios

Seção intitulada “Listar estágios”
GET /crm/pipelines/{id}/stages

Listar estágios

Retorna os estágios do pipeline ordenados por sort_order.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim ID do pipeline (UUID). 
curl -X GET https://api.maestron.com.br/api/v1/crm/pipelines/{id}/stages \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/api/v1/crm/pipelines/{id}/stages', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.get(
    "https://api.maestron.com.br/api/v1/crm/pipelines/{id}/stages",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/api/v1/crm/pipelines/{id}/stages", {
  method: "GET",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.GetAsync("https://api.maestron.com.br/api/v1/crm/pipelines/{id}/stages");
var data = await response.Content.ReadAsStringAsync();
GET /crm/pipelines/{id}/stages HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Estágios.",
  "data": [
    {
      "id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Sem contato",
      "color": "#94a3b8",
      "sort_order": 0,
      "default_probability": 10,
      "sla_days": null,
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-01-10T09:00:00Z"
    },
    {
      "id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Negociando",
      "color": "#f59e0b",
      "sort_order": 1,
      "default_probability": 50,
      "sla_days": 7,
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-01-10T09:00:00Z"
    }
  ]
}
{
  "message": "Não autenticado.",
  "data": null
}
{
  "message": "Recurso não encontrado.",
  "data": null
}

Criar pipeline

Seção intitulada “Criar pipeline”

stages é obrigatório — pelo menos um estágio inicial (máximo 50). Os catálogos de status, origem, motivo de perda e tipo de atividade são semeados automaticamente com os padrões do sistema; não há campo para customizá-los nesta chamada.

POST /crm/pipelines

Criar pipeline

Cria um pipeline com seus estágios iniciais. idempotency_key é opcional — ver Sandbox & Idempotência.

Corpo (body)

CampoTipoObrigatórioDescrição
name string Sim Nome do pipeline. Máx. 120 caracteres.
color string — Cor de exibição. Máx. 30 caracteres.
icon string — Ícone de exibição. Máx. 60 caracteres.
default_assignee_id string — Usuário responsável padrão dos negócios criados neste pipeline sem assignee_id explícito.
stages array Sim Entre 1 e 50 estágios: name (obrigatório, máx. 120), color, sort_order, default_probability (0–100), sla_days (1–3650).
idempotency_key string — Opcional — evita duplicar o pipeline em um retry. 
curl -X POST https://api.maestron.com.br/api/v1/crm/pipelines \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Funil Comercial",
    "color": "#3b82f6",
    "stages": [
      {
        "name": "Sem contato",
        "default_probability": 10
      },
      {
        "name": "Negociando",
        "default_probability": 50,
        "sla_days": 7
      },
      {
        "name": "Proposta enviada",
        "default_probability": 80
      }
    ],
    "idempotency_key": "3f7b1c9a-2d4e-4f6a-8b0c-5d9e1f3a7c2b"
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/pipelines', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'name' => 'Funil Comercial',
        'color' => '#3b82f6',
        'stages' => [object Object],[object Object],[object Object],
        'idempotency_key' => '3f7b1c9a-2d4e-4f6a-8b0c-5d9e1f3a7c2b',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "Funil Comercial",
    "color": "#3b82f6",
    "stages": [object Object],[object Object],[object Object],
    "idempotency_key": "3f7b1c9a-2d4e-4f6a-8b0c-5d9e1f3a7c2b",
}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/pipelines",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/api/v1/crm/pipelines", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Funil Comercial",
    "color": "#3b82f6",
    "stages": [
      {
        "name": "Sem contato",
        "default_probability": 10
      },
      {
        "name": "Negociando",
        "default_probability": 50,
        "sla_days": 7
      },
      {
        "name": "Proposta enviada",
        "default_probability": 80
      }
    ],
    "idempotency_key": "3f7b1c9a-2d4e-4f6a-8b0c-5d9e1f3a7c2b"
  }),
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"name\":\"Funil Comercial\",\"color\":\"#3b82f6\",\"stages\":[{\"name\":\"Sem contato\",\"default_probability\":10},{\"name\":\"Negociando\",\"default_probability\":50,\"sla_days\":7},{\"name\":\"Proposta enviada\",\"default_probability\":80}],\"idempotency_key\":\"3f7b1c9a-2d4e-4f6a-8b0c-5d9e1f3a7c2b\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/pipelines", payload);
var data = await response.Content.ReadAsStringAsync();
POST /crm/pipelines HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "name": "Funil Comercial",
  "color": "#3b82f6",
  "stages": [
    {
      "name": "Sem contato",
      "default_probability": 10
    },
    {
      "name": "Negociando",
      "default_probability": 50,
      "sla_days": 7
    },
    {
      "name": "Proposta enviada",
      "default_probability": 80
    }
  ],
  "idempotency_key": "3f7b1c9a-2d4e-4f6a-8b0c-5d9e1f3a7c2b"
}

Respostas

{
  "message": "Pipeline criado.",
  "data": {
    "id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Funil Comercial",
    "color": "#3b82f6",
    "icon": null,
    "cards_count": 0,
    "total_value": 0,
    "stages": [
      {
        "id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
        "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "Sem contato",
        "color": null,
        "sort_order": 0,
        "default_probability": 10,
        "sla_days": null,
        "created_at": "2026-06-20T14:30:00Z",
        "updated_at": "2026-06-20T14:30:00Z"
      }
    ],
    "archived_at": null,
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado.",
  "data": null
}
{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}
{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "name": [
      "O campo name é obrigatório."
    ],
    "stages": [
      "O campo stages deve ter pelo menos 1 item."
    ]
  }
}

Atualizar pipeline

Seção intitulada “Atualizar pipeline”

Enviar stages substitui a lista atual: um item sem id cria um estágio novo; um item com id atualiza o estágio existente; um estágio existente ausente do array enviado é removido.

PATCH /crm/pipelines/{id}

Atualizar pipeline

Atualiza os atributos do pipeline e, se enviado, sincroniza a lista de estágios.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim ID do pipeline (UUID).

Corpo (body)

CampoTipoObrigatórioDescrição
name string — Nome do pipeline.
color string — Cor de exibição.
icon string — Ícone de exibição.
default_assignee_id string — Usuário responsável padrão.
stages array — Lista completa de estágios. Item com id atualiza; sem id cria; estágio existente ausente é removido. 
curl -X PATCH https://api.maestron.com.br/api/v1/crm/pipelines/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Funil Comercial 2026"
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/api/v1/crm/pipelines/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'name' => 'Funil Comercial 2026',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "Funil Comercial 2026",
}
response = requests.patch(
    "https://api.maestron.com.br/api/v1/crm/pipelines/{id}",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/api/v1/crm/pipelines/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Funil Comercial 2026"
  }),
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"name\":\"Funil Comercial 2026\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/api/v1/crm/pipelines/{id}") { Content = payload });
var data = await response.Content.ReadAsStringAsync();
PATCH /crm/pipelines/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "name": "Funil Comercial 2026"
}

Respostas

{
  "message": "Pipeline atualizado.",
  "data": {
    "id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Funil Comercial 2026",
    "color": "#3b82f6",
    "icon": null,
    "cards_count": 12,
    "total_value": 18500000,
    "stages": [],
    "archived_at": null,
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-06-20T15:00:00Z"
  }
}
{
  "message": "Não autenticado.",
  "data": null
}
{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}
{
  "message": "Recurso não encontrado.",
  "data": null
}
{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "name": [
      "O campo name deve ter no máximo 120 caracteres."
    ]
  }
}

Remover pipeline

Seção intitulada “Remover pipeline”
DELETE /crm/pipelines/{id}

Remover pipeline

Remove o pipeline e, em cascata, todos os seus negócios.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim ID do pipeline (UUID). 
curl -X DELETE https://api.maestron.com.br/api/v1/crm/pipelines/{id} \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/api/v1/crm/pipelines/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.delete(
    "https://api.maestron.com.br/api/v1/crm/pipelines/{id}",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/api/v1/crm/pipelines/{id}", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
  },
});
const data = await response.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var response = await client.DeleteAsync("https://api.maestron.com.br/api/v1/crm/pipelines/{id}");
var data = await response.Content.ReadAsStringAsync();
DELETE /crm/pipelines/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Pipeline removido.",
  "data": null
}
{
  "message": "Não autenticado.",
  "data": null
}
{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}
{
  "message": "Recurso não encontrado.",
  "data": null
}

Para o detalhamento de cada código de status, consulte Erros.