Financiamento de Projeto

A API de Upload de Financiamento de Projetos (V3) é utilizada para criar entradas em massa de itens de financiamento de projetos.

A API de Financiamento de Projetos permite o upload programático e o gerenciamento de registros de financiamento de projetos no Fluid. Ela suporta o upload em massa de entradas de financiamento de projetos por meio de uma API JSON RESTful.

Os itens de financiamento de projetos representam o orçamento alocado para um projeto, opcionalmente dividido por ano fiscal e categoria de despesa. Cada registro armazena o valor do financiamento em moeda local, moeda padrão (convertida) e moeda reapresentada (se configurada). Quando o ano fiscal é omitido, o registro é tratado como uma entrada de financiamento Life-to-Date (projeto completo).

As seguintes funções do Fluid são necessárias para usar esta API:

Cada requisição é tratada como o snapshot completo de financiamento para todos os projetos que ela contém. Ao ser enviada, as linhas existentes para esses projetos são substituídas pelas linhas no payload.

Para resultados precisos e previsíveis:

• Envie o financiamento completo de cada projeto em uma única requisição — inclua todos os anos fiscais, categorias de despesa e a entrada do projeto completo (Life-to-Date). Qualquer item omitido será removido.

• Use o endpoint bulk (POST /rest/api/projectfunding/bulk) — ele é dimensionado para conter o histórico completo de financiamento de um projeto em uma única chamada.

• Combine múltiplos projetos em uma única requisição quando conveniente. Cada projeto é processado de forma independente, portanto projetos não relacionados não são afetados.

Dica: Trate cada chamada como "este é o quadro completo de financiamento do projeto X", não como "adicionar estas linhas ao projeto X".

Requisição bulk única contendo o conjunto completo de financiamento para MM1000 (três linhas de AF + uma linha Life-to-Date):

[
  {
    "fields": {
      "projectRef": "MM1000",
      "fiscalYear": 2024,
      "expenseCategory": "Resource Cost",
      "amount": 50000
    }
  },
  {
    "fields": {
      "projectRef": "MM1000",
      "fiscalYear": 2024,
      "expenseCategory": "Non-resource Cost",
      "amount": 20000
    }
  },
  {
    "fields": {
      "projectRef": "MM1000",
      "fiscalYear": 2025,
      "expenseCategory": "Resource Cost",
      "amount": 70000
    }
  },
  {
    "fields": {
      "projectRef": "MM1000",
      "expenseCategory": "Resource Cost",
      "amount": 120000
    }
  }
]

Se MM1000 for dividido em duas chamadas, o payload da segunda chamada se torna o novo estado para MM1000 — as linhas enviadas na primeira chamada não são mais mantidas.

Array JSON para criação em massa.

NOTA: Propriedades personalizadas atualmente não são suportadas para registros de financiamento de projetos por meio desta API.

POST {rooturl}/rest/api/projectfunding/bulk
Content-Type: application/json

[
  {
    "Fields": {
      "ProjectRef": "MM1000",
      "FiscalYear": 2024,
      "ExpenseCategory": "Non-resource Cost",
      "Amount": 50000.00
    }
  },
  {
    "Fields": {
      "ProjectRef": "MM1000",
      "FiscalYear": 2025,
      "ExpenseCategory": "Non-resource Cost",
      "Amount": 60000.00
    }
  },
  {
    "Fields": {
      "ProjectRef": "HD1000",
      "FiscalYear": 2024,
      "ExpenseCategory": "Resource Cost",
      "Amount": 80000.00,
      "Capex": 20000.00,
      "Opex": 60000.00
    }
  }
]

Retorna um BulkProjectFundingResponseModel com:

{
  "Status": "partial",
  "TotalCount": 3,
  "ValidCount": 2,
  "InvalidCount": 1,
  "CorrelationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Results": [
    {
      "Fields": {        
        "IsValid": true,
        "Status": "valid",
        "RowIndex": 1,
        "ValidationMessages": []
      }
    },
    {
      "Fields": {
        "IsValid": true,
        "Status": "valid",
        "RowIndex": 2,
        "ValidationMessages": []
      }
    },
    {
      "Fields": {
        "IsValid": false,
        "Status": "invalid",
        "RowIndex": 3,
        "ValidationMessages": [
          "This row was skipped as no projects could be found with ProjectRef specified in the file."
        ]
      }
    }
  ]
}

1. Identificador do Projeto: Pelo menos um dos campos ProjectRef, ProjectId ou ProjectGuid deve ser fornecido. O projeto deve existir no banco de dados do Fluid.

2. Valor: O campo Amount é obrigatório. Um valor de 0 removerá o registro de financiamento do ano fiscal existente para aquela combinação de projeto e categoria de despesa.

3. ExpenseCategory: Opcional. O carregador original de upload em Excel tratava este campo como opcional, e a API V3 preserva esse comportamento para paridade.

4. Código de Moeda: Opcional. O Código de Moeda é padronizado para a moeda do sistema quando não fornecido, e é ignorado quando nenhuma Moeda Secundária está definida no sistema Fluid.

5. FiscalYear: Opcional. Se omitido ou null, o registro é tratado como uma entrada de financiamento Life-to-Date / projeto completo.

6. Capex e Opex: Ambos opcionais. Se nenhum for fornecido (ou ambos forem 0), o valor total de Amount é aplicado ao Opex.

7. Tratamento de Duplicatas: Se já existir um registro para o mesmo projeto, ano fiscal e categoria de despesa, ele será atualizado (caso contrário, um novo registro será criado). O conjunto completo de registros para uma determinada combinação de projeto + ano fiscal é substituído a cada upload.

8. Geração Automática do Ano Completo: Se existirem registros de ano fiscal, mas nenhum registro Life-to-Date explícito for fornecido, um registro de resumo do ano completo é gerado automaticamente pela soma de todos os registros de ano fiscal por projeto e categoria de despesa.