SDKs & Bibliotecas

A API Maestron é uma API REST sobre HTTP com JSON e autenticação por Bearer token. Pode ser consumida por qualquer cliente HTTP, com ou sem SDK.

SDKs oficiais

Em breve

Os SDKs oficiais ainda não foram publicados. Quando disponíveis, cada um encapsulará autenticação, paginação, tratamento do envelope de resposta e os erros padronizados.

Linguagem	Pacote previsto	Status
Node.js / TypeScript	@maestron/sdk	Em breve
PHP	maestron/maestron-php	Em breve
Python	maestron-python	Em breve
C# / .NET	Maestron.Sdk	Em breve

API em desenvolvimento

A API pública ainda não foi lançada. Esta documentação descreve a API planejada. O módulo CRM é o primeiro disponível; Estoque, Helpdesk e Marketing estão marcados como “Em breve”.

Consumindo a API sem SDK

Enquanto os SDKs não são publicados, a API é consumida diretamente via HTTP. As regras aplicáveis a qualquer chamada:

• Base URL: https://api.maestron.com.br/v1.
• Header Authorization: Bearer SEU_TOKEN em toda requisição autenticada.
• A empresa (tenant) é resolvida automaticamente a partir do token — não há header de empresa. Detalhes em Autenticação.
• Respostas seguem o envelope padrão (message + data); listagens incluem meta. Erros seguem Erros.

O endpoint de login abaixo é público (não exige Authorization) e devolve o token usado nas demais chamadas.

POST /auth/login Copiar para LLM

Autenticar e obter token

Autentica por e-mail e senha e retorna o token Bearer e o contexto de empresa ativo.

Corpo (body)

Campo	Tipo	Obrigatório	Descriçã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.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@empresa.com",
    "password": "sua_senha",
    "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' => 'dev@empresa.com',
        'password' => 'sua_senha',
        'remember_me' => true,
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
payload = {
    "email": "dev@empresa.com",
    "password": "sua_senha",
    "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": "dev@empresa.com",
    "password": "sua_senha",
    "remember_me": true
  }),
});
const data = await response.json();

using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"dev@empresa.com\",\"password\":\"sua_senha\",\"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": "dev@empresa.com",
  "password": "sua_senha",
  "remember_me": true
}

Respostas

200 · Autenticado422 · Validação401 · Credenciais inválidas429 · Excesso de tentativas

{
  "message": "Autenticado com sucesso.",
  "data": {
    "token": "mst_live_8f3c2a91d7b04e6f",
    "token_type": "Bearer",
    "expires_at": "2026-07-20T14:30:00Z",
    "user": {
      "id": "user_01J9Z3K8",
      "name": "Maria Souza",
      "email": "dev@empresa.com"
    },
    "company": {
      "id": "comp_01J9Z3K8",
      "name": "Empresa Exemplo"
    }
  }
}

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

{
  "message": "Credenciais inválidas."
}

{
  "message": "Muitas tentativas. Tente novamente mais tarde."
}

Use o componente acima para copiar o exemplo de login em cURL, PHP, Python, Node.js, C# ou HTTP cru. O endpoint a seguir é a primeira chamada autenticada típica: listar contatos do CRM usando o token obtido.

GET /crm/contacts Copiar para LLM

Listar contatos (request autenticado)

Lista os contatos da empresa resolvida pelo token. Exemplo de primeira chamada autenticada após o login.

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 do contato.

cURLPHPPythonNode.jsC#HTTP / Postman

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

200 · Contatos listados401 · Não autenticado

{
  "message": "Contatos listados.",
  "data": [
    {
      "id": "cont_01J9Z3K8",
      "name": "João Pereira",
      "email": "joao@cliente.com",
      "phone": "+5511999990000",
      "company_id": "comp_01J9Z3K8",
      "tags": [
        "lead",
        "prioritario"
      ],
      "created_at": "2026-06-18T09:12:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

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

Dica

Cada <Endpoint> traz o botão Copiar para LLM, que exporta o request e as respostas em markdown otimizado para uso com modelos de linguagem.

Fluxo mínimo de integração

O mesmo fluxo se aplica a qualquer linguagem, com ou sem SDK:

1. POST /auth/login — obter o token Bearer.
2. Enviar Authorization: Bearer SEU_TOKEN nas chamadas autenticadas.
3. Consumir os recursos do CRM (ex.: GET /crm/contacts).
4. Para trocar de empresa, emitir novo token via POST /auth/context (ver Autenticação).

Quando o token expira, a API retorna 401. Renovação e expiração estão descritas em Autenticação; os códigos de erro, em Erros; e os limites de requisição, em Rate limiting.

Ferramentas de cliente HTTP

Postman

Cliente de API com coleções, ambientes e variáveis. Importa especificações OpenAPI via URL ou arquivo.

Insomnia

Cliente REST e GraphQL com ambientes e encadeamento de requisições. Importa OpenAPI.

Bruno

Cliente open-source que armazena as coleções como arquivos no próprio repositório, versionáveis em Git.

HTTPie

Cliente de linha de comando para testes rápidos no terminal, com sintaxe enxuta para JSON e headers.

Importação de coleção via OpenAPI

Em breve

A especificação OpenAPI da API pública ainda não foi publicada. Quando disponível, ela poderá ser importada diretamente em Postman, Insomnia e Bruno pela URL do documento, gerando automaticamente as requisições de cada endpoint com a Base URL https://api.maestron.com.br/v1.

Até lá, cada endpoint desta documentação pode ser exportado individualmente pela aba HTTP do <Endpoint> (formato cru compatível com a importação “Raw” do Postman) ou pelo botão Copiar para LLM.