Visão Geral

A API Maestron é uma interface REST sobre JSON para integração programática com os módulos da plataforma Maestron. Toda comunicação ocorre por HTTPS, com corpos de requisição e resposta em application/json.

Base URL

Todas as rotas partem da base URL versionada:

https://api.maestron.com.br/v1

A versão (v1) faz parte da URL e é gerenciada centralmente. Os caminhos documentados ao longo desta referência são relativos a essa base — por exemplo, /crm/contacts corresponde a https://api.maestron.com.br/v1/crm/contacts.

Formato REST/JSON

Os métodos HTTP seguem a semântica REST: GET (leitura), POST (criação), PATCH/PUT (atualização), DELETE (remoção).
Requisições com corpo enviam Content-Type: application/json.
As respostas retornam application/json e usam o código de status HTTP adequado à operação.

Envelope de resposta

Toda resposta de sucesso usa um envelope com message e data:

{
  "message": "Registro retornado.",
  "data": {}
}

message: descrição padronizada da operação.
data: o recurso (objeto) ou a coleção (array).
Criação retorna 201; leitura, atualização e ações retornam 200.
Listagens incluem o objeto meta de paginação:

{
  "message": "Registros listados.",
  "data": [],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 0,
    "last_page": 1
  }
}

Respostas de erro usam o envelope com message e, em validação, errors:

{
  "message": "Os dados informados são inválidos.",
  "errors": {
    "email": ["O campo e-mail é obrigatório."]
  }
}

O detalhamento de cada código de status está centralizado em Erros.

Autenticação

As requisições autenticadas enviam o token no header HTTP Authorization:

Authorization: Bearer SEU_TOKEN

A empresa (tenant) é resolvida automaticamente a partir do token — não é necessário informar nenhum header de empresa. O token carrega o contexto da empresa ativa. O fluxo completo de obtenção, renovação e troca de contexto está descrito em Autenticação.

Identificadores e tipos de dado

IDs são strings prefixadas por recurso (ex.: cont_, comp_, deal_), nunca UUID cru.
Valores monetários são inteiros em centavos (ex.: R$ 150,00 vira 15000).
Datas e horários usam ISO-8601 (ex.: 2026-06-20T14:30:00Z).

Módulos

CRM

Contatos, empresas, negócios, pipelines, estágios e atividades. Disponível

Estoque

Produtos, movimentações e controle de inventário. Em breve

Helpdesk

Tickets e atendimento ao cliente. Em breve

Marketing

Campanhas e automações. Em breve

Próximos passos

Autenticação — obtenção e uso do token.
Erros — códigos de status e formato dos erros.
Rate limiting — limites de requisição e headers de controle.