Referência da API

Referência completa dos endpoints da API pública Maestron, organizada pelo ciclo do CRM: pipeline → estágio → negócio → atividade. Cada recurso tem uma página dedicada com o detalhamento de campos e exemplos de request/response.

A base URL é https://api.maestron.com.br/api/v1. A autenticação usa uma API Key no header Authorization: Bearer <segredo> — não JWT de usuário. 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, os escopos em Escopos & Permissões e os limites de uso em Rate limiting.

Convenções da coluna Escopo

Cada linha mostra o escopo mínimo exigido — ver o detalhamento completo, incluindo escopos finos dentro de um mesmo endpoint, em Escopos & Permissões.

Pipelines & Estágios

Funis de vendas e seus estágios. Documentação detalhada em Pipelines & Estágios.

Método	Path	Descrição	Escopo
`GET`	`/crm/pipelines`	Lista os pipelines da empresa	`crm.view`
`GET`	`/crm/pipelines/{id}`	Retorna um pipeline com seus estágios	`crm.view`
`GET`	`/crm/pipelines/{id}/stages`	Lista os estágios de um pipeline	`crm.view`
`POST`	`/crm/pipelines`	Cria um pipeline com seus estágios iniciais	`crm.funnels.manage`
`PATCH`	`/crm/pipelines/{id}`	Atualiza o pipeline e sincroniza estágios	`crm.funnels.manage`
`DELETE`	`/crm/pipelines/{id}`	Remove o pipeline e seus negócios	`crm.funnels.manage`

Negócios (Deals)

Oportunidades de venda dentro de um pipeline. Documentação detalhada em Negócios.

Método	Path	Descrição	Escopo
`GET`	`/crm/deals`	Lista negócios, paginado	`crm.view`
`GET`	`/crm/deals/{id}`	Retorna um negócio	`crm.view`
`GET`	`/crm/deals/{id}/activities`	Lista as atividades do negócio	`crm.view`
`POST`	`/crm/deals`	Cria um negócio	`crm.leads.create`
`PATCH`	`/crm/deals/{id}`	Atualiza parcialmente um negócio	`crm.leads.edit`
`DELETE`	`/crm/deals/{id}`	Remove um negócio	`crm.leads.delete`
`PATCH`	`/crm/deals/{id}/stage`	Move o negócio para outro estágio	`crm.leads.edit`
`POST`	`/crm/deals/{id}/win`	Marca o negócio como ganho	`crm.leads.close`
`POST`	`/crm/deals/{id}/lose`	Marca o negócio como perdido	`crm.leads.close`
`POST`	`/crm/deals/{id}/reopen`	Reabre um negócio ganho ou perdido	`crm.leads.close`

Atividades

Ligações, reuniões, tarefas e notas vinculadas a um negócio. Documentação detalhada em Atividades.

Método	Path	Descrição	Escopo
`GET`	`/crm/activities`	Lista atividades, paginado	`crm.view`
`GET`	`/crm/activities/{id}`	Retorna uma atividade	`crm.view`
`POST`	`/crm/activities`	Cria uma atividade	`crm.leads.edit`
`PATCH`	`/crm/activities/{id}`	Atualiza parcialmente uma atividade	`crm.leads.edit`
`DELETE`	`/crm/activities/{id}`	Remove uma atividade	`crm.leads.edit`
`POST`	`/crm/activities/{id}/complete`	Marca a atividade como concluída	`crm.leads.edit`
`POST`	`/crm/activities/{id}/reopen`	Reabre uma atividade concluída	`crm.leads.edit`

Catálogo do CRM

Produtos e serviços comerciais usados em negócios e orçamentos. Documentação detalhada em Catálogo do CRM.

Método	Path	Descrição	Escopo
`GET`	`/crm/catalog-items`	Lista os itens do catálogo, paginado	`crm.view`
`GET`	`/crm/catalog-items/{id}`	Retorna um item do catálogo	`crm.view`
`POST`	`/crm/catalog-items`	Cria um item (ou vincula um produto do estoque)	`crm.catalog.manage`
`PATCH`	`/crm/catalog-items/{id}`	Atualiza parcialmente um item	`crm.catalog.manage`
`DELETE`	`/crm/catalog-items/{id}`	Remove um item	`crm.catalog.manage`

Companies & Contacts

Cadastro de clientes (pessoas e organizações) e das pessoas dentro deles. Documentação detalhada em Companies e Contacts.

Método	Path	Descrição	Escopo
`GET`	`/crm/companies`	Lista as companies da empresa, paginado	`customers.view`
`GET`	`/crm/companies/{id}`	Retorna uma company	`customers.view`
`POST`	`/crm/companies`	Cria uma company (pessoa física ou organização)	`customers.manage`
`PATCH`	`/crm/companies/{id}`	Atualiza parcialmente uma company	`customers.manage`
`DELETE`	`/crm/companies/{id}`	Remove uma company	`customers.manage`
`GET`	`/crm/contacts`	Lista contacts, paginado, opcionalmente por `company_id`	`customers.view`
`GET`	`/crm/contacts/{id}`	Retorna um contact	`customers.view`
`POST`	`/crm/contacts`	Cria um contact numa company organização	`customers.manage`
`PATCH`	`/crm/contacts/{id}`	Atualiza parcialmente um contact	`customers.manage`
`DELETE`	`/crm/contacts/{id}`	Remove um contact	`customers.manage`

Captação de Leads

Endpoint público que cria negócios a partir de um formulário de site. Não usa API Key — a identidade vem de um token publicável (mcf_...) na URL, configurado por funil no painel. Documentação detalhada em Captação de Leads.

Método	Path	Descrição	Escopo
`POST`	`/crm/intake/{token}`	Cria um negócio no funil/estágio do formulário	token publicável (sem API Key)
`GET`	`/crm/intake/{token}/config`	Configuração do formulário para a tag `intake.js`	token publicável (sem API Key)
`GET`	`/crm/intake/{version}/intake.js`	Baixa a tag de captação (versão `1.0`)	público

Webhooks do CRM

Eventos do ciclo de vida do negócio por webhook assinado ou pelo feed de polling. Recurso de plano (integrations.webhooks). Documentação detalhada em Webhooks do CRM.

Método	Path	Descrição	Escopo
`GET`	`/crm/events`	Feed de eventos por polling, paginado por cursor	`crm.view`

Configurar os endpoints de webhook em si é feito no painel (não pela API pública) — aba Webhooks em Configurar funil.

Módulos futuros

A API pública cobre hoje só o módulo CRM. Estoque, Helpdesk e Marketing seguirão as mesmas convenções de envelope, autenticação e escopo quando forem lançados — nenhum tem endpoint público ainda.

Módulo	Status
Estoque	Planejado
Helpdesk	Planejado
Marketing	Planejado