Companies

Uma company é o registro de um cliente da empresa — pode ser uma pessoa física (kind: individual) ou uma organização (kind: organization). É o cadastro central: documento (CPF/CNPJ), endereço e dados de contato. Um contact é sempre uma pessoa dentro de uma company organização.

Nome interno: Customer

Internamente esse recurso é o cadastro de clientes (Customer) do painel Maestron, compartilhado entre CRM e outros módulos. O nome público company segue o vocabulário do contrato da API.

Escopo: customers.view para leitura, customers.manage para escrita — ver Escopos & Permissões.

Esquema

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	leitura	Identificador da company.
kind	string	sim	individual (pessoa física) ou organization (pessoa jurídica).
name	string	sim	Nome da pessoa ou razão social.
legal_name	string | null	não	Nome fantasia ou outra denominação.
document	string | null	não	CPF ou CNPJ, só dígitos. Único por empresa. Aceita entrada mascarada — os dígitos são extraídos antes de gravar.
document_type	string | null	leitura*	cpf, cnpj ou other. Derivado do tamanho do document quando não informado.
email	string | null	não
phone	string | null	não
owner_user_id	string (UUID) | null	não	Usuário da empresa responsável por esta company.
notes	string | null	não	Texto livre. Máx. 20000 caracteres.
metadata	object	não	Objeto livre.
active	boolean	não	Padrão true.
address_street, address_number, address_complement, address_neighborhood, address_city, address_state, address_zipcode	string | null	não	Endereço. address_state com 2 letras.
cnae_code, cnae_description, registration_status, opened_at	string/date | null	não	Dados de registro (tipicamente de uma organização).
created_at	string (ISO-8601)	leitura
updated_at	string (ISO-8601)	leitura

Listar companies

GET /crm/companies Copiar para LLM

Listar companies

Retorna as companies da empresa, paginado, ordenado por nome.

Parâmetros de query

Campo	Tipo	Obrigatório	Descrição
kind	string	—	individual ou organization.
document_type	string	—	cpf, cnpj ou other.
active	boolean	—
search	string	—	Busca livre por nome, razão social, e-mail ou documento (dígitos).
per_page	integer	—	Entre 1 e 100. Padrão 20.

cURLPHPPythonNode.jsC#HTTP / Postman

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

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

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

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

Respostas

200 · Sucesso401 · Não autenticado403 · Sem escopo

{
  "message": "Companies.",
  "data": [
    {
      "id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
      "kind": "organization",
      "name": "ACME Distribuidora LTDA",
      "legal_name": "ACME",
      "document": "12345678000190",
      "document_type": "cnpj",
      "email": "contato@acme.com",
      "phone": null,
      "owner_user_id": null,
      "notes": null,
      "metadata": {},
      "active": true,
      "address_street": null,
      "address_number": null,
      "address_complement": null,
      "address_neighborhood": null,
      "address_city": null,
      "address_state": null,
      "address_zipcode": null,
      "cnae_code": null,
      "cnae_description": null,
      "registration_status": null,
      "opened_at": null,
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

Obter uma company

GET /crm/companies/{id} Copiar para LLM

Obter company

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da company (UUID).

cURLPHPPythonNode.jsC#HTTP / Postman

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

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

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

GET /crm/companies/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Sucesso401 · Não autenticado404 · Não encontrado

{
  "message": "Company.",
  "data": {
    "id": "a1b2c3d4-1111-4a5b-8c9d-0e1f2a3b4c5d",
    "kind": "organization",
    "name": "ACME Distribuidora LTDA"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Criar company

POST /crm/companies Copiar para LLM

Criar company

idempotency_key é opcional — ver Sandbox & Idempotência.

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
kind	string	Sim	individual ou organization.
name	string	Sim	Máx. 200 caracteres.
legal_name	string	—
document	string	—	CPF/CNPJ, com ou sem máscara. Único por empresa.
email	string	—
phone	string	—
owner_user_id	string	—
active	boolean	—	Padrão true.
idempotency_key	string	—

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X POST https://api.maestron.com.br/api/v1/crm/companies \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "organization",
    "name": "Nova Cliente LTDA",
    "document": "12.345.678/0001-90",
    "email": "contato@novacliente.com"
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maestron.com.br/api/v1/crm/companies', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'kind' => 'organization',
        'name' => 'Nova Cliente LTDA',
        'document' => '12.345.678/0001-90',
        'email' => 'contato@novacliente.com',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "kind": "organization",
    "name": "Nova Cliente LTDA",
    "document": "12.345.678/0001-90",
    "email": "contato@novacliente.com",
}
response = requests.post(
    "https://api.maestron.com.br/api/v1/crm/companies",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/companies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "kind": "organization",
    "name": "Nova Cliente LTDA",
    "document": "12.345.678/0001-90",
    "email": "contato@novacliente.com"
  }),
});
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(
    "{\"kind\":\"organization\",\"name\":\"Nova Cliente LTDA\",\"document\":\"12.345.678/0001-90\",\"email\":\"contato@novacliente.com\"}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.maestron.com.br/api/v1/crm/companies", payload);
var data = await response.Content.ReadAsStringAsync();

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

{
  "kind": "organization",
  "name": "Nova Cliente LTDA",
  "document": "12.345.678/0001-90",
  "email": "contato@novacliente.com"
}

Respostas

201 · Criado401 · Não autenticado403 · Sem escopo422 · Validação

{
  "message": "Company criado.",
  "data": {
    "id": "b2c3d4e5-2222-4a5b-8c9d-0e1f2a3b4c5d",
    "kind": "organization",
    "name": "Nova Cliente LTDA",
    "document": "12345678000190",
    "document_type": "cnpj",
    "active": true,
    "created_at": "2026-06-20T14:30:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "kind": [
      "O campo tipo não contém um valor válido."
    ],
    "document": [
      "O campo documento já está em uso."
    ]
  }
}

Atualizar company

PATCH /crm/companies/{id} Copiar para LLM

Atualizar company

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim

Corpo (body)

Campo	Tipo	Obrigatório	Descrição
name	string	—
active	boolean	—

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X PATCH https://api.maestron.com.br/api/v1/crm/companies/{id} \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('PATCH', 'https://api.maestron.com.br/api/v1/crm/companies/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
    'json' => [
        'active' => false,
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
payload = {
    "active": False,
}
response = requests.patch(
    "https://api.maestron.com.br/api/v1/crm/companies/{id}",
    headers=headers,
    json=payload,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/api/v1/crm/companies/{id}", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer SEU_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "active": false
  }),
});
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(
    "{\"active\":false}",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.SendAsync(new HttpRequestMessage(
    new HttpMethod("PATCH"), "https://api.maestron.com.br/api/v1/crm/companies/{id}") { Content = payload });
var data = await response.Content.ReadAsStringAsync();

PATCH /crm/companies/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "active": false
}

Respostas

200 · Atualizado401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Company atualizado.",
  "data": {
    "id": "b2c3d4e5-2222-4a5b-8c9d-0e1f2a3b4c5d",
    "active": false
  }
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Remover company

Contacts não são removidos junto

Remover uma company não apaga os contacts dela — eles ficam órfãos de uma company inexistente. Remova os contacts primeiro se precisar de uma limpeza completa.

DELETE /crm/companies/{id} Copiar para LLM

Remover company

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
id	string	Sim

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X DELETE https://api.maestron.com.br/api/v1/crm/companies/{id} \
  -H "Authorization: Bearer SEU_TOKEN"

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.maestron.com.br/api/v1/crm/companies/{id}', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'Accept' => 'application/json',
    ],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {"Authorization": "Bearer SEU_TOKEN"}
response = requests.delete(
    "https://api.maestron.com.br/api/v1/crm/companies/{id}",
    headers=headers,
)
data = response.json()

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

DELETE /crm/companies/{id} HTTP/1.1
Host: api.maestron.com.br
Authorization: Bearer SEU_TOKEN

Respostas

200 · Removido401 · Não autenticado403 · Sem escopo404 · Não encontrado

{
  "message": "Company removido.",
  "data": null
}

{
  "message": "Não autenticado.",
  "data": null
}

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

{
  "message": "Recurso não encontrado.",
  "data": null
}

Para o detalhamento de cada código de status, consulte Erros.