Versionamento

A API Maestron usa versionamento na URL. A versão atual é a v1, presente em todas as rotas:

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

A versão é gerenciada centralmente e faz parte da Base URL. Ver Autenticação para o envio do token e a resolução automática da empresa.

Nota

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”.

Esquema de versão

• O identificador de versão é um único segmento na URL: v1, v2, etc.
• Apenas mudanças incompatíveis (breaking changes) geram uma nova versão major.
• Mudanças retrocompatíveis são entregues dentro da versão atual, sem alteração da URL.

A versão não é negociada por header (Accept, Api-Version) nem por query string. O único mecanismo de seleção de versão é o segmento da URL.

Retrocompatibilidade

Dentro de uma mesma versão major, as seguintes mudanças são consideradas retrocompatíveis e podem ocorrer sem aviso de quebra:

• Adição de novos endpoints.
• Adição de novos campos opcionais em corpos de requisição.
• Adição de novos campos em objetos de resposta.
• Adição de novos valores em enums já existentes.
• Adição de novos parâmetros de query opcionais.
• Alteração da ordem dos campos em respostas JSON.

São consideradas mudanças incompatíveis (exigem nova versão major):

• Remoção ou renomeação de endpoints, campos ou parâmetros.
• Alteração do tipo de um campo.
• Tornar obrigatório um campo antes opcional.
• Alteração da estrutura do envelope de resposta de sucesso ou de erro.
• Alteração do significado de um valor de enum existente.
• Alteração do prefixo de um identificador de recurso (ex.: cont_).

Cuidado

A integração deve tolerar campos desconhecidos na resposta e novos valores de enum. Tratar campos extras como erro pode quebrar a integração quando um campo retrocompatível for adicionado.

Headers de depreciação

Quando um endpoint ou uma versão entra em processo de descontinuação, a API passa a retornar headers padronizados em todas as respostas do recurso afetado, sem alterar o status nem o corpo:

Header	Descrição
Deprecation	Data ISO-8601 em que o recurso foi marcado como descontinuado (ex.: Deprecation: 2026-09-01T00:00:00Z).
Sunset	Data ISO-8601 a partir da qual o recurso deixará de responder, passando a retornar 410 Gone (ex.: Sunset: 2027-03-01T00:00:00Z).
Link	Aponta para a documentação de migração e/ou para o recurso substituto, com rel="deprecation" e/ou rel="successor-version".

Exemplo de headers em uma resposta de recurso descontinuado:

HTTP/1.1 200 OK
Deprecation: 2026-09-01T00:00:00Z
Sunset: 2027-03-01T00:00:00Z
Link: <https://developers.maestron.com.br/pt-br/intro/versioning/>; rel="deprecation", <https://api.maestron.com.br/v2/crm/contacts>; rel="successor-version"
Content-Type: application/json

• Entre a data de Deprecation e a de Sunset, o recurso continua funcionando normalmente.
• A partir da data de Sunset, requisições ao recurso retornam 410 Gone.

Verificação de versão

Endpoint para inspecionar as versões disponíveis e o estado da versão atual. Não exige autenticação.

GET /versions Copiar para LLM

Listar versões

Retorna as versões da API e o status de cada uma (ativa ou descontinuada).

cURLPHPPythonNode.jsC#HTTP / Postman

curl -X GET https://api.maestron.com.br/v1/versions

<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.maestron.com.br/v1/versions', [
    'headers' => ['Accept' => 'application/json'],
]);
$data = json_decode($response->getBody(), true);

import requests
headers = {}
response = requests.get(
    "https://api.maestron.com.br/v1/versions",
    headers=headers,
)
data = response.json()

const response = await fetch("https://api.maestron.com.br/v1/versions", {
  method: "GET",
  headers: {
  },
});
const data = await response.json();

using var client = new HttpClient();
var response = await client.GetAsync("https://api.maestron.com.br/v1/versions");
var data = await response.Content.ReadAsStringAsync();

GET /versions HTTP/1.1
Host: api.maestron.com.br

Respostas

200 · Registros listados.500 · Erro interno.

{
  "message": "Registros listados.",
  "data": [
    {
      "version": "v1",
      "status": "active",
      "released_at": "2026-06-20T00:00:00Z",
      "deprecated_at": null,
      "sunset_at": null,
      "docs_url": "https://developers.maestron.com.br/pt-br/"
    }
  ]
}

{
  "message": "Erro interno do servidor."
}

Estados de uma versão

Estado	Significado
active	Versão suportada e recomendada.
deprecated	Versão ainda funcional, com headers Deprecation e Sunset presentes.
sunset	Versão encerrada; requisições retornam 410 Gone.

Como migrar

1. Monitore os headers Deprecation e Sunset nas respostas. Eles sinalizam o início e o fim do período de transição de cada recurso.
2. Consulte o Link rel="successor-version" para identificar a rota equivalente na nova versão.
3. Aponte as requisições para a nova versão trocando o segmento da URL (ex.: /v1/crm/contacts torna-se /v2/crm/contacts).
4. Revise as mudanças incompatíveis listadas no guia de migração da nova versão antes de cortar o tráfego.
5. Conclua a migração antes da data de Sunset para evitar respostas 410 Gone.

Dica

As duas versões coexistem durante todo o período entre Deprecation e Sunset, permitindo migração incremental por recurso.

Para o detalhamento dos códigos de status, consulte Erros. Para os limites de requisição, consulte Rate limiting.