Visão Geral do CRM

O módulo CRM é o primeiro disponível na API Maestron. Ele organiza o relacionamento comercial em torno de seis recursos: contatos, empresas, negócios (deals), pipelines, estágios e atividades. Todos os recursos do módulo vivem sob o prefixo /crm e seguem as convenções canônicas da API — autenticação por Bearer token, envelope de resposta padronizado e identificadores prefixados por recurso.

Recursos do módulo

Contatos

Pessoas físicas com quem há relacionamento comercial. Prefixo cont_. Ver Contatos.

Empresas

Organizações às quais contatos e negócios podem estar vinculados. Prefixo comp_. Ver Empresas.

Negócios

Oportunidades comerciais (deals) que percorrem um pipeline. Prefixo deal_. Ver Negócios.

Pipelines

Funis de vendas que agrupam estágios ordenados. Prefixo pipe_. Ver Pipelines.

Estágios

Etapas ordenadas dentro de um pipeline. Prefixo stg_. Ver Estágios.

Atividades

Tarefas, ligações, reuniões e notas associadas a contatos, empresas ou negócios. Prefixo act_. Ver Atividades.

Modelo de dados e relações

As relações entre os recursos do CRM são as seguintes:

Uma empresa (comp_) agrupa zero ou mais contatos (cont_).
Um contato pode pertencer a uma única empresa (company_id), ou a nenhuma.
Um negócio (deal_) está sempre vinculado a um pipeline (pipe_) e a um estágio (stg_) desse pipeline. Pode referenciar opcionalmente um contato e/ou uma empresa.
Um pipeline contém um ou mais estágios ordenados por position.
Um estágio pertence a exatamente um pipeline. Negócios transitam entre estágios do mesmo pipeline.
Uma atividade (act_) é polimórfica: pode estar associada a um contato, a uma empresa ou a um negócio, identificados pelos campos subject_type e subject_id.

Pipeline (pipe_)
  └── Estágio (stg_)  ──┐
                        │
Empresa (comp_)         ├──> Negócio (deal_)
  └── Contato (cont_) ──┘          │
            │                      │
            └──────────────────────┴──> Atividade (act_)

Campos compartilhados

Todos os recursos do CRM expõem os seguintes campos no envelope data:

Campo	Tipo	Descrição
`id`	string	Identificador prefixado por recurso (ver Identificadores).
`created_at`	string	Data e hora de criação em ISO-8601.
`updated_at`	string	Data e hora da última atualização em ISO-8601.

Valores monetários (como value em negócios e annual_revenue em empresas) são inteiros em centavos. Datas e horários são strings em ISO-8601. Os campos específicos de cada recurso estão documentados na respectiva página.

Filtros globais de listagem

Todos os endpoints de listagem do módulo /crm aceitam os mesmos parâmetros via query string. Filtros específicos de cada recurso são documentados na página correspondente.

Parâmetro	Tipo	Descriçã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 nos campos relevantes do recurso.
`sort`	string	Campo de ordenação.
`direction`	`asc` \| `desc`	Direção da ordenação.
`created_from`	date	Filtra por data de criação (início), formato `YYYY-MM-DD`.
`created_to`	date	Filtra por data de criação (fim), formato `YYYY-MM-DD`.

A listagem retorna o envelope de sucesso com data (array) e o objeto meta de paginação. O exemplo abaixo usa o recurso de contatos para ilustrar a forma da resposta; cada recurso documenta seus próprios campos.

GET /crm/contacts

Listar recursos do CRM (exemplo)

Endpoint ilustrativo de listagem demonstrando os filtros globais e o envelope de paginação. Aplica-se a todos os recursos do módulo /crm.

Parâmetros de query

Campo	Tipo	Obrigatório	Descriçã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 nos campos relevantes do recurso.
`sort`	string	—	Campo de ordenação.
`direction`	string	—	Direção da ordenação: asc ou desc.
`created_from`	date	—	Filtra por data de criação (início), formato YYYY-MM-DD.
`created_to`	date	—	Filtra por data de criação (fim), formato YYYY-MM-DD.

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": "Ana Souza",
      "email": "ana.souza@exemplo.com.br",
      "company_id": "comp_01J9Z3K8",
      "created_at": "2026-06-20T14:30:00Z",
      "updated_at": "2026-06-20T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

{
  "message": "Não autenticado."
}

Próximos passos

Contatos — CRUD de pessoas e seus vínculos.
Empresas — CRUD de organizações do CRM.
Negócios — oportunidades, movimentação entre estágios e marcação de ganho/perdido.
Pipelines — funis de vendas e seus estágios.
Estágios — etapas ordenadas dentro de um pipeline.
Atividades — tarefas, ligações, reuniões e notas.

Para o formato completo de erros e códigos de status, ver Erros. Para limites de requisição, ver Rate limiting.