Pular para o conteúdo
Maestron Maestron / Docs /
Acessar painel

Referência da API

Referência completa de todos os endpoints da API Maestron, organizada por módulo. Cada recurso possui uma página dedicada com o detalhamento de campos, filtros e exemplos de request/response.

A base URL é https://api.maestron.com.br/v1. A autenticação usa token Bearer no header Authorization; a empresa (tenant) é resolvida automaticamente a partir do token. Os formatos de envelope, identificadores e tipos de dado seguem as convenções da API. Os códigos de status são detalhados em Erros e os limites de uso em Rate limiting.

Convenções da coluna Auth

Seção intitulada “Convenções da coluna Auth”
  • ✅ — exige Authorization: Bearer SEU_TOKEN.
  • — (traço) — endpoint público; não exige token.

Autenticação

Seção intitulada “Autenticação”

Endpoints de criação de conta, login, renovação de token, 2FA e redefinição de senha. Os endpoints públicos não exigem Authorization; os demais sim. Documentação detalhada em Autenticação.

MétodoPathDescriçãoAuth
POST/auth/registerCria uma conta de usuário e a empresa inicial—
POST/auth/loginAutentica com e-mail e senha e retorna o token Bearer—
POST/auth/refreshRenova o token de acesso a partir do token atual✅
POST/auth/logoutInvalida o token atual no servidor✅
GET/auth/meRetorna o usuário autenticado e a empresa ativa✅
GET/auth/social/{provider}/redirectInicia o fluxo OAuth (google, microsoft)—
GET/auth/social/{provider}/callbackCallback OAuth do provedor—
POST/auth/2fa/challengeConfirma o login com 2FA e emite o token de acesso—
POST/auth/2fa/enableInicia a ativação de 2FA (secret + otpauth URI)✅
POST/auth/2fa/confirmConfirma a ativação de 2FA e retorna recovery codes✅
DELETE/auth/2faDesativa o 2FA da conta✅
POST/auth/2fa/recovery-codesRegenera os recovery codes do 2FA✅
POST/auth/forgot-passwordDispara e-mail de redefinição de senha—
POST/auth/reset-passwordRedefine a senha usando o token recebido por e-mail—
POST /auth/login

Autenticar

Autentica com e-mail e senha e retorna um token Bearer. Quando o 2FA está ativo, retorna pending_2fa=true e um two_factor_token a ser usado em POST /auth/2fa/challenge.

Corpo (body)

CampoTipoObrigatórioDescrição
email string Sim E-mail do usuário.
password string Sim Senha do usuário.
remember_me boolean — Estende a validade do token quando verdadeiro. 
curl -X POST https://api.maestron.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@exemplo.com",
    "password": "senha-secreta",
    "remember_me": true
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/login', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'email' => 'usuario@exemplo.com',
        'password' => 'senha-secreta',
        'remember_me' => true,
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {}
payload = {
    "email": "usuario@exemplo.com",
    "password": "senha-secreta",
    "remember_me": True,
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/login",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/auth/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "usuario@exemplo.com",
    "password": "senha-secreta",
    "remember_me": true
  }),
});
const data = await response.json();
using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"usuario@exemplo.com\",\"password\":\"senha-secreta\",\"remember_me\":true}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/login", payload);
var data = await response.Content.ReadAsStringAsync();
POST /auth/login HTTP/1.1
Host: api.maestron.com.br
Content-Type: application/json

{
  "email": "usuario@exemplo.com",
  "password": "senha-secreta",
  "remember_me": true
}

Respostas

{
  "message": "Autenticado.",
  "data": {
    "token": "eyJ0eXAiOiJKV1Qi...",
    "token_type": "Bearer",
    "expires_at": "2026-07-20T14:30:00Z",
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Souza",
      "email": "usuario@exemplo.com"
    }
  }
}
{
  "message": "Verificação em duas etapas necessária.",
  "data": {
    "pending_2fa": true,
    "two_factor_token": "tfa_01J9Z3K8..."
  }
}
{
  "message": "Credenciais inválidas."
}
{
  "message": "Conta inativa."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "O campo e-mail é obrigatório."
    ]
  }
}
{
  "message": "Muitas tentativas. Tente novamente mais tarde."
}

Contexto do usuário e da empresa

Seção intitulada “Contexto do usuário e da empresa”

Listagem das empresas (tenants) do usuário, troca de contexto ativo e gerenciamento do perfil. Trocar de contexto emite um novo token Bearer já vinculado à empresa selecionada.

MétodoPathDescriçãoAuth
GET/user/companiesLista as empresas do usuário e o papel em cada uma✅
GET/user/companies/{id}Retorna os detalhes de uma empresa do usuário✅
POST/auth/contextTroca o contexto ativo e emite um novo token Bearer✅
GET/user/profileRetorna o perfil do usuário autenticado✅
PATCH/user/profileAtualiza dados do perfil do usuário✅
PATCH/user/passwordAltera a senha do usuário autenticado✅
POST /auth/context

Trocar contexto de empresa

Emite um novo token Bearer com a empresa selecionada. O token resultante resolve a empresa automaticamente em todas as requisições seguintes.

Corpo (body)

CampoTipoObrigatórioDescrição
company_id string Sim Identificador da empresa-tenant (comp_) à qual o usuário pertence. 
curl -X POST https://api.maestron.com.br/v1/auth/context \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "comp_01J9Z3K8"
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/context', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'company_id' => 'comp_01J9Z3K8',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "company_id": "comp_01J9Z3K8",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/context",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/auth/context", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": "comp_01J9Z3K8"
  }),
});
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(
    "{\"company_id\":\"comp_01J9Z3K8\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/context", payload);
var data = await response.Content.ReadAsStringAsync();
POST /auth/context HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "company_id": "comp_01J9Z3K8"
}

Respostas

{
  "message": "Contexto atualizado.",
  "data": {
    "token": "eyJ0eXAiOiJKV1Qi...",
    "token_type": "Bearer",
    "expires_at": "2026-07-20T14:30:00Z",
    "company": {
      "id": "comp_01J9Z3K8",
      "name": "Acme Ltda",
      "role": "owner"
    }
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Você não tem acesso a esta empresa."
}
{
  "message": "Empresa não encontrada."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "company_id": [
      "O campo company_id é obrigatório."
    ]
  }
}

CRM — Contatos

Seção intitulada “CRM — Contatos”

Pessoas físicas. Documentação detalhada em Contatos.

MétodoPathDescriçãoAuth
GET/crm/contactsLista contatos (paginado, buscável, filtrável)✅
POST/crm/contactsCria um contato✅
GET/crm/contacts/{id}Retorna um contato✅
PATCH/crm/contacts/{id}Atualiza parcialmente um contato✅
DELETE/crm/contacts/{id}Remove um contato✅
GET/crm/contacts/{id}/dealsLista os negócios vinculados ao contato✅
GET/crm/contacts/{id}/activitiesLista as atividades vinculadas ao contato✅
GET /crm/contacts

Listar contatos

Retorna a coleção paginada de contatos da empresa ativa. Aceita paginação, busca e ordenação padrão, além dos filtros específicos abaixo.

Parâmetros de query

CampoTipoObrigatórioDescrição
page integer — Página atual (padrão: 1).
per_page integer — Itens por página (padrão: 20, máx: 100).
search string — Busca textual por nome, e-mail ou telefone.
tag string — Filtra por tag.
company_id string — Filtra por empresa CRM vinculada (comp_).
owner_id string — Filtra por responsável (user_). 
curl -X GET https://api.maestron.com.br/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/crm/contacts', [
    '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/v1/crm/contacts",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts", {
  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/v1/crm/contacts");
var data = await response.Content.ReadAsStringAsync();
GET /crm/contacts HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Contatos listados.",
  "data": [
    {
      "id": "cont_01J9Z3K8",
      "name": "João Pereira",
      "email": "joao@cliente.com",
      "phone": "+5511999990000",
      "job_title": "Comprador",
      "company_id": "comp_01J9Z3K8",
      "owner_id": "user_01J9Z3K8",
      "tags": [
        "lead",
        "prioridade"
      ],
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-10T12:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}
{
  "message": "Não autenticado."
}
POST /crm/contacts

Criar contato

Cria um contato na empresa ativa.

Corpo (body)

CampoTipoObrigatórioDescrição
name string Sim Nome do contato.
email string — E-mail do contato.
phone string — Telefone do contato.
job_title string — Cargo do contato.
company_id string — Empresa CRM vinculada (comp_).
owner_id string — Responsável pelo contato (user_).
tags string[] — Lista de tags.
notes string — Observações livres. 
curl -X POST https://api.maestron.com.br/v1/crm/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Pereira",
    "email": "joao@cliente.com",
    "phone": "+5511999990000",
    "job_title": "Comprador",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "lead"
    ],
    "notes": "Indicado por parceiro."
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/contacts', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'name' => 'João Pereira',
        'email' => 'joao@cliente.com',
        'phone' => '+5511999990000',
        'job_title' => 'Comprador',
        'company_id' => 'comp_01J9Z3K8',
        'owner_id' => 'user_01J9Z3K8',
        'tags' => lead,
        'notes' => 'Indicado por parceiro.',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "João Pereira",
    "email": "joao@cliente.com",
    "phone": "+5511999990000",
    "job_title": "Comprador",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": lead,
    "notes": "Indicado por parceiro.",
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/contacts",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "João Pereira",
    "email": "joao@cliente.com",
    "phone": "+5511999990000",
    "job_title": "Comprador",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "lead"
    ],
    "notes": "Indicado por parceiro."
  }),
});
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\":\"João Pereira\",\"email\":\"joao@cliente.com\",\"phone\":\"+5511999990000\",\"job_title\":\"Comprador\",\"company_id\":\"comp_01J9Z3K8\",\"owner_id\":\"user_01J9Z3K8\",\"tags\":[\"lead\"],\"notes\":\"Indicado por parceiro.\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/crm/contacts", payload);
var data = await response.Content.ReadAsStringAsync();
POST /crm/contacts HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "name": "João Pereira",
  "email": "joao@cliente.com",
  "phone": "+5511999990000",
  "job_title": "Comprador",
  "company_id": "comp_01J9Z3K8",
  "owner_id": "user_01J9Z3K8",
  "tags": [
    "lead"
  ],
  "notes": "Indicado por parceiro."
}

Respostas

{
  "message": "Contato criado.",
  "data": {
    "id": "cont_01J9Z3K8",
    "name": "João Pereira",
    "email": "joao@cliente.com",
    "phone": "+5511999990000",
    "job_title": "Comprador",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "lead"
    ],
    "notes": "Indicado por parceiro.",
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Já existe um contato com este e-mail nesta empresa."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "name": [
      "O campo nome é obrigatório."
    ]
  }
}
GET /crm/contacts/{id}

Retornar contato

Retorna um contato com empresa vinculada, responsável, tags e timestamps.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do contato (cont_). 
curl -X GET https://api.maestron.com.br/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/crm/contacts/{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/v1/crm/contacts/{id}",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts/{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/v1/crm/contacts/{id}");
var data = await response.Content.ReadAsStringAsync();
GET /crm/contacts/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Contato retornado.",
  "data": {
    "id": "cont_01J9Z3K8",
    "name": "João Pereira",
    "email": "joao@cliente.com",
    "phone": "+5511999990000",
    "job_title": "Comprador",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "tags": [
      "lead"
    ],
    "notes": "Indicado por parceiro.",
    "created_at": "2026-06-01T10:00:00Z",
    "updated_at": "2026-06-10T12:00:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Contato não encontrado."
}
PATCH /crm/contacts/{id}

Atualizar contato

Atualiza parcialmente um contato. Apenas os campos enviados são alterados.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do contato (cont_).

Corpo (body)

CampoTipoObrigatórioDescrição
name string — Nome do contato.
email string — E-mail do contato.
phone string — Telefone do contato.
job_title string — Cargo do contato.
tags string[] — Lista de tags.
notes string — Observações livres. 
curl -X PATCH https://api.maestron.com.br/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_title": "Gerente de Compras",
    "tags": [
      "lead",
      "prioridade"
    ]
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/v1/crm/contacts/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'job_title' => 'Gerente de Compras',
        'tags' => lead,prioridade,
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "job_title": "Gerente de Compras",
    "tags": lead,prioridade,
}
response = requests.patch(
    "https://api.maestron.com.br/v1/crm/contacts/{id}",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "job_title": "Gerente de Compras",
    "tags": [
      "lead",
      "prioridade"
    ]
  }),
});
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(
    "{\"job_title\":\"Gerente de Compras\",\"tags\":[\"lead\",\"prioridade\"]}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/v1/crm/contacts/{id}") { Content = payload });
var data = await response.Content.ReadAsStringAsync();
PATCH /crm/contacts/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "job_title": "Gerente de Compras",
  "tags": [
    "lead",
    "prioridade"
  ]
}

Respostas

{
  "message": "Contato atualizado.",
  "data": {
    "id": "cont_01J9Z3K8",
    "name": "João Pereira",
    "job_title": "Gerente de Compras",
    "tags": [
      "lead",
      "prioridade"
    ],
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Contato não encontrado."
}
{
  "message": "Já existe um contato com este e-mail nesta empresa."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": [
      "O e-mail informado é inválido."
    ]
  }
}
DELETE /crm/contacts/{id}

Remover contato

Remove um contato permanentemente. Negócios e atividades vinculados são desvinculados, não removidos.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do contato (cont_). 
curl -X DELETE https://api.maestron.com.br/v1/crm/contacts/{id} \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/v1/crm/contacts/{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/v1/crm/contacts/{id}",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/contacts/{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/v1/crm/contacts/{id}");
var data = await response.Content.ReadAsStringAsync();
DELETE /crm/contacts/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Contato removido.",
  "data": {
    "id": "cont_01J9Z3K8"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Contato não encontrado."
}

CRM — Empresas

Seção intitulada “CRM — Empresas”

Pessoas jurídicas do CRM. Documentação detalhada em Empresas.

MétodoPathDescriçãoAuth
GET/crm/companiesLista empresas CRM (paginado, buscável, filtrável)✅
POST/crm/companiesCria uma empresa CRM✅
GET/crm/companies/{id}Retorna uma empresa CRM✅
PATCH/crm/companies/{id}Atualiza parcialmente uma empresa CRM✅
DELETE/crm/companies/{id}Remove uma empresa CRM✅
GET/crm/companies/{id}/contactsLista os contatos da empresa CRM✅
GET/crm/companies/{id}/dealsLista os negócios da empresa CRM✅
POST /crm/companies

Criar empresa CRM

Cria uma empresa (pessoa jurídica) no CRM da empresa ativa. O campo annual_revenue é um inteiro em centavos.

Corpo (body)

CampoTipoObrigatórioDescrição
name string Sim Razão social ou nome fantasia.
document string — CNPJ.
industry string — Setor de atuação.
website string — Site da empresa.
size string — Porte da empresa.
annual_revenue integer — Faturamento anual em centavos.
phone string — Telefone.
tags string[] — Lista de tags.
notes string — Observações livres. 
curl -X POST https://api.maestron.com.br/v1/crm/companies \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Indústria Ltda",
    "document": "12.345.678/0001-90",
    "industry": "Manufatura",
    "website": "https://acme.example.com",
    "size": "51-200",
    "annual_revenue": 1500000000,
    "phone": "+551133334444",
    "tags": [
      "parceiro"
    ],
    "notes": "Cliente estratégico."
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/companies', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'name' => 'Acme Indústria Ltda',
        'document' => '12.345.678/0001-90',
        'industry' => 'Manufatura',
        'website' => 'https://acme.example.com',
        'size' => '51-200',
        'annual_revenue' => 1500000000,
        'phone' => '+551133334444',
        'tags' => parceiro,
        'notes' => 'Cliente estratégico.',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "Acme Indústria Ltda",
    "document": "12.345.678/0001-90",
    "industry": "Manufatura",
    "website": "https://acme.example.com",
    "size": "51-200",
    "annual_revenue": 1500000000,
    "phone": "+551133334444",
    "tags": parceiro,
    "notes": "Cliente estratégico.",
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/companies",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/companies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Acme Indústria Ltda",
    "document": "12.345.678/0001-90",
    "industry": "Manufatura",
    "website": "https://acme.example.com",
    "size": "51-200",
    "annual_revenue": 1500000000,
    "phone": "+551133334444",
    "tags": [
      "parceiro"
    ],
    "notes": "Cliente estratégico."
  }),
});
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\":\"Acme Indústria Ltda\",\"document\":\"12.345.678/0001-90\",\"industry\":\"Manufatura\",\"website\":\"https://acme.example.com\",\"size\":\"51-200\",\"annual_revenue\":1500000000,\"phone\":\"+551133334444\",\"tags\":[\"parceiro\"],\"notes\":\"Cliente estratégico.\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/crm/companies", payload);
var data = await response.Content.ReadAsStringAsync();
POST /crm/companies HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "name": "Acme Indústria Ltda",
  "document": "12.345.678/0001-90",
  "industry": "Manufatura",
  "website": "https://acme.example.com",
  "size": "51-200",
  "annual_revenue": 1500000000,
  "phone": "+551133334444",
  "tags": [
    "parceiro"
  ],
  "notes": "Cliente estratégico."
}

Respostas

{
  "message": "Empresa criada.",
  "data": {
    "id": "comp_01J9Z3K8",
    "name": "Acme Indústria Ltda",
    "document": "12.345.678/0001-90",
    "industry": "Manufatura",
    "website": "https://acme.example.com",
    "size": "51-200",
    "annual_revenue": 1500000000,
    "phone": "+551133334444",
    "tags": [
      "parceiro"
    ],
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Já existe uma empresa com este documento nesta empresa."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "name": [
      "O campo nome é obrigatório."
    ]
  }
}

CRM — Negócios

Seção intitulada “CRM — Negócios”

Oportunidades de venda em pipelines. Documentação detalhada em Negócios.

MétodoPathDescriçãoAuth
GET/crm/dealsLista negócios (paginado, buscável, filtrável)✅
POST/crm/dealsCria um negócio✅
GET/crm/deals/{id}Retorna um negócio✅
PATCH/crm/deals/{id}Atualiza parcialmente um negócio✅
DELETE/crm/deals/{id}Remove um negócio✅
PATCH/crm/deals/{id}/stageMove o negócio para outro estágio✅
POST/crm/deals/{id}/winMarca o negócio como ganho✅
POST/crm/deals/{id}/loseMarca o negócio como perdido✅
POST/crm/deals/{id}/reopenReabre um negócio ganho ou perdido✅
GET/crm/deals/{id}/activitiesLista as atividades vinculadas ao negócio✅
POST /crm/deals

Criar negócio

Cria um negócio em um pipeline e estágio existentes. O campo value é um inteiro em centavos e probability vai de 0 a 100.

Corpo (body)

CampoTipoObrigatórioDescrição
title string Sim Título do negócio.
pipeline_id string Sim Pipeline do negócio (pipe_).
stage_id string Sim Estágio do negócio (stg_).
value integer — Valor do negócio em centavos.
contact_id string — Contato vinculado (cont_).
company_id string — Empresa CRM vinculada (comp_).
owner_id string — Responsável pelo negócio (user_).
expected_close_date date — Data prevista de fechamento (YYYY-MM-DD).
probability integer — Probabilidade de fechamento (0 a 100).
tags string[] — Lista de tags. 
curl -X POST https://api.maestron.com.br/v1/crm/deals \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implantação Acme",
    "pipeline_id": "pipe_01J9Z3K8",
    "stage_id": "stg_01J9Z3K8",
    "value": 1500000,
    "contact_id": "cont_01J9Z3K8",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "expected_close_date": "2026-08-31",
    "probability": 40,
    "tags": [
      "enterprise"
    ]
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/deals', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'title' => 'Implantação Acme',
        'pipeline_id' => 'pipe_01J9Z3K8',
        'stage_id' => 'stg_01J9Z3K8',
        'value' => 1500000,
        'contact_id' => 'cont_01J9Z3K8',
        'company_id' => 'comp_01J9Z3K8',
        'owner_id' => 'user_01J9Z3K8',
        'expected_close_date' => '2026-08-31',
        'probability' => 40,
        'tags' => enterprise,
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "title": "Implantação Acme",
    "pipeline_id": "pipe_01J9Z3K8",
    "stage_id": "stg_01J9Z3K8",
    "value": 1500000,
    "contact_id": "cont_01J9Z3K8",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "expected_close_date": "2026-08-31",
    "probability": 40,
    "tags": enterprise,
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/deals",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/deals", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Implantação Acme",
    "pipeline_id": "pipe_01J9Z3K8",
    "stage_id": "stg_01J9Z3K8",
    "value": 1500000,
    "contact_id": "cont_01J9Z3K8",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "expected_close_date": "2026-08-31",
    "probability": 40,
    "tags": [
      "enterprise"
    ]
  }),
});
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(
    "{\"title\":\"Implantação Acme\",\"pipeline_id\":\"pipe_01J9Z3K8\",\"stage_id\":\"stg_01J9Z3K8\",\"value\":1500000,\"contact_id\":\"cont_01J9Z3K8\",\"company_id\":\"comp_01J9Z3K8\",\"owner_id\":\"user_01J9Z3K8\",\"expected_close_date\":\"2026-08-31\",\"probability\":40,\"tags\":[\"enterprise\"]}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/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

{
  "title": "Implantação Acme",
  "pipeline_id": "pipe_01J9Z3K8",
  "stage_id": "stg_01J9Z3K8",
  "value": 1500000,
  "contact_id": "cont_01J9Z3K8",
  "company_id": "comp_01J9Z3K8",
  "owner_id": "user_01J9Z3K8",
  "expected_close_date": "2026-08-31",
  "probability": 40,
  "tags": [
    "enterprise"
  ]
}

Respostas

{
  "message": "Negócio criado.",
  "data": {
    "id": "deal_01J9Z3K8",
    "title": "Implantação Acme",
    "pipeline_id": "pipe_01J9Z3K8",
    "stage_id": "stg_01J9Z3K8",
    "status": "open",
    "value": 1500000,
    "contact_id": "cont_01J9Z3K8",
    "company_id": "comp_01J9Z3K8",
    "owner_id": "user_01J9Z3K8",
    "expected_close_date": "2026-08-31",
    "probability": 40,
    "tags": [
      "enterprise"
    ],
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Pipeline ou estágio não encontrado."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "title": [
      "O campo título é obrigatório."
    ]
  }
}
POST /crm/deals/{id}/win

Marcar negócio como ganho

Fecha o negócio com status won. Retorna 409 se o negócio já estiver fechado.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do negócio (deal_).

Corpo (body)

CampoTipoObrigatórioDescrição
won_at date — Data do ganho (opcional, padrão: data atual).
notes string — Observações sobre o fechamento. 
curl -X POST https://api.maestron.com.br/v1/crm/deals/{id}/win \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "won_at": "2026-06-20",
    "notes": "Contrato assinado."
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/deals/{id}/win', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'won_at' => '2026-06-20',
        'notes' => 'Contrato assinado.',
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "won_at": "2026-06-20",
    "notes": "Contrato assinado.",
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/deals/{id}/win",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/deals/{id}/win", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "won_at": "2026-06-20",
    "notes": "Contrato assinado."
  }),
});
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(
    "{\"won_at\":\"2026-06-20\",\"notes\":\"Contrato assinado.\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/crm/deals/{id}/win", payload);
var data = await response.Content.ReadAsStringAsync();
POST /crm/deals/{id}/win HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "won_at": "2026-06-20",
  "notes": "Contrato assinado."
}

Respostas

{
  "message": "Negócio marcado como ganho.",
  "data": {
    "id": "deal_01J9Z3K8",
    "status": "won",
    "won_at": "2026-06-20T00:00:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Negócio não encontrado."
}
{
  "message": "O negócio já está fechado."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "won_at": [
      "A data informada é inválida."
    ]
  }
}

CRM — Atividades

Seção intitulada “CRM — Atividades”

Tarefas, ligações, reuniões, e-mails e notas. Documentação detalhada em Atividades.

MétodoPathDescriçãoAuth
GET/crm/activitiesLista atividades (paginado, buscável, filtrável)✅
POST/crm/activitiesCria uma atividade✅
GET/crm/activities/{id}Retorna uma atividade✅
PATCH/crm/activities/{id}Atualiza parcialmente uma atividade✅
DELETE/crm/activities/{id}Remove uma atividade✅
POST/crm/activities/{id}/completeMarca a atividade como concluída✅
POST/crm/activities/{id}/reopenReabre uma atividade concluída✅
POST /crm/activities

Criar atividade

Cria uma atividade, opcionalmente vinculada a um contato, empresa CRM ou negócio via related_to.

Corpo (body)

CampoTipoObrigatórioDescrição
type string Sim Tipo: call, meeting, email, task ou note.
title string Sim Título da atividade.
description string — Descrição da atividade.
scheduled_at string — Data e hora agendada (ISO-8601).
duration_minutes integer — Duração estimada em minutos.
owner_id string — Responsável pela atividade (user_).
related_to.type string — Tipo da entidade relacionada: contact, company ou deal.
related_to.id string — Identificador da entidade relacionada. 
curl -X POST https://api.maestron.com.br/v1/crm/activities \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "meeting",
    "title": "Reunião de descoberta",
    "description": "Mapear necessidades do cliente.",
    "scheduled_at": "2026-06-25T15:00:00Z",
    "duration_minutes": 45,
    "owner_id": "user_01J9Z3K8",
    "related_to": {
      "type": "deal",
      "id": "deal_01J9Z3K8"
    }
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/activities', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'type' => 'meeting',
        'title' => 'Reunião de descoberta',
        'description' => 'Mapear necessidades do cliente.',
        'scheduled_at' => '2026-06-25T15:00:00Z',
        'duration_minutes' => 45,
        'owner_id' => 'user_01J9Z3K8',
        'related_to' => [object Object],
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "type": "meeting",
    "title": "Reunião de descoberta",
    "description": "Mapear necessidades do cliente.",
    "scheduled_at": "2026-06-25T15:00:00Z",
    "duration_minutes": 45,
    "owner_id": "user_01J9Z3K8",
    "related_to": [object Object],
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/activities",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/activities", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "meeting",
    "title": "Reunião de descoberta",
    "description": "Mapear necessidades do cliente.",
    "scheduled_at": "2026-06-25T15:00:00Z",
    "duration_minutes": 45,
    "owner_id": "user_01J9Z3K8",
    "related_to": {
      "type": "deal",
      "id": "deal_01J9Z3K8"
    }
  }),
});
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(
    "{\"type\":\"meeting\",\"title\":\"Reunião de descoberta\",\"description\":\"Mapear necessidades do cliente.\",\"scheduled_at\":\"2026-06-25T15:00:00Z\",\"duration_minutes\":45,\"owner_id\":\"user_01J9Z3K8\",\"related_to\":{\"type\":\"deal\",\"id\":\"deal_01J9Z3K8\"}}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/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

{
  "type": "meeting",
  "title": "Reunião de descoberta",
  "description": "Mapear necessidades do cliente.",
  "scheduled_at": "2026-06-25T15:00:00Z",
  "duration_minutes": 45,
  "owner_id": "user_01J9Z3K8",
  "related_to": {
    "type": "deal",
    "id": "deal_01J9Z3K8"
  }
}

Respostas

{
  "message": "Atividade criada.",
  "data": {
    "id": "act_01J9Z3K8",
    "type": "meeting",
    "title": "Reunião de descoberta",
    "status": "pending",
    "scheduled_at": "2026-06-25T15:00:00Z",
    "duration_minutes": 45,
    "owner_id": "user_01J9Z3K8",
    "related_to": {
      "type": "deal",
      "id": "deal_01J9Z3K8"
    },
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Entidade relacionada não encontrada."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "type": [
      "O campo tipo é obrigatório."
    ]
  }
}

CRM — Pipelines

Seção intitulada “CRM — Pipelines”

Funis de vendas. Documentação detalhada em Pipelines.

MétodoPathDescriçãoAuth
GET/crm/pipelinesLista pipelines com estágios e contadores✅
POST/crm/pipelinesCria um pipeline, opcionalmente com estágios✅
GET/crm/pipelines/{id}Retorna um pipeline com estágios ordenados✅
PATCH/crm/pipelines/{id}Atualiza nome e/ou is_default do pipeline✅
DELETE/crm/pipelines/{id}Remove um pipeline✅
POST /crm/pipelines

Criar pipeline

Cria um pipeline, opcionalmente já com seus estágios. Cada estágio possui name, order e probability (0 a 100).

Corpo (body)

CampoTipoObrigatórioDescrição
name string Sim Nome do pipeline.
is_default boolean — Define o pipeline como padrão.
stages object[] — Estágios iniciais: name, order e probability. 
curl -X POST https://api.maestron.com.br/v1/crm/pipelines \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Funil de Vendas",
    "is_default": true,
    "stages": [
      {
        "name": "Prospecção",
        "order": 1,
        "probability": 10
      },
      {
        "name": "Proposta",
        "order": 2,
        "probability": 50
      },
      {
        "name": "Fechamento",
        "order": 3,
        "probability": 90
      }
    ]
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/crm/pipelines', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'name' => 'Funil de Vendas',
        'is_default' => true,
        'stages' => [object Object],[object Object],[object Object],
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "name": "Funil de Vendas",
    "is_default": True,
    "stages": [object Object],[object Object],[object Object],
}
response = requests.post(
    "https://api.maestron.com.br/v1/crm/pipelines",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/pipelines", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Funil de Vendas",
    "is_default": true,
    "stages": [
      {
        "name": "Prospecção",
        "order": 1,
        "probability": 10
      },
      {
        "name": "Proposta",
        "order": 2,
        "probability": 50
      },
      {
        "name": "Fechamento",
        "order": 3,
        "probability": 90
      }
    ]
  }),
});
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 de Vendas\",\"is_default\":true,\"stages\":[{\"name\":\"Prospecção\",\"order\":1,\"probability\":10},{\"name\":\"Proposta\",\"order\":2,\"probability\":50},{\"name\":\"Fechamento\",\"order\":3,\"probability\":90}]}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/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 de Vendas",
  "is_default": true,
  "stages": [
    {
      "name": "Prospecção",
      "order": 1,
      "probability": 10
    },
    {
      "name": "Proposta",
      "order": 2,
      "probability": 50
    },
    {
      "name": "Fechamento",
      "order": 3,
      "probability": 90
    }
  ]
}

Respostas

{
  "message": "Pipeline criado.",
  "data": {
    "id": "pipe_01J9Z3K8",
    "name": "Funil de Vendas",
    "is_default": true,
    "stages": [
      {
        "id": "stg_01J9Z3K8",
        "name": "Prospecção",
        "order": 1,
        "probability": 10
      },
      {
        "id": "stg_01J9Z3K9",
        "name": "Proposta",
        "order": 2,
        "probability": 50
      },
      {
        "id": "stg_01J9Z3KA",
        "name": "Fechamento",
        "order": 3,
        "probability": 90
      }
    ],
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "name": [
      "O campo nome é obrigatório."
    ]
  }
}

CRM — Estágios

Seção intitulada “CRM — Estágios”

Etapas de um pipeline. Documentação detalhada em Pipelines.

MétodoPathDescriçãoAuth
GET/crm/pipelines/{id}/stagesLista os estágios de um pipeline (ordenados)✅
POST/crm/pipelines/{id}/stagesCria um estágio no pipeline✅
GET/crm/pipelines/{id}/stages/{stage_id}Retorna um estágio do pipeline✅
PATCH/crm/pipelines/{id}/stages/{stage_id}Atualiza um estágio✅
DELETE/crm/pipelines/{id}/stages/{stage_id}Remove um estágio✅
PATCH/crm/pipelines/{id}/stages/reorderReordena os estágios em lote✅
PATCH /crm/pipelines/{id}/stages/reorder

Reordenar estágios

Reordena os estágios de um pipeline em lote. O corpo envia a nova ordem de cada estágio.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do pipeline (pipe_).

Corpo (body)

CampoTipoObrigatórioDescrição
stages object[] Sim Lista de estágios com id (stg_) e order. 
curl -X PATCH https://api.maestron.com.br/v1/crm/pipelines/{id}/stages/reorder \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stages": [
      {
        "id": "stg_01J9Z3KA",
        "order": 1
      },
      {
        "id": "stg_01J9Z3K9",
        "order": 2
      },
      {
        "id": "stg_01J9Z3K8",
        "order": 3
      }
    ]
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/v1/crm/pipelines/{id}/stages/reorder', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'stages' => [object Object],[object Object],[object Object],
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "stages": [object Object],[object Object],[object Object],
}
response = requests.patch(
    "https://api.maestron.com.br/v1/crm/pipelines/{id}/stages/reorder",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/crm/pipelines/{id}/stages/reorder", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "stages": [
      {
        "id": "stg_01J9Z3KA",
        "order": 1
      },
      {
        "id": "stg_01J9Z3K9",
        "order": 2
      },
      {
        "id": "stg_01J9Z3K8",
        "order": 3
      }
    ]
  }),
});
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(
    "{\"stages\":[{\"id\":\"stg_01J9Z3KA\",\"order\":1},{\"id\":\"stg_01J9Z3K9\",\"order\":2},{\"id\":\"stg_01J9Z3K8\",\"order\":3}]}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/v1/crm/pipelines/{id}/stages/reorder") { Content = payload });
var data = await response.Content.ReadAsStringAsync();
PATCH /crm/pipelines/{id}/stages/reorder HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "stages": [
    {
      "id": "stg_01J9Z3KA",
      "order": 1
    },
    {
      "id": "stg_01J9Z3K9",
      "order": 2
    },
    {
      "id": "stg_01J9Z3K8",
      "order": 3
    }
  ]
}

Respostas

{
  "message": "Estágios reordenados.",
  "data": [
    {
      "id": "stg_01J9Z3KA",
      "order": 1
    },
    {
      "id": "stg_01J9Z3K9",
      "order": 2
    },
    {
      "id": "stg_01J9Z3K8",
      "order": 3
    }
  ]
}
{
  "message": "Não autenticado."
}
{
  "message": "Pipeline não encontrado."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "stages": [
      "O campo stages é obrigatório."
    ]
  }
}

Webhooks

Seção intitulada “Webhooks”

Entrega de eventos para URLs externas, com gestão de entregas e secret de assinatura. Documentação detalhada em Webhooks.

MétodoPathDescriçãoAuth
GET/webhooksLista os webhooks da empresa ativa✅
POST/webhooksCria um webhook✅
GET/webhooks/eventsLista os tipos de eventos disponíveis✅
GET/webhooks/{id}Retorna um webhook✅
PATCH/webhooks/{id}Atualiza um webhook✅
DELETE/webhooks/{id}Remove um webhook✅
POST/webhooks/{id}/pingEnvia um evento de teste para o webhook✅
POST/webhooks/{id}/rotate-secretGera um novo secret de assinatura✅
GET/webhooks/{id}/deliveriesLista as entregas do webhook✅
GET/webhooks/{id}/deliveries/{delivery_id}Retorna uma entrega✅
POST/webhooks/{id}/deliveries/{delivery_id}/retryReenvia uma entrega que falhou✅
POST /webhooks

Criar webhook

Registra um webhook para receber eventos. O campo events recebe os tipos retornados por GET /webhooks/events.

Corpo (body)

CampoTipoObrigatórioDescrição
url string Sim URL de destino das entregas.
events string[] Sim Tipos de eventos assinados.
secret string — Secret usado na assinatura do payload.
is_active boolean — Ativa ou desativa o webhook. 
curl -X POST https://api.maestron.com.br/v1/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.exemplo.com/webhooks/maestron",
    "events": [
      "crm.contact.created",
      "crm.deal.won"
    ],
    "secret": "whsec_exemplo",
    "is_active": true
  }'
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/webhooks', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'url' => 'https://app.exemplo.com/webhooks/maestron',
        'events' => crm.contact.created,crm.deal.won,
        'secret' => 'whsec_exemplo',
        'is_active' => true,
    ],
]);
$data = json_decode($response->getBody(), true);
import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "url": "https://app.exemplo.com/webhooks/maestron",
    "events": crm.contact.created,crm.deal.won,
    "secret": "whsec_exemplo",
    "is_active": True,
}
response = requests.post(
    "https://api.maestron.com.br/v1/webhooks",
    headers=headers,
    json=payload,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://app.exemplo.com/webhooks/maestron",
    "events": [
      "crm.contact.created",
      "crm.deal.won"
    ],
    "secret": "whsec_exemplo",
    "is_active": true
  }),
});
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(
    "{\"url\":\"https://app.exemplo.com/webhooks/maestron\",\"events\":[\"crm.contact.created\",\"crm.deal.won\"],\"secret\":\"whsec_exemplo\",\"is_active\":true}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/webhooks", payload);
var data = await response.Content.ReadAsStringAsync();
POST /webhooks HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "url": "https://app.exemplo.com/webhooks/maestron",
  "events": [
    "crm.contact.created",
    "crm.deal.won"
  ],
  "secret": "whsec_exemplo",
  "is_active": true
}

Respostas

{
  "message": "Webhook criado.",
  "data": {
    "id": "whk_01J9Z3K8",
    "url": "https://app.exemplo.com/webhooks/maestron",
    "events": [
      "crm.contact.created",
      "crm.deal.won"
    ],
    "is_active": true,
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "url": [
      "O campo url é obrigatório."
    ]
  }
}
POST /webhooks/{id}/deliveries/{delivery_id}/retry

Reenviar entrega

Reenvia manualmente uma entrega que falhou. Retorna 409 se a entrega não estiver em estado reenviável.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
id string Sim Identificador do webhook (whk_).
delivery_id string Sim Identificador da entrega (whd_). 
curl -X POST https://api.maestron.com.br/v1/webhooks/{id}/deliveries/{delivery_id}/retry \
  -H "Authorization: Bearer SEU_TOKEN"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/webhooks/{id}/deliveries/{delivery_id}/retry', [
    '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/v1/webhooks/{id}/deliveries/{delivery_id}/retry",
    headers=headers,
)
data = response.json()
const response = await fetch("https://api.maestron.com.br/v1/webhooks/{id}/deliveries/{delivery_id}/retry", {
  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/v1/webhooks/{id}/deliveries/{delivery_id}/retry", null);
var data = await response.Content.ReadAsStringAsync();
POST /webhooks/{id}/deliveries/{delivery_id}/retry HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

{
  "message": "Entrega reenviada.",
  "data": {
    "id": "whd_01J9Z3K8",
    "status": "pending",
    "attempts": 2
  }
}
{
  "message": "Não autenticado."
}
{
  "message": "Entrega não encontrada."
}
{
  "message": "A entrega não está em estado reenviável."
}

Módulos futuros

Seção intitulada “Módulos futuros”

Os módulos abaixo seguirão as mesmas convenções de envelope, autenticação e identificadores descritas nesta referência.

MóduloStatus
EstoqueEm breve
HelpdeskEm breve
MarketingEm breve