openapi: 3.0.3

info:
  title: API de Dados Abertos — Portal de Transparência Sispub
  version: 1.0.0
  description: |
    API pública de dados abertos do Portal de Transparência Sispub.

    ## Multi-tenant

    Todos os endpoints são prefixados por `/api/{empresa}/{ano}`:

    - `empresa` — código da entidade no cadastro `transparencia_empresa` (ex.: `rnp001`).
      O 3º caractere indica o poder: `p` = Prefeitura, `c` = Câmara.
    - `ano` — exercício (ano base) dos dados consultados.

    O middleware `GetTenancy` resolve o banco de dados do município a partir desses
    dois parâmetros antes de a consulta ser executada.

    Exemplo de chamada em produção:

    ```
    https://transparencia.sispub.lemarq.inf.br/api/rnp001/2026/emenda?perPage=25
    ```

    ## Autenticação

    Não há autenticação — os dados são abertos e de consulta pública (somente leitura).

    ## Paginação

    As quatro listagens usam o mesmo envelope paginado (`status`, `pagination`, `data`).
    A navegação é feita por `?page=`; o tamanho da página por `?perPage=` (aceita também
    `perpage`), com padrão `10` e faixa válida de `1` a `100`. Valores fora da faixa
    caem silenciosamente no padrão `10`.

    ## Valores monetários e datas

    Nos endpoints de **emendas** os valores são convertidos para número (`float`) e as
    datas normalizadas para `YYYY-MM-DD` (ou `YYYY-MM-DD HH:MM:SS`).

    Nos endpoints de **receita** e **empenho** os campos numéricos e de data vêm
    diretamente do banco, portanto são serializados como *string* (ex.: `"1234.56"`,
    `"2026-03-15"`).

    ## Anexos

    Os campos de anexo das emendas (`cronograma.anexo_url`, `documentos[].arquivo_url`,
    `instrumentos[].documento_url`) retornam a URL absoluta gravada no cadastro — o
    domínio de armazenamento dos arquivos varia por município e não é necessariamente
    o domínio do portal.
  contact:
    name: Lemarq Sistemas
    url: https://www.lemarq.com.br
  license:
    name: Uso público — dados abertos

servers:
  - url: https://transparencia.sispub.lemarq.inf.br/api
    description: Produção
  - url: /api
    description: Instância atual (mesmo host da documentação)

tags:
  - name: Emendas
    description: Emendas parlamentares e emendas PIX — listagem e detalhamento.
  - name: Receitas
    description: Arrecadação orçamentária do exercício.
  - name: Empenhos
    description: Despesa empenhada do exercício (empenhos correntes, sem restos a pagar).

paths:

  /{empresa}/{ano}/emenda:
    get:
      tags: [Emendas]
      operationId: listarEmendas
      summary: Lista as emendas parlamentares / PIX
      description: |
        Retorna, de forma paginada, as emendas do exercício com o cabeçalho completo
        (domínios já resolvidos: origem, tipo, forma de repasse, função de governo,
        status, fonte, entidade executora e autores) e os valores de **previsto** e
        **repasse** (soma dos recebimentos vinculados).

        Os campos de domínio seguem o formato `{ codigo, descricao }` e vêm como `null`
        quando não há código cadastrado.

        Para os demais valores e para as coleções filhas (dotações, contratos, empenhos,
        recebimentos, documentos e instrumentos), use o endpoint de detalhe.
      parameters:
        - $ref: '#/components/parameters/Empresa'
        - $ref: '#/components/parameters/Ano'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Lista paginada de emendas.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/EnvelopePaginado'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/EmendaLista'
              example:
                status: true
                pagination:
                  current_page: 1
                  per_page: 10
                  from: 1
                  to: 1
                  total_pages: 3
                  total_items: 24
                data:
                  - id: 12
                    numero: '000004'
                    exercicio: '2026'
                    numero_ano: '2026/000004'
                    natureza:
                      codigo: I
                      descricao: Impositiva
                    origem:
                      codigo: 1
                      descricao: Federal
                    tipo:
                      codigo: 2
                      descricao: Emenda Individual
                    forma_repasse:
                      codigo: 1
                      descricao: Transferência Especial (PIX)
                    funcao_governo:
                      codigo: 10
                      descricao: Saúde
                    status:
                      codigo: 3
                      descricao: Em execução
                      cor: '#2563eb'
                    fonte:
                      codigo: '17510000'
                      descricao: Transferências da União
                    entidade_executora:
                      codigo: '004512'
                      descricao: SECRETARIA MUNICIPAL DE SAÚDE
                    autores:
                      - codigo: 7
                        nome: 'Deputado Exemplo'
                    nr_convenio: '901234/2026'
                    ato_normativo: 'Portaria nº 123/2026'
                    terceiro_setor: 'Não'
                    localidade_beneficiada: 'Zona Rural'
                    beneficiario: 'População do município'
                    objeto: 'Aquisição de equipamentos hospitalares'
                    area_tematica: 'Atenção Básica'
                    objeto_despesa: 'Equipamentos e material permanente'
                    cronograma:
                      descricao: 'Execução em 3 etapas'
                      anexo_url: 'https://arquivos.exemplo.gov.br/cronograma-12.pdf'
                      anexo_descricao: 'Cronograma físico-financeiro'
                    vigencia:
                      inicio: '2026-02-01'
                      fim: '2026-12-31'
                    pc_fisico_executado: 45.5
                    atualizado_em: '2026-07-20 14:32:10'
                    atualizado_sistema_em: '2026-07-21 03:00:00'
                    valores:
                      previsto: 500000
                      repasse: 250000
        '400': { $ref: '#/components/responses/ParametrosInvalidos' }
        '404': { $ref: '#/components/responses/TenantNaoEncontrado' }
        '422': { $ref: '#/components/responses/ErroValidacao' }
        '500': { $ref: '#/components/responses/ErroInterno' }

  /{empresa}/{ano}/emenda/{id}:
    get:
      tags: [Emendas]
      operationId: detalharEmenda
      summary: Detalha uma emenda
      description: |
        Retorna o mesmo cabeçalho da listagem, acrescido dos **seis valores** de
        acompanhamento (previsto, repasse, rendimento de aplicação, atualizado,
        execução e percentual físico) e das **seis coleções filhas**: dotações,
        contratos, empenhos, recebimentos, documentos e instrumentos vinculados.

        Resposta sem paginação: `{ status, data }`.
      parameters:
        - $ref: '#/components/parameters/Empresa'
        - $ref: '#/components/parameters/Ano'
        - name: id
          in: path
          required: true
          description: Identificador interno da emenda (campo `id` da listagem).
          schema:
            type: integer
            minimum: 1
          example: 12
      responses:
        '200':
          description: Detalhe da emenda.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/EmendaDetalhe'
              example:
                status: true
                data:
                  id: 12
                  numero: '000004'
                  exercicio: '2026'
                  numero_ano: '2026/000004'
                  natureza:
                    codigo: I
                    descricao: Impositiva
                  origem:
                    codigo: 1
                    descricao: Federal
                  tipo:
                    codigo: 2
                    descricao: Emenda Individual
                  forma_repasse:
                    codigo: 1
                    descricao: Transferência Especial (PIX)
                  funcao_governo:
                    codigo: 10
                    descricao: Saúde
                  status:
                    codigo: 3
                    descricao: Em execução
                    cor: '#2563eb'
                  fonte:
                    codigo: '17510000'
                    descricao: Transferências da União
                  entidade_executora:
                    codigo: '004512'
                    descricao: SECRETARIA MUNICIPAL DE SAÚDE
                  autores:
                    - codigo: 7
                      nome: 'Deputado Exemplo'
                  nr_convenio: '901234/2026'
                  ato_normativo: 'Portaria nº 123/2026'
                  terceiro_setor: 'Não'
                  localidade_beneficiada: 'Zona Rural'
                  beneficiario: 'População do município'
                  objeto: 'Aquisição de equipamentos hospitalares'
                  area_tematica: 'Atenção Básica'
                  objeto_despesa: 'Equipamentos e material permanente'
                  cronograma:
                    descricao: 'Execução em 3 etapas'
                    anexo_url: 'https://arquivos.exemplo.gov.br/cronograma-12.pdf'
                    anexo_descricao: 'Cronograma físico-financeiro'
                  vigencia:
                    inicio: '2026-02-01'
                    fim: '2026-12-31'
                  pc_fisico_executado: 45.5
                  atualizado_em: '2026-07-20 14:32:10'
                  atualizado_sistema_em: '2026-07-21 03:00:00'
                  valores:
                    previsto: 500000
                    repasse: 250000
                    rendimento_aplicacao: 1250.35
                    atualizado: 501250.35
                    execucao: 180000
                    fisico_percentual: 45.5
                  dotacoes:
                    - unidade_orcamentaria:
                        codigo: '0201'
                      acao:
                        codigo: '2001'
                      elemento_despesa:
                        codigo: '444905200000'
                      fonte:
                        codigo: '17510000'
                      descricao: 'Manutenção da Atenção Básica'
                      valor_orcado: 500000
                      saldo: 320000
                  contratos:
                    - tipo: 'Contrato'
                      numero: '0012/2026'
                      objeto: 'Aquisição de equipamentos hospitalares'
                      fornecedor:
                        codigo: '004512'
                        descricao: 'EMPRESA EXEMPLO LTDA'
                      inicio: '2026-03-01'
                      termino: '2026-12-31'
                      valor: 180000
                  empenhos:
                    - numero: '000123'
                      data: '2026-03-10'
                      fornecedor: 'EMPRESA EXEMPLO LTDA'
                      empenhado: 180000
                      liquidado: 90000
                      pago: 90000
                  recebimentos:
                    - data: '2026-02-15'
                      documento: 'OB 000045'
                      conta_bancaria:
                        codigo: '001'
                        descricao: 'BANCO DO BRASIL - C/C 12345-6'
                      fonte:
                        codigo: '17510000'
                        descricao: 'Transferências da União'
                      descricao: 'Repasse 1ª parcela'
                      valor: 250000
                  documentos:
                    - tipo:
                        codigo: 2
                        descricao: 'Nota Fiscal'
                      observacao: 'NF-e 000123'
                      empenho: '000123 - EMPRESA EXEMPLO LTDA'
                      liquidacao: '000098 - EMPRESA EXEMPLO LTDA'
                      arquivo_url: 'https://arquivos.exemplo.gov.br/nf-000123.pdf'
                  instrumentos:
                    - descricao: 'Termo de Compromisso nº 55/2026'
                      documento_url: 'https://arquivos.exemplo.gov.br/termo-55.pdf'
        '400': { $ref: '#/components/responses/ParametrosInvalidos' }
        '404':
          description: Emenda inexistente, ou empresa/conexão não encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
              example:
                status: false
                message: 'Emenda não encontrada.'
        '422': { $ref: '#/components/responses/ErroValidacao' }
        '500': { $ref: '#/components/responses/ErroInterno' }
  /{empresa}/{ano}/receita:
    get:
      tags: [Receitas]
      operationId: listarReceitas
      summary: Lista as receitas do exercício
      description: |
        Retorna, de forma paginada, os lançamentos de receita do exercício informado,
        já enriquecidos com o nome da unidade gestora e o nome da conta de receita.

        Ordenação fixa: código da conta (asc), depois data da receita (asc).
      parameters:
        - $ref: '#/components/parameters/Empresa'
        - $ref: '#/components/parameters/Ano'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Lista paginada de receitas.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/EnvelopePaginado'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Receita'
              example:
                status: true
                pagination:
                  current_page: 1
                  per_page: 10
                  from: 1
                  to: 2
                  total_pages: 148
                  total_items: 1476
                data:
                  - data_receita: '2026-01-05'
                    unidade:
                      codigo: '01'
                      nome: PREFEITURA MUNICIPAL
                    conta:
                      codigo: '111105000000'
                      nome: 'IPTU - Imposto Predial e Territorial Urbano'
                    valor_receita: '15230.44'
                    conta_corrente: '001'
                    codigo_fonte: '15000000'
                  - data_receita: '2026-01-06'
                    unidade:
                      codigo: '01'
                      nome: PREFEITURA MUNICIPAL
                    conta:
                      codigo: '111105000000'
                      nome: 'IPTU - Imposto Predial e Territorial Urbano'
                    valor_receita: '3410.00'
                    conta_corrente: '001'
                    codigo_fonte: '15000000'
        '400': { $ref: '#/components/responses/ParametrosInvalidos' }
        '404': { $ref: '#/components/responses/TenantNaoEncontrado' }
        '422': { $ref: '#/components/responses/ErroValidacao' }
        '500': { $ref: '#/components/responses/ErroInterno' }

  /{empresa}/{ano}/empenho:
    get:
      tags: [Empenhos]
      operationId: listarEmpenhos
      summary: Lista os empenhos (despesas) do exercício
      description: |
        Retorna, de forma paginada, os empenhos de despesa do exercício, com a
        classificação orçamentária completa (órgão, unidade, função, subfunção,
        programa, ação, natureza da despesa, subelemento e fonte), o credor e,
        quando houver, o vínculo com licitação e contrato.

        Considera apenas empenhos do exercício corrente (`rnp = 0`) — restos a pagar
        não são retornados por este endpoint.

        Ordenação fixa: data de emissão (asc).

        O CPF do credor é retornado parcialmente mascarado (`**1.234.567-**`) por
        proteção de dados pessoais; CNPJ é retornado formatado e completo.
      parameters:
        - $ref: '#/components/parameters/Empresa'
        - $ref: '#/components/parameters/Ano'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Lista paginada de empenhos.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/EnvelopePaginado'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Empenho'
              example:
                status: true
                pagination:
                  current_page: 1
                  per_page: 10
                  from: 1
                  to: 1
                  total_pages: 932
                  total_items: 9315
                data:
                  - orgao: '02'
                    unidade: '0201'
                    funcao: '04'
                    subfuncao: '122'
                    programa: '0002'
                    acao: '2001'
                    codigo_despesa: '333903'
                    subelemento: '39'
                    nome_subelemento: 'Outros Serviços de Terceiros - PJ'
                    fonte: '15000000'
                    numero_empenho: '000123'
                    valor: '12500.00'
                    data_emissao: '2026-01-12'
                    descricao: 'Contratação de serviços de manutenção predial'
                    cpf_cnpj_credor: '12.345.678/0001-99'
                    nome_credor: 'EMPRESA EXEMPLO LTDA'
                    numero_licitacao: '000005'
                    numero_contrato: '0012/2026'
                    procedimento_licitatorio: '07'
                    nome_procedimento_licitatorio: 'Pregão Eletrônico'
                    numero_procedimento_licitatorio: '000003'
                    tipo_empenho: 'G'
        '400': { $ref: '#/components/responses/ParametrosInvalidos' }
        '404': { $ref: '#/components/responses/TenantNaoEncontrado' }
        '422': { $ref: '#/components/responses/ErroValidacao' }
        '500': { $ref: '#/components/responses/ErroInterno' }


components:

  parameters:

    Empresa:
      name: empresa
      in: path
      required: true
      description: |
        Código da entidade (tenant) cadastrada em `transparencia_empresa`.
        O 3º caractere identifica o poder: `p` = Prefeitura, `c` = Câmara.
      schema:
        type: string
        maxLength: 255
      example: rnp001

    Ano:
      name: ano
      in: path
      required: true
      description: |
        Exercício consultado. Aceita do ano corrente até 10 anos atrás;
        fora dessa faixa a requisição é rejeitada com `422`.
      schema:
        type: integer
      example: 2026

    Page:
      name: page
      in: query
      required: false
      description: Página desejada. Padrão `1`.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1

    PerPage:
      name: perPage
      in: query
      required: false
      description: |
        Itens por página. Padrão `10`, mínimo `1`, máximo `100`.
        O parâmetro `perpage` (minúsculo) é aceito como alias.
        Valores fora da faixa são substituídos pelo padrão `10`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
      example: 10

  responses:

    ParametrosInvalidos:
      description: Parâmetros de tenant inválidos (`empresa` vazia ou `ano` no futuro).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
          example:
            status: false
            message: 'Parâmetros inválidos.'

    TenantNaoEncontrado:
      description: Empresa não cadastrada ou sem conexão de banco disponível.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
          example:
            status: false
            message: 'Empresa não encontrada.'

    ErroValidacao:
      description: Falha de validação dos parâmetros da requisição.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErroValidacao'
          example:
            status: false
            message: 'Erro de validação'
            errors:
              ano:
                - 'O campo "ano" deve ser no máximo 2026.'

    ErroInterno:
      description: |
        Falha ao processar a consulta. O detalhe técnico é registrado em log e só
        aparece no campo `error` quando a aplicação está em modo debug.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erro'
          example:
            status: false
            message: 'Falha ao processar a API.'

  schemas:

    EnvelopePaginado:
      type: object
      description: Envelope padrão das listagens.
      required: [status, pagination, data]
      properties:
        status:
          type: boolean
          description: Sempre `true` em respostas de sucesso.
          example: true
        pagination:
          $ref: '#/components/schemas/Paginacao'
        data:
          type: array
          description: Itens da página atual.
          items:
            type: object

    Paginacao:
      type: object
      properties:
        current_page:
          type: integer
          description: Página atual.
          example: 1
        per_page:
          type: integer
          description: Itens por página.
          example: 10
        from:
          type: integer
          nullable: true
          description: Índice do primeiro item da página (`null` se vazia).
          example: 1
        to:
          type: integer
          nullable: true
          description: Índice do último item da página (`null` se vazia).
          example: 10
        total_pages:
          type: integer
          description: Quantidade total de páginas.
          example: 148
        total_items:
          type: integer
          description: Quantidade total de registros.
          example: 1476

    Erro:
      type: object
      properties:
        status:
          type: boolean
          description: Sempre `false`.
          example: false
        message:
          type: string
          description: Mensagem legível do erro.
          example: 'Falha ao processar a API.'
        error:
          type: string
          description: Detalhe técnico da exceção — presente apenas em modo debug.

    ErroValidacao:
      type: object
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: 'Erro de validação'
        errors:
          type: object
          description: Mapa `campo → lista de mensagens`.
          additionalProperties:
            type: array
            items:
              type: string

    Referencia:
      type: object
      nullable: true
      description: |
        Par código/descrição de um domínio. Retorna `null` quando não há código
        cadastrado. `codigo` sai como inteiro quando numérico, senão como string.
      properties:
        codigo:
          description: Código do domínio.
          oneOf:
            - type: integer
            - type: string
          example: 1
        descricao:
          type: string
          nullable: true
          description: Descrição do domínio.
          example: Federal

    ReferenciaStatus:
      allOf:
        - $ref: '#/components/schemas/Referencia'
        - type: object
          properties:
            cor:
              type: string
              nullable: true
              description: Cor associada ao status (hexadecimal), para uso em interfaces.
              example: '#2563eb'

    Autor:
      type: object
      properties:
        codigo:
          oneOf:
            - type: integer
            - type: string
          description: Código do autor da emenda.
          example: 7
        nome:
          type: string
          description: Nome do autor (parlamentar).
          example: 'Deputado Exemplo'

    Receita:
      type: object
      description: Lançamento de receita orçamentária.
      properties:
        data_receita:
          type: string
          format: date
          nullable: true
          description: Data do lançamento da receita (`YYYY-MM-DD`).
          example: '2026-01-05'
        unidade:
          type: object
          description: Unidade gestora responsável pela arrecadação.
          properties:
            codigo:
              type: string
              nullable: true
              description: Código da unidade gestora (`receita.cd_ug`).
              example: '01'
            nome:
              type: string
              nullable: true
              description: Nome da unidade gestora.
              example: 'PREFEITURA MUNICIPAL'
        conta:
          type: object
          description: Conta de receita (natureza da receita).
          properties:
            codigo:
              type: string
              nullable: true
              description: Código da conta de receita.
              example: '111105000000'
            nome:
              type: string
              nullable: true
              description: Descrição da conta de receita.
              example: 'IPTU - Imposto Predial e Territorial Urbano'
        valor_receita:
          type: string
          description: Valor arrecadado, em reais. Decimal serializado como string.
          example: '15230.44'
        conta_corrente:
          type: string
          nullable: true
          description: Conta bancária de movimentação (`receita.nr_bcmov`).
          example: '001'
        codigo_fonte:
          type: string
          nullable: true
          description: Código da fonte/destinação de recursos.
          example: '15000000'

    Empenho:
      type: object
      description: Empenho de despesa com classificação orçamentária e credor.
      properties:
        orgao:
          type: string
          nullable: true
          description: Código do órgão orçamentário.
          example: '02'
        unidade:
          type: string
          nullable: true
          description: Código da unidade orçamentária.
          example: '0201'
        funcao:
          type: string
          nullable: true
          description: Código da função de governo.
          example: '04'
        subfuncao:
          type: string
          nullable: true
          description: Código da subfunção.
          example: '122'
        programa:
          type: string
          nullable: true
          description: Código do programa.
          example: '0002'
        acao:
          type: string
          nullable: true
          description: Código da ação (projeto/atividade).
          example: '2001'
        codigo_despesa:
          type: string
          nullable: true
          description: Natureza da despesa — 6 primeiros dígitos da conta de despesa.
          example: '333903'
        subelemento:
          type: string
          nullable: true
          description: Código do subelemento de despesa.
          example: '39'
        nome_subelemento:
          type: string
          nullable: true
          description: Descrição do subelemento de despesa.
          example: 'Outros Serviços de Terceiros - PJ'
        fonte:
          type: string
          nullable: true
          description: Código da fonte/destinação de recursos.
          example: '15000000'
        numero_empenho:
          type: string
          nullable: true
          description: Número do empenho.
          example: '000123'
        valor:
          type: string
          description: Valor empenhado, em reais. Decimal serializado como string.
          example: '12500.00'
        data_emissao:
          type: string
          format: date
          nullable: true
          description: Data de emissão do empenho (`YYYY-MM-DD`).
          example: '2026-01-12'
        descricao:
          type: string
          nullable: true
          description: Histórico/objeto do empenho.
          example: 'Contratação de serviços de manutenção predial'
        cpf_cnpj_credor:
          type: string
          nullable: true
          description: |
            Documento do credor. CPF vem parcialmente mascarado (`**1.234.567-**`);
            CNPJ vem formatado e completo (`12.345.678/0001-99`).
          example: '12.345.678/0001-99'
        nome_credor:
          type: string
          nullable: true
          description: Nome/razão social do credor.
          example: 'EMPRESA EXEMPLO LTDA'
        numero_licitacao:
          type: string
          nullable: true
          description: Número da licitação vinculada, quando houver.
          example: '000005'
        numero_contrato:
          type: string
          nullable: true
          description: Número do contrato vinculado, quando houver.
          example: '0012/2026'
        procedimento_licitatorio:
          type: string
          nullable: true
          description: Código da modalidade de licitação.
          example: '07'
        nome_procedimento_licitatorio:
          type: string
          nullable: true
          description: Descrição da modalidade de licitação.
          example: 'Pregão Eletrônico'
        numero_procedimento_licitatorio:
          type: string
          nullable: true
          description: Número da modalidade no processo licitatório.
          example: '000003'
        tipo_empenho:
          type: string
          nullable: true
          description: 'Tipo do empenho (ex.: `O` ordinário, `G` global, `E` estimativo).'
          example: 'G'

    EmendaCabecalho:
      type: object
      description: Campos de identificação e classificação comuns à listagem e ao detalhe.
      properties:
        id:
          type: integer
          description: Identificador interno da emenda — use no endpoint de detalhe.
          example: 12
        numero:
          type: string
          nullable: true
          description: Número da emenda.
          example: '000004'
        exercicio:
          type: string
          nullable: true
          description: Exercício da emenda.
          example: '2026'
        numero_ano:
          type: string
          description: Composição `exercício/número`.
          example: '2026/000004'
        natureza:
          type: object
          nullable: true
          description: |
            Natureza de execução: `I` = Impositiva, `D` = Discricionária.
            `null` para qualquer outro valor.
          properties:
            codigo:
              type: string
              enum: [I, D]
              example: I
            descricao:
              type: string
              enum: [Impositiva, Discricionária]
              example: Impositiva
        origem:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: 'Origem da emenda (ex.: Federal, Estadual).'
        tipo:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: 'Tipo de emenda (ex.: Individual, Bancada, Comissão).'
        forma_repasse:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: 'Forma de repasse dos recursos (ex.: Transferência Especial/PIX).'
        funcao_governo:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: Função de governo beneficiada.
        status:
          allOf:
            - $ref: '#/components/schemas/ReferenciaStatus'
          description: Situação atual da emenda, com a cor usada na interface.
        fonte:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: Fonte/destinação de recursos.
        entidade_executora:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: Entidade responsável pela execução (cadastro de fornecedores).
        autores:
          type: array
          description: Autores da emenda. Lista vazia quando não houver autor vinculado.
          items:
            $ref: '#/components/schemas/Autor'
        nr_convenio:
          type: string
          nullable: true
          description: Número do convênio/transferência, quando houver.
          example: '901234/2026'
        ato_normativo:
          type: string
          nullable: true
          description: Ato normativo que fundamenta a emenda.
          example: 'Portaria nº 123/2026'
        terceiro_setor:
          type: string
          enum: ['Sim', 'Não']
          description: Indica se a execução envolve entidade do terceiro setor.
          example: 'Não'
        localidade_beneficiada:
          type: string
          nullable: true
          description: Localidade beneficiada pela emenda.
          example: 'Zona Rural'
        beneficiario:
          type: string
          nullable: true
          description: Beneficiário da emenda.
          example: 'População do município'
        objeto:
          type: string
          nullable: true
          description: Objeto da emenda.
          example: 'Aquisição de equipamentos hospitalares'
        area_tematica:
          type: string
          nullable: true
          description: Área temática.
          example: 'Atenção Básica'
        objeto_despesa:
          type: string
          nullable: true
          description: Objeto de despesa.
          example: 'Equipamentos e material permanente'
        cronograma:
          type: object
          description: Cronograma de execução e respectivo anexo.
          properties:
            descricao:
              type: string
              nullable: true
              example: 'Execução em 3 etapas'
            anexo_url:
              type: string
              nullable: true
              description: URL do arquivo do cronograma.
              example: 'https://arquivos.exemplo.gov.br/cronograma-12.pdf'
            anexo_descricao:
              type: string
              nullable: true
              example: 'Cronograma físico-financeiro'
        vigencia:
          type: object
          description: Período de vigência do cronograma.
          properties:
            inicio:
              type: string
              format: date
              nullable: true
              example: '2026-02-01'
            fim:
              type: string
              format: date
              nullable: true
              example: '2026-12-31'
        pc_fisico_executado:
          type: number
          format: float
          description: Percentual de execução física (0 a 100).
          example: 45.5
        atualizado_em:
          type: string
          nullable: true
          description: Última atualização do registro (`YYYY-MM-DD HH:MM:SS`).
          example: '2026-07-20 14:32:10'
        atualizado_sistema_em:
          type: string
          nullable: true
          description: Data/hora da última carga do sistema (`YYYY-MM-DD HH:MM:SS`).
          example: '2026-07-21 03:00:00'

    EmendaLista:
      allOf:
        - $ref: '#/components/schemas/EmendaCabecalho'
        - type: object
          properties:
            valores:
              type: object
              description: Valores resumidos exibidos na listagem.
              properties:
                previsto:
                  type: number
                  format: float
                  description: Valor previsto da emenda.
                  example: 500000
                repasse:
                  type: number
                  format: float
                  description: Total efetivamente repassado (soma dos recebimentos).
                  example: 250000

    EmendaDetalhe:
      allOf:
        - $ref: '#/components/schemas/EmendaCabecalho'
        - type: object
          properties:
            valores:
              type: object
              description: Os seis valores de acompanhamento da emenda.
              properties:
                previsto:
                  type: number
                  format: float
                  description: Valor previsto.
                  example: 500000
                repasse:
                  type: number
                  format: float
                  description: Total repassado.
                  example: 250000
                rendimento_aplicacao:
                  type: number
                  format: float
                  description: Rendimento de aplicação financeira dos recursos.
                  example: 1250.35
                atualizado:
                  type: number
                  format: float
                  description: '`previsto` + `rendimento_aplicacao`.'
                  example: 501250.35
                execucao:
                  type: number
                  format: float
                  description: Total empenhado vinculado à emenda.
                  example: 180000
                fisico_percentual:
                  type: number
                  format: float
                  description: Percentual de execução física.
                  example: 45.5
            dotacoes:
              type: array
              description: Dotações orçamentárias vinculadas.
              items:
                $ref: '#/components/schemas/EmendaDotacao'
            contratos:
              type: array
              description: Contratos e demais instrumentos contratuais vinculados.
              items:
                $ref: '#/components/schemas/EmendaContrato'
            empenhos:
              type: array
              description: Empenhos vinculados, com execução financeira.
              items:
                $ref: '#/components/schemas/EmendaEmpenho'
            recebimentos:
              type: array
              description: Receitas/repasses recebidos.
              items:
                $ref: '#/components/schemas/EmendaRecebimento'
            documentos:
              type: array
              description: Documentos comprobatórios vinculados.
              items:
                $ref: '#/components/schemas/EmendaDocumento'
            instrumentos:
              type: array
              description: Instrumentos vinculados (termos, planos de trabalho etc.).
              items:
                $ref: '#/components/schemas/EmendaInstrumento'

    EmendaDotacao:
      type: object
      properties:
        unidade_orcamentaria:
          type: object
          properties:
            codigo:
              type: string
              nullable: true
              example: '0201'
        acao:
          type: object
          properties:
            codigo:
              type: string
              nullable: true
              example: '2001'
        elemento_despesa:
          type: object
          properties:
            codigo:
              type: string
              nullable: true
              example: '444905200000'
        fonte:
          type: object
          properties:
            codigo:
              type: string
              nullable: true
              example: '17510000'
        descricao:
          type: string
          nullable: true
          description: Descrição da ação orçamentária.
          example: 'Manutenção da Atenção Básica'
        valor_orcado:
          type: number
          format: float
          description: Valor orçado na dotação.
          example: 500000
        saldo:
          type: number
          format: float
          description: Saldo disponível na dotação.
          example: 320000

    EmendaContrato:
      type: object
      properties:
        tipo:
          type: string
          nullable: true
          description: Tipo do instrumento (contrato, ata, convênio…).
          example: 'Contrato'
        numero:
          type: string
          nullable: true
          example: '0012/2026'
        objeto:
          type: string
          nullable: true
          example: 'Aquisição de equipamentos hospitalares'
        fornecedor:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: Fornecedor contratado.
        inicio:
          type: string
          format: date
          nullable: true
          example: '2026-03-01'
        termino:
          type: string
          format: date
          nullable: true
          example: '2026-12-31'
        valor:
          type: number
          format: float
          description: Valor do contrato.
          example: 180000

    EmendaEmpenho:
      type: object
      properties:
        numero:
          type: string
          nullable: true
          example: '000123'
        data:
          type: string
          format: date
          nullable: true
          example: '2026-03-10'
        fornecedor:
          type: string
          nullable: true
          example: 'EMPRESA EXEMPLO LTDA'
        empenhado:
          type: number
          format: float
          example: 180000
        liquidado:
          type: number
          format: float
          example: 90000
        pago:
          type: number
          format: float
          example: 90000

    EmendaRecebimento:
      type: object
      properties:
        data:
          type: string
          format: date
          nullable: true
          example: '2026-02-15'
        documento:
          type: string
          nullable: true
          description: Número do documento do recebimento.
          example: 'OB 000045'
        conta_bancaria:
          type: object
          description: Conta bancária de crédito.
          properties:
            codigo:
              type: string
              nullable: true
              example: '001'
            descricao:
              type: string
              nullable: true
              example: 'BANCO DO BRASIL - C/C 12345-6'
        fonte:
          type: object
          properties:
            codigo:
              type: string
              nullable: true
              example: '17510000'
            descricao:
              type: string
              nullable: true
              example: 'Transferências da União'
        descricao:
          type: string
          nullable: true
          example: 'Repasse 1ª parcela'
        valor:
          type: number
          format: float
          example: 250000

    EmendaDocumento:
      type: object
      properties:
        tipo:
          allOf:
            - $ref: '#/components/schemas/Referencia'
          description: Tipo de documento.
        observacao:
          type: string
          nullable: true
          example: 'NF-e 000123'
        empenho:
          type: string
          nullable: true
          description: 'Empenho vinculado, no formato `número - fornecedor`.'
          example: '000123 - EMPRESA EXEMPLO LTDA'
        liquidacao:
          type: string
          nullable: true
          description: 'Liquidação vinculada, no formato `número - fornecedor`.'
          example: '000098 - EMPRESA EXEMPLO LTDA'
        arquivo_url:
          type: string
          nullable: true
          description: URL do arquivo do documento.
          example: 'https://arquivos.exemplo.gov.br/nf-000123.pdf'

    EmendaInstrumento:
      type: object
      properties:
        descricao:
          type: string
          nullable: true
          example: 'Termo de Compromisso nº 55/2026'
        documento_url:
          type: string
          nullable: true
          description: URL do instrumento.
          example: 'https://arquivos.exemplo.gov.br/termo-55.pdf'
