# Despezzas API > Documentação da API pública do Despezzas: lançamentos, contas, cartões, faturas, categorias, metas, limites, relatórios e Despezzas Business por HTTP, autenticados com uma chave de API (token + secret) criada em https://despezzas.com/settings/api-keys. Base URL: https://api.despezzas.com. Especificação OpenAPI 3.1: https://api.despezzas.com/v1/openapi.json ## Guia - [Visão geral](https://docs.despezzas.com/): O que a Despezzas API expõe, quem pode usar e por onde começar. - [Autenticação](https://docs.despezzas.com/autenticacao): Token + secret, por HTTP Basic ou por headers. - [Changelog](https://docs.despezzas.com/changelog): Mudanças na API pública. - [Contextos e escopos](https://docs.despezzas.com/contextos-e-escopos): A que dados a chave tem acesso, e o que ela pode fazer com eles. - [Erros](https://docs.despezzas.com/erros): O envelope de erro e o que cada status significa. - [Despezzas Business](https://docs.despezzas.com/guias/business): A API para a empresa: títulos, fluxo de caixa, DRE e cadastros. - [Categorias, tags e regras](https://docs.despezzas.com/guias/categorias-e-tags): Como classificar lançamentos. - [Contas, cartões e faturas](https://docs.despezzas.com/guias/contas-e-cartoes): Saldos, limites e a fatura do mês. - [Lançamentos](https://docs.despezzas.com/guias/lancamentos): Criar, listar, editar, pagar e conciliar receitas e despesas. - [Início rápido](https://docs.despezzas.com/inicio-rapido): Crie uma chave e faça a primeira chamada. - [Limites de taxa](https://docs.despezzas.com/limites-de-taxa): Quantas requisições por minuto, e como reagir a um 429. - [Paginação e filtros](https://docs.despezzas.com/paginacao-e-filtros): Como as listas se comportam, especialmente a de lançamentos. ## Referência da API — Cartões - [Atualizar cartão](https://docs.despezzas.com/api-reference/cart%C3%B5es/atualizar-cart%C3%A3o): Escopo necessário: write. - [Criar cartão](https://docs.despezzas.com/api-reference/cart%C3%B5es/criar-cart%C3%A3o): Cria um cartão manual ligado a uma conta. limit em centavos; closing_date e expiring_date são dias do mês. Escopo necessário: write. - [Excluir cartão](https://docs.despezzas.com/api-reference/cart%C3%B5es/excluir-cart%C3%A3o): Exclusão lógica do cartão e dos seus lançamentos. Se o cartão era o último de uma conexão Open Finance, o consentimento é revogado no banco. Devolve o cartão excluído. Escopo necessário: write. - [Listar cartões](https://docs.despezzas.com/api-reference/cart%C3%B5es/listar-cart%C3%B5es): Escopo necessário: read. ## Referência da API — Categorias - [Atualizar categoria](https://docs.despezzas.com/api-reference/categorias/atualizar-categoria): Categorias do sistema não são alteradas: a edição é guardada por usuário/contexto e a resposta é essa edição. Personalizadas são alteradas na linha. Escopo necessário: write. - [Atualizar subcategoria](https://docs.despezzas.com/api-reference/categorias/atualizar-subcategoria): Subcategorias do sistema viram uma edição do contexto (a resposta é a edição); personalizadas são alteradas na linha. Escopo necessário: write. - [Buscar ícones](https://docs.despezzas.com/api-reference/categorias/buscar-%C3%ADcones): Lista de ícones prontos para categorias. O termo é aceito por compatibilidade: a lista devolvida é sempre a completa. Escopo necessário: read. - [Criar categoria](https://docs.despezzas.com/api-reference/categorias/criar-categoria): Escopo necessário: write. - [Criar subcategoria](https://docs.despezzas.com/api-reference/categorias/criar-subcategoria): Escopo necessário: write. - [Excluir categoria personalizada](https://docs.despezzas.com/api-reference/categorias/excluir-categoria-personalizada): Só categorias do contexto (não as do sistema). Resposta 200 sem corpo. Escopo necessário: write. - [Excluir subcategoria personalizada](https://docs.despezzas.com/api-reference/categorias/excluir-subcategoria-personalizada): Devolve a subcategoria excluída. Escopo necessário: write. - [Listar categorias personalizadas](https://docs.despezzas.com/api-reference/categorias/listar-categorias-personalizadas): Escopo necessário: read. - [Listar categorias (sistema + personalizadas)](https://docs.despezzas.com/api-reference/categorias/listar-categorias-sistema-+-personalizadas): Categorias do sistema (sem user_id) já com as edições do contexto aplicadas, mais as personalizadas do contexto. Escopo necessário: read. - [Listar subcategorias personalizadas](https://docs.despezzas.com/api-reference/categorias/listar-subcategorias-personalizadas): Escopo necessário: read. - [Listar subcategorias (sistema + personalizadas)](https://docs.despezzas.com/api-reference/categorias/listar-subcategorias-sistema-+-personalizadas): Escopo necessário: read. ## Referência da API — Conta - [Listar empresas (Business)](https://docs.despezzas.com/api-reference/conta/listar-empresas-business): Empresas Despezzas Business de que o usuário é dono ou membro. Útil para descobrir o id ao criar uma chave presa a uma empresa. Escopo necessário: read. - [Quem sou eu](https://docs.despezzas.com/api-reference/conta/quem-sou-eu): Dados básicos da conta autenticada, o contexto ao qual a chave está presa (pessoal, Perfil de Acesso ou empresa) e a própria chave. Escopo necessário: read. ## Referência da API — Contas - [Atualizar conta](https://docs.despezzas.com/api-reference/contas/atualizar-conta): name e logo continuam obrigatórios; os demais campos só mudam se enviados. Escopo necessário: write. - [Criar conta](https://docs.despezzas.com/api-reference/contas/criar-conta): Cria uma conta manual. balance em centavos. Escopo necessário: write. - [Excluir conta](https://docs.despezzas.com/api-reference/contas/excluir-conta): Exclusão lógica da conta e dos seus lançamentos; os cartões ligados a ela passam para outra conta. Se a conta era a última de uma conexão Open Finance, o consentimento é revogado no banco — o mesmo que acontece no app. Escopo necessário: write. - [Listar contas](https://docs.despezzas.com/api-reference/contas/listar-contas): Escopo necessário: read. ## Referência da API — Despezzas Business - [Atualizar centro de custo](https://docs.despezzas.com/api-reference/despezzas-business/atualizar-centro-de-custo): Escopo necessário: write. - [Atualizar contato](https://docs.despezzas.com/api-reference/despezzas-business/atualizar-contato): Escopo necessário: write. - [Atualizar mapeamento do DRE](https://docs.despezzas.com/api-reference/despezzas-business/atualizar-mapeamento-do-dre): Substitui o grupo das categorias informadas e devolve o mapeamento completo. Escopo necessário: write. - [Contas a pagar](https://docs.despezzas.com/api-reference/despezzas-business/contas-a-pagar): Escopo necessário: read. - [Contas a receber](https://docs.despezzas.com/api-reference/despezzas-business/contas-a-receber): Escopo necessário: read. - [Criar centro de custo](https://docs.despezzas.com/api-reference/despezzas-business/criar-centro-de-custo): Escopo necessário: write. - [Criar contato](https://docs.despezzas.com/api-reference/despezzas-business/criar-contato): Escopo necessário: write. - [DRE](https://docs.despezzas.com/api-reference/despezzas-business/dre): Escopo necessário: read. - [Empresa do contexto](https://docs.despezzas.com/api-reference/despezzas-business/empresa-do-contexto): Escopo necessário: read. - [Excluir centro de custo](https://docs.despezzas.com/api-reference/despezzas-business/excluir-centro-de-custo): Escopo necessário: write. - [Excluir contato](https://docs.despezzas.com/api-reference/despezzas-business/excluir-contato): Escopo necessário: write. - [Fluxo de caixa](https://docs.despezzas.com/api-reference/despezzas-business/fluxo-de-caixa): Realizado e previsto por dia ou mês. Sem to, cobre days dias a partir de from (padrão: hoje). Escopo necessário: read. - [Licença da empresa](https://docs.despezzas.com/api-reference/despezzas-business/licen%C3%A7a-da-empresa): Escopo necessário: read. - [Listar centros de custo](https://docs.despezzas.com/api-reference/despezzas-business/listar-centros-de-custo): Escopo necessário: read. - [Listar cobranças](https://docs.despezzas.com/api-reference/despezzas-business/listar-cobran%C3%A7as): Cobranças (boleto/Pix) já emitidas, lidas do banco de dados. A emissão fica fora da API. Escopo necessário: read. - [Listar cobranças recorrentes](https://docs.despezzas.com/api-reference/despezzas-business/listar-cobran%C3%A7as-recorrentes): Escopo necessário: read. - [Listar contatos](https://docs.despezzas.com/api-reference/despezzas-business/listar-contatos): Escopo necessário: read. - [Listar notas fiscais](https://docs.despezzas.com/api-reference/despezzas-business/listar-notas-fiscais): Escopo necessário: read. - [Mapeamento do DRE](https://docs.despezzas.com/api-reference/despezzas-business/mapeamento-do-dre): Categorias da empresa e do sistema com o grupo do DRE em que cada uma cai. Escopo necessário: read. ## Referência da API — Faturas - [Ajustar dia de fechamento](https://docs.despezzas.com/api-reference/faturas/ajustar-dia-de-fechamento): Muda o dia de fechamento (e vencimento) do cartão e recalcula as faturas no alcance de edition_type. Escopo necessário: write. - [Fatura atual](https://docs.despezzas.com/api-reference/faturas/fatura-atual): A fatura que o app mostra ao abrir o cartão: a aberta ou a que vence a seguir, conforme as preferências. date navega para outro mês. Escopo necessário: read. - [Fatura do mês](https://docs.despezzas.com/api-reference/faturas/fatura-do-m%C3%AAs): Fatura do cartão no mês de referência, com totais, status e os lançamentos que a compõem. Escopo necessário: read. - [Lançamentos da fatura](https://docs.despezzas.com/api-reference/faturas/lan%C3%A7amentos-da-fatura): Escopo necessário: read. - [Pagar fatura](https://docs.despezzas.com/api-reference/faturas/pagar-fatura): Registra o pagamento de uma fatura a partir de uma conta: cria o débito na conta e o crédito no cartão e atualiza a fatura. amount em centavos. Aceita o header Idempotency-Key para repetir a chamada com segurança. Escopo necessário: write. ## Referência da API — Investimentos - [Aportes e resgates](https://docs.despezzas.com/api-reference/investimentos/aportes-e-resgates): Aportes, resgates e dividendos registrados como lançamentos nas contas de investimento no período (padrão: mês atual). Escopo necessário: read. - [Distribuição por tipo](https://docs.despezzas.com/api-reference/investimentos/distribui%C3%A7%C3%A3o-por-tipo): Escopo necessário: read. - [Rentabilidade](https://docs.despezzas.com/api-reference/investimentos/rentabilidade): Rendimento diário das posições importadas pelo Open Finance, calculado a partir dos snapshots de saldo (sem consulta ao vivo). Escopo necessário: read. - [Série histórica](https://docs.despezzas.com/api-reference/investimentos/s%C3%A9rie-hist%C3%B3rica): Escopo necessário: read. ## Referência da API — Lançamentos - [Adicionar parcelas](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/adicionar-parcelas): Acrescenta quantity parcelas ao final de uma compra parcelada existente, copiando valor e destino da última. Escopo necessário: write. - [Assinaturas detectadas](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/assinaturas-detectadas): Lançamentos recorrentes identificados como assinaturas, no mesmo formato da listagem. Aceita os mesmos filtros de GET /v1/transactions. Escopo necessário: read. - [Atualizar lançamento](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/atualizar-lan%C3%A7amento): Atualiza só os campos enviados. Em recorrências e parcelas, edition_type define o alcance (THIS, THIS_AND_NEXT, ALL). Escopo necessário: write. - [Atualizar vários lançamentos](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/atualizar-v%C3%A1rios-lan%C3%A7amentos): Aplica os campos do corpo (categoria, tags, etc.) a todos os ids informados na query. Devolve os lançamentos atualizados. Escopo necessário: write. - [Baixar título (Business)](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/baixar-t%C3%ADtulo-business): Marca um título a pagar/receber como liquidado. Requer chave presa a uma empresa com licença ativa. Escopo necessário: write. - [Candidatos à conciliação](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/candidatos-%C3%A0-concilia%C3%A7%C3%A3o): Para um lançamento previsto, lista os lançamentos reais (importados ou lançados) que podem tê-lo liquidado, ordenados por pontuação. Escopo necessário: read. - [Conciliar lançamento](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/conciliar-lan%C3%A7amento): Liga o lançamento previsto {id} ao lançamento real informado no corpo. O previsto sai dos totais; o real continua contando. Escopo necessário: write. - [Criar lançamento](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/criar-lan%C3%A7amento): Cria um lançamento no contexto da chave. Informe account_id ou credit_card_id. amount em centavos. Em parcelamentos (PARCELLED) devolve a primeira parcela; as demais nascem ligadas por connected_transaction_id. Escopo necessário: write. - [Criar transferência entre contas](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/criar-transfer%C3%AAncia-entre-contas): Cria o par de lançamentos (saída na conta de origem e entrada na de destino). Devolve o lançamento de saída. Escopo necessário: write. - [Desfazer conciliação](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/desfazer-concilia%C3%A7%C3%A3o): Remove o vínculo e devolve o lançamento previsto aos totais. Escopo necessário: write. - [Duplicar lançamento](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/duplicar-lan%C3%A7amento): Cria uma cópia do lançamento já marcada como paga (mesma data, valor, conta/cartão e categoria; tags não são copiadas). Escopo necessário: write. - [Excluir lançamento](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/excluir-lan%C3%A7amento): Exclusão lógica. Em recorrências e parcelas, type no corpo define o alcance (THIS, THIS_AND_NEXT, ALL). Resposta 200 sem corpo. Escopo necessário: write. - [Excluir vários lançamentos](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/excluir-v%C3%A1rios-lan%C3%A7amentos): Exclusão lógica em lote. Resposta 200 sem corpo. Escopo necessário: write. - [Ignorar alerta de duplicidade](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/ignorar-alerta-de-duplicidade): Marca os lançamentos como não duplicados: o app para de sugerir a exclusão. Resposta 200 sem corpo. Escopo necessário: write. - [Listar lançamentos](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/listar-lan%C3%A7amentos): Retorna um array (sem envelope) com os lançamentos do contexto da chave, com relações expandidas e campos calculados. Sem filtros, traz o mês atual. Valores em centavos. Escopo necessário: read. - [Marcar como pago/pendente](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/marcar-como-pagopendente): Alterna o status de pagamento de um lançamento de conta (lançamentos de cartão são sempre pagos). Devolve o lançamento atualizado. Escopo necessário: write. - [Resumo do mês (v1)](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/resumo-do-m%C3%AAs-v1): Totais de receitas, despesas e saldo do mês de referência, mais o saldo por conta. Escopo necessário: read. - [Resumo do mês (v2)](https://docs.despezzas.com/api-reference/lan%C3%A7amentos/resumo-do-m%C3%AAs-v2): Saldo atual, saldo inicial e movimento de cada conta, e os totais do mês (recebido, a receber, pago, a pagar, saldo previsto). Escopo necessário: read. ## Referência da API — Limites de gastos - [Atualizar limite](https://docs.despezzas.com/api-reference/limites-de-gastos/atualizar-limite): Mesmos campos obrigatórios da criação. Escopo necessário: write. - [Criar limite](https://docs.despezzas.com/api-reference/limites-de-gastos/criar-limite): amount em centavos. Escopo necessário: write. - [Excluir limite](https://docs.despezzas.com/api-reference/limites-de-gastos/excluir-limite): Resposta 200 sem corpo. Escopo necessário: write. - [Gráfico do ritmo de gastos](https://docs.despezzas.com/api-reference/limites-de-gastos/gr%C3%A1fico-do-ritmo-de-gastos): Gasto acumulado dia a dia do mês e do mês anterior. Escopo necessário: read. - [Listar limites](https://docs.despezzas.com/api-reference/limites-de-gastos/listar-limites): Limites do contexto com a categoria, a subcategoria e o gasto acumulado na janela atual. Escopo necessário: read. - [Recomendações de limites](https://docs.despezzas.com/api-reference/limites-de-gastos/recomenda%C3%A7%C3%B5es-de-limites): Escopo necessário: read. - [Ritmo de gastos do mês](https://docs.despezzas.com/api-reference/limites-de-gastos/ritmo-de-gastos-do-m%C3%AAs): Compara o gasto de hoje, da semana e do mês com o mesmo ponto do mês anterior. Escopo necessário: read. ## Referência da API — Metas - [Aportes da meta](https://docs.despezzas.com/api-reference/metas/aportes-da-meta): Escopo necessário: read. - [Atualizar meta](https://docs.despezzas.com/api-reference/metas/atualizar-meta): title e amount continuam obrigatórios. Escopo necessário: write. - [Criar meta](https://docs.despezzas.com/api-reference/metas/criar-meta): amount em centavos. Escopo necessário: write. - [Detalhar meta](https://docs.despezzas.com/api-reference/metas/detalhar-meta): Escopo necessário: read. - [Excluir meta](https://docs.despezzas.com/api-reference/metas/excluir-meta): Devolve a meta excluída. Escopo necessário: write. - [Imagens disponíveis para metas](https://docs.despezzas.com/api-reference/metas/imagens-dispon%C3%ADveis-para-metas): Escopo necessário: read. - [Listar metas](https://docs.despezzas.com/api-reference/metas/listar-metas): Metas do contexto com aportes, lembrete e categoria, mais a soma dos aportes. Escopo necessário: read. - [Recomendações de metas](https://docs.despezzas.com/api-reference/metas/recomenda%C3%A7%C3%B5es-de-metas): Sugestões prontas (dicas de economia e um desafio) no idioma da requisição. Escopo necessário: read. - [Registrar aporte](https://docs.despezzas.com/api-reference/metas/registrar-aporte): value em centavos; is_expense: true registra uma retirada. Escopo necessário: write. ## Referência da API — Preferências - [Atualizar preferências](https://docs.despezzas.com/api-reference/prefer%C3%AAncias/atualizar-prefer%C3%AAncias): Escopo necessário: write. - [Preferências de cálculo](https://docs.despezzas.com/api-reference/prefer%C3%AAncias/prefer%C3%AAncias-de-c%C3%A1lculo): Escopo necessário: read. ## Referência da API — Regras de categorização - [Atualizar regra](https://docs.despezzas.com/api-reference/regras-de-categoriza%C3%A7%C3%A3o/atualizar-regra): Escopo necessário: write. - [Criar regra](https://docs.despezzas.com/api-reference/regras-de-categoriza%C3%A7%C3%A3o/criar-regra): Cria uma regra a partir de um lançamento de origem; apply_to_existing recategoriza o histórico. Devolve a regra e o que foi recategorizado. Escopo necessário: write. - [Excluir regra](https://docs.despezzas.com/api-reference/regras-de-categoriza%C3%A7%C3%A3o/excluir-regra): Escopo necessário: write. - [Listar regras](https://docs.despezzas.com/api-reference/regras-de-categoriza%C3%A7%C3%A3o/listar-regras): Escopo necessário: read. - [Pré-visualizar regra](https://docs.despezzas.com/api-reference/regras-de-categoriza%C3%A7%C3%A3o/pr%C3%A9-visualizar-regra): Calcula os critérios disponíveis e quantos lançamentos existentes uma regra atingiria. Não grava nada — exige apenas o escopo read. Escopo necessário: read. ## Referência da API — Relatórios - [Calendário de gastos](https://docs.despezzas.com/api-reference/relat%C3%B3rios/calend%C3%A1rio-de-gastos): Escopo necessário: read. - [Detalhe por categoria](https://docs.despezzas.com/api-reference/relat%C3%B3rios/detalhe-por-categoria): Escopo necessário: read. - [Detalhe por subcategoria](https://docs.despezzas.com/api-reference/relat%C3%B3rios/detalhe-por-subcategoria): Escopo necessário: read. - [Evolução por categoria](https://docs.despezzas.com/api-reference/relat%C3%B3rios/evolu%C3%A7%C3%A3o-por-categoria): Escopo necessário: read. - [Fluxo de caixa](https://docs.despezzas.com/api-reference/relat%C3%B3rios/fluxo-de-caixa): Realizado e previsto no intervalo (regime de caixa), com saldo acumulado por dia e por mês. Escopo necessário: read. - [Gastos por cartão](https://docs.despezzas.com/api-reference/relat%C3%B3rios/gastos-por-cart%C3%A3o): Escopo necessário: read. - [Linha do tempo](https://docs.despezzas.com/api-reference/relat%C3%B3rios/linha-do-tempo): Receitas e despesas dia a dia no período, com o período anterior para comparação. Escopo necessário: read. - [Parcelamentos em aberto](https://docs.despezzas.com/api-reference/relat%C3%B3rios/parcelamentos-em-aberto): Escopo necessário: read. - [Previsão](https://docs.despezzas.com/api-reference/relat%C3%B3rios/previs%C3%A3o): Projeção dos próximos meses (regime de caixa) a partir do histórico. Escopo necessário: read. - [Regime de competência](https://docs.despezzas.com/api-reference/relat%C3%B3rios/regime-de-compet%C3%AAncia): Escopo necessário: read. - [Relatório do período](https://docs.despezzas.com/api-reference/relat%C3%B3rios/relat%C3%B3rio-do-per%C3%ADodo): Totais e rankings por categoria, subcategoria e tag no período. Sem datas, usa o mês atual. Escopo necessário: read. ## Referência da API — Tags - [Atualizar tag](https://docs.despezzas.com/api-reference/tags/atualizar-tag): Escopo necessário: write. - [Criar tag](https://docs.despezzas.com/api-reference/tags/criar-tag): Escopo necessário: write. - [Excluir tag](https://docs.despezzas.com/api-reference/tags/excluir-tag): Resposta 200 sem corpo. Escopo necessário: write. - [Listar tags](https://docs.despezzas.com/api-reference/tags/listar-tags): Escopo necessário: read.