Primeiros passos

Este guia leva você do zero ao primeiro request autenticado: obter credenciais, autenticar e consumir o CRM.

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.

Pré-requisitos

1. Uma conta Maestron com acesso a pelo menos uma empresa.

2. As credenciais de acesso (e-mail e senha) do usuário que fará as requisições.

3. Um cliente HTTP capaz de enviar o header Authorization (cURL, Postman, ou qualquer biblioteca HTTP da sua linguagem).

Como funciona a autenticação

A API usa Bearer token no header Authorization de toda requisição autenticada:

Authorization: Bearer SEU_TOKEN

A empresa (tenant) é resolvida automaticamente a partir do token — o token carrega o contexto da empresa ativa. Não existe header de empresa: você não precisa e não deve enviar nenhum identificador de empresa manualmente.

Dica

Para operar em outra empresa à qual o usuário pertence, emita um novo token com o contexto daquela empresa via POST /auth/context. Detalhes em Autenticação.

Passo 1 — Login

Envie e-mail e senha para obter o token. Este endpoint é público e não exige Authorization.

POST /auth/login Copiar para LLM

Autenticar e obter token

Troca e-mail e senha por um token Bearer com o contexto da empresa ativa.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	E-mail do usuário.
password	string	Sim	Senha do usuário.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@empresa.com.br",
    "password": "senha-secreta"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/login', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'email' => 'usuario@empresa.com.br',
        'password' => 'senha-secreta',
    ],
]);
$data = json_decode($response->getBody(), true);

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

using var client = new HttpClient();
var payload = new StringContent(
    "{\"email\":\"usuario@empresa.com.br\",\"password\":\"senha-secreta\"}",
    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@empresa.com.br",
  "password": "senha-secreta"
}

Respostas

200 · Sucesso401 · Credenciais inválidas422 · Validação429 · Excesso de tentativas

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

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

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

{
  "message": "Muitas tentativas de login. Tente novamente em instantes."
}

Guarde o valor de data.token: ele vai no header Authorization de todas as próximas chamadas.

Nota

O formato exato de erro de cada status está centralizado em Erros. Os limites de tentativas (429) estão em Rate limiting.

Passo 2 — Primeira chamada autenticada

Com o token em mãos, liste os contatos do CRM. A empresa é resolvida pelo token — nenhum identificador de empresa é enviado.

GET /crm/contacts Copiar para LLM

Listar contatos

Retorna a primeira página de contatos da empresa resolvida pelo token.

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 · Sucesso401 · Não autenticado

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

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

Uma resposta 200 com o envelope acima confirma que a integração está funcionando ponta a ponta.

Tratamento de erro

A API responde sempre com o envelope de erro:

{
  "message": "string",
  "errors": {
    "campo": ["mensagem"]
  }
}

O campo errors aparece apenas em validação (422). Os dois erros mais comuns nos primeiros requests:

401 — Não autenticado

O token está ausente, malformado ou expirado. Verifique o header Authorization: Bearer SEU_TOKEN e refaça o login (Passo 1) se o token tiver expirado.

422 — Validação

O corpo da requisição não passou na validação. O objeto errors indica, por campo, o que precisa ser corrigido.

A lista completa de códigos de status e seus significados está em Erros.

Próximos passos

Autenticação

Token, expiração, troca de contexto de empresa e endpoints públicos. Ver Autenticação.

CRM — Contatos

CRUD completo de contatos, filtros e sub-recursos. Ver Contatos.

Erros

Todos os códigos de status e o formato do envelope de erro. Ver Erros.

Rate limiting

Limites de requisição e headers de controle. Ver Rate limiting.