# Autenticação (/autenticacao)
### Gere uma credencial [#gere-uma-credencial]
No workspace, o dono ou um administrador gera uma **credencial**: uma **API Key** (`mdk_…`)
e um **Secret** (`mds_…`). O secret aparece **uma única vez**, na criação — guarde-o num
cofre. Perdeu o secret, gere outra credencial e revogue a antiga.
### Troque a credencial por tokens [#troque-a-credencial-por-tokens]
`POST /auth/token` devolve um par de tokens.
### Envie o access token [#envie-o-access-token]
Em toda chamada: `Authorization: Bearer mda_…`. Ele vale **1 hora**.
### Renove pelo refresh token [#renove-pelo-refresh-token]
Quando o access token expirar, use o **refresh token** (`mdr_…`, válido por 30 dias) em
`POST /auth/refresh`. Cada refresh gera um par novo e **invalida o anterior**; o mesmo refresh
enviado duas vezes ao mesmo tempo gera par novo para uma só das chamadas.
Revogar a credencial derruba na hora todos os tokens emitidos com ela.
# Cartões e faturas (/cartoes)
Cartões de crédito e faturas, com os números da tela da fatura.
## Permissões [#permissões]
Exige a permissão de ver Cartões de crédito; sem ela, **403**. Cartão oculto para a credencial
responde **404**.
## Valores [#valores]
Os valores têm o sinal do lançamento: compra negativa, estorno e pagamento positivos. O `valor`
da fatura negativo é o que se deve.
## Fatura [#fatura]
A fatura é identificada pelo mês do vencimento (`AAAA-MM`). `status`: `fechada`, `aberta` ou
`futura`.
Recorrências e parcelas que o app ainda não gravou entram com `projetado: true` e `id` nulo, como
o app vai gravá-las.
## Todos os cartões numa chamada [#todos-os-cartões-numa-chamada]
`GET /cartoes/faturas` traz o resumo da fatura de cada cartão em uso que vence no `mes` (sem ele,
a aberta de cada um), e `GET /cartoes/parcelas-futuras`, as parcelas futuras de todos, um bloco por
cartão. Os números são os das rotas de um cartão; o cartão oculto e o que não está em uso ficam de
fora.
# Erros (/erros)
Todo erro tem o mesmo formato:
```json
{"error": {"code": "...", "message": "..."}}
```
Programe contra o `code`; o `message` é texto para gente e pode mudar.
| HTTP | `code` | Causa comum |
| ---- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 400 | `bad_request` | parâmetro inválido (`limit`, `cursor`, filtro); o `message` diz qual |
| 401 | `unauthorized` | token vencido (renove), credencial revogada ou secret errado |
| 403 | `forbidden` | o papel da credencial não cobre a chamada, conta somente leitura, workspace fora do acesso antecipado ou desativado |
| 404 | `not_found` | recurso inexistente ou oculto para a credencial |
| 405 | `method_not_allowed` | método HTTP que a rota não aceita |
| 422 | `unprocessable` | dado válido no formato, mas recusado pela regra |
| 429 | `rate_limited` | mais de 120 chamadas no minuto; espere o `Retry-After` |
| 500 | `internal_error` | falha do nosso lado |
# Introdução (/)
A API pública do Meu Dinheiro é uma API REST para integrar sistemas externos a um
**workspace**: ler os cadastros, os relatórios com os mesmos números da tela, os cartões e
as faturas.
Esta versão está disponível só para os workspaces do programa de acesso antecipado e pode
mudar antes do lançamento. Hoje ela cobre a autenticação, os cadastros, os relatórios e os
cartões com as faturas; os demais recursos (lançamentos…) entram nas próximas versões.
## Por onde começar [#por-onde-começar]
Da credencial até a primeira resposta, em quatro passos.
Todas as rotas, parâmetros e respostas, geradas do OpenAPI.
## URL base [#url-base]
```
https://app.meudinheiroweb.com.br/api/public/v1
```
## Nomes [#nomes]
O que é do negócio fica em português (`categorias`, `nome_completo`, `categoria_pai_id`); o
que é genérico, em inglês (`id`, `status`, `limit`, `cursor`). Tudo em snake_case, sem acento.
## Para assistentes de IA [#para-assistentes-de-ia]
Para conversar com o Claude, o ChatGPT ou o Gemini sobre o seu workspace, sem escrever código, use o
servidor MCP: veja [Conectar um assistente](/mcp).
Esta documentação inteira está em texto puro em [`/llms.txt`](/llms.txt) e
[`/llms-full.txt`](/llms-full.txt), e cada página tem o botão **Copiar Markdown**.
# Investimentos (/investimentos)
A carteira de investimentos do workspace, com os números das telas do módulo de investimentos.
Somente leitura.
## Acesso [#acesso]
Exige a permissão do módulo de investimentos e **o módulo no plano** do workspace. Sem a permissão,
**403** `forbidden`; sem o módulo no plano vigente, **403** `plan_required`. Conta oculta para a
credencial fica fora de toda soma, e pedi-la em `contas` responde **404**.
## O que cada rota traz [#o-que-cada-rota-traz]
| Rota | Para quê |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `GET /investimentos/carteira` | A posição de hoje, por ativo em cada conta: quantidade, preço médio, valor investido, valor atual, resultado e participação |
| `GET /investimentos/estrategias` | As estratégias de alocação e os grupos, para filtrar as outras rotas |
| `GET /investimentos/rentabilidade` | A série da rentabilidade, da carteira ou de um recorte, com benchmarks |
| `GET /investimentos/rentabilidade/ativos` | A rentabilidade de cada ativo no período, do maior para o menor |
| `GET /investimentos/benchmarks` | Os índices de comparação: `cdi`, `ipca`, `igpm`, `poupanca`, `selic`, `ibovespa`, `smll`, `ifix`, `sp500`, `msci_world`, `usd` |
| `GET /investimentos/indicadores` | Rentabilidade, volatilidade (diária e anualizada) e Sharpe contra o CDI |
| `GET /investimentos/analise` | Por mês ou ano: saldos, aportes, retiradas, proventos, variação, custos e IR |
## Rentabilidade por cotização [#rentabilidade-por-cotização]
A rentabilidade é a variação da **cota** da carteira, como num fundo: aporte e retirada não a
distorcem. É diferente do **resultado** da posição (`valor_atual − valor_investido`, sobre o preço
médio), que muda com cada compra e venda. Valores em fração: `0.05` é 5%.
A série acumula desde o dia anterior ao `inicio`, e `rentabilidade_periodo` é a do último ponto.
`benchmarks_periodo` traz cada índice pedido na mesma janela, para comparar direto.
Para comparar vários ativos, peça `por_ativo=true`: a resposta traz `series`, uma por ativo de
`ativos` (ou da estratégia), ou uma por conta de `contas` quando não há ativos, até 20, cada uma
com os benchmarks por ponto, com `intervalo` `mes` ou `ano` (a série diária é um ativo por vez). "Quais ativos ficaram abaixo do CDI, e desde quando" sai em duas
chamadas: o ranking (`/rentabilidade/ativos`) e a série dos que ficaram abaixo, com `por_ativo`.
## `atualizado_ate` [#atualizado_ate]
O Meu Dinheiro calcula a rentabilidade dia a dia quando o módulo de investimentos é aberto no app.
`atualizado_ate` é o último dia calculado: a série e os benchmarks param nele. Se não for ontem, a
carteira não foi aberta desde então, e os números são de `atualizado_ate`. O valor dos títulos
indexados e das contas na posição também vem desse cálculo. Para atualizar, abra **Investimentos**
no Meu Dinheiro; a API não recalcula nem grava durante a leitura.
## Período [#período]
* **Marco:** não há rentabilidade antes de 2018-01-01. `inicio` anterior vira 2018-01-01, e a
resposta traz o `inicio` usado.
* **Série:** `intervalo` `mes` (padrão), `ano` ou `dia`, este até 366 dias. O ponto do mês e do
ano é o último dia com cota nele.
* **Análise:** `inicio` e `fim` em `AAAA-MM`, até 60 meses. Ela roda na hora e pesa pelo número
de ativos × meses: numa carteira grande, o período pedido pode não caber de uma vez. Aí a
resposta é **422** `analysis_too_complex`, com `max_meses_sugerido` dentro de `error` (o maior
período que cabe; nulo quando nem um mês cabe). Repita com ele ou recorte por `contas`.
* **Indicadores:** do primeiro dia do mês de `inicio` ao último do de `fim`.
## Recorte [#recorte]
`contas` e `ativos` (listas de ids), ou `estrategia` e `grupo` (de `GET /investimentos/estrategias`;
a estratégia `0` é "Tipo de ativo", e o id do grupo dela é o código do tipo). `ativos` e
`estrategia` não se combinam. A rentabilidade e os indicadores aceitam os quatro; a carteira e a
análise, todos menos `ativos`; a rentabilidade por ativo não recorta. `moeda` em ISO 4217 converte os valores; padrão BRL.
## Limites conhecidos [#limites-conhecidos]
Os números são os da tela, inclusive onde o cálculo ainda está em revisão (venda parcial de título
indexado, custódia em conta de investimento, posição vendida sem cotação). Quando eles mudarem no
app, mudam aqui também.
# Limite de requisições (/limites)
Janela fixa de 1 minuto: **120 requisições por credencial** nas rotas autenticadas e
**10 por API Key** em `/auth/*`. Toda resposta que consumiu cota traz:
| Cabeçalho | Significado |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit` | cota da janela |
| `X-RateLimit-Remaining` | quanto ainda resta nela |
| `X-RateLimit-Reset` | quando a janela vira (Unix timestamp, segundos) |
Excedida a cota, a resposta é **429** com `Retry-After` em segundos.
# Casos de uso (/mcp/casos-de-uso)
Copie, ajuste o período e pergunte. Os nomes entre aspas são exemplos: use os do seu workspace.
## Perguntas de uma vez [#perguntas-de-uma-vez]
### Gastos e receitas [#gastos-e-receitas]
* "Quanto gastei por categoria no mês passado? Mostre as cinco maiores."
* "Quais foram as receitas e as despesas de cada mês deste ano?"
* "Quanto o projeto "Reforma" já custou até hoje, por categoria?"
* "Quanto paguei ao fornecedor "Gráfica Central" nos últimos seis meses?"
### Saldos e caixa [#saldos-e-caixa]
* "Qual o saldo de cada conta hoje, e o total?"
* "Como fica o fluxo de caixa dos próximos 90 dias?"
### Cartões [#cartões]
* "Qual fatura vence primeiro, e de quanto ela é?"
* "Quanto já está comprometido em parcelas nas próximas faturas do cartão "Visa"?"
* "Compare as últimas seis faturas do cartão principal."
### Orçamento e demonstrativos [#orçamento-e-demonstrativos]
* "Em quais categorias estourei a meta neste mês?"
* "Monte o DRE do último trimestre."
* "Mostre o DFC do ano passado e explique de onde veio o caixa."
### Investimentos [#investimentos]
* "Minha carteira rendeu mais que o CDI nos últimos 12 meses?"
* "Qual ativo puxou a rentabilidade para baixo este ano?"
* "Quanto paguei de custos e IR na carteira este ano?"
* "Como está a carteira contra a minha estratégia de alocação?"
## Roteiros de vários passos [#roteiros-de-vários-passos]
### Fechamento do mês [#fechamento-do-mês]
> "Faça o fechamento de setembro: receitas × despesas, as cinco categorias que mais pesaram,
> as metas estouradas e o saldo final de cada conta. Termine com três pontos de atenção."
O assistente chama o resultado, os totais por categoria, as metas e os saldos, e junta tudo
num resumo.
### Investigar um aumento de gastos [#investigar-um-aumento-de-gastos]
> "As despesas de agosto subiram em relação a julho. Descubra quais categorias explicam a
> diferença e, dentro delas, quais contatos."
Ele compara os totais por categoria nos dois meses e, nas que mais subiram, desce para os
totais por contato.
### Planejar o pagamento dos cartões [#planejar-o-pagamento-dos-cartões]
> "Liste as faturas abertas de todos os cartões, com vencimento e valor, some as parcelas que
> ainda vão cair e compare com o saldo das contas na data de cada vencimento."
Ele cruza cartões, faturas, parcelas futuras e saldos para dizer se o caixa cobre cada
vencimento.
### Aportes contra o caixa [#aportes-contra-o-caixa]
> "Quanto aportei nos investimentos por mês este ano? Compare com o que sobrou no fluxo de caixa
> de cada mês e diga se os aportes cabem no que sobra."
Ele chama a análise mensal da carteira e o fluxo de caixa do mesmo período e compara mês a mês.
# ChatGPT (/mcp/chatgpt)
No ChatGPT, conectores personalizados ficam no **modo desenvolvedor**, disponível **só nos
planos Pro, Business e Enterprise/Edu** (o Plus e o gratuito não têm). Os nomes dos menus mudam um pouco por tipo de conta.
## Endereço do conector [#endereço-do-conector]
```
https://app.meudinheiroweb.com.br/api/public/mcp
```
## Criar o conector [#criar-o-conector]
### Ligue o modo desenvolvedor [#ligue-o-modo-desenvolvedor]
No [ChatGPT](https://chatgpt.com), abra **Configurações → Apps e conectores → Avançado** e ligue
o **Modo desenvolvedor**.
### Crie o conector [#crie-o-conector]
Ainda em **Apps e conectores**, clique em **Criar** e preencha:
| Campo | Valor |
| ------------------- | ---------------- |
| Nome | `Meu Dinheiro` |
| URL do servidor MCP | o endereço acima |
| Autenticação | **OAuth** |
Marque que confia no aplicativo e clique em **Criar**.
### Conecte [#conecte]
O ChatGPT abre a tela de aprovação do Meu Dinheiro ([veja abaixo](#aprovar-o-acesso)).
## Aprovar o acesso [#aprovar-o-acesso]
A tela **"ChatGPT quer acessar o Meu Dinheiro"** abre no navegador:
1. entre com o seu login do Meu Dinheiro, se pedir;
2. em **Workspace que a IA vai acessar**, escolha qual;
3. confira a lista do que o ChatGPT poderá fazer; para ele também criar, alterar e excluir cadastros
(contas, cartões, categorias, centros de custo, tags, formas de pagamento, projetos e contatos),
ligue **Permitir alterações**;
4. clique em **Permitir acesso**.
## Primeira pergunta [#primeira-pergunta]
Numa conversa nova, ative o **Meu Dinheiro** no menu **+** (em **Modo desenvolvedor**) e pergunte:
> "Quem sou eu no Meu Dinheiro, e quais contas eu tenho?"
Um assistente pode ser enganado por texto malicioso num arquivo ou página que ele leia
(*prompt injection*). Confira as chamadas que ele faz antes de confirmar.
## Próximos passos [#próximos-passos]
* [Casos de uso](/mcp/casos-de-uso): perguntas prontas e roteiros de vários passos.
* [Ferramentas](/mcp/ferramentas): tudo o que o servidor expõe.
* [Perguntas frequentes](/mcp/perguntas-frequentes): limites, permissões e como desconectar.
# Claude Code (/mcp/claude-code)
O Claude Code conversa com o servidor MCP direto do terminal: útil para cruzar os números do
workspace com planilhas, scripts e relatórios que você está montando.
## Endereço do conector [#endereço-do-conector]
```
https://app.meudinheiroweb.com.br/api/public/mcp
```
## Adicionar o servidor [#adicionar-o-servidor]
Escolha onde a configuração fica:
Vale em qualquer pasta, só no seu usuário:
```bash
claude mcp add --transport http meu-dinheiro https://app.meudinheiroweb.com.br/api/public/mcp -s user
```
Vale para quem abrir o projeto, porque fica no `.mcp.json` da raiz dele:
```bash
claude mcp add --transport http meu-dinheiro https://app.meudinheiroweb.com.br/api/public/mcp -s project
```
O arquivo fica assim, e pode ir para o repositório: não há segredo nele.
```json title=".mcp.json"
{
"mcpServers": {
"meu-dinheiro": {
"type": "http",
"url": "https://app.meudinheiroweb.com.br/api/public/mcp"
}
}
}
```
Cada pessoa faz o próprio login e escolhe o próprio workspace.
## Fazer o login [#fazer-o-login]
### Abra o painel de MCP [#abra-o-painel-de-mcp]
No Claude Code, rode `/mcp`, escolha **meu-dinheiro** e **Authenticate**.
### Aprove no navegador [#aprove-no-navegador]
A tela **"Claude Code quer acessar o Meu Dinheiro"** abre no navegador. Escolha o workspace e,
para o Claude Code também criar, alterar e excluir cadastros, ligue **Permitir alterações**.
Depois, clique em **Permitir acesso**.
A tela avisa que **a conexão volta para um programa neste computador**: é o próprio Claude Code
esperando a resposta. Só permita se foi você quem acabou de iniciar o login.
### Volte ao terminal [#volte-ao-terminal]
O `/mcp` mostra o **meu-dinheiro** como conectado. O login se renova sozinho; se o Claude Code
pedir de novo, repita o `/mcp`.
## Primeira pergunta [#primeira-pergunta]
> "Use o Meu Dinheiro: quem sou eu, e quais contas eu tenho?"
Um assistente pode ser enganado por texto malicioso num arquivo ou página que ele leia
(*prompt injection*). Revise as chamadas de ferramenta antes de aprová-las.
## Próximos passos [#próximos-passos]
* [Casos de uso](/mcp/casos-de-uso): perguntas prontas e roteiros de vários passos.
* [Ferramentas](/mcp/ferramentas): tudo o que o servidor expõe.
* [Perguntas frequentes](/mcp/perguntas-frequentes): limites, permissões e como desconectar.
# Claude (/mcp/claude)
Com o conector, o Claude consulta o seu workspace no meio da conversa: cadastros, relatórios,
cartões e faturas. Se você permitir alterações na aprovação, ele também cria, altera e exclui
cadastros.
## Endereço do conector [#endereço-do-conector]
```
https://app.meudinheiroweb.com.br/api/public/mcp
```
## Adicionar o conector [#adicionar-o-conector]
O caminho muda conforme o tipo de conta no Claude:
### Abra os conectores [#abra-os-conectores]
No [claude.ai](https://claude.ai/customize/connectors) ou no Claude Desktop, vá em
**Personalizar → Conectores**.
### Adicione o Meu Dinheiro [#adicione-o-meu-dinheiro]
Clique em **+ → Adicionar conector personalizado**, dê o nome **Meu Dinheiro**, cole o endereço
acima e clique em **Adicionar**.
### Conecte [#conecte]
Clique em **Conectar** no conector. O Claude abre a tela de aprovação do Meu Dinheiro
([veja abaixo](#aprovar-o-acesso)).
Numa organização, **só o dono adiciona** o conector; depois cada pessoa conecta a própria conta.
### O dono adiciona [#o-dono-adiciona]
Nas configurações da organização no Claude, em **Conectores**, o dono adiciona um conector
personalizado com o nome **Meu Dinheiro** e o endereço acima.
### Cada pessoa conecta [#cada-pessoa-conecta]
Em **Personalizar → Conectores**, a pessoa encontra o Meu Dinheiro e clica em **Conectar**. A
aprovação é individual: cada uma escolhe o próprio workspace.
O conector adicionado pela web aparece também no Claude Desktop e no app do celular, com a
mesma conta. Não é preciso adicionar de novo.
## Aprovar o acesso [#aprovar-o-acesso]
A tela **"Claude quer acessar o Meu Dinheiro"** abre no navegador:
1. entre com o seu login do Meu Dinheiro, se pedir;
2. em **Workspace que a IA vai acessar**, escolha qual;
3. confira a lista do que o Claude poderá fazer; para ele também criar, alterar e excluir cadastros
(contas, cartões, categorias, centros de custo, tags, formas de pagamento, projetos e contatos),
ligue **Permitir alterações**;
4. clique em **Permitir acesso**.
Você volta para o Claude com o conector ativo.
## Primeira pergunta [#primeira-pergunta]
Numa conversa nova, confira que o **Meu Dinheiro** está ligado no menu de ferramentas e pergunte:
> "Quem sou eu no Meu Dinheiro, e quais contas eu tenho?"
O Claude pede para usar as ferramentas na primeira vez; permita e ele responde com o seu nome, o
workspace e a lista de contas.
Um assistente pode ser enganado por texto malicioso num arquivo ou página que ele leia
(*prompt injection*). Confira o que ele pede para usar antes de permitir.
## Próximos passos [#próximos-passos]
* [Casos de uso](/mcp/casos-de-uso): perguntas prontas e roteiros de vários passos.
* [Ferramentas](/mcp/ferramentas): tudo o que o servidor expõe.
* [Perguntas frequentes](/mcp/perguntas-frequentes): limites, permissões e como desconectar.
# Ferramentas (/mcp/ferramentas)
Cada ferramenta é a mesma operação de uma rota da [API pública](/referencia): mesmos filtros,
mesma paginação, mesmo JSON. As de leitura valem para toda conexão; as de escrita, só para a
conexão aprovada com **Permitir alterações**.
O assistente só enxerga as ferramentas que **você** pode usar no workspace conectado: se o seu
perfil não vê o DRE na tela, a ferramenta do DRE nem aparece para a IA.
## Workspace [#workspace]
| Ferramenta | O que faz | Acesso |
| ---------- | ------------------------------------------------------------------------- | --------------- |
| `quem_sou` | O workspace conectado, quem aprovou a conexão, quando e com que permissão | qualquer membro |
## Cadastros [#cadastros]
| Ferramenta | O que faz | Acesso |
| ---------------------------------------------- | ---------------------------------------------------------------------------------- | --------------- |
| `list_contas`, `get_conta` | Contas (corrente, poupança, carteira…) | qualquer membro |
| `list_categorias`, `get_categoria` | Categorias de receita, despesa e transferência, com as subcategorias | qualquer membro |
| `list_centros`, `get_centro` | Centros de custo | qualquer membro |
| `list_projetos`, `get_projeto` | Projetos | qualquer membro |
| `list_tags`, `get_tag` | Tags | qualquer membro |
| `list_formas_pagamento`, `get_forma_pagamento` | Formas de pagamento | qualquer membro |
| `list_contatos`, `get_contato` | Contatos (clientes e fornecedores), **sem** documento, e-mail, telefone e endereço | qualquer membro |
## Cadastros: escrita [#cadastros-escrita]
As ferramentas de escrita ainda não foram liberadas. Esta seção mostra como elas vão funcionar;
até lá, toda conexão só consulta, e o **Permitir alterações** não aparece na aprovação.
Só com **Permitir alterações** na aprovação, e só para o que **você** pode alterar: quem edita
contas sem poder excluí-las não vê as ferramentas de exclusão. As ferramentas orientam o
assistente a pedir a sua confirmação antes de gravar; se ele estiver configurado para aprovar
ferramentas sozinho, grava sem perguntar.
| Ferramenta | O que faz | Acesso |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `create_conta`, `update_conta` | Cria ou altera uma conta (corrente, dinheiro, poupança, contas a pagar…) | editar contas |
| `delete_conta` | Exclui uma conta sem lançamentos, operações nem cartão vinculado; a última do workspace não se exclui | excluir contas |
| `create_categoria`, `update_categoria` | Cria ou altera uma categoria de receita ou despesa, ou uma subcategoria (as de sistema não se alteram) | editar categorias |
| `delete_categoria` | Exclui uma categoria e leva os lançamentos dela para outra, que você escolhe; as metas de orçamento dela saem. Categoria de sistema e categoria com subcategorias não se excluem | excluir categorias |
| `create_centro`, `update_centro` | Cria ou altera um centro de custo | editar centros |
| `delete_centro` | Exclui um centro; os lançamentos, agendas e regras vão para outro centro, se você indicar, ou ficam sem centro | excluir centros |
| `create_contato`, `update_contato` | Cria ou altera um cliente ou fornecedor: nome, razão social, tipos, status e categoria (documento, e-mail, telefones e endereço só no app) | editar contatos |
| `delete_contato` | Exclui um contato sem proposta comercial; os lançamentos, agendas e regras vão para outro contato, se você indicar, ou ficam sem contato | excluir contatos |
| `create_forma_pagamento`, `update_forma_pagamento` | Cria ou altera uma forma de pagamento (a de cartão de crédito é do Meu Dinheiro e não muda) | editar formas de pagamento |
| `delete_forma_pagamento` | Exclui uma forma de pagamento e a tira dos lançamentos, agendas e regras | excluir formas de pagamento |
| `create_projeto`, `update_projeto` | Cria ou altera um projeto, com cor, período e metas | editar projetos |
| `delete_projeto` | Exclui um projeto; os lançamentos, agendas e regras vão para outro projeto, se você indicar, ou ficam sem projeto. As metas por categoria saem | excluir projetos |
| `create_tag`, `update_tag` | Cria ou altera uma tag | editar tags |
| `delete_tag` | Exclui uma tag e a tira dos lançamentos, agendas e regras | excluir tags |
| `create_cartao`, `update_cartao` | Cria ou altera um cartão de crédito e os plásticos dele | editar contas |
| `delete_cartao` | Exclui um cartão sem lançamentos | excluir contas |
## Cartões e faturas [#cartões-e-faturas]
| Ferramenta | O que faz | Acesso |
| ---------------------------- | ------------------------------------------------------------------------------------ | ------------------- |
| `list_cartoes`, `get_cartao` | Cartões de crédito, com limite, limite disponível e vencimento | ver cartões na tela |
| `list_faturas` | Histórico de faturas de um cartão | ver cartões na tela |
| `get_fatura` | A fatura de um mês, com o resumo da tela (valor, anterior, despesas, receitas…) | ver cartões na tela |
| `list_faturas_mes` | A fatura de todos os cartões num mês (sem mês, a aberta de cada um), numa chamada só | ver cartões na tela |
| `list_parcelas_futuras` | Parcelas que ainda vão cair nas próximas faturas, de um cartão ou de todos | ver cartões na tela |
## Relatórios [#relatórios]
Os números são os mesmos dos relatórios da tela, para o período pedido.
| Ferramenta | O que faz | Acesso |
| --------------------------- | ------------------------------------------------------------ | ------------------------------------ |
| `get_relatorio_totais` | Totais por categoria, centro, contato, projeto, tag ou conta | o relatório de totais correspondente |
| `get_relatorio_resultado` | Receitas × despesas | resultado na tela |
| `get_relatorio_saldos` | Saldo das contas numa data | saldos na tela |
| `get_relatorio_fluxo_caixa` | Fluxo de caixa | fluxo de caixa na tela |
| `get_relatorio_metas` | Metas × realizado, por categoria ou centro de custo | metas na tela |
| `get_relatorio_dre` | DRE | DRE na tela |
| `get_relatorio_dfc` | DFC | DFC na tela |
## Investimentos [#investimentos]
Os números são os da carteira de investimentos na tela. Exigem ver o módulo de investimentos e o
módulo no **plano** do workspace: sem ele, a ferramenta aparece, mas a resposta pede para mudar de
plano. Detalhe do contrato no guia [Investimentos](/investimentos).
| Ferramenta | O que faz | Acesso |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| `get_carteira_investimentos` | A posição de hoje, por ativo e conta: quantidade, preço médio, valor investido, valor atual e resultado | ver investimentos |
| `list_estrategias` | As estratégias de alocação e os grupos, para recortar as outras | ver investimentos |
| `get_rentabilidade` | A rentabilidade da carteira (ou de contas, ativos, um grupo), por dia, mês ou ano, comparada a CDI, IPCA, Ibovespa…; com `por_ativo`, uma série mensal ou anual por ativo na mesma chamada | ver investimentos |
| `list_rentabilidade_ativos` | A rentabilidade de cada ativo desde uma data, do melhor para o pior | ver investimentos |
| `list_benchmarks` | Os índices de comparação disponíveis | ver investimentos |
| `get_indicadores_carteira` | Rentabilidade, volatilidade e índice de Sharpe contra o CDI | ver investimentos |
| `get_analise_carteira` | Por mês ou ano: aportes, retiradas, proventos, variação, custos e IR, com a rentabilidade e a TIR do período inteiro | ver investimentos |
A rentabilidade é por cotização, como a da tela: aporte e retirada não a distorcem. Ela é calculada
quando o módulo de investimentos é aberto no app, e as respostas dizem até que dia vão
(`atualizado_ate`); se faz dias que você não abre o módulo, o assistente avisa a data.
A análise roda na hora, e numa carteira com muitos ativos um período longo pode não caber de uma
vez: a resposta diz quantos meses cabem, e o assistente repete com esse período ou por contas.
## Paginação [#paginação]
As ferramentas `list_*` devolvem uma página por vez. Enquanto `next_cursor` vier preenchido, o
assistente chama de novo com ele, sozinho; para listas grandes, peça um recorte ("só as
categorias de despesa ativas") em vez da lista inteira.
# Gemini (/mcp/gemini)
Com o conector, o Gemini consulta o seu workspace no meio da conversa: cadastros, relatórios,
cartões e faturas. Se você permitir alterações na aprovação, ele também cria, altera e exclui
cadastros, sempre pedindo a sua confirmação antes.
## Endereço do conector [#endereço-do-conector]
```
https://app.meudinheiroweb.com.br/api/public/mcp
```
## Adicionar o conector [#adicionar-o-conector]
### Abra os conectores [#abra-os-conectores]
No [Gemini](https://gemini.google.com), vá em **Mais → Personalizar → Conectores**.
### Adicione um conector personalizado [#adicione-um-conector-personalizado]
Clique em **+ Personalizado**.
### Cole o endereço [#cole-o-endereço]
Cole o endereço acima e deixe **Configurações avançadas** em branco: não é preciso ID nem chave
secreta do cliente.
### Conecte [#conecte]
Clique em **Avançar**. O Gemini abre a tela de aprovação do Meu Dinheiro
([veja abaixo](#aprovar-o-acesso)).
## Aprovar o acesso [#aprovar-o-acesso]
A tela **"Gemini quer acessar o Meu Dinheiro"** abre no navegador:
1. entre com o seu login do Meu Dinheiro, se pedir;
2. em **Workspace que a IA vai acessar**, escolha qual;
3. confira a lista do que o Gemini poderá fazer; para ele também criar, alterar e excluir cadastros
(contas, cartões, categorias, centros de custo, tags, formas de pagamento, projetos e contatos),
ligue **Permitir alterações**;
4. clique em **Permitir acesso**.
Você volta para o Gemini com o conector ativo, e a conexão aparece como **Gemini** em
**Gerenciar conta e plano → Conexões de IA**. Se a sessão do Meu Dinheiro tiver vencido, a tela
pede o login de novo e segue para a aprovação.
## Primeira pergunta [#primeira-pergunta]
Numa conversa nova, digite **@** e escolha o **Meu Dinheiro**, ou pergunte direto:
> "Quem sou eu no Meu Dinheiro, e quais contas eu tenho?"
O Gemini responde com o seu nome, o workspace e a lista de contas.
## O Gemini pediu ID e chave secreta do cliente [#o-gemini-pediu-id-e-chave-secreta-do-cliente]
No app do Gemini, isso aparece quando ele não consegue se registrar sozinho no Meu Dinheiro.
Confira se o endereço está exatamente como acima e tente de novo; se continuar, fale com o
suporte. O par de ID e chave que o Meu Dinheiro gera é só para o
[Gemini Enterprise](#gemini-enterprise) e não funciona no app.
## Gemini Enterprise [#gemini-enterprise]
Se algum passo falhar, [fale com o suporte](https://docs.meudinheiroweb.com.br/perguntas-frequentes/conceitos-e-duvidas-gerais#como-abrir-e-acompanhar-um-chamado-de-suporte) e diga em qual.
No Gemini Enterprise, quem conecta é o administrador da empresa no Google Cloud, com um par de
**ID do cliente** e **chave secreta** gerado no Meu Dinheiro. O par é de um workspace: ele só
conecta aquele workspace, e revogá-lo encerra na hora as conexões feitas com ele.
### Gere o par no Meu Dinheiro [#gere-o-par-no-meu-dinheiro]
Em **Gerenciar conta e plano → Conexões de IA**, clique em **Conectar assistente**, escolha o
**Gemini** e, em **Usa o Gemini Enterprise da empresa?**, clique em **Gerar par** e dê um nome. A
tela mostra o ID do cliente, a chave secreta e as URLs para o Google Cloud. **A chave secreta
aparece só dessa vez**: copie antes de concluir. O par fica na lista de IAs conectadas.
Só quem gerencia os usuários do workspace vê a opção.
### Crie o conector no Google Cloud [#crie-o-conector-no-google-cloud]
No console do Gemini Enterprise, crie um data store do tipo **Custom MCP Server** e preencha com o
que a tela mostrou: a URL do servidor MCP, a URL de autorização, a URL do token, o ID do cliente,
a chave secreta e os escopos **read write**. A URL de retorno é a do próprio Google
(`https://vertexaisearch.cloud.google.com/oauth-redirect`), a única que o Meu Dinheiro aceita.
### Aprove o acesso [#aprove-o-acesso]
Em **Verify Auth**, o Google abre a tela de aprovação do Meu Dinheiro. Entre com o seu login e
aprove: só aparece o workspace em que o par foi gerado.
### Ligue as ações [#ligue-as-ações]
No Gemini Enterprise as ações do conector começam desligadas. Ligue as que a sua empresa vai usar;
as de consulta não pedem confirmação, as de criar, alterar e excluir pedem.
Para cortar o acesso, revogue o par em **Conexões de IA**. As conexões feitas com ele caem na
hora, e o Google passa a receber erro de autenticação.
Um assistente pode ser enganado por texto malicioso num arquivo ou página que ele leia
(*prompt injection*). Confira o que ele pede para fazer antes de confirmar.
## Próximos passos [#próximos-passos]
* [Casos de uso](/mcp/casos-de-uso): perguntas prontas e roteiros de vários passos.
* [Ferramentas](/mcp/ferramentas): tudo o que o servidor expõe.
* [Perguntas frequentes](/mcp/perguntas-frequentes): limites, permissões e como desconectar.
# Conectar um assistente (/mcp)
O servidor **MCP** (Model Context Protocol) do Meu Dinheiro deixa um assistente de IA consultar e
organizar o seu workspace em linguagem natural: pergunte quanto gastou por categoria, qual fatura
vence primeiro, como está o DRE do trimestre ou se a carteira de investimentos bateu o CDI, e a IA
busca os números certos, os mesmos da tela.
Funciona com o **Claude** (web, Desktop e celular), o **Claude Code**, o **ChatGPT** e o **Gemini**. Por padrão
a IA só lê; criar, alterar e excluir cadastros (contas, cartões, categorias, centros de custo, tags,
formas de pagamento, projetos e contatos) só com **Permitir alterações** ligado na aprovação.
As conexões de IA estão disponíveis só para os workspaces do programa de acesso antecipado. Fale
com o suporte para participar.
## Escolha o seu assistente [#escolha-o-seu-assistente]
Web, Desktop e celular, como conector personalizado.
Conector no modo desenvolvedor, nos planos Pro, Business e Enterprise/Edu.
Conector personalizado no app do Gemini, ou no Gemini Enterprise com um par gerado no Meu Dinheiro.
Um comando no terminal e o login pelo navegador.
## Endereço do conector [#endereço-do-conector]
```
https://app.meudinheiroweb.com.br/api/public/mcp
```
É o mesmo para todos os assistentes, e também aparece com o botão **Copiar** no Meu Dinheiro, em
**Gerenciar conta e plano → Conexões de IA → Conectar assistente**.
## Como o acesso funciona [#como-o-acesso-funciona]
Não há chave para copiar. Ao conectar, o assistente abre uma tela do Meu Dinheiro em que você:
1. entra com o seu login, se ainda não estiver logado;
2. escolhe o workspace que a IA vai acessar;
3. confere o que ela poderá ver e, se quiser que ela também crie, altere e exclua cadastros, liga
**Permitir alterações**;
4. clica em **Permitir acesso**.
A IA passa a agir **com as mesmas permissões que você tem** naquele workspace: o que está oculto
para você continua oculto para ela. Se você só consulta, ela também só consulta, e o
**Permitir alterações** nem aparece. Para desfazer, desconecte em **Conexões de IA**; para passar
uma conexão somente leitura a alterações, conecte de novo.
## O que dá para fazer [#o-que-dá-para-fazer]
> "Quanto gastei por categoria no mês passado? Mostre as cinco maiores."
O assistente chama o relatório de totais por categoria e devolve a lista já ordenada, com os
valores da tela.
> "Qual fatura do cartão vence primeiro, e de quanto ela é?"
Ele busca a fatura aberta de todos os cartões numa chamada só e compara vencimentos e valores.
> "Monte o DRE do último trimestre e compare com o anterior."
Ele chama o DRE dos dois períodos e explica as diferenças linha a linha.
> "Minha carteira de investimentos rendeu mais que o CDI no último ano?"
Ele busca a rentabilidade da carteira com o CDI do mesmo período e compara, avisando até que dia
o cálculo vai.
> "Crie a tag Viagem e um centro de custo Marketing."
Com **Permitir alterações** ligado, ele cria os dois, e eles já aparecem no app.
Mais exemplos em [Casos de uso](/mcp/casos-de-uso).
## Vá mais fundo [#vá-mais-fundo]
Perguntas prontas e roteiros de vários passos.
Tudo o que o servidor expõe, por grupo.
Limites, permissões, segurança e como desconectar.
# Perguntas frequentes (/mcp/perguntas-frequentes)
## Quanto custa? [#quanto-custa]
Conectar e usar o servidor MCP não tem custo adicional no Meu Dinheiro. O assistente de IA
segue as regras do plano que você tem com ele (o ChatGPT, por exemplo, só aceita conectores nos
planos Pro, Business e Enterprise/Edu).
## Quem pode conectar? [#quem-pode-conectar]
Qualquer membro de um workspace do acesso antecipado: dono, administrador ou usuário adicional.
A conexão é **de quem aprova**, e a IA lê com as permissões dessa pessoa.
## Preciso criar uma credencial (API Key)? [#preciso-criar-uma-credencial-api-key]
Não. O assistente faz o login pelo navegador e você aprova na tela do Meu Dinheiro. A
credencial com API Key e Secret é para integrações de sistemas, como um ERP: veja a
[Primeira chamada](/primeira-chamada). A exceção é o Gemini Enterprise, que pede um par de ID e
chave secreta gerado em **Conexões de IA**: veja [Gemini Enterprise](/mcp/gemini#gemini-enterprise).
## A IA pode alterar meus dados? [#a-ia-pode-alterar-meus-dados]
Só se você permitir. A conexão nasce **somente leitura**; na aprovação, **Permitir alterações**
(desligado de início) deixa a IA criar, alterar e excluir cadastros (contas, cartões, categorias,
centros de custo, tags, formas de pagamento, projetos e contatos), e a tela lista o que ela vai
poder alterar. Ela nunca passa do que você mesmo pode fazer no workspace: se o seu
acesso é só de consulta, a opção nem aparece. Para mudar uma conexão que já existe, conecte de
novo.
## O que a IA consegue ver? [#o-que-a-ia-consegue-ver]
O mesmo que você vê no workspace escolhido, nos cadastros, relatórios, cartões, faturas e
investimentos listados em [Ferramentas](/mcp/ferramentas). Contas ocultas para você continuam ocultas, e os
contatos chegam **sem** documento, e-mail, telefone e endereço.
## Por que os números de investimentos param numa data? [#por-que-os-números-de-investimentos-param-numa-data]
A rentabilidade da carteira é calculada dia a dia quando você abre o módulo de **Investimentos** no
Meu Dinheiro. Se faz alguns dias que você não o abre, o assistente responde com os números até o
último dia calculado e avisa a data; para atualizar, abra o módulo no app. Não há rentabilidade
antes de 1º de janeiro de 2018. Os investimentos só chegam à IA se o plano do workspace inclui o
módulo de investimentos.
## Posso conectar mais de um workspace? [#posso-conectar-mais-de-um-workspace]
Cada conexão lê **um** workspace, escolhido na aprovação. Para outro workspace, adicione o
conector de novo com outro nome (por exemplo, "Meu Dinheiro – Empresa") e escolha o outro na
aprovação.
## Há limite de uso? [#há-limite-de-uso]
Sim: **120 chamadas por minuto por conexão**, a mesma cota da API pública. Passou disso, o
assistente recebe um aviso para esperar alguns segundos. Veja
[Limite de requisições](/limites).
## Como desconecto? [#como-desconecto]
No Meu Dinheiro, em **Gerenciar conta e plano → Conexões de IA**, clique em
**Desconectar** na conexão. O acesso cai na hora. Dono e administrador veem e desconectam
qualquer conexão do workspace; o usuário adicional, as que ele aprovou.
Remover o conector só no assistente não basta para cortar o acesso: desconecte também no Meu
Dinheiro. No Gemini Enterprise, revogue o par na mesma tela: as conexões feitas com ele caem
juntas ([Gemini Enterprise](/mcp/gemini#gemini-enterprise)).
## Para onde vão os meus dados? [#para-onde-vão-os-meus-dados]
Os dados que o assistente consulta são enviados ao provedor dele (Anthropic, no Claude; OpenAI,
no ChatGPT; Google, no Gemini) para montar a resposta, conforme a política de privacidade de cada
um. No Gemini, a conversa fica na sua Atividade nos apps Gemini, que você gerencia na conta
Google. O Meu Dinheiro registra cada conexão e quem a aprovou.
## É seguro? [#é-seguro]
O acesso é por login e aprovação explícita, somente leitura salvo quando você permite
alterações, e revogável a qualquer momento.
O risco que fica é o do próprio assistente: texto malicioso num arquivo ou página que ele leia
pode tentar induzi-lo a algo (*prompt injection*). Confira o que ele pede para usar antes de
permitir.
## A tela diz que nenhuma das minhas contas participa do acesso antecipado [#a-tela-diz-que-nenhuma-das-minhas-contas-participa-do-acesso-antecipado]
As conexões de IA estão liberadas só para os workspaces do programa de acesso antecipado. Fale
com o suporte para participar.
# Listas e paginação (/paginacao)
Toda listagem responde `{"data": [...], "next_cursor": "..."}` e aceita:
| Parâmetro | Significado |
| --------- | --------------------------------------------- |
| `limit` | itens por página, de 1 a 500 (padrão 100) |
| `cursor` | o `next_cursor` da página anterior, como veio |
`next_cursor` nulo é a última página. O cursor é opaco: não monte nem altere, só repasse.
A ordem é a de criação (id crescente), então o que for criado durante a leitura aparece no
fim, sem repetir nem pular itens.
# Papéis (/papeis)
A credencial tem um destes acessos:
| Acesso | O que pode |
| ---------------------- | ---------------------------------------------------------------------------- |
| **Leitor** | só lê |
| **Editor** | lê, cria, altera e exclui |
| Escopos personalizados | só o que foi marcado, funcionalidade a funcionalidade (ver, editar, excluir) |
Credenciais antigas podem ter um papel customizado do workspace; ao editar o acesso, ele aparece
como escopos personalizados.
Ela também pode ter contas **ocultas** (respondem 404, como se não existissem) ou **somente
leitura** (escrita responde 403). Chamada que o papel não cobre responde **403**. Quem
administra o workspace define isso na tela de credenciais, com as contas na aba **Restrições de contas**.
# Primeira chamada (/primeira-chamada)
### 1. Gere uma credencial [#1-gere-uma-credencial]
O dono ou um administrador do workspace gera a credencial em **Gerenciar conta e
plano → API pública**. A tela mostra duas coisas:
* a **API Key** (`mdk_…`), que identifica a credencial e aparece de novo na lista;
* o **Secret** (`mds_…`), que aparece **uma única vez**. Guarde-o num cofre de segredos.
Escolha o papel **Leitor** se a integração só consulta, ou **Escritor** se ela também cria ou
altera dados.
### 2. Troque a credencial por um token [#2-troque-a-credencial-por-um-token]
```bash
curl -s -X POST https://app.meudinheiroweb.com.br/api/public/v1/auth/token \
-H 'Content-Type: application/json' \
-d '{"api_key": "mdk_…", "api_secret": "mds_…"}'
```
```json
{
"access_token": "mda_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "mdr_…",
"refresh_expires_in": 2592000
}
```
O access token vale 1 hora. Antes de ele vencer, renove pelo refresh token — o par antigo deixa
de valer:
```bash
curl -s -X POST https://app.meudinheiroweb.com.br/api/public/v1/auth/refresh \
-H 'Content-Type: application/json' \
-d '{"refresh_token": "mdr_…"}'
```
### 3. Chame a API [#3-chame-a-api]
```bash
curl -s https://app.meudinheiroweb.com.br/api/public/v1/me \
-H 'Authorization: Bearer mda_…'
```
```json
{
"workspace": {"id": 123, "name": "Minha empresa"},
"credential": {"name": "ERP", "api_key": "mdk_…", "roles": [{"id": "leitor", "name": "Leitor", "system": true}], "expires_at": null}
}
```
### 4. Leia uma lista [#4-leia-uma-lista]
Toda listagem é paginada por cursor: repasse o `next_cursor` até ele vir nulo.
```bash
curl -s 'https://app.meudinheiroweb.com.br/api/public/v1/categorias?tipo=despesa&limit=100' \
-H 'Authorization: Bearer mda_…'
```
```json
{
"data": [
{"id": 1001, "nome": "Alimentação", "nome_completo": "Alimentação", "tipo": "despesa", "categoria_pai_id": null, "status": "active", "sistema": false},
{"id": 1042, "nome": "Delivery", "nome_completo": "Alimentação/Delivery", "tipo": "despesa", "categoria_pai_id": 1001, "status": "active", "sistema": false}
],
"next_cursor": "eyJpZCI6MTA0Mn0"
}
```
Os outros cadastros seguem o mesmo formato: `GET /contas` (tipo, moeda e banco de cada conta),
`/centros`, `/formas-pagamento`, `/tags`, `/projetos` (com período e metas) e `/contatos` (clientes e fornecedores, com documento,
e-mail, telefones e endereço). Cada um tem também a consulta por id, como `GET /contatos/9120`.
## O que pode dar errado [#o-que-pode-dar-errado]
| Resposta | Causa comum |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 bad_request` | parâmetro inválido (`limit`, `cursor`, filtro); o `message` diz qual |
| `401 unauthorized` | token vencido (renove), credencial revogada ou secret errado |
| `403 forbidden` | chamada que o papel da credencial não cobre (escrita com Leitor, por exemplo), conta somente leitura, workspace fora do acesso antecipado ou desativado |
| `429 rate_limited` | mais de 120 chamadas no minuto; espere o `Retry-After` |
Todo erro vem como `{"error": {"code": "...", "message": "..."}}` — trate pelo `code`.
# Referência (/referencia)
Cada rota tem parâmetros, corpo de resposta por status, exemplos em várias linguagens e o
botão **Testar**, que chama a API a partir desta página com o seu access token.
O spec completo está em [`/openapi.json`](/openapi.json) — importe no Postman, no Insomnia ou
num gerador de cliente.
# Relatórios (/relatorios)
Os relatórios de lançamentos do app, com os mesmos números da tela: totais por cadastro,
resultado, saldos, fluxo de caixa, metas, DRE e DFC.
## Permissões [#permissões]
Cada relatório exige a permissão de leitura da tela equivalente; sem ela, **403**. Conta oculta
para a credencial fica fora de toda soma.
## Valores [#valores]
Os valores têm sinal: despesa e saída negativas, receita e entrada positivas. Toda soma traz:
| Campo | O que soma |
| ------------ | --------------------------------------------------------------------------- |
| `projetado` | tudo o que o filtro alcança, inclusive o que ainda não foi pago ou recebido |
| `confirmado` | só o realizado |
## Período [#período]
`inicio` e `fim` em `AAAA-MM-DD`, até 5 anos (366 dias com `intervalo=dia`). O lançamento
recorrente entra em todos os relatórios: as agendas geram as ocorrências até o `fim` antes da
soma.
# Troca a credencial por um par de tokens (/referencia/autenticacao/issue-token)
`POST /auth/token`
```json
{
"operationId": "issueToken",
"tags": [
"Autenticação"
],
"summary": "Troca a credencial por um par de tokens",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"api_key",
"api_secret"
],
"properties": {
"api_key": {
"type": "string",
"examples": [
"mdk_7bba95be3df304bd8c3ab559"
]
},
"api_secret": {
"type": "string",
"format": "password"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/TokenPair"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Renova o par de tokens pelo refresh token (/referencia/autenticacao/refresh-token)
`POST /auth/refresh`
```json
{
"operationId": "refreshToken",
"tags": [
"Autenticação"
],
"summary": "Renova o par de tokens pelo refresh token",
"description": "O par usado deixa de valer, inclusive o access token dele.",
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"refresh_token"
],
"properties": {
"refresh_token": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/TokenPair"
},
"400": {
"$ref": "#/components/responses/Error"
},
"401": {
"$ref": "#/components/responses/Error"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# O workspace e a credencial ou a conexão do token (/referencia/credencial/me)
`GET /me`
```json
{
"operationId": "me",
"tags": [
"Credencial"
],
"summary": "O workspace e a credencial ou a conexão do token",
"description": "A primeira chamada de quem integra, para conferir o token. Token de credencial (Key +\nSecret) traz `credential`; token de uma conexão MCP aprovada por um usuário traz `connection`.\n",
"responses": {
"200": {
"description": "Credencial válida.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Me"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista as contas (/referencia/contas/list-contas)
`GET /contas`
```json
{
"operationId": "listContas",
"tags": [
"Contas"
],
"summary": "Lista as contas",
"description": "Todas as contas do workspace: correntes, dinheiro, cartões de crédito, investimentos,\npoupança, imóveis, empréstimos e as demais contas do balanço. Inclui as inativas e as\nencerradas; filtre com `status=active` para só as que estão em uso. Não traz saldo.\n\nConta **oculta** para a credencial não aparece (e responde 404 na consulta por id); conta\n**somente leitura** aparece normalmente.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "tipo",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TipoConta"
}
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusConta"
}
}
],
"responses": {
"200": {
"description": "Uma página de contas.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContaPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria uma conta (/referencia/contas/create-conta)
`POST /contas`
```json
{
"operationId": "createConta",
"tags": [
"Contas"
],
"summary": "Cria uma conta",
"description": "Cria uma conta do workspace, com o saldo inicial lançado na data informada. Exige o papel\n**Editor** ou um papel com permissão de editar Contas.\n\nCartão de crédito se cria em `POST /cartoes`, e esta versão não cria `aplicacao_financeira`;\nos dois tipos aqui respondem 400. Em\n`contas_a_pagar` a `finalidade` é obrigatória (nos outros tipos, 400), e o tipo só existe em\nworkspace de pessoa jurídica: em pessoa física responde 422, como o app, que não o oferece.\nEm conta de passivo e de patrimônio líquido (`emprestimo_contratado`, `outros_passivos`,\n`capital_social`, `contas_a_pagar`) o saldo inicial é gravado negativo, como no app. Poupança\nsó existe em BRL.\n\nA resposta é a conta criada, no mesmo formato do `GET /contas/{id}`. Campo fora da lista\nresponde 400.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContaCriacao"
}
}
}
},
"responses": {
"201": {
"description": "A conta criada.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Conta"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite criar contas, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A regra do Meu Dinheiro recusa a conta: saldo inicial no futuro (ou de hoje em poupança e imóvel), poupança fora de BRL, conta a pagar em workspace de pessoa física ou o limite de contas do workspace atingido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Uma conta (/referencia/contas/get-conta)
`GET /contas/{id}`
```json
{
"operationId": "getConta",
"tags": [
"Contas"
],
"summary": "Uma conta",
"description": "Conta de outro workspace, inexistente ou oculta para a credencial responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "A conta.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Conta"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma conta (só os campos enviados) (/referencia/contas/update-conta)
`PATCH /contas/{id}`
```json
{
"operationId": "updateConta",
"tags": [
"Contas"
],
"summary": "Altera uma conta (só os campos enviados)",
"description": "Altera só os campos enviados; os demais ficam como estão. Nulo limpa `banco`, `agencia` e\n`numero_conta`. As regras são as do `PUT`. Para tirar a conta de uso sem perder o histórico,\nmude o `status` para `closed` (encerrada) ou `inactive`.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContaAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "A conta alterada, no formato do `GET /contas/{id}`.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Conta"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite alterar contas, a conta é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A regra do Meu Dinheiro recusa a alteração (ver o `PUT`).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui uma conta (/referencia/contas/delete-conta)
`DELETE /contas/{id}`
```json
{
"operationId": "deleteConta",
"tags": [
"Contas"
],
"summary": "Exclui uma conta",
"description": "Exclui a conta e o saldo inicial dela. Exige o papel **Editor** ou um papel com permissão\nde excluir Contas. A exclusão é definitiva.\n\nConta com lançamentos, com operações de investimento ou que paga um cartão de crédito não é\nexcluída, nem a última conta do workspace: a resposta é 422, e a saída que guarda o\nhistórico é encerrar a conta (`PATCH` com `status: closed`). Os tipos que a API não cria\nrespondem 422.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Excluída.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite excluir contas, a conta é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A conta tem lançamentos, operações de investimento ou cartão pago por ela, é a última do workspace, ou é de um tipo que a API não exclui nesta versão.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma conta (todos os campos) (/referencia/contas/replace-conta)
`PUT /contas/{id}`
```json
{
"operationId": "replaceConta",
"tags": [
"Contas"
],
"summary": "Altera uma conta (todos os campos)",
"description": "Troca todos os campos graváveis da conta; para alterar só alguns, use `PATCH`. Exige o papel\n**Editor** ou um papel com permissão de editar Contas. O `tipo` não muda depois de criada:\n`tipo` e `id` no corpo respondem 400.\n\nNesta versão a API altera só os tipos que ela cria; `cartao_credito` (que se altera em\n`/cartoes`) e `aplicacao_financeira` respondem 422. Em `contas_a_pagar` a `finalidade` também é exigida. Em conta de passivo e\nde patrimônio líquido o saldo inicial é gravado negativo, como na criação.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContaAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "A conta alterada, no formato do `GET /contas/{id}`.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Conta"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite alterar contas, a conta é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A regra do Meu Dinheiro recusa a alteração: saldo inicial no futuro (ou de hoje em poupança e imóvel), poupança fora de BRL, troca de moeda em conta com operações de investimento, ou tipo que a API não altera nesta versão.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista os cartões de crédito (/referencia/cartoes/list-cartoes)
`GET /cartoes`
```json
{
"operationId": "listCartoes",
"tags": [
"Cartões"
],
"summary": "Lista os cartões de crédito",
"description": "Os cartões do workspace com limite, vencimento, fechamento, a conta que paga a fatura e os\nplásticos. Inclui os inativos e os encerrados; filtre com `status=active` para só os que estão\nem uso. Cartão **oculto** para a credencial não aparece.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusConta"
}
}
],
"responses": {
"200": {
"description": "Uma página de cartões.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CartaoPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria um cartão (/referencia/cartoes/create-cartao)
`POST /cartoes`
```json
{
"operationId": "createCartao",
"tags": [
"Cartões"
],
"summary": "Cria um cartão",
"description": "Cria um cartão de crédito com os plásticos (um titular e os adicionais) e a fatura do mês\nanterior ao vencimento, já fechada com o `valor_fatura_anterior`. Exige o papel **Editor** ou\num papel com permissão de editar Contas (o mesmo do app). A conta de pagamento precisa estar na\nmoeda do cartão e ser conta corrente, dinheiro, poupança ou conta do balanço.\n\nA resposta é o cartão criado, no formato do `GET /cartoes/{id}`. O cartão também aparece em\n`/contas`, com `tipo` `cartao_credito`, mas só se escreve aqui.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CartaoCriacao"
}
}
}
},
"responses": {
"201": {
"description": "O cartão criado.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Cartao"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite criar contas, o cartão é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A regra do Meu Dinheiro recusa o cartão: sem titular ou com dois, conta de pagamento de outra moeda ou de tipo que não paga fatura, ou o limite de contas do workspace atingido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# A fatura de todos os cartões num mês (/referencia/cartoes/list-faturas-do-mes)
`GET /cartoes/faturas`
```json
{
"operationId": "listFaturasDoMes",
"tags": [
"Cartões"
],
"summary": "A fatura de todos os cartões num mês",
"description": "O resumo da fatura de cada cartão em uso que vence no mês, numa chamada só: \"quanto vou\npagar de cartão este mês\". Sem `mes`, a fatura aberta de cada cartão. Os números são os de\n`GET /cartoes/{id}/faturas/{mes}`, sem os lançamentos; cartão cuja fatura do mês passa do\nhorizonte de faturas futuras fica de fora.\n",
"parameters": [
{
"name": "mes",
"in": "query",
"description": "O mês do vencimento, `AAAA-MM`. Sem ele, a fatura aberta de cada cartão.",
"schema": {
"$ref": "#/components/schemas/Mes"
}
}
],
"responses": {
"200": {
"description": "Uma linha por cartão.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FaturasDoMes"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# As parcelas futuras de todos os cartões (/referencia/cartoes/list-parcelas-futuras-de-todos)
`GET /cartoes/parcelas-futuras`
```json
{
"operationId": "listParcelasFuturasDeTodos",
"tags": [
"Cartões"
],
"summary": "As parcelas futuras de todos os cartões",
"description": "As parcelas futuras de cada cartão em uso, numa chamada só, um bloco por cartão no formato de `GET /cartoes/{id}/parcelas-futuras`.",
"responses": {
"200": {
"description": "Um bloco por cartão.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParcelasFuturas"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Um cartão (/referencia/cartoes/get-cartao)
`GET /cartoes/{id}`
```json
{
"operationId": "getCartao",
"tags": [
"Cartões"
],
"summary": "Um cartão",
"description": "Cartão de outro workspace, inexistente, oculto para a credencial ou conta que não é cartão responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "O cartão.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Cartao"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um cartão (só os campos enviados) (/referencia/cartoes/update-cartao)
`PATCH /cartoes/{id}`
```json
{
"operationId": "updateCartao",
"tags": [
"Cartões"
],
"summary": "Altera um cartão (só os campos enviados)",
"description": "Altera só os campos enviados; as regras são as do `PUT`. Para tirar o cartão de uso sem perder\no histórico, mude o `status` para `closed`.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CartaoAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "O cartão alterado, no formato do `GET /cartoes/{id}`.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Cartao"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite alterar contas, o cartão é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A regra do Meu Dinheiro recusa a alteração (ver o `PUT`).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui um cartão (/referencia/cartoes/delete-cartao)
`DELETE /cartoes/{id}`
```json
{
"operationId": "deleteCartao",
"tags": [
"Cartões"
],
"summary": "Exclui um cartão",
"description": "Exclui o cartão, os plásticos e as faturas. Exige o papel **Editor** ou um papel com\npermissão de excluir Contas. A exclusão é definitiva. Cartão com lançamentos não é\nexcluído (422): a saída que guarda o histórico é encerrá-lo (`PATCH` com `status: closed`).\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Excluído.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite excluir contas, o cartão é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O cartão tem lançamentos.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um cartão (todos os campos) (/referencia/cartoes/replace-cartao)
`PUT /cartoes/{id}`
```json
{
"operationId": "replaceCartao",
"tags": [
"Cartões"
],
"summary": "Altera um cartão (todos os campos)",
"description": "Troca todos os campos do cartão (menos `valor_fatura_anterior`, opcional); para alterar só\nalguns, use `PATCH`. Exige o papel **Editor** ou um papel com permissão de editar Contas.\n\nPlásticos: com `id`, o existente (nome e status; o titular não se inativa); sem `id`, um novo.\nPlástico fora da lista fica como está, e adicional inativado sem lançamentos é excluído, como\nno app. Trocar o `proximo_vencimento` desloca as faturas abertas: no máximo um mês adiante, e\npara trás só se aquele mês não tem fatura fechada; adiante, com fatura fechada antiga, a fatura\naberta é fechada.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CartaoAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "O cartão alterado, no formato do `GET /cartoes/{id}`.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Cartao"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"description": "O papel da credencial não permite alterar contas, o cartão é somente leitura para ela, ou o workspace está fora do acesso antecipado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A regra do Meu Dinheiro recusa a alteração: vencimento fora do que o app aceita, titular inativado, conta de pagamento de outra moeda ou de tipo que não paga fatura, troca de moeda em cartão com operações.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# As faturas do cartão, mês a mês (/referencia/cartoes/list-faturas)
`GET /cartoes/{id}/faturas`
```json
{
"operationId": "listFaturas",
"tags": [
"Cartões"
],
"summary": "As faturas do cartão, mês a mês",
"description": "Um resumo por fatura, de `inicio` a `fim`: vencimento, situação, valor e pagamentos. Os meses\nantes da fatura aberta só aparecem quando a fatura existe; da aberta em diante, todos — a futura\ntraz o que já foi lançado nela, inclusive parcelas e recorrências.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
},
{
"name": "inicio",
"in": "query",
"description": "O primeiro mês. Sem o parâmetro, 11 meses antes do `fim`.",
"schema": {
"$ref": "#/components/schemas/Mes"
}
},
{
"name": "fim",
"in": "query",
"description": "O último mês, até 36 depois do de `inicio` e da fatura aberta. Sem o parâmetro, o mês da fatura aberta.",
"schema": {
"$ref": "#/components/schemas/Mes"
}
}
],
"responses": {
"200": {
"description": "O histórico.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoricoFaturas"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Uma fatura com os lançamentos (/referencia/cartoes/get-fatura)
`GET /cartoes/{id}/faturas/{mes}`
```json
{
"operationId": "getFatura",
"tags": [
"Cartões"
],
"summary": "Uma fatura com os lançamentos",
"description": "A fatura que vence em `mes`, com o resumo da tela e todos os lançamentos (sem paginação). Mês\nsem fatura — antes do cartão, a primeira (que só guarda o saldo anterior ao cadastro) ou anterior\nà aberta que não existe — responde 404.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
},
{
"name": "mes",
"in": "path",
"required": true,
"description": "O mês do vencimento.",
"schema": {
"$ref": "#/components/schemas/Mes"
}
}
],
"responses": {
"200": {
"description": "A fatura.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Fatura"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# As parcelas que ainda vão cair (/referencia/cartoes/list-parcelas-futuras)
`GET /cartoes/{id}/parcelas-futuras`
```json
{
"operationId": "listParcelasFuturas",
"tags": [
"Cartões"
],
"summary": "As parcelas que ainda vão cair",
"description": "As parcelas de compras parceladas nas faturas depois da aberta, como na tela Parcelas futuras.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "O id do cartão (o mesmo da conta em `/contas`).",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "As parcelas.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ParcelasFuturas"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista as categorias (/referencia/categorias/list-categorias)
`GET /categorias`
```json
{
"operationId": "listCategorias",
"tags": [
"Categorias"
],
"summary": "Lista as categorias",
"description": "Categorias de receita, despesa e transferência, com as subcategorias na mesma lista\n(`categoria_pai_id` aponta para a categoria de cima). Inclui as inativas, que lançamentos\nantigos ainda usam; filtre com `status=active` para ficar só com as ativas.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "tipo",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TipoCategoria"
}
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"active",
"inactive"
]
}
}
],
"responses": {
"200": {
"description": "Uma página de categorias.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriaPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria uma categoria (/referencia/categorias/create-categoria)
`POST /categorias`
```json
{
"operationId": "createCategoria",
"tags": [
"Categorias"
],
"summary": "Cria uma categoria",
"description": "Cria uma categoria ativa de receita ou despesa; com `categoria_pai_id`, uma subcategoria\n(um nível só, do mesmo tipo da de cima, que deve estar ativa). Transferência é do Meu\nDinheiro e não se cria. As linhas do DRE e do DFC não fazem parte da API: a categoria\nnasce sem elas, e quem usa os demonstrativos as liga pelo app. Exige o papel\n**Editor** ou um papel com permissão de editar Categorias. A resposta tem o mesmo\nformato do `GET /categorias/{id}`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriaCriacao"
}
}
}
},
"responses": {
"201": {
"description": "A categoria criada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Categoria"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"422": {
"description": "O limite de categorias do workspace foi atingido, ou a categoria de cima não existe,\né de outro tipo, é uma subcategoria ou está inativa.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Uma categoria (/referencia/categorias/get-categoria)
`GET /categorias/{id}`
```json
{
"operationId": "getCategoria",
"tags": [
"Categorias"
],
"summary": "Uma categoria",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "A categoria.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Categoria"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma categoria (só os campos enviados) (/referencia/categorias/update-categoria)
`PATCH /categorias/{id}`
```json
{
"operationId": "updateCategoria",
"tags": [
"Categorias"
],
"summary": "Altera uma categoria (só os campos enviados)",
"description": "Altera somente os campos enviados; `categoria_pai_id` nulo leva a categoria ao primeiro\nnível. Inativar a que tem subcategoria ativa, ou pôr sob outra a que tem subcategorias, é\n422. Exige o papel **Editor** ou um papel com permissão de editar Categorias.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriaAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "A categoria alterada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Categoria"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui uma categoria (/referencia/categorias/delete-categoria)
`DELETE /categorias/{id}`
```json
{
"operationId": "deleteCategoria",
"tags": [
"Categorias"
],
"summary": "Exclui uma categoria",
"description": "Exclui a categoria e leva para `destino_id`, **obrigatório**, os lançamentos, agendas e\nregras que a usavam: lançamento não fica sem categoria. O destino deve ser outra categoria\ndo mesmo workspace e do mesmo tipo (inativa ou subcategoria também serve). As metas de\norçamento da categoria são apagadas. Categoria de sistema e categoria com subcategorias não\nse excluem. Exige o papel **Editor** ou um papel com permissão de excluir Categorias. A\nexclusão é definitiva.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "destino_id",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"204": {
"description": "Excluída."
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O destino é a própria categoria ou de outro tipo, a categoria é de sistema ou tem subcategorias.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma categoria (todos os campos) (/referencia/categorias/replace-categoria)
`PUT /categorias/{id}`
```json
{
"operationId": "replaceCategoria",
"tags": [
"Categorias"
],
"summary": "Altera uma categoria (todos os campos)",
"description": "Troca nome, categoria de cima e status; `tipo` não muda (400). Categoria de sistema não se\naltera (422). Para alterar só alguns campos, use `PATCH`. Exige o papel **Editor** ou um\npapel com permissão de editar Categorias.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriaAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "A categoria alterada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Categoria"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista os centros de custo (/referencia/centros-de-custo/list-centros)
`GET /centros`
```json
{
"operationId": "listCentros",
"tags": [
"Centros de custo"
],
"summary": "Lista os centros de custo",
"description": "Os centros de custo do workspace, que classificam lançamentos por área, setor ou\natividade. Inclui os inativos; `status` filtra.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusCadastro"
}
}
],
"responses": {
"200": {
"description": "Uma página.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CentroPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria um centro de custo (/referencia/centros-de-custo/create-centro)
`POST /centros`
```json
{
"operationId": "createCentro",
"tags": [
"Centros de custo"
],
"summary": "Cria um centro de custo",
"description": "Cria um centro de custo ativo. Exige o papel **Editor** ou um papel com permissão de\neditar Centros. A resposta tem o mesmo formato do `GET /centros/{id}`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CentroCriacao"
}
}
}
},
"responses": {
"201": {
"description": "O centro criado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Centro"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"422": {
"description": "O limite de centros de custo do workspace foi atingido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Um centro de custo (/referencia/centros-de-custo/get-centro)
`GET /centros/{id}`
```json
{
"operationId": "getCentro",
"tags": [
"Centros de custo"
],
"summary": "Um centro de custo",
"description": "Centro de outro workspace, ou inexistente, responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "O item.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Centro"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um centro de custo (só os campos enviados) (/referencia/centros-de-custo/update-centro)
`PATCH /centros/{id}`
```json
{
"operationId": "updateCentro",
"tags": [
"Centros de custo"
],
"summary": "Altera um centro de custo (só os campos enviados)",
"description": "Altera somente `nome` e/ou `status`; os campos ausentes ficam como estão. Exige o papel\n**Editor** ou um papel com permissão de editar Centros.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CentroAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "O centro alterado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Centro"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui um centro de custo (/referencia/centros-de-custo/delete-centro)
`DELETE /centros/{id}`
```json
{
"operationId": "deleteCentro",
"tags": [
"Centros de custo"
],
"summary": "Exclui um centro de custo",
"description": "Exclui o centro. `destino_id` leva para outro centro os lançamentos, agendas e regras\nque o usavam; sem destino, eles ficam sem centro. O destino deve pertencer ao mesmo\nworkspace e ser diferente do excluído. Exige o papel **Editor** ou um papel com permissão\nde excluir Centros. A exclusão é definitiva.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "destino_id",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"204": {
"description": "Excluído."
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O destino é o próprio centro excluído.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um centro de custo (todos os campos) (/referencia/centros-de-custo/replace-centro)
`PUT /centros/{id}`
```json
{
"operationId": "replaceCentro",
"tags": [
"Centros de custo"
],
"summary": "Altera um centro de custo (todos os campos)",
"description": "Troca `nome` e `status`; para alterar só um deles, use `PATCH`. Exige o papel **Editor**\nou um papel com permissão de editar Centros.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CentroAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "O centro alterado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Centro"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista as tags (/referencia/tags/list-tags)
`GET /tags`
```json
{
"operationId": "listTags",
"tags": [
"Tags"
],
"summary": "Lista as tags",
"description": "As tags do workspace, marcadores livres dos lançamentos. Inclui as inativas;\n`status` filtra.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusCadastro"
}
}
],
"responses": {
"200": {
"description": "Uma página.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TagPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria uma tag (/referencia/tags/create-tag)
`POST /tags`
```json
{
"operationId": "createTag",
"tags": [
"Tags"
],
"summary": "Cria uma tag",
"description": "Cria uma tag ativa. Exige o papel **Editor** ou um papel com permissão de editar Tags.\nA resposta tem o mesmo formato do `GET /tags/{id}`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TagCriacao"
}
}
}
},
"responses": {
"201": {
"description": "A tag criada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tag"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"422": {
"description": "O nome já existe ou o limite de tags do workspace foi atingido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Uma tag (/referencia/tags/get-tag)
`GET /tags/{id}`
```json
{
"operationId": "getTag",
"tags": [
"Tags"
],
"summary": "Uma tag",
"description": "Tag de outro workspace, ou inexistente, responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "O item.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tag"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma tag (só os campos enviados) (/referencia/tags/update-tag)
`PATCH /tags/{id}`
```json
{
"operationId": "updateTag",
"tags": [
"Tags"
],
"summary": "Altera uma tag (só os campos enviados)",
"description": "Altera somente `nome`, `cor` e/ou `status`; os campos ausentes ficam como estão. Exige o\npapel **Editor** ou um papel com permissão de editar Tags.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TagAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "A tag alterada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tag"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O nome já pertence a outra tag.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui uma tag (/referencia/tags/delete-tag)
`DELETE /tags/{id}`
```json
{
"operationId": "deleteTag",
"tags": [
"Tags"
],
"summary": "Exclui uma tag",
"description": "Exclui a tag e a tira dos lançamentos, das agendas e das regras que a usavam. Exige o papel\n**Editor** ou um papel com permissão de excluir Tags. A exclusão é definitiva.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Excluída."
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma tag (todos os campos) (/referencia/tags/replace-tag)
`PUT /tags/{id}`
```json
{
"operationId": "replaceTag",
"tags": [
"Tags"
],
"summary": "Altera uma tag (todos os campos)",
"description": "Troca `nome`, `cor` e `status`; para alterar só alguns deles, use `PATCH`. Exige o papel\n**Editor** ou um papel com permissão de editar Tags.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TagAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "A tag alterada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Tag"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O nome já pertence a outra tag.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista as formas de pagamento (/referencia/formas-de-pagamento/list-formas-pagamento)
`GET /formas-pagamento`
```json
{
"operationId": "listFormasPagamento",
"tags": [
"Formas de pagamento"
],
"summary": "Lista as formas de pagamento",
"description": "As formas de pagamento do workspace. Inclui as inativas; `tipo` e `status` filtram.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "tipo",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TipoFormaPagamento"
}
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusCadastro"
}
}
],
"responses": {
"200": {
"description": "Uma página.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamentoPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria uma forma de pagamento (/referencia/formas-de-pagamento/create-forma-pagamento)
`POST /formas-pagamento`
```json
{
"operationId": "createFormaPagamento",
"tags": [
"Formas de pagamento"
],
"summary": "Cria uma forma de pagamento",
"description": "Cria uma forma ativa do tipo `normal`; no workspace que ainda não tem formas, cria antes as\nformas padrão. A de `cartao_credito` é criada pelo Meu Dinheiro e não se cria pela API.\nExige o papel **Editor** ou um papel com permissão de editar Formas de pagamento.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamentoCriacao"
}
}
}
},
"responses": {
"201": {
"description": "A forma criada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamento"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"422": {
"description": "O tipo é `cartao_credito` ou o limite de formas do workspace foi atingido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Uma forma de pagamento (/referencia/formas-de-pagamento/get-forma-pagamento)
`GET /formas-pagamento/{id}`
```json
{
"operationId": "getFormaPagamento",
"tags": [
"Formas de pagamento"
],
"summary": "Uma forma de pagamento",
"description": "Forma de outro workspace, ou inexistente, responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "O item.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamento"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma forma de pagamento (só os campos enviados) (/referencia/formas-de-pagamento/update-forma-pagamento)
`PATCH /formas-pagamento/{id}`
```json
{
"operationId": "updateFormaPagamento",
"tags": [
"Formas de pagamento"
],
"summary": "Altera uma forma de pagamento (só os campos enviados)",
"description": "Altera `nome` e/ou `status`; o `tipo` não muda e os campos ausentes ficam como estão. Exige\no papel **Editor** ou um papel com permissão de editar Formas de pagamento.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamentoAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "A forma alterada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamento"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A forma é a de cartão de crédito, criada pelo Meu Dinheiro.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui uma forma de pagamento (/referencia/formas-de-pagamento/delete-forma-pagamento)
`DELETE /formas-pagamento/{id}`
```json
{
"operationId": "deleteFormaPagamento",
"tags": [
"Formas de pagamento"
],
"summary": "Exclui uma forma de pagamento",
"description": "Exclui a forma e a tira dos lançamentos, das agendas e das regras que a usavam. A de cartão\nde crédito não pode ser excluída. Exige o papel **Editor** ou um papel com permissão de\nexcluir Formas de pagamento. A exclusão é definitiva.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Excluída."
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A forma é a de cartão de crédito, criada pelo Meu Dinheiro.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera uma forma de pagamento (todos os campos) (/referencia/formas-de-pagamento/replace-forma-pagamento)
`PUT /formas-pagamento/{id}`
```json
{
"operationId": "replaceFormaPagamento",
"tags": [
"Formas de pagamento"
],
"summary": "Altera uma forma de pagamento (todos os campos)",
"description": "Troca `nome` e `status`; o `tipo` não muda. Para alterar só um campo, use `PATCH`. Exige o\npapel **Editor** ou um papel com permissão de editar Formas de pagamento.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamentoAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "A forma alterada.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormaPagamento"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A forma é a de cartão de crédito, criada pelo Meu Dinheiro.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista os projetos (/referencia/projetos/list-projetos)
`GET /projetos`
```json
{
"operationId": "listProjetos",
"tags": [
"Projetos"
],
"summary": "Lista os projetos",
"description": "Os projetos do workspace, que agrupam lançamentos de uma obra, evento ou cliente, com\no período e as metas do projeto inteiro. Inclui os inativos; `status` filtra.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusCadastro"
}
}
],
"responses": {
"200": {
"description": "Uma página.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjetoPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria um projeto (/referencia/projetos/create-projeto)
`POST /projetos`
```json
{
"operationId": "createProjeto",
"tags": [
"Projetos"
],
"summary": "Cria um projeto",
"description": "Cria um projeto ativo. Exige o papel **Editor** ou um papel com permissão de\neditar Projetos. A resposta tem o mesmo formato do `GET /projetos/{id}`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjetoCriacao"
}
}
}
},
"responses": {
"201": {
"description": "O projeto criado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Projeto"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"422": {
"description": "O limite de projetos do workspace foi atingido, ou o fim é antes do início.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Um projeto (/referencia/projetos/get-projeto)
`GET /projetos/{id}`
```json
{
"operationId": "getProjeto",
"tags": [
"Projetos"
],
"summary": "Um projeto",
"description": "Projeto de outro workspace, ou inexistente, responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "O item.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Projeto"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um projeto (só os campos enviados) (/referencia/projetos/update-projeto)
`PATCH /projetos/{id}`
```json
{
"operationId": "updateProjeto",
"tags": [
"Projetos"
],
"summary": "Altera um projeto (só os campos enviados)",
"description": "Altera somente os campos enviados; os ausentes ficam como estão, e nulo em `inicio`, `fim`\nou nas metas remove o valor. Exige o papel **Editor** ou um papel com permissão de editar\nProjetos.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjetoAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "O projeto alterado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Projeto"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui um projeto (/referencia/projetos/delete-projeto)
`DELETE /projetos/{id}`
```json
{
"operationId": "deleteProjeto",
"tags": [
"Projetos"
],
"summary": "Exclui um projeto",
"description": "Exclui o projeto. `destino_id` leva para outro projeto os lançamentos, agendas e regras\nque o usavam; sem destino, eles ficam sem projeto. As metas por categoria do projeto são\napagadas nos dois casos. O destino deve pertencer ao mesmo workspace e ser diferente do\nexcluído. Exige o papel **Editor** ou um papel com permissão de excluir Projetos. A\nexclusão é definitiva.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "destino_id",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"204": {
"description": "Excluído."
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O destino é o próprio projeto excluído.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um projeto (todos os campos) (/referencia/projetos/replace-projeto)
`PUT /projetos/{id}`
```json
{
"operationId": "replaceProjeto",
"tags": [
"Projetos"
],
"summary": "Altera um projeto (todos os campos)",
"description": "Troca todos os campos; `inicio`, `fim` e as metas aceitam nulo. Para alterar só alguns, use\n`PATCH`. Exige o papel **Editor** ou um papel com permissão de editar Projetos.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjetoAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "O projeto alterado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Projeto"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Lista os contatos (/referencia/contatos/list-contatos)
`GET /contatos`
```json
{
"operationId": "listContatos",
"tags": [
"Contatos"
],
"summary": "Lista os contatos",
"description": "Os clientes e fornecedores do workspace, com documento, e-mail, telefones e\nendereço. Inclui os inativos. `tipo_contato=cliente` traz também quem é cliente **e**\nfornecedor (`ambos`); o mesmo vale para `fornecedor`.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "tipo_pessoa",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TipoPessoa"
}
},
{
"name": "tipo_contato",
"in": "query",
"schema": {
"$ref": "#/components/schemas/TipoContato"
}
},
{
"name": "status",
"in": "query",
"schema": {
"$ref": "#/components/schemas/StatusCadastro"
}
}
],
"responses": {
"200": {
"description": "Uma página.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContatoPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Cria um contato (/referencia/contatos/create-contato)
`POST /contatos`
```json
{
"operationId": "createContato",
"tags": [
"Contatos"
],
"summary": "Cria um contato",
"description": "Cria um contato ativo. `nome`, `tipo_pessoa` e `tipo_contato` são obrigatórios; o\n`documento` é validado (CPF na pessoa física, CNPJ, inclusive alfanumérico, na jurídica) e\ngravado sem pontuação. RG, nascimento, inscrições, observação, campos personalizados e\nanexos ficam fora do contrato. Exige o papel **Editor** ou um papel com permissão de\neditar Contatos. A resposta tem o mesmo formato do `GET /contatos/{id}`.\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContatoCriacao"
}
}
}
},
"responses": {
"201": {
"description": "O contato criado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contato"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"422": {
"description": "O limite de contatos do workspace foi atingido, ou a categoria não existe.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Um contato (/referencia/contatos/get-contato)
`GET /contatos/{id}`
```json
{
"operationId": "getContato",
"tags": [
"Contatos"
],
"summary": "Um contato",
"description": "Contato de outro workspace, ou inexistente, responde 404.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "O item.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contato"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um contato (só os campos enviados) (/referencia/contatos/update-contato)
`PATCH /contatos/{id}`
```json
{
"operationId": "updateContato",
"tags": [
"Contatos"
],
"summary": "Altera um contato (só os campos enviados)",
"description": "Altera somente os campos enviados; os ausentes ficam como estão. Trocar `tipo_pessoa`\nconfere o documento gravado contra o tipo novo. Exige o papel **Editor** ou um papel com\npermissão de editar Contatos.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContatoAlteracaoParcial"
}
}
}
},
"responses": {
"200": {
"description": "O contato alterado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contato"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Exclui um contato (/referencia/contatos/delete-contato)
`DELETE /contatos/{id}`
```json
{
"operationId": "deleteContato",
"tags": [
"Contatos"
],
"summary": "Exclui um contato",
"description": "Exclui o contato. `destino_id` leva para outro contato os lançamentos, agendas e regras\nque o usavam; sem destino, eles ficam sem contato. Contato com proposta comercial não é\nexcluído (422). O destino deve pertencer ao mesmo workspace e ser diferente do excluído.\nExige o papel **Editor** ou um papel com permissão de excluir Contatos. A exclusão é\ndefinitiva.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "destino_id",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"204": {
"description": "Excluído."
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "O destino é o próprio contato excluído, ou o contato tem proposta comercial.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Altera um contato (todos os campos) (/referencia/contatos/replace-contato)
`PUT /contatos/{id}`
```json
{
"operationId": "replaceContato",
"tags": [
"Contatos"
],
"summary": "Altera um contato (todos os campos)",
"description": "Troca todos os campos do contrato; nulo limpa. O que está fora do contrato (RG, nascimento,\ninscrições, observação, campos personalizados, anexos) fica como está. Para alterar só\nalguns, use `PATCH`. Exige o papel **Editor** ou um papel com permissão de editar\nContatos.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContatoAlteracao"
}
}
}
},
"responses": {
"200": {
"description": "O contato alterado.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contato"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/NotEnabled"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Totais por categoria (/referencia/relatorios/relatorio-totais-categorias)
`GET /relatorios/totais/categorias`
```json
{
"operationId": "relatorioTotaisCategorias",
"tags": [
"Relatórios"
],
"summary": "Totais por categoria",
"description": "Soma por categoria, com a categoria de cima em `categoria_pai`. É a tela Totais por categoria; com `intervalo`, a Evolução por categoria. Sem `tipo`, receita e despesa.\n\nExige a permissão de ver Totais por categoria, Evolução por categoria, Despesas/Receitas por categoria da visão geral ou Lançamentos por categoria.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
},
{
"name": "agrupar_subcategorias",
"in": "query",
"description": "Soma a subcategoria na categoria de cima.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "Os totais.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotaisPorCategorias"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Totais por centro de custo (/referencia/relatorios/relatorio-totais-centros)
`GET /relatorios/totais/centros`
```json
{
"operationId": "relatorioTotaisCentros",
"tags": [
"Relatórios"
],
"summary": "Totais por centro de custo",
"description": "Soma por centro de custo e tipo. É a tela Totais por centro; com `intervalo`, a Evolução por centro. Sem `tipo`, receita e despesa.\n\nExige a permissão de ver Totais por centro, Evolução por centro, Despesas/Receitas/Resultados por centro da visão geral ou Lançamentos por centro.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "Os totais.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotaisPorCentros"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Totais por contato (/referencia/relatorios/relatorio-totais-contatos)
`GET /relatorios/totais/contatos`
```json
{
"operationId": "relatorioTotaisContatos",
"tags": [
"Relatórios"
],
"summary": "Totais por contato",
"description": "Soma por contato (cliente ou fornecedor) e tipo. Sem `tipo`, receita e despesa.\n\nExige a permissão de ver Totais por contato, Evolução por contato, Resultados por contato ou Lançamentos por contato.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "Os totais.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotaisPorContatos"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Totais por projeto (/referencia/relatorios/relatorio-totais-projetos)
`GET /relatorios/totais/projetos`
```json
{
"operationId": "relatorioTotaisProjetos",
"tags": [
"Relatórios"
],
"summary": "Totais por projeto",
"description": "Soma por projeto e tipo. Sem `tipo`, receita e despesa.\n\nExige a permissão de ver Totais por projeto, Resultados por projeto ou Lançamentos por projeto.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "Os totais.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotaisPorProjetos"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Totais por tag (/referencia/relatorios/relatorio-totais-tags)
`GET /relatorios/totais/tags`
```json
{
"operationId": "relatorioTotaisTags",
"tags": [
"Relatórios"
],
"summary": "Totais por tag",
"description": "Soma por tag e tipo. Lançamento sem tag não entra; com duas tags, entra nas duas. Sem `tipo`, receita e despesa.\n\nExige a permissão de ver Totais por categoria.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "Os totais.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotaisPorTags"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Totais por conta (/referencia/relatorios/relatorio-totais-contas)
`GET /relatorios/totais/contas`
```json
{
"operationId": "relatorioTotaisContas",
"tags": [
"Relatórios"
],
"summary": "Totais por conta",
"description": "Movimento do período por conta e tipo, na apuração de resultado (sem saldo inicial). Para o saldo, use `/relatorios/saldos`. Sem `tipo`, receita e despesa.\n\nExige a permissão de ver Lançamentos de caixa, Extrato de contas, Saldos de caixa ou Resultados de caixa.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "Os totais.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotaisPorContas"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Receitas × despesas (/referencia/relatorios/relatorio-resultado)
`GET /relatorios/resultado`
```json
{
"operationId": "relatorioResultado",
"tags": [
"Relatórios"
],
"summary": "Receitas × despesas",
"description": "Receitas, despesas e o resultado do período, com as transferências à parte. É o Resultado\ndo mês da visão geral; com `intervalo`, a evolução dele.\n\nExige a permissão de ver Resultados do mês, Comparação entre períodos ou Lançamentos de caixa.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "O resultado.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Resultado"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Saldo de cada conta numa data (/referencia/relatorios/relatorio-saldos)
`GET /relatorios/saldos`
```json
{
"operationId": "relatorioSaldos",
"tags": [
"Relatórios"
],
"summary": "Saldo de cada conta numa data",
"description": "O saldo de cada conta ao fim de `data`, como no card Saldos de caixa: saldo inicial e todos\nos lançamentos até a data, com a fatura do cartão projetada na conta que a paga. `projetado`\ninclui o que vence até a data e ainda não foi pago; `confirmado`, só o realizado.\n\nExige a permissão de ver Saldos de caixa, Extrato de contas, Lançamentos de caixa ou Fluxo de caixa.\n",
"parameters": [
{
"name": "data",
"in": "query",
"description": "O dia do saldo. Sem o parâmetro, hoje.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "Os saldos.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Saldos"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Fluxo de caixa (/referencia/relatorios/relatorio-fluxo-caixa)
`GET /relatorios/fluxo-caixa`
```json
{
"operationId": "relatorioFluxoCaixa",
"tags": [
"Relatórios"
],
"summary": "Fluxo de caixa",
"description": "Saldo inicial, entradas, saídas, resultado e saldo acumulado por período, no total e por conta,\ncomo na tela Fluxo de caixa. Entram as contas de caixa (disponíveis, ativas, na moeda pedida;\nsem cartão nem carteira de investimentos), e a fatura do cartão aparece projetada na conta que\na paga. Os valores são os projetados: `status` decide o que entra.\n\nOs pendentes vencidos seguem a configuração do workspace (o\n`pendentes_no_presente` não se aplica aqui, como na tela).\n\nExige a permissão de ver Fluxo de caixa.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"name": "intervalo",
"in": "query",
"description": "Tamanho de cada período.",
"schema": {
"type": "string",
"enum": [
"dia",
"mes",
"ano"
],
"default": "mes"
}
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"name": "transferencias_entre_contas_caixa",
"in": "query",
"description": "Inclui as transferências entre duas contas de caixa (que não mudam o saldo total).",
"schema": {
"type": "boolean",
"default": true
}
},
{
"name": "contas_pagar_receber",
"in": "query",
"description": "Soma também os pendentes das contas de Contas a pagar e a receber. Só vale sem o filtro `contas`.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "O fluxo de caixa.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FluxoCaixa"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Meta × realizado por categoria (/referencia/relatorios/relatorio-metas-categorias)
`GET /relatorios/metas/categorias`
```json
{
"operationId": "relatorioMetasCategorias",
"tags": [
"Relatórios"
],
"summary": "Meta × realizado por categoria",
"description": "O Orçamento: a meta de cada categoria no período, o realizado e quanto falta ou excedeu. A categoria de cima soma as filhas; o que foi lançado direto nela, sem subcategoria, vem numa linha própria com `lancado_na_categoria_pai: true`. As metas de investimento não entram.\n\nO período conta em meses inteiros (`inicio` vai ao primeiro dia do mês e `fim`, ao último).\nCom `intervalo=mes`, uma linha por mês; outro intervalo é 400.\n\nExige a permissão de ver Metas de orçamento ou Metas de despesa/receita da visão geral.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "As metas.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetasCategorias"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Meta × realizado por centro de custo (/referencia/relatorios/relatorio-metas-centros)
`GET /relatorios/metas/centros`
```json
{
"operationId": "relatorioMetasCentros",
"tags": [
"Relatórios"
],
"summary": "Meta × realizado por centro de custo",
"description": "As Metas por centro: a meta de despesa e de receita de cada centro de custo no período, o realizado e quanto falta ou excedeu.\n\nO período conta em meses inteiros (`inicio` vai ao primeiro dia do mês e `fim`, ao último).\nCom `intervalo=mes`, uma linha por mês; outro intervalo é 400.\n\nExige a permissão de ver Metas por centros.\n",
"parameters": [
{
"$ref": "#/components/parameters/Inicio"
},
{
"$ref": "#/components/parameters/Fim"
},
{
"$ref": "#/components/parameters/Regime"
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Tipo"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/Intervalo"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCategorias"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "As metas.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetasCentros"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Demonstração do Resultado do Exercício (DRE) (/referencia/relatorios/relatorio-dre)
`GET /relatorios/dre`
```json
{
"operationId": "relatorioDre",
"tags": [
"Relatórios"
],
"summary": "Demonstração do Resultado do Exercício (DRE)",
"description": "As linhas do DRE, com o valor de cada período, a análise vertical (sobre a Receita Líquida) e\na horizontal (sobre o período anterior), a média e o total. A categoria vai para a linha a que\nestá vinculada na tela do DRE; sem vínculo, para a linha padrão do tipo dela. Linhas de\n`tipo: categorias` trazem as categorias em `itens`.\n\nExige a permissão de ver o DRE.\n",
"parameters": [
{
"name": "fim",
"in": "query",
"description": "Um dia do último mês do demonstrativo. Sem o parâmetro, o mês atual.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "intervalo",
"in": "query",
"description": "Tamanho de cada período (coluna).",
"schema": {
"type": "string",
"enum": [
"mes",
"trimestre",
"semestre",
"ano"
],
"default": "mes"
}
},
{
"name": "periodos",
"in": "query",
"description": "Quantos períodos, contando para trás a partir do `fim`. A janela vai até 5 anos.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 60,
"default": 12
}
},
{
"name": "regime",
"in": "query",
"required": true,
"description": "`caixa` pela data de pagamento; `competencia` pela data de competência.",
"schema": {
"type": "string",
"enum": [
"caixa",
"competencia"
]
}
},
{
"name": "linhas_zeradas",
"in": "query",
"description": "Inclui as linhas sem valor em nenhum período.",
"schema": {
"type": "boolean",
"default": true
}
},
{
"name": "contas_pagar_receber",
"in": "query",
"description": "Soma os pendentes das contas de Contas a pagar e a receber no mês atual (só no regime de caixa).",
"schema": {
"type": "boolean",
"default": true
}
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "O DRE.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Demonstrativo"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Demonstração do Fluxo de Caixa (DFC) (/referencia/relatorios/relatorio-dfc)
`GET /relatorios/dfc`
```json
{
"operationId": "relatorioDfc",
"tags": [
"Relatórios"
],
"summary": "Demonstração do Fluxo de Caixa (DFC)",
"description": "As linhas do DFC por atividade (operacional, investimento e financiamento), do saldo inicial ao\nsaldo final de caixa, com o valor de cada período, as análises, a média e o total. Sempre no\nregime de caixa, sobre as contas de caixa.\n\nExige a permissão de ver o DFC.\n",
"parameters": [
{
"name": "fim",
"in": "query",
"description": "Um dia do último mês do demonstrativo. Sem o parâmetro, o mês atual.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "intervalo",
"in": "query",
"description": "Tamanho de cada período (coluna).",
"schema": {
"type": "string",
"enum": [
"mes",
"trimestre",
"semestre",
"ano"
],
"default": "mes"
}
},
{
"name": "periodos",
"in": "query",
"description": "Quantos períodos, contando para trás a partir do `fim`. A janela vai até 5 anos.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 60,
"default": 12
}
},
{
"name": "linhas_zeradas",
"in": "query",
"description": "Inclui as linhas sem valor em nenhum período.",
"schema": {
"type": "boolean",
"default": true
}
},
{
"name": "contas_pagar_receber",
"in": "query",
"description": "Soma os pendentes das contas de Contas a pagar e a receber.",
"schema": {
"type": "boolean",
"default": true
}
},
{
"$ref": "#/components/parameters/Status"
},
{
"$ref": "#/components/parameters/Moeda"
},
{
"$ref": "#/components/parameters/PendentesNoPresente"
},
{
"$ref": "#/components/parameters/FiltroContas"
},
{
"$ref": "#/components/parameters/FiltroCentros"
},
{
"$ref": "#/components/parameters/FiltroContatos"
},
{
"$ref": "#/components/parameters/FiltroProjetos"
},
{
"$ref": "#/components/parameters/FiltroTags"
},
{
"$ref": "#/components/parameters/FiltroFormasPagamento"
}
],
"responses": {
"200": {
"description": "O DFC.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Demonstrativo"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# A posição da carteira, por ativo e conta (/referencia/investimentos/get-carteira-investimentos)
`GET /investimentos/carteira`
```json
{
"operationId": "getCarteiraInvestimentos",
"tags": [
"Investimentos"
],
"summary": "A posição da carteira, por ativo e conta",
"description": "Uma linha por ativo em cada conta de investimento (`tipo: ativo`) e uma por conta de\ninvestimento que não é carteira de ativos, como um CDB ou uma poupança (`tipo: conta`).\nOs valores são os da tela da carteira. O valor dos títulos indexados e das contas vem da série\nde rentabilidade, calculada até `atualizado_ate`. Se a data não for ontem, abra Investimentos\nno Meu Dinheiro para atualizar; a leitura não recalcula nem grava.\n\nA conta oculta para a credencial não entra, e pedi-la em `contas` responde 404. Sem o módulo\nde investimentos no plano, 403 com `code` `plan_required`.\n",
"parameters": [
{
"$ref": "#/components/parameters/Limit"
},
{
"$ref": "#/components/parameters/Cursor"
},
{
"name": "contas",
"in": "query",
"description": "Ids das contas de investimento, separados por vírgula. Sem o parâmetro, todas.",
"schema": {
"type": "string",
"examples": [
"12,15"
]
}
},
{
"name": "moeda",
"in": "query",
"description": "Código ISO 4217 em que os valores saem, convertidos. Sem o parâmetro, BRL.",
"schema": {
"type": "string",
"examples": [
"BRL"
]
}
},
{
"name": "estrategia",
"in": "query",
"description": "O id de uma estratégia (`GET /investimentos/estrategias`). Com ela, cada linha traz os `grupos` da estratégia em que entra.",
"schema": {
"type": "integer"
}
},
{
"name": "grupo",
"in": "query",
"description": "O id de um grupo da `estrategia`; exige `estrategia`.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "A posição.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CarteiraInvestimentosPage"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# As estratégias de alocação da carteira (/referencia/investimentos/list-estrategias)
`GET /investimentos/estrategias`
```json
{
"operationId": "listEstrategias",
"tags": [
"Investimentos"
],
"summary": "As estratégias de alocação da carteira",
"description": "\"Tipo de ativo\" (id 0), que o app monta a partir do tipo de cada ativo, e as estratégias\nativas do workspace. Sem o plano avançado de investimentos, só as do sistema, como no app.\nO id do grupo da \"Tipo de ativo\" é o código do tipo.\n",
"responses": {
"200": {
"description": "As estratégias.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EstrategiaList"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# A rentabilidade da carteira, com benchmarks (/referencia/investimentos/get-rentabilidade)
`GET /investimentos/rentabilidade`
```json
{
"operationId": "getRentabilidade",
"tags": [
"Investimentos"
],
"summary": "A rentabilidade da carteira, com benchmarks",
"description": "A rentabilidade por cotização (como a tela: aporte e retirada não distorcem), acumulada desde\no dia anterior ao `inicio`, da carteira inteira ou de um recorte (`contas`, `ativos` ou o\ngrupo de uma estratégia). Valores em fração: 0,05 é 5%.\n\nA série só vai até `atualizado_ate`, o último dia que o Meu Dinheiro calculou; os benchmarks\nparam na mesma data, para a comparação ser na mesma janela. `inicio` antes de 2018-01-01, o\nmarco da rentabilidade, vira 2018-01-01, e a resposta traz o `inicio` usado. Se\n`atualizado_ate` não for ontem, abra Investimentos no Meu Dinheiro para atualizar; a leitura\nnão recalcula nem grava.\n",
"parameters": [
{
"name": "inicio",
"in": "query",
"description": "O primeiro dia do período. Sem o parâmetro, um ano antes do `fim`.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "fim",
"in": "query",
"description": "O último dia, até ontem. Sem o parâmetro, ontem.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "intervalo",
"in": "query",
"description": "Um ponto por `dia` (até 366 dias), `mes` ou `ano`; o ponto do mês e do ano é o último dia com cota nele.",
"schema": {
"type": "string",
"enum": [
"dia",
"mes",
"ano"
],
"default": "mes"
}
},
{
"name": "benchmarks",
"in": "query",
"description": "Os índices para comparar, separados por vírgula (`GET /investimentos/benchmarks`).",
"schema": {
"type": "string",
"examples": [
"cdi,ibovespa"
]
}
},
{
"name": "contas",
"in": "query",
"description": "Ids das contas de investimento, separados por vírgula.",
"schema": {
"type": "string"
}
},
{
"name": "ativos",
"in": "query",
"description": "Ids dos ativos, separados por vírgula. Não combina com `estrategia`.",
"schema": {
"type": "string"
}
},
{
"name": "estrategia",
"in": "query",
"description": "O id de uma estratégia (`GET /investimentos/estrategias`).",
"schema": {
"type": "integer"
}
},
{
"name": "grupo",
"in": "query",
"description": "O id de um grupo da `estrategia`; exige `estrategia`.",
"schema": {
"type": "integer"
}
},
{
"name": "moeda",
"in": "query",
"description": "Código ISO 4217 em que a carteira é medida, convertida. Sem o parâmetro, BRL.",
"schema": {
"type": "string",
"examples": [
"BRL"
]
}
},
{
"name": "detalhar",
"in": "query",
"description": "Com `true`, cada ponto traz também o `saldo` do dia e os `aportes` e as `retiradas` desde o ponto anterior (o primeiro, desde o `inicio`).",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "por_ativo",
"in": "query",
"description": "Com `true`, a resposta traz também `series`: uma série para cada ativo de `ativos` (ou da `estrategia`), restrita às `contas`; sem ativos, uma para cada conta de `contas`. Até 20 séries, cada uma com os benchmarks por ponto, e só com `intervalo` `mes` ou `ano` (com `dia`, 400). Compara vários ativos numa chamada só.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "A série.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SerieRentabilidade"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# A rentabilidade de cada ativo no período, do maior para o menor (/referencia/investimentos/list-rentabilidade-ativos)
`GET /investimentos/rentabilidade/ativos`
```json
{
"operationId": "listRentabilidadeAtivos",
"tags": [
"Investimentos"
],
"summary": "A rentabilidade de cada ativo no período, do maior para o menor",
"description": "Por ativo em cada conta, desde `inicio` até a última cota calculada (`atualizado_ate`), com o\nvalor atual e a participação da posição de hoje (nulos quando a posição já fechou).\n",
"parameters": [
{
"name": "inicio",
"in": "query",
"description": "O primeiro dia. Sem o parâmetro, um ano atrás; antes de 2018-01-01, 2018-01-01.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "moeda",
"in": "query",
"description": "Código ISO 4217 do `valor_atual`. Sem o parâmetro, BRL.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "O ranking.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RankingRentabilidade"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Os índices que a rentabilidade compara (/referencia/investimentos/list-benchmarks)
`GET /investimentos/benchmarks`
```json
{
"operationId": "listBenchmarks",
"tags": [
"Investimentos"
],
"summary": "Os índices que a rentabilidade compara",
"responses": {
"200": {
"description": "Os benchmarks, na ordem da tela.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BenchmarkList"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# Rentabilidade, volatilidade e Sharpe da carteira (/referencia/investimentos/get-indicadores-carteira)
`GET /investimentos/indicadores`
```json
{
"operationId": "getIndicadoresCarteira",
"tags": [
"Investimentos"
],
"summary": "Rentabilidade, volatilidade e Sharpe da carteira",
"description": "Os indicadores do card da tela, do primeiro dia do mês de `inicio` ao último do de `fim` (até\nontem). A volatilidade é o desvio padrão da variação diária da cota; a anual, ela × √252. O\nSharpe compara com o CDI do mesmo período. Com menos de duas cotas no período, os campos vêm\nnulos.\n",
"parameters": [
{
"name": "inicio",
"in": "query",
"description": "Um dia do primeiro mês. Sem o parâmetro, 12 meses antes do `fim`; antes de 2018, 2018-01-01.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "fim",
"in": "query",
"description": "Um dia do último mês. Sem o parâmetro, ontem.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "ativos",
"in": "query",
"description": "Ids dos ativos, separados por vírgula. Não combina com `estrategia`.",
"schema": {
"type": "string"
}
},
{
"name": "contas",
"in": "query",
"description": "Ids das contas de investimento, separados por vírgula.",
"schema": {
"type": "string"
}
},
{
"name": "estrategia",
"in": "query",
"description": "O id de uma estratégia (`GET /investimentos/estrategias`).",
"schema": {
"type": "integer"
}
},
{
"name": "grupo",
"in": "query",
"description": "O id de um grupo da `estrategia`; exige `estrategia`.",
"schema": {
"type": "integer"
}
},
{
"name": "moeda",
"in": "query",
"description": "Código ISO 4217 dos valores, convertidos. Sem o parâmetro, BRL.",
"schema": {
"type": "string",
"examples": [
"BRL"
]
}
}
],
"responses": {
"200": {
"description": "Os indicadores.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndicadoresCarteira"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json
# A análise da carteira por mês ou por ano (/referencia/investimentos/get-analise-carteira)
`GET /investimentos/analise`
```json
{
"operationId": "getAnaliseCarteira",
"tags": [
"Investimentos"
],
"summary": "A análise da carteira por mês ou por ano",
"description": "Por período: saldo inicial e final, aportes, retiradas, transferências de custódia,\nproventos, variação, rendimentos, resultado das vendas, custos, IR e apurações; e o total do\nintervalo, com a rentabilidade por cotização e a TIR. Os números são os das telas de análise\nda carteira. Até 60 meses.\n\nA análise roda na hora e pesa pelo número de ativos × meses: numa carteira grande, o período\npedido pode passar do que dá para calcular de uma vez. Aí a resposta é **422**\n`analysis_too_complex`, com `max_meses_sugerido` (o maior período que cabe; nulo quando nem\num mês cabe), antes de qualquer cálculo. Repita com o período sugerido ou recorte por `contas`.\n",
"parameters": [
{
"name": "inicio",
"in": "query",
"description": "O primeiro mês. Sem o parâmetro, 11 meses antes do `fim`; antes de 2018-01, 2018-01.",
"schema": {
"$ref": "#/components/schemas/Mes"
}
},
{
"name": "fim",
"in": "query",
"description": "O último mês, até o corrente. Sem o parâmetro, o mês corrente.",
"schema": {
"$ref": "#/components/schemas/Mes"
}
},
{
"name": "intervalo",
"in": "query",
"description": "Um período por `mes` ou por `ano`.",
"schema": {
"type": "string",
"enum": [
"mes",
"ano"
],
"default": "mes"
}
},
{
"name": "detalhar",
"in": "query",
"description": "Com `true`, traz também os `grupos` da estratégia (ou dos tipos de ativo), com os ativos.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "contas",
"in": "query",
"description": "Ids das contas de investimento, separados por vírgula.",
"schema": {
"type": "string"
}
},
{
"name": "estrategia",
"in": "query",
"description": "O id de uma estratégia (`GET /investimentos/estrategias`).",
"schema": {
"type": "integer"
}
},
{
"name": "grupo",
"in": "query",
"description": "O id de um grupo da `estrategia`; exige `estrategia`.",
"schema": {
"type": "integer"
}
},
{
"name": "moeda",
"in": "query",
"description": "Código ISO 4217 dos valores, convertidos. Sem o parâmetro, BRL.",
"schema": {
"type": "string",
"examples": [
"BRL"
]
}
}
],
"responses": {
"200": {
"description": "A análise.",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/RateLimitLimit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/RateLimitRemaining"
},
"X-RateLimit-Reset": {
"$ref": "#/components/headers/RateLimitReset"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnaliseCarteira"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"description": "A análise passa do que dá para calcular de uma vez nesta carteira.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnalysisTooComplex"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
```
Schemas referenciados: /openapi.json