openapi: 3.2.0 info: title: Financeiro Categorias API version: v1 description: A API de Financeiro tem como objetivo oferecer um conjunto de recursos para gerenciar de forma programática os principais aspectos financeiros de uma empresa, desde a criação de eventos de contas a receber ou pagar, passando pela gestão de contas financeiras, centros de custo, categorias, até a consulta de saldos. servers: - url: https://api-v2.contaazul.com description: Servidor de produção security: - BearerAuth: [] tags: - name: Categorias paths: /v1/categorias: summary: Endpoint de Categorias get: summary: Retornar as categorias por filtro operationId: searchCategories tags: - Categorias description: Permite listar as categorias utilizadas para classificação de receitas ou despesas. Auxilia no controle, agrupamento e geração de relatórios financeiros baseados em categorias. parameters: - in: query name: pagina description: Página example: 1 schema: type: number required: true - in: query name: tamanho_pagina description: Tamanho da página example: 10 schema: enum: - 10 - 20 - 50 - 100 - 200 - 500 - 1000 type: number required: true - in: query name: campo_ordenado_ascendente description: Campo para ordenação ascendente. Se informado ele desconsidera o valor do campo_ordenado_descendente. É possível ordenar por 'NOME' ou 'TIPO' example: NOME schema: type: string enum: - NOME - TIPO required: false - in: query name: campo_ordenado_descendente description: Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente não deverá ser informado. É possível ordenar por 'NOME' ou 'TIPO' example: TIPO schema: type: string enum: - NOME - TIPO required: false - in: query name: busca description: Busca textual por nome ou código example: '010' schema: type: string required: false - in: query name: tipo description: Tipo da categoria example: RECEITA schema: type: string enum: - RECEITA - DESPESA required: false - in: query name: apenas_filhos description: Filtrar apenas categorias filhas example: true schema: type: boolean required: false - in: query name: nome description: Nome da categoria example: Eletrônicos schema: type: string required: false - in: query name: permite_apenas_filhos description: Permite apenas categorias filhas example: true schema: type: boolean required: true responses: '200': description: OK content: application/json: schema: type: object properties: itens_totais: type: integer example: 6 itens: type: array items: $ref: '#/components/schemas/Categoria' totais: $ref: '#/components/schemas/Totais' '400': description: Bad Request '401': description: Unauthorized '429': description: Too Many Requests '500': description: Internal Server Error /v1/categorias/configuracao-padrao: summary: Configuração padrão de categorias get: summary: Retornar a configuração de de-para de categorias operationId: getDefaultCategoryConfig tags: - Categorias description: Retorna o de-para entre as operações financeiras e as categorias configuradas para o tenant, incluindo opcionalmente a sugestão padrão de categoria para cada operação. parameters: - in: query name: sugestao_padrao description: Quando verdadeiro (padrão), inclui o objeto `sugestao_padrao` em cada item. Quando falso, o campo `sugestao_padrao` é retornado como `null`. example: true schema: type: boolean default: true required: false responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/ConfiguracaoPadraoCategoria' '400': description: Bad Request '401': description: Unauthorized '429': description: Too Many Requests '500': description: Internal Server Error components: schemas: Totais: type: object properties: ativo: type: integer description: Total de centros de custo ativos example: 6 inativo: type: integer description: Total de centros de custo inativos example: 0 todos: type: integer description: Total de centros de custo example: 6 SugestaoPadrao: type: - object - 'null' description: Sugestão padrão de categoria para a operação. Quando `sugestao_padrao=false`, este campo é retornado como `null`. properties: id: type: - string - 'null' format: uuid description: Identificador da categoria sugerida example: 1bb1b4fa-0fba-49e6-9fb6-a0342b7575eb nome: type: string description: Nome da operação financeira correspondente à sugestão example: Fretes recebidos ConfiguracaoPadraoCategoria: type: object description: Item do de-para entre uma operação financeira e a categoria configurada para o tenant properties: tipo_operacao: type: string description: 'Tipo da operação financeira. Valores possíveis: - `FRETES_RECEBIDOS`: Categoria para valor de frete inserido na venda. - `FRETES_PAGOS`: Categoria para valor de frete inserido na compra. - `IMPOSTOS_RETIDOS_EM_VENDAS`: Categoria para valor dos impostos retidos na venda. - `DESCONTOS_INCONDICIONAIS_OBTIDOS`: Categoria para descontos obtidos na compra. - `DESCONTOS_INCONDICIONAIS_CONCEDIDOS`: Categoria para descontos concedidos na venda. - `DESCONTOS_FINANCEIROS_OBTIDOS`: Categoria para descontos obtidos, no caso de baixas em despesas com desconto. - `DESCONTOS_FINANCEIROS_CONCEDIDOS`: Categoria para descontos concedidos, no caso de baixas em receitas com desconto. - `MULTAS_RECEBIDAS`: Categoria para multas recebidas, em baixas no Contas a receber. - `MULTAS_PAGAS`: Categoria para multas pagas, em baixas no Contas a pagar. - `JUROS_RECEBIDOS`: Categoria para juros recebidos em baixas no Contas a receber. - `JUROS_PAGOS`: Categoria para juros pagos, em baixas no Contas a pagar. - `TARIFAS`: Categorias para tarifas pagas, em baixas no contas a receber. - `PERDAS`: Categoria para perdas, quando a parcela é dada como perda no Contas a receber.' example: FRETES_RECEBIDOS enum: - FRETES_RECEBIDOS - FRETES_PAGOS - IMPOSTOS_RETIDOS_EM_VENDAS - DESCONTOS_INCONDICIONAIS_OBTIDOS - DESCONTOS_INCONDICIONAIS_CONCEDIDOS - DESCONTOS_FINANCEIROS_OBTIDOS - DESCONTOS_FINANCEIROS_CONCEDIDOS - MULTAS_RECEBIDAS - MULTAS_PAGAS - JUROS_RECEBIDOS - JUROS_PAGOS - TARIFAS - PERDAS id_categoria: type: - string - 'null' format: uuid description: Identificador da categoria configurada para a operação example: e82ba6fd-a291-422f-8ef7-eb383205d743 nome_categoria: type: - string - 'null' description: Nome da categoria configurada para a operação example: 0.5 categoria dre sugestao_padrao: $ref: '#/components/schemas/SugestaoPadrao' Categoria: type: object properties: id: type: string format: uuid example: 35473eec-4e74-11ee-b500-9f61de8a8b8b versao: type: integer example: 0 nome: type: string example: Eletrônicos categoria_pai: type: - string - 'null' example: 3d39b8d2-8b16-42d6-abd8-6cfd9d2e06c4 tipo: type: string example: RECEITA entrada_dre: type: string example: DESPESAS_ADMINISTRATIVAS considera_custo_dre: type: boolean example: true securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Token de autorização Bearer JWT