Mais Gestão · API Pública

Primeiros passos com curl

Confirme o tenant e o host do ambiente. O contrato usa https://{tenant}.{host}/public-api/v1; os paths já começam após /v1. A origem dos arquivos de documentação não é a base de chamadas da sua empresa.

Crie a chave de acesso no painel com um administrador. O exemplo abaixo usa login: envie X-Public-Access-Key, email e password; HTTP 201 devolve api_key. Se receber 202, conclua o segundo fator conforme /auth/sessions no contrato antes de continuar. Não compartilhe credenciais em conversas ou histórico de terminal.

Defina as variáveis no seu ambiente seguro. Em BASE_URL informe a URL completa com tenant, host e /public-api/v1. Em AUTH_JSON_FILE informe o caminho de um arquivo JSON protegido com email e password. Após HTTP 201, preencha PUBLIC_API_KEY com api_key. A listagem exige as permissões correspondentes.

# Variáveis: BASE_URL, PUBLIC_ACCESS_KEY e AUTH_JSON_FILE
curl --fail-with-body -i "$BASE_URL/auth/sessions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Public-Access-Key: $PUBLIC_ACCESS_KEY" \
  --data-binary "@$AUTH_JSON_FILE"

# Após HTTP 201: PUBLIC_API_KEY recebe api_key
curl --fail-with-body "$BASE_URL/clients?page=1&per_page=20" \
  -H "Accept: application/json" \
  -H "X-Public-Access-Key: $PUBLIC_ACCESS_KEY" \
  -H "X-Public-API-Key: $PUBLIC_API_KEY"

Da chave à primeira cobrança

Esta jornada usa POST /charges com IntegrationChargeRequest e um cliente existente. Não há sandbox ou homologação oferecidos neste portal: executar os comandos pode criar uma conta a receber e emitir uma cobrança real. Credenciamento e configuração podem exigir etapas prévias; não há promessa de emissão em cinco minutos. Copiar um snippet não executa chamada alguma.

Pré-requisitos: empresa com boleto/PIX habilitado e credenciamento aprovado para o meio escolhido, módulos contratados, cliente ativo com endereço nacional válido, caixa da própria empresa, conta contábil ativa do tipo receivable e categoria compatível. Confira também o centro de custo: no modo múltiplos, informe cost_center_id ativo conforme o contrato. Verifique o credenciamento no painel; GET /configuration/payment-activation permite consultar o estado com bank_slip.configure ou card_receiving.configure.

Permissões do atalho: accounts.view e clients.view; accounts.create para criar a conta; bank_slip.emit e bank_slip.print para boleto/PIX. Reutilizar o cliente evita exigir clients.create; criar cliente ou categoria exige as permissões de criação correspondentes. Os catálogos usados abaixo exigem std_launch.view e categories.view. A consulta de caixas não exige permissão específica adicional além da autenticação.

Após autenticar, consulte GET /clients, GET /cashboxes, GET /account-standard-launches?type=receivable e GET /categories. Percorra a paginação, escolha registros da empresa e use os IDs retornados. Não invente UUIDs. No corpo, o cliente existente é client: { id }; não existe client_id nesse schema. Use category_id para reutilizar a categoria; não combine com category.

Baixe o JSON de exemplo, substitua os placeholders pelos IDs consultados e revise valor e vencimento. A data ilustrativa 2027-03-03 deve ser substituída por um dia útil e ano aceitos no contrato. O exemplo usa PIX: charge.kind=pix e account.payment_method=pix. Para boleto, use charge.kind=boleto e account.payment_method=bank_slip. O enum de kind também admite payment_link, que possui módulo e permissões próprios.

Guarde uma chave Idempotency-Key de 8 a 128 caracteres por pedido. Reutilize a mesma chave, conteúdo, empresa, chave de acesso e identidade ao recuperar a mesma operação; conteúdo diferente com a mesma chave pode retornar 409. O campo idempotency_key no JSON é alternativa ao cabeçalho; se enviar ambos, devem ser iguais.

HTTP 201 indica operação criada, mas exige conferir data.status e artefatos; 202 indica processamento ou resposta externa inconclusiva; 200 pode recuperar operação existente. Guarde data.operation_id. Consulte GET /charges/{operation} com esse ID e a mesma identidade; outra chave ou usuário recebe 404. status_url, quando publicado, indica a consulta de acompanhamento.

A resposta da operação de cobrança define data.status: processing, uncertain, completed, failed e canceled. processing pede acompanhamento; uncertain exige reconciliação, sem nova emissão; completed conclui a operação de emissão, não comprova pagamento; failed e canceled exigem verificar a mensagem e os artefatos antes de decidir o próximo passo. data.charge.status é separado e não tem enum neste schema: não suponha paid ou settled.

Para polling GET em 429/5xx, use backoff exponencial com jitter, limite de tentativas e prazo máximo; respeite Retry-After quando presente. Após timeout de criação, consulte pelo operation_id conhecido antes de qualquer repetição. Sem ID, reconcilie o pedido por suporte/consulta documentada, preservando a chave original; não repita a emissão automaticamente nem crie uma chave nova para contornar uncertain. Webhooks externos ficam para uma entrega futura; este fluxo usa polling.

# Salve o JSON disponibilizado abaixo como primeira-cobranca.json.
# Substitua os IDs, revise os dados e valide a sintaxe localmente:
node -e 'JSON.parse(require("fs").readFileSync("primeira-cobranca.json","utf8")); console.log("JSON válido")'

# Só execute após revisar: emissão real. Defina IDEMPOTENCY_KEY uma vez por pedido.
curl --fail-with-body -i "$BASE_URL/charges" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Public-Access-Key: $PUBLIC_ACCESS_KEY" \
  -H "X-Public-API-Key: $PUBLIC_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @primeira-cobranca.json

# OPERATION_ID recebe data.operation_id. Apenas consulta; não emite novamente.
curl --fail-with-body "$BASE_URL/charges/$OPERATION_ID" \
  -H "Accept: application/json" \
  -H "X-Public-Access-Key: $PUBLIC_ACCESS_KEY" \
  -H "X-Public-API-Key: $PUBLIC_API_KEY"

JSON da primeira cobrança

Arquivo: https://maisgestao.com.br/docs/examples/first-charge.json. Este é um modelo JSON válido sintaticamente, mas os placeholders precisam ser substituídos por IDs reais antes de validar contra IntegrationChargeRequest. Nenhum segredo ou dado pessoal real está incluído.

{
  "client": {
    "id": "<UUID_CLIENTE_ATIVO>"
  },
  "account": {
    "unit_price": 150,
    "payment_method": "pix",
    "due_date": "2027-03-03",
    "cashbox_id": "<UUID_CAIXA>",
    "account_standard_launch_id": "<UUID_CONTA_CONTABIL_RECEIVABLE>",
    "category_id": "<UUID_CATEGORIA>",
    "description": "Serviço de exemplo"
  },
  "charge": {
    "kind": "pix"
  }
}

Baixar primeira-cobranca.json

Credenciais e permissões

No fluxo com login, as operações usam X-Public-Access-Key e X-Public-API-Key. A chave temporária tem validade de 24h; um novo login não encerra as anteriores. Não use o Bearer MCP nas rotas públicas REST.

Uma chave criada com require_login: false permite somente as permissões concedidas sem login, usando X-Public-Access-Key. Operações que exigem login respondem 403 sem a chave temporária. Confira security e as regras de cada operação no contrato.

Erros em Problem Details (RFC 9457)

Todo erro HTTP 400–599 retorna application/problem+json com o schema ProblemDetails. O formato obrigatório independe do cabeçalho Accept, inclusive quando ausente. As respostas de sucesso seguem o schema e a mídia de cada operação.

O corpo contém type, title, status, detail, instance e code textual. Use code para decisões do integrador e errors para mensagens por campo quando disponíveis. instance é o caminho público sem query string; erros 5xx são mascarados. Confira as extensões e os exemplos publicados no OpenAPI.

Trate o status HTTP antes do corpo: 401 pede revisão das credenciais; 403 pede revisão das permissões; 422 pede correção dos dados. Em 429 respeite Retry-After quando presente. Não repita escritas cegamente após timeout.

# Resposta de erro HTTP 400–599, sem necessidade de Accept
Content-Type: application/problem+json
# Sucesso: segue o schema e a mídia da operação

Processamento e polling

Uma solicitação aceita pode ainda estar em processamento. Use a operação de consulta documentada para acompanhar o mesmo recurso pelo identificador retornado, até o estado final definido pelo contrato. Percorra a paginação quando aplicável.

Como estratégia do integrador, use backoff exponencial com jitter (variação aleatória da espera), limite de tentativas e prazo máximo para consultas que retornem 429 ou 5xx. Em 429, aguarde no mínimo Retry-After quando presente. Após timeout de criação ou emissão, consulte por ID quando disponível e reconcilie o estado; não repita a emissão automaticamente. Se o ID não chegou, recupere-o por uma consulta documentada ou peça suporte. Use idempotência somente onde o contrato a prevê.

Exemplo do contrato: GET /accounts-payable/scan/{scan_id} retorna ScanStatus na raiz: pending aguarda, ready permite revisar a leitura e failed encerra com falha. Esses estados não indicam pagamento nem criação de conta. Cada GET tem seu próprio schema; não reutilize o vocabulário de outro recurso.

O acompanhamento descrito aqui é por consulta (polling). Esta documentação não oferece assinatura de webhook externo. Use apenas os recursos publicados para o seu ambiente.

Valores monetários sem perda de precisão

Consulte o schema da operação: entradas de contas aceitam números JSON, enquanto saídas como unit_price, balance e balance_paid são texto decimal com duas casas, por exemplo "1500.00". Não converta todas as entradas em texto ou todas as saídas em número.

Não use ponto flutuante binário (float) para somar valores financeiros. Use aritmética decimal ou inteiros na menor unidade monetária, com conversão e arredondamento explícitos conforme o campo. Preserve as strings decimais recebidas.

Encerrar a chave temporária

Ao terminar as consultas e a jornada de cobrança, encerre a chave temporária com DELETE /auth/session.

# Encerre a chave temporária ao concluir
curl --fail-with-body -X DELETE "$BASE_URL/auth/session" \
  -H "Accept: application/json" \
  -H "X-Public-Access-Key: $PUBLIC_ACCESS_KEY" \
  -H "X-Public-API-Key: $PUBLIC_API_KEY"

Suporte e versionamento

O caminho /public-api/v1 identifica a versão REST. Consulte a política de evolução e o changelog datado abaixo antes de atualizar a integração. A versão efetivamente publicada continua sendo a informada no contrato do ambiente.

Para suporte, consulte https://maisgestao.com.br/contato; clientes também abrem tickets no sistema em Ajuda → Meus chamados. Informe operação, método, horário, status HTTP, versão do contrato e identificador de requisição se disponível. Remova senhas, chaves, tokens, dados pessoais e documentos do material enviado.

As chamadas atuam no ambiente e na empresa informados. Verifique os dados e as permissões antes de executar operações financeiras.

Falar com o suporte · Política de evolução · Changelog — 2026-10-29

Política de evolução e compatibilidade

A referência de evolução desta entrega é OpenAPI info.version 1.1.0, com o caminho /public-api/v1 preservado. info.version identifica a revisão do contrato; não muda sozinho a versão da URL. A versão efetivamente publicada vem do OpenAPI do ambiente: um artefato ainda em 1.0.0 não deve ser tratado como 1.1.0 apenas por ler este guia.

Na linha v1, adições compatíveis preservam os campos, tipos, autenticação, respostas de sucesso e comportamento já documentados dos clientes existentes. Novos campos opcionais, operações e capacidades devem ser descritos no contrato e no changelog. O cliente deve tolerar campos opcionais ausentes e campos adicionais de resposta.

Erros HTTP 400–599 usam obrigatoriamente application/problem+json no formato RFC 9457 (Problem Details), independente do cabeçalho Accept. O formato obrigatório preserva as respostas de sucesso documentadas por operação.

Mudanças incompatíveis, como remoção de campo, alteração de tipo, permissão ou semântica exigida de clientes existentes, exigem nova versão ou migração explícita documentada antes da adoção, com impactos e passos de atualização. Descontinuações devem indicar o recurso afetado e a alternativa; não há prazo de antecedência, compatibilidade ou SLA inventado neste guia.

No MCP, negocie a versão de protocolo aceita na inicialização e confira os schemas do catálogo. A versão do servidor MCP e a revisão OpenAPI são independentes. O changelog desta entrega está na seção datada abaixo.

Changelog — 2026-10-29

Portal REST/MCP: índices curtos como contexto padrão; arquivos completos explicitamente separados; recortes por endpoint ou ferramenta; referências transitivas REST; cópia de contexto, links e exemplos sem execução automática.

Integração: jornada da chave à primeira cobrança com JSON de placeholders obrigatórios e Idempotency-Key, polling com estados do contrato, precisão decimal, autenticação distinta REST/MCP e confirmação humana nas operações MCP de revisão.

Evolução: referência OpenAPI info.version 1.1.0 mantendo /public-api/v1; erros RFC 9457 com application/problem+json obrigatório para HTTP 400–599, preservando as respostas de sucesso. Esta seção registra a entrega documental e a política de evolução, não comprova publicação do runtime em cada ambiente.

Correção da revisão: suporte direcionado à central oficial existente, política de compatibilidade e este changelog acessíveis nos portais e exports. Webhooks externos e sandbox são roadmap futuro, indisponíveis nesta entrega e sem data ou prazo de entrega.

Guias da API REST