Primeiros passos

Este guia percorre o ciclo completo do CRM pela API pública: gerar uma chave, criar um pipeline, criar um negócio nele, movê-lo de etapa, marcá-lo como ganho e registrar uma atividade.

Pré-requisitos

Uma conta Maestron com uma empresa e um usuário com permissão para gerenciar API Keys.
Uma API Key gerada em Configurações → API Keys, com os escopos crm.view, crm.funnels.manage, crm.leads.create, crm.leads.edit e crm.leads.close. Passo a passo em Gerando sua API Key.
Um cliente HTTP capaz de enviar o header Authorization (cURL, a collection Postman, ou qualquer biblioteca HTTP da sua linguagem).

Como funciona a autenticação

Toda requisição autenticada envia o segredo da chave no header Authorization:

Authorization: Bearer maestron_pk_test_SEU_SEGREDO

A empresa é resolvida automaticamente a partir da chave — não existe header de empresa. Detalhes em Autenticação.

Passo 1 — Criar um pipeline

Todo negócio precisa de um pipeline com pelo menos um estágio. Crie um com três estágios:

POST /crm/pipelines

Criar pipeline

Cria o pipeline com os estágios iniciais. Os catálogos de status/origem/motivo de perda/tipo de atividade nascem com os padrões do sistema.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do pipeline.
`stages`	array	Sim	Estágios iniciais, na ordem desejada.

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",
    "stages": [
      {
        "name": "Sem contato"
      },
      {
        "name": "Negociando"
      },
      {
        "name": "Proposta enviada"
      }
    ]
  }'

<?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',
        'stages' => [object Object],[object Object],[object Object],
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "Funil Comercial",
    "stages": [object Object],[object Object],[object Object],
}
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",
    "stages": [
      {
        "name": "Sem contato"
      },
      {
        "name": "Negociando"
      },
      {
        "name": "Proposta enviada"
      }
    ]
  }),
});
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\",\"stages\":[{\"name\":\"Sem contato\"},{\"name\":\"Negociando\"},{\"name\":\"Proposta enviada\"}]}",
    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",
  "stages": [
    {
      "name": "Sem contato"
    },
    {
      "name": "Negociando"
    },
    {
      "name": "Proposta enviada"
    }
  ]
}

Respostas

{
  "message": "Pipeline criado.",
  "data": {
    "id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "name": "Funil Comercial",
    "stages": [
      {
        "id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
        "name": "Sem contato",
        "sort_order": 0
      },
      {
        "id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
        "name": "Negociando",
        "sort_order": 1
      }
    ]
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

Guarde o id do pipeline e o id do primeiro estágio — eles vão no próximo passo.

Passo 2 — Criar um negócio

POST /crm/deals

Criar negócio

Cria o negócio no pipeline e estágio do passo 1.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
`funnel_id`	string	Sim	ID do pipeline criado no passo 1.
`stage_id`	string	Sim	ID do primeiro estágio.
`contact_name`	string	Sim	Nome do contato.
`contact_date`	string	Sim	Data do primeiro contato.
`status`	string	Sim	Valor do catálogo padrão do pipeline (ex.: sem_contato).

curl -X POST https://api.maestron.com.br/api/v1/crm/deals \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "stage_id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "contact_name": "Maria Silva",
    "company_name": "Acme Ltda",
    "contact_date": "2026-06-20",
    "status": "sem_contato",
    "prospected_value": 1500000
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/deals', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'funnel_id' => 'b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d',
        'stage_id' => 'a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e',
        'contact_name' => 'Maria Silva',
        'company_name' => 'Acme Ltda',
        'contact_date' => '2026-06-20',
        'status' => 'sem_contato',
        'prospected_value' => 1500000,
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "stage_id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "contact_name": "Maria Silva",
    "company_name": "Acme Ltda",
    "contact_date": "2026-06-20",
    "status": "sem_contato",
    "prospected_value": 1500000,
}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/deals",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/deals", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
    "stage_id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "contact_name": "Maria Silva",
    "company_name": "Acme Ltda",
    "contact_date": "2026-06-20",
    "status": "sem_contato",
    "prospected_value": 1500000
  }),
});
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(
    "{\"funnel_id\":\"b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d\",\"stage_id\":\"a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e\",\"contact_name\":\"Maria Silva\",\"company_name\":\"Acme Ltda\",\"contact_date\":\"2026-06-20\",\"status\":\"sem_contato\",\"prospected_value\":1500000}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/deals", payload);
var data = await response.Content.ReadAsStringAsync();

POST /crm/deals HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "funnel_id": "b7e8c1a2-3d4f-4a5b-8c9d-0e1f2a3b4c5d",
  "stage_id": "a1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "contact_name": "Maria Silva",
  "company_name": "Acme Ltda",
  "contact_date": "2026-06-20",
  "status": "sem_contato",
  "prospected_value": 1500000
}

Respostas

{
  "message": "Negócio criado.",
  "data": {
    "id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "status": "sem_contato"
  }
}

{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "contact_name": [
      "O campo contact_name é obrigatório."
    ]
  }
}

Passo 3 — Mover o negócio de etapa

PATCH /crm/deals/{id}/stage

Mover para o próximo estágio

Move o negócio criado no passo 2 para o estágio 'Negociando'.

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID do negócio.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
`stage_id`	string	Sim	ID do estágio "Negociando" do passo 1.

curl -X PATCH https://api.maestron.com.br/api/v1/crm/deals/{id}/stage \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/api/v1/crm/deals/{id}/stage', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'stage_id' => 'c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "stage_id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
}
response = requests.patch(
    "https://api.maestron.com.br/api/v1/crm/deals/{id}/stage",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/deals/{id}/stage", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "stage_id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f"
  }),
});
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(
    "{\"stage_id\":\"c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/api/v1/crm/deals/{id}/stage") { Content = payload });
var data = await response.Content.ReadAsStringAsync();

PATCH /crm/deals/{id}/stage HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "stage_id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f"
}

Respostas

{
  "message": "Negócio movido de etapa.",
  "data": {
    "id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "stage_id": "c3d4e5f6-7a8b-4c9d-0e1f-2a3b4c5d6e7f"
  }
}

{
  "message": "A etapa selecionada não pertence ao funil do negócio.",
  "data": null
}

Passo 4 — Marcar como ganho

POST /crm/deals/{id}/win

Marcar negócio como ganho

status é opcional aqui — o pipeline recém-criado tem um único status padrão de kind ganho ('ganho').

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID do negócio.

curl -X POST https://api.maestron.com.br/api/v1/crm/deals/{id}/win \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/deals/{id}/win', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/deals/{id}/win",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/deals/{id}/win", {
  method: "POST",
  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.PostAsync("https://api.maestron.com.br/api/v1/crm/deals/{id}/win", null);
var data = await response.Content.ReadAsStringAsync();

POST /crm/deals/{id}/win HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Negócio marcado como ganho.",
  "data": {
    "id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "status": "ganho"
  }
}

Passo 5 — Registrar uma atividade

Toda atividade pertence a um negócio e a um tipo do catálogo do pipeline. Um pipeline novo já tem os 8 tipos padrão — use o activity_type_id de uma chamada anterior ou consulte o painel Maestron (ver a nota em Atividades).

POST /crm/activities

Registrar uma ligação

Cria uma atividade vinculada ao negócio criado no passo 2.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
`lead_id`	string	Sim	ID do negócio.
`activity_type_id`	string	Sim	ID do tipo "Ligação" do catálogo do pipeline.
`subject`	string	Sim	Assunto da atividade.

curl -X POST https://api.maestron.com.br/api/v1/crm/activities \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "subject": "Ligação de fechamento"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/activities', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'lead_id' => 'f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c',
        'activity_type_id' => 'e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b',
        'subject' => 'Ligação de fechamento',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "subject": "Ligação de fechamento",
}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/activities",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/activities", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
    "subject": "Ligação de fechamento"
  }),
});
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(
    "{\"lead_id\":\"f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c\",\"activity_type_id\":\"e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b\",\"subject\":\"Ligação de fechamento\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/activities", payload);
var data = await response.Content.ReadAsStringAsync();

POST /crm/activities HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "lead_id": "f1a2b3c4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
  "activity_type_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
  "subject": "Ligação de fechamento"
}

Respostas

{
  "message": "Atividade criada.",
  "data": {
    "id": "d4e5f6a7-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
    "done_at": null
  }
}

Uma resposta 201/200 com o envelope acima em cada passo confirma que a integração está funcionando ponta a ponta.

Tratamento de erro

A API sempre responde com data: null em erro, e errors por campo quando é validação:

{
  "message": "string",
  "data": null,
  "errors": { "campo": ["mensagem"] }
}

401 — Não autenticado

O segredo está ausente, malformado, revogado ou expirado. Verifique o header Authorization: Bearer <segredo> em Autenticação.

403 — Sem escopo

A chave não tem o escopo exigido pela operação. Ver Escopos & Permissões.

422 — Validação

O corpo não passou na validação, ou uma regra de negócio foi violada (ex.: estágio de outro pipeline). Ver Erros.

Próximos passos

Escopos & Permissões

O que cada escopo libera e quais endpoints exigem escopo fino. Ver Escopos & Permissões.

Sandbox & Idempotência

Como testar sem gravar e evitar duplicar escritas em retry. Ver Sandbox & Idempotência.

Referência completa

Todos os endpoints, com escopo e exemplos. Ver Referência da API.

Postman

Baixe a collection completa e importe no seu cliente HTTP. Ver Postman & Ferramentas.