API do Gestão+

Comece em 3 passos

1. 1

   Crie uma chave

   No painel, vá em Configurações → Integrações e clique em Nova chave (ou Chave de teste para usar dados fictícios). Só o proprietário ou um administrador cria chaves. A chave aparece uma única vez: guarde num cofre de senhas.
2. 2

   Teste a chave

   curl https://gestaomais.app/api/v1/ping \
     -H "Authorization: Bearer $GESTAO_API_KEY"

3. 3

   Busque dados

   curl "https://gestaomais.app/api/v1/clientes?limit=20" \
     -H "Authorization: Bearer $GESTAO_API_KEY"

Autenticação

Envie a chave no cabeçalho Authorization: Bearer gm_live_… (ou x-api-key). Cada chave pertence a uma única empresa: a API nunca aceita um id de empresa vindo de fora, então uma chave só enxerga os dados da própria empresa.

Chaves reais e de teste

Toda resposta traz ambiente (live ou test) para a sua automação saber de onde vieram os dados.

Planos e limites

Respostas trazem x-ratelimit-limit e x-ratelimit-remaining. Ao passar do limite, a API devolve 429 com Retry-After (segundos). Espere esse tempo antes de tentar de novo. Ver planos

Paginação e filtros

Listas vêm das mais recentes para as mais antigas, com até 100 itens por página (padrão 50). Para a próxima página, envie o next_cursor recebido em cursor. Quando has_more for false, acabou.

{
  "data": [ { "id": "…", "nome": "…" } ],
  "has_more": true,
  "next_cursor": "WyIyMDI2LTEwLTMxVDEyOjAwOjAwWiIsIi4uLiJd",
  "ambiente": "live",
  "request_id": "req_…"
}

Para sincronizar com outro sistema, guarde a data da última leitura e use atualizado_desde. Parâmetro desconhecido ou com valor inválido devolve 400, para nenhum erro de digitação passar despercebido.

Criar e atualizar

Crie com POST /v1/{recurso} e altere com PATCH /v1/{recurso}/{id}, enviando JSON. No PATCH, mande só os campos que mudam. Campos fora da lista abaixo são recusados com 400, para nada ser gravado por engano.

curl -X POST https://gestaomais.app/api/v1/clientes \
  -H "Authorization: Bearer $GESTAO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"nome": "Maria Oliveira", "cidade": "Recife", "estado": "PE", "tags": ["site"]}'

• Vendas, contas e categorias são só leitura pela API. Vendas entram pelo PDV, que cuida do estoque e do caixa.
• O estoque de produtos não é alterado pela API: use as movimentações do painel ou o PDV.
• Os limites de cadastro do plano, a validação de CPF/CNPJ e as travas de lançamentos gerados pelo PDV continuam valendo.
• Cliente, conta e categoria citados num lançamento ou compromisso precisam ser da mesma empresa.
• Agenda usa data e hora com fuso, por exemplo 2026-11-03T14:00:00-03:00.

Webhooks

Em vez de consultar a API o tempo todo, receba um aviso quando algo acontece. Cadastre o endereço em Configurações → Integrações → Webhooks (proprietário ou administrador, a partir do plano Start) e escolha os eventos. O Gestão+ envia um POST com JSON em até 1 minuto depois do evento.

{
  "id": "evt_6f1c2b9e1d2a4b8c9f00123456789abc",
  "type": "venda.concluida",
  "api_version": "2026-10-31",
  "created_at": "2026-10-31T18:42:07.512Z",
  "empresa_id": "…",
  "data": { "object": "venda", "id": "…", "numero": 1042, "total": 189.9, "cliente_id": "…" }
}

Confira a assinatura

Cada aviso tem o cabeçalho Gestao-Signature: t=1793472127,v1=…. O v1 é o HMAC-SHA256, em hexadecimal, de {t}.{corpo bruto} com o segredo whsec_… mostrado ao criar o webhook. Recuse avisos com assinatura errada ou com t de mais de 5 minutos atrás. Também vêm Gestao-Event, Gestao-Event-Id e Gestao-Delivery.

import crypto from "node:crypto";

// Use o corpo BRUTO (texto), antes de qualquer JSON.parse.
export function assinaturaValida(corpo, cabecalho, segredo) {
  const partes = Object.fromEntries(cabecalho.split(",").map((p) => p.split("=")));
  const t = Number(partes.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const esperado = crypto.createHmac("sha256", segredo).update(`${t}.${corpo}`).digest("hex");
  const a = Buffer.from(esperado), b = Buffer.from(partes.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Entrega e novas tentativas

• Responda com status 2xx em até 10 segundos. Processe o aviso depois, em segundo plano, se precisar.
• Sem 2xx, tentamos de novo em 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h (8 tentativas). Depois disso, o envio aparece como “Falhou” no painel, com botão para reenviar.
• Um aviso pode chegar mais de uma vez e fora de ordem: use Gestao-Event-Id para ignorar repetidos.
• Endereços só com https, porta 443 e nome de domínio público. Antes de cada envio conferimos o DNS e recusamos domínios que apontam para rede interna. Redirecionamentos não são seguidos: cadastre o endereço final.
• Endpoint que falha sem parar por 3 dias é desativado.
• O botão “Testar” envia um evento ping para conferir a integração.

Assistentes de IA (MCP)

O Gestão+ tem um servidor MCP (Model Context Protocol), o padrão que assistentes de IA usam para chamar ferramentas. Conectado, o assistente consegue, por exemplo, listar as contas a receber da semana, conferir o estoque de um produto ou cadastrar um cliente, sempre com as permissões da chave.

claude mcp add --transport http gestao https://gestaomais.app/api/mcp \
  --header "Authorization: Bearer $GESTAO_API_KEY"

Funciona com clientes MCP que permitem enviar um cabeçalho de autorização. Conectores que exigem login por OAuth ainda não são suportados.

Erros

Erros têm sempre o formato { "error": { "code", "message" }, "request_id" }. Informe o request_id ao suporte para localizarmos a chamada.

Segurança

• Guardamos só o hash

  O texto da chave não fica salvo em lugar nenhum. Se perder, revogue e crie outra.

• Menor permissão

  Escolha só os escopos necessários. Para IA, prefira chaves somente leitura.

• Dados pessoais protegidos

  CPF/CNPJ, e-mail, telefone e endereço só saem (e só podem ser alterados) com o escopo dados_pessoais:ler; sem ele, vêm null.

• Validade e revogação

  Toda chave expira (30 dias a 1 ano), pode ser revogada na hora e para de funcionar se quem a criou deixar de ser proprietário ou administrador.

• Registro de uso

  Cada chamada fica registrada por 90 dias (rota, status, IP e tempo), sem o conteúdo.

• Isolamento por empresa

  A empresa vem sempre da chave. Pedir um id de outra empresa devolve 404.

Automações e IA

Qualquer ferramenta que faça uma requisição HTTP conversa com a API. Nas ferramentas de automação, use o bloco de requisição HTTP com método GET, a URL do recurso e o cabeçalho Authorization guardado como credencial.

Assistentes de IA que aceitam ferramentas por OpenAPI (como ações personalizadas) podem importar openapi.json e chamar a API com uma chave somente leitura. Comece com uma chave de teste.

const res = await fetch("https://gestaomais.app/api/v1/lancamentos?tipo=entrada&status=previsto", {
  headers: { Authorization: `Bearer ${process.env.GESTAO_API_KEY}` },
});
if (res.status === 429) {
  const wait = Number(res.headers.get("retry-after") ?? 60);
  // aguarde `wait` segundos e tente de novo
}
const { data, next_cursor } = await res.json();

Referência

Endereço base: https://gestaomais.app/api/v1. Valores em reais vêm como número (ex.: 149.9); datas em ISO 8601.

Permissões (escopos)

Os webhooks são gerenciados no painel. O escopo webhooks:gerenciar fica reservado para gerenciá-los pela API numa próxima versão.

Em breve

• Login por OAuth no servidor MCP, para conectores de IA que não aceitam cabeçalho de autorização.
• Gerenciar webhooks pela API (escopo webhooks:gerenciar).

Novidades da API aparecem no changelog. Dúvidas: fale com a gente.