Perguntas Frequentes sobre APIS

Owned by Elkar Almeida
Last updated: Oct 16, 2024 by Phelipe Luiz Winter da Silva
13 min read

1. O que é o UserId na API de Mapa de Alocação de Projetos?

Pergunta:
O que é o UserId?

Resposta:
O UserId representa o identificador único do usuário no sistema. Para obter mais informações detalhadas sobre um usuário específico, você deve consultar a API de usuários.

Documentação relacionada:

 

2. Qual a diferença entre name.1, name.2 e name.3 na API de Apontamentos?

Pergunta:
Qual a diferença entre name.1, name.2 e name.3 que parecem representar a empresa?

Resposta:
Esses campos representam diferentes informações relacionadas à empresa ou cliente associada ao usuário ou projeto, conforme abaixo:

  • company: Sempre refere-se à empresa ou cliente vinculado diretamente ao usuário.

  • payingCompany: Dependendo da configuração do projeto, pode se referir à empresa ou cliente do projeto ou do usuário. Esse campo define a “Empresa pagadora” e pode ser ajustado no menu do projeto em:
    Configurações > Parâmetros do projeto > Apropriação do custo de trabalho (empresa pagadora).

  • client: Também depende da configuração do projeto e pode se referir à empresa ou cliente do projeto, do usuário, ou de uma empresa específica. Esse campo define a “Empresa recebedora” e pode ser configurado no menu do projeto em:
    Configurações > Parâmetros do projeto > Apropriação do custo de trabalho (empresa recebedora).

Documentação relacionada:

 

3. O que é o campo code na API de Projetos?

Pergunta:
O que significa o campo code?

Resposta:
Se o campo code estiver relacionado à API de projetos, ele representa o código do projeto. Esse campo não é obrigatório, e por isso, muitas vezes pode aparecer em branco.

Caso necessário, é possível solicitar ao suporte a ativação da configuração "Replicar o ID do projeto para o campo Código". Com essa configuração habilitada, o campo code será preenchido automaticamente com um número sequencial que identifica o projeto.

Documentação relacionada:

 

4. Onde está o apontamento do time feito no módulo Agile?

Pergunta:
Onde estão os apontamentos do time realizados no módulo Agile?

Resposta:
Quando uma atividade está integrada com o Agile, todos os apontamentos feitos no Agile serão sincronizados com o Channel e aparecerão na API de Apontamentos, preenchendo os campos agileId, codeItemAgile e agileTimeSheetId.

Essa integração pode ser configurada de três formas através do cronograma do projeto:

  1. Acessando o ícone de Configurações e associando o Agile na raiz do projeto.

  2. Selecionando uma atividade e nas ações, clicando em Criar itens no Agile.

  3. Clicando com o botão direito sobre a atividade e selecionando Associar Agile como atividade filha ou Associar Agile à atividade.

Tipos de integração:

  • Projeto: Associa o projeto completo do Agile, integrando todos os apontamentos desse projeto à atividade vinculada no Channel.

  • Épico: Associa todos os apontamentos realizados em Itens/Cards vinculados ao épico à atividade correspondente no Channel.

  • Sprint: Associa todos os apontamentos realizados nos itens dentro da sprint à atividade vinculada.

  • Item: Associa os apontamentos realizados no item diretamente à atividade vinculada.

Importante: Apontamentos em itens do Agile que não possuem integração com o Channel não serão exibidos na API de Apontamentos do Channel.

Documentação relacionada:

Comentário adicional:
Recomenda-se que o timesheet formal seja integrado ao Channel, e não ao Agile diretamente. Certifique-se de que todos os projetos Agile estejam vinculados a um projeto correspondente no Channel para garantir a integração correta.

 

5. Por que o campo role está em branco em todas as linhas na API de Alocações de Atividades?

Pergunta:
Por que o campo role está em branco em todas as linhas?

Resposta:
Na alocação de recursos, você pode alocar tanto um usuário (recurso humano) quanto um papel (função específica). O comportamento dos campos é o seguinte:

  • role: Refere-se aos papéis (funções) alocados na atividade.

  • user: Refere-se aos recursos humanos (usuários) alocados na atividade.

Se um usuário tiver um papel associado, o campo role também será preenchido com essa função. Caso o campo esteja em branco, pode ser que o usuário alocado não tenha um papel específico atribuído.

Atribuição de papéis ao usuário:
Para associar um papel a um usuário, siga os passos: Administração > Usuários > Ações > Mais Opções > Associar Papéis.

Documentação relacionada:

 

6. O que significa o campo synthetic na API de Áreas?

Pergunta:
Qual o conteúdo do campo synthetic? Ele deveria ser "sim e não", ou "1 ou 0", mas está retornando diversos números.

Resposta:
Foi realizado um ajuste na estrutura, onde foram adicionados os campos leaf e parent. O campo synthetic continua retornando o valor id da área pai, ou seja, o mesmo valor que o campo parent reflete.

O campo synthetic anteriormente era utilizado para indicar uma condição binária (como "sim e não" ou "1 e 0"), mas agora ele segue o comportamento vinculado à área pai.

Documentação relacionada:

 

7. Por que a maioria das linhas está em branco nas colunas plannedWork e actualWork na API de Lista de Atividades?

Pergunta:
Por que a maioria das linhas está em branco nas colunas plannedWork e actualWork?

Resposta:
Esses campos refletem informações do cronograma e estão diretamente relacionadas aos dados de alocação de recursos e apontamentos de horas:

  • plannedWork: Representa a coluna "Trabalho planejado" do cronograma. Este valor é calculado com base na soma do trabalho dos recursos alocados à atividade. Para verificar essa informação, acesse o cronograma em Detalhes da atividade > Recursos.

  • actualWork: Representa a coluna "Trabalho realizado" do cronograma. Esse valor é a soma das horas apontadas nos timesheets vinculados à atividade. Você pode visualizar esses dados em Detalhes da atividade > Apontamentos.

Se essas colunas estiverem em branco, pode indicar que não há recursos alocados ou horas apontadas para as atividades específicas.

Documentação relacionada:

 

8. Por que a coluna value na API de Custos Realizados contém apenas custos de RH? Onde estão os demais custos?

Pergunta:
Por que a coluna value contém apenas custos de Recursos Humanos? Onde estão os demais custos?

Resposta:
Os custos reais de uma atividade podem ser registrados de duas maneiras:

  1. Apontamentos de horas:
    Quando o campo account possui id = -1 e name = "Recursos Humanos", significa que esse custo real veio de apontamentos de horas. Esses dados podem ser visualizados em:
    Detalhes da atividade > Apontamentos.

  2. Cadastro de Custos Reais:
    Quando o campo account possui id > 0, significa que o custo foi registrado como um custo real direto. Esses dados podem ser visualizados em:
    Detalhes da atividade > Custos reais.

Se os custos de outros itens além de Recursos Humanos não estiverem aparecendo, é possível que ainda não tenham sido cadastrados como custos reais na plataforma.

Documentação relacionada:

 

9. Por que a coluna value na API de Custos Planejados contém apenas custos de RH? Onde estão os demais custos?

Pergunta:
Por que a coluna value contém apenas custos de Recursos Humanos? Onde estão os demais custos?

Resposta:
Os custos planejados de uma atividade podem ser registrados de duas formas:

  1. Alocação de recursos:
    Quando o campo account possui id = -1 e name = "Recursos Humanos", significa que o custo planejado veio da alocação de recursos na atividade. Esses dados podem ser visualizados em:
    Detalhes da atividade > Recursos.

    No Channel, o valor da alocação do recurso é distribuído pela duração em dias úteis da atividade. Por exemplo, uma atividade com duração de 5 dias e um recurso alocado com um custo total de 500, resultará em um custo diário de 100 por cada dia útil. Devido a essa divisão, o valor pode aparecer com várias casas decimais, como no exemplo: "value": 32.25806451612903.

  2. Cadastro de Custos Planejados:
    Quando o campo account possui id > 0, significa que o custo foi registrado diretamente como um Custo Planejado. Esses dados podem ser visualizados em:
    Detalhes da atividade > Custos planejados.

Se a API está retornando apenas custos de Recursos Humanos, pode ser que outros custos ainda não tenham sido registrados como Custos Planejados na plataforma.

Documentação relacionada:

 

10. Por que existe o campo plannedStart na API de Marcos, se um marco tem start = finished?

Pergunta:
Por que a API de Marcos contém o campo plannedStart, se um marco possui a mesma data de início e término?

Resposta:
A API de Marcos retorna os mesmos dados da API de Atividades, por isso o campo plannedStart está presente. Mesmo que, por definição, um marco tenha a mesma data de início e de término, o campo plannedStart é herdado da estrutura de atividades e é retornado pela API.

Documentação relacionada:

 

11. Por que o campo duration está presente na API de Marcos, se a duração de um marco deveria ser zero?

Pergunta:
Por que a API de Marcos contém o campo duration, se a duração de um marco deveria ser zero?

Resposta:
A API de Marcos retorna os mesmos dados da API de Atividades, por isso o campo duration está presente. Embora um marco, por definição, tenha duração zero, o campo duration é herdado da estrutura de atividades e é retornado pela API.

Documentação relacionada:

 

12. Por que várias colunas estão em branco, como performance, income, day, tickets, demandOriginId, etc.?

Pergunta:
Por que várias colunas, como performance, income, day, tickets, demandOriginId, entre outras, estão em branco na API de Projetos?

Resposta:
Alguns dos atributos mencionados não são preenchidos diretamente na API de Projetos. Aqui estão os detalhes para cada um deles:

  • day: Para informações relacionadas ao dia, deve-se utilizar o atributo dates, que está disponível na maioria das APIs de projetos.

  • income: Esse dado foi dividido em quatro endpoints separados:

    • Para obter o plannedIncome e o realizedIncome por projeto, utilize os endpoints:
      {id}/plannedIncome e {id}/realizedIncome.

    • Para obter esses valores para todos os projetos, utilize os endpoints:
      /plannedIncome e /realizedIncome.

  • performance: Um endpoint separado foi criado para lidar com a performance, conforme documentado em outro local.

  • demandOriginId: Um endpoint separado também foi criado para essa informação.

Esses atributos não estão preenchidos diretamente na API de Projetos porque foram movidos para endpoints específicos, que podem ser consultados conforme a necessidade.

Documentação relacionada:

 

13. Por que há algumas linhas sem atribuição de profissional na alocação de recursos em atividades?

Pergunta:
Por que há algumas linhas sem a atribuição de um profissional na alocação de recursos em atividades?

Resposta:
O Channel permite a alocação de um papel (função) antes de definir qual será o profissional específico (recurso humano). Isso significa que pode ser alocado um papel, como Analista, Cliente ou Programador, mas o recurso humano ainda não foi definido.

Quando for decidido qual profissional ocupará o papel, será possível realizar a transferência da alocação do papel para um recurso humano específico.

Exemplo:
Um Analista pode ser alocado inicialmente como papel, e posteriormente, a alocação será transferida para o profissional designado para a função.

 

14. Qual a diferença entre a tabela "Projetos - Atividades" e "Atividades - Lista de Atividades"?

Pergunta:
Qual a diferença entre a tabela "Projetos - Atividades" e "Atividades - Lista de Atividades"?

Resposta:
Essas duas tabelas são iguais, pois ambas retornam os mesmos dados. A Atividades -Lista de atividades está depreciada, ou seja, recomendamos a utilizar Projetos -Atividades.

 

 

15. Por que o campo classifier está em branco? Ele não deveria trazer nossos classificadores?

Pergunta:
Por que o campo classifier está em branco? Ele não deveria exibir nossos classificadores?

Resposta:
O campo classifier só será preenchido para atividades que possuem um classificador atribuído. Quando houver um classificador, o campo será apresentado no seguinte formato:

"classifier": { "id": 2, "name": "DELIVERABLE" }

Se o campo estiver em branco, significa que a atividade não possui um classificador atribuído.

 

16. Por que o campo actualCost está em branco, mas o plannedCost contém valores na API de Projetos - Atividades?

Pergunta:
Por que o campo actualCost está em branco enquanto o plannedCost contém valores?

Resposta:
Foi realizado um ajuste para obter as informações das tabelas de processamento de custos. Agora, os pacotes de atividades retornam a soma de seus custos reais juntamente com os custos das atividades filhas. Se o campo actualCost estiver em branco, isso pode indicar que os custos ainda não foram processados ou não há registros de custos reais associados às atividades.

 

17. Por que os totalizadores da API de Projetos - Lista de Totalizadores de Tarefas não batem com o que é visto no Channel?

Pergunta:
Por que os totalizadores da API de Projetos - Lista de Totalizadores de Tarefas não estão de acordo com o que é visto no Channel?

Resposta:
Essa API considera apenas atividades individuais e desconsidera pacotes de atividades. Portanto, os totalizadores podem não incluir os custos e valores agregados de pacotes, resultando em diferenças em relação ao que é exibido diretamente no Channel.

 

18. Por que a API de "Projetos - Performance dos Projetos" traz dados mensais e não semanais?

Pergunta:
Por que a API de "Projetos - Performance dos Projetos" retorna apenas dados mensais, em vez de semanais?

Resposta:
O processamento dos dados de performance é complexo e exige um tempo considerável, principalmente devido ao volume de informações envolvidas. Se a periodicidade fosse ajustada para fornecer dados semanais, o tempo de resposta da API aumentaria significativamente, podendo comprometer a eficiência e a experiência de uso. Para balancear entre a granularidade dos dados e o desempenho da API, os dados são consolidados mensalmente, proporcionando uma resposta mais ágil sem sobrecarregar o sistema.

 

19. Explicação das colunas na API de "Projetos - Referência Atual do Projeto" e a repetição de spi e cpi

Pergunta:
Qual o significado das colunas na API "Projetos - Referência Atual do Projeto", e por que spi e cpi aparecem novamente?

Resposta:
A seguir, uma explicação detalhada dos principais campos retornados pela API:

  • capex:

    • actual: Custos reais cadastrados para o projeto, onde o plano de contas está configurado com o tipo de despesa CAPEX.

    • available: Orçamento CAPEX solicitado por meio da proposta de projeto.

    • beaconColor: Indica se o CAPEX realizado está acima ou abaixo do orçamento solicitado. (#cc0000 = Vermelho, quando o CAPEX realizado é maior; #009900 = Verde, quando está dentro do orçamento).

    • planned: Custos planejados no plano de contas com tipo de despesa CAPEX.

    • status: Pode ser OVER_BUDGET (CAPEX realizado maior que solicitado) ou WITHIN_BUDGET (CAPEX realizado dentro do orçamento).

  • cost:

    • actual: Custo total realizado do projeto.

    • deviation: Diferença entre o custo planejado total e o custo real total.

    • deviationColor: Cor que representa a variação percentual do custo real em relação ao planejado.

    • deviationToDate: Diferença entre o custo planejado até a data atual e o custo real total.

    • deviationToDateColor: Cor que representa a variação percentual do custo real em relação ao planejado até a data atual.

    • planned: Custo total planejado para o projeto.

    • plannedToDate: Custo planejado até a data atual.

    • status: Pode ser ON_BUDGET (dentro do orçamento), UNDER_BUDGET (abaixo do orçamento), ou OVER_BUDGET (acima do orçamento).

  • opex:

    • actual: Custos reais de OPEX (inclui apontamentos de horas e despesas operacionais).

    • available: Orçamento OPEX solicitado no início do projeto.

    • beaconColor: Mesmo esquema de cores do CAPEX para indicar se o OPEX está dentro ou fora do orçamento.

    • planned: Custos planejados para OPEX, incluindo alocação de recursos.

    • status: Pode ser OVER_BUDGET (OPEX realizado acima do solicitado) ou WITHIN_BUDGET (dentro do orçamento).

  • otherValues:

    • actualPercentage: Percentual concluído do projeto até a data atual.

    • cpi: Índice de desempenho de custo. Se o projeto tem custo realizado, é calculado como Valor Agregado / Custo Realizado. Caso contrário, o valor é null.

    • earned: Valor agregado do projeto.

    • percentageDeviation: Diferença percentual entre o percentual concluído e o percentual planejado até a data atual.

    • percentageDeviationColor: Cor que indica o desvio percentual do prazo (planejado versus realizado).

    • plannedPercentage: Percentual planejado até a data atual.

    • spi: Índice de desempenho de prazo, calculado como Valor Agregado / Custo Planejado até a data atual.

  • schedule:

    • status: Status do cronograma, podendo ser ADVANCED (projeto adiantado), LATE (atrasado), UP_TO_DATE (no prazo) ou WITHOUT_SCHEDULE (sem cronograma).

  • work:

    • actual: Trabalho realizado até a data atual, com base nos apontamentos.

    • deviation e deviationColor: Não preenchidos.

    • plannedToDate: Trabalho planejado até a data atual.

    • totalPlanned: Trabalho total planejado para o projeto.

Repetição de spi e cpi:
Esses indicadores são fundamentais para a avaliação do desempenho de custo (cpi) e prazo (spi). Eles aparecem em diferentes contextos (como parte dos valores globais do projeto e também em relatórios de desvio), o que pode levar à sua presença em múltiplos pontos da API para fornecer flexibilidade na análise.

Documentação relacionada:

 

20. Por que o campo roles está totalmente em branco na API de "Projetos - Usuários Associados"?

Pergunta:
Por que o campo roles está em branco, mesmo havendo atribuições de papéis para alguns profissionais?

Resposta:
O campo roles só será preenchido quando o usuário alocado tiver papéis explicitamente associados. Na alocação de recursos, o mesmo usuário pode aparecer repetidamente, uma vez para cada papel associado, permitindo alocar o recurso de acordo com o seu papel específico no projeto.

Como associar papéis a um usuário:
Para atribuir papéis a um usuário, siga o caminho:
Administração > Usuários > Ações > Mais Opções > Associar Papéis.

 

21. O que significam os campos id* e name.* na API de Riscos?

Pergunta:
Como interpretar os campos id* e name.* na API de Riscos?

Resposta:
Os campos id* e name.* representam diferentes atributos relacionados ao cadastro de riscos no projeto. A seguir, a explicação de cada campo e suas funcionalidades:

  • Cadastro do risco:

    • status: Indica o status atual do risco (ex.: Aberto, Fechado).

    • owner: Nome do responsável ou proprietário do risco.

    • strategy: Estratégia de resposta ao risco (ex.: Mitigação, Aceitação).

    • category: Classificação do risco conforme a EAR (Estrutura Analítica de Riscos).

  • Visualização no plano de riscos (Menu do projeto > Documentação > Plano integrado > selecionar Riscos > Ver plano):

    • level: Nível de criticidade do risco, podendo ser inicial ou atual.

    • impact: Impacto do risco, considerando tanto o impacto inicial quanto o atual.

    • likelihood: Probabilidade do risco, também podendo ser inicial ou atual.

Esses campos fornecem uma visão detalhada sobre o risco e como ele está sendo monitorado e gerenciado no projeto.

 

22. Onde estão as ações do plano de ação associado ao risco?

Pergunta:
Onde posso encontrar as ações do plano de ação associado a um risco? Não localizei uma API para isso.

Resposta:
Foi realizado um ajuste, e agora as ações associadas aos riscos estão disponíveis na API chamada "Ações do Risco".

Você pode acessar essa API diretamente para consultar as ações do plano de ação associado a um risco, utilizando o seguinte link: