Contexto da empresa (Multi-tenancy)

A API Maestron é multi-tenant: cada conta de usuário pode pertencer a uma ou mais empresas, e todos os recursos (contatos, empresas do CRM, negócios, atividades, pipelines, etc.) são isolados por empresa. A empresa em que uma requisição opera é chamada de contexto da empresa (tenant).

Resolução automática pelo token

A empresa não é informada em nenhum header de requisição. Ela é resolvida automaticamente a partir do Bearer token: o token carrega o contexto da empresa ativa, e a API aplica esse contexto a todas as operações.

Authorization: Bearer SEU_TOKEN

Isso significa que:

• Não existe header de empresa. Qualquer cabeçalho desse tipo é ignorado e não faz parte do contrato da API.
• Cada token está vinculado a exatamente uma empresa. O escopo de tudo o que o token acessa é a empresa nele codificada.
• O mesmo endpoint retorna conjuntos de dados diferentes dependendo do token apresentado, pois cada token resolve a sua própria empresa.

Para detalhes sobre como obter, renovar e usar o token, ver Autenticação.

Isolamento de dados

Todo recurso pertence a uma empresa. As consequências do isolamento são:

• Listagens (GET de coleção) retornam apenas registros da empresa do token. Não há vazamento entre empresas.
• A busca por identificador (GET /{id}) só localiza recursos da empresa do token. Um ID válido em outra empresa responde 404, e não 403 — para não revelar a existência do recurso fora do contexto.
• Operações de escrita (POST, PATCH, PUT, DELETE) afetam exclusivamente recursos da empresa do token.
• Os identificadores prefixados (cont_, comp_, deal_, etc.) são únicos por recurso; ainda assim, a resolução por ID é sempre filtrada pela empresa do token.

Listar as empresas do usuário

Retorna as empresas às quais o usuário autenticado pertence. O resultado indica qual delas é a empresa ativa no token atual.

GET /user/companies Copiar para LLM

Listar empresas do usuário

Lista as empresas às quais o usuário autenticado pertence, indicando a empresa ativa do token atual.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
search	string	—	Busca textual pelo nome da empresa.
page	integer	—	Página atual (padrão: 1).
per_page	integer	—	Itens por página (padrão: 20, máx: 100).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/user/companies \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/user/companies', [
    '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/user/companies",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/user/companies", {
  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/user/companies");
var data = await response.Content.ReadAsStringAsync();

GET /user/companies HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · OK401 · Não autenticado

{
  "message": "Empresas listadas.",
  "data": [
    {
      "id": "comp_01J9Z3K8",
      "name": "Maestron Tecnologia",
      "document": "12.345.678/0001-90",
      "is_active": true,
      "role": "owner"
    },
    {
      "id": "comp_01J9Z3M2",
      "name": "Filial Sul",
      "document": "98.765.432/0001-10",
      "is_active": false,
      "role": "member"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "last_page": 1
  }
}

{
  "message": "Token ausente, inválido ou expirado."
}

O campo is_active indica a empresa resolvida pelo token em uso. O campo role descreve o papel do usuário naquela empresa.

Trocar de contexto

Para operar em outra empresa à qual o usuário pertence, solicite um novo token com o contexto daquela empresa. O token retornado já resolve a empresa sozinho — basta passar a usá-lo no header Authorization. O token anterior continua válido para a empresa que ele representa.

POST /auth/context Copiar para LLM

Trocar o contexto da empresa

Emite um novo token vinculado à empresa informada, desde que o usuário pertença a ela.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
company_id	string	Sim	ID da empresa de destino (prefixo comp_). O usuário precisa pertencer a ela.

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/v1/auth/context \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "comp_01J9Z3M2"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/v1/auth/context', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'company_id' => 'comp_01J9Z3M2',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "company_id": "comp_01J9Z3M2",
}
response = requests.post(
    "https://api.maestron.com.br/v1/auth/context",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/auth/context", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": "comp_01J9Z3M2"
  }),
});
const data = await response.json();

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "SEU_TOKEN");
var payload = new StringContent(
    "{\"company_id\":\"comp_01J9Z3M2\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/v1/auth/context", payload);
var data = await response.Content.ReadAsStringAsync();

POST /auth/context HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "company_id": "comp_01J9Z3M2"
}

Respostas

200 · OK401 · Não autenticado403 · Sem acesso à empresa404 · Empresa não encontrada422 · Validação

{
  "message": "Contexto da empresa alterado.",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "bearer",
    "expires_in": 43200,
    "company": {
      "id": "comp_01J9Z3M2",
      "name": "Filial Sul"
    }
  }
}

{
  "message": "Token ausente, inválido ou expirado."
}

{
  "message": "O usuário não pertence à empresa informada."
}

{
  "message": "Empresa não encontrada."
}

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

Nota

O company_id precisa ser uma empresa retornada por GET /user/companies. Solicitar contexto de uma empresa à qual o usuário não pertence responde 403.

Requisição sem token ou com token de outra empresa

• Sem token (ou com token inválido/expirado): a requisição é rejeitada com 401. Nenhum contexto de empresa é resolvido.
• Token de outra empresa: a requisição é processada no contexto da empresa daquele token. Recursos pertencentes a outra empresa não são visíveis — a busca por ID responde 404. Quando a operação exige um acesso que o papel do usuário naquela empresa não possui, a resposta é 403.

O detalhamento completo de cada código de status fica centralizado em Erros.