Metas
Alvos de recuperação da equipe ou de um coletor, em valor negociado ou quantidade de acordos. A situação (SCHEDULED, ACTIVE, CLOSED) é derivada das datas e do encerramento — não há coluna de status.
Listar metas
Retorna uma lista paginada de metas da conta. O realizado e o progresso de cada meta são apurados na hora. Metas abertas vêm primeiro, depois pela data de fim.
query Parameters
user_idFiltrar pelo coletor responsável. Omita para listar todas as metas (gerais e de coletores).
debt_group_idFiltrar pelo grupo de dívidas. Omita para listar todas as metas (de todos os grupos e de um grupo específico).
statusFiltrar por status. Aceita múltiplos valores separados por vírgula (SCHEDULED, ACTIVE, CLOSED).
pageNúmero da página
per_pageNúmero de itens por página
Listar metas › Responses
Lista de metas
Dados do item.
Metadados da paginacao.
Criar meta
Cria uma meta de valor negociado (VALUE) ou de quantidade de acordos (CONTRACTS). Sem user_id a meta vale para toda a equipe; sem debt_group_id, para todos os grupos. Se o início for hoje ou no passado, a meta já nasce ativa; se for no futuro, nasce agendada. O período não pode passar de 730 dias. Meta recorrente: envie is_recurring: true. A duração da meta, contada em dias de start_date a end_date (inclusive), vira o intervalo da série: a próxima meta começa no dia seguinte ao fim da anterior, com o mesmo número de dias, e copia nome, tipo, alvo e escopo. Como a contagem é em dias, e não em meses, as datas andam no calendário: 30 dias a partir de 01/10 dão 01/10 a 30/10, depois 31/10 a 29/11. A próxima meta é criada agendada assim que a atual começa, e a série segue até ser interrompida com POST /goals/{id}/stop-recurrence. A resposta traz a primeira meta, com recurrence.index 0.
Criar meta › Request Body
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Maior que zero. Em CONTRACTS deve ser inteiro.
start_dateInício do período de apuração.
end_dateFim do período de apuração. Igual ou posterior ao início. O período não pode passar de 730 dias. Em meta recorrente, não pode ser alterado na atualização.
user_idID do coletor da unidade. Omita ou envie nulo para meta geral (toda a equipe).
debt_group_idID do grupo de dívidas da unidade. Omita ou envie nulo para todos os grupos.
is_recurringSó na criação; ignorado na atualização. true torna a meta recorrente: quando o período termina, uma nova meta com a mesma duração (em dias, de start_date a end_date) começa no dia seguinte. Veja POST /goals.
apply_to_followingSó na atualização de meta de uma série ativa. Verdadeiro aplica a alteração também à meta agendada seguinte e torna esta meta a meta-modelo da série. Falso (padrão) altera só esta meta. Editar a própria meta-modelo sempre vale para as próximas.
Criar meta › Responses
Meta criada com sucesso
idIdentificador unico da meta.
business_unit_idID da unidade de negocio da meta.
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Em VALUE é um valor em reais; em CONTRACTS é a quantidade de acordos (inteiro).
realizedRealizado no período da meta, na mesma unidade do alvo. Meta agendada retorna 0.
user_idID do coletor responsável. Nulo quando a meta vale para toda a equipe.
debt_group_idID do grupo de dívidas. Nulo quando a meta vale para todos os grupos.
start_dateInício do período de apuração.
end_dateFim do período de apuração.
closed_atInstante do encerramento, em UTC. Nulo enquanto a meta estiver aberta. No encerramento por prazo e o fim do ultimo dia do periodo, que em UTC cai no dia seguinte ao end_date.
statusSituação da meta: SCHEDULED (período ainda não começou), ACTIVE (em andamento) ou CLOSED (encerrada). Encerrar é irreversível. O prazo vencido também encerra a meta.
status_reasonPor que a meta foi encerrada: MANUALLY_CLOSED (alguém clicou) ou DEADLINE_REACHED (o período acabou). Nulo enquanto estiver aberta.
is_frozenIndica se a composição de acordos foi congelada (ao encerrar).
Série recorrente da qual a meta faz parte. Nulo em meta avulsa.
Diagnóstico da meta agora. Nulo se ainda estiver agendada.
created_atData e hora de criacao da meta, em UTC.
updated_atData e hora da ultima atualizacao da meta, em UTC.
Obter meta
Retorna a meta com o realizado, o diagnóstico de progresso, o realizado de cada dia e, se a composição estiver congelada, os acordos da composição.
path Parameters
idID da meta
Obter meta › Responses
Detalhes da meta
idIdentificador unico da meta.
business_unit_idID da unidade de negocio da meta.
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Em VALUE é um valor em reais; em CONTRACTS é a quantidade de acordos (inteiro).
realizedRealizado no período da meta, na mesma unidade do alvo. Meta agendada retorna 0.
user_idID do coletor responsável. Nulo quando a meta vale para toda a equipe.
debt_group_idID do grupo de dívidas. Nulo quando a meta vale para todos os grupos.
start_dateInício do período de apuração.
end_dateFim do período de apuração.
closed_atInstante do encerramento, em UTC. Nulo enquanto a meta estiver aberta. No encerramento por prazo e o fim do ultimo dia do periodo, que em UTC cai no dia seguinte ao end_date.
statusSituação da meta: SCHEDULED (período ainda não começou), ACTIVE (em andamento) ou CLOSED (encerrada). Encerrar é irreversível. O prazo vencido também encerra a meta.
status_reasonPor que a meta foi encerrada: MANUALLY_CLOSED (alguém clicou) ou DEADLINE_REACHED (o período acabou). Nulo enquanto estiver aberta.
is_frozenIndica se a composição de acordos foi congelada (ao encerrar).
Série recorrente da qual a meta faz parte. Nulo em meta avulsa.
Diagnóstico da meta agora. Nulo se ainda estiver agendada.
created_atData e hora de criacao da meta, em UTC.
updated_atData e hora da ultima atualizacao da meta, em UTC.
Realizado de cada dia de start_date até o fim da apuração (measured_until limitado ao end_date). Dias sem acordo vêm com amount 0, e a soma fecha com realized. Vazio em meta agendada.
Acordos congelados na composição da meta. Vazio enquanto a composição não estiver congelada — como na meta ativa deste exemplo. Cada acordo tem os campos de GoalContractSnapshot.
Atualizar meta
Enquanto a meta está agendada, todos os campos podem ser alterados. Depois que o período começa, só o nome é aplicado — alvo, tipo, período e escopo enviados no corpo são ignorados. Meta encerrada não pode ser editada e retorna GOL_001. Em meta recorrente o período nunca muda, e apply_to_following decide se a alteração vale também para as próximas metas da série. Encerrar uma meta usa POST /goals/{id}/close.
path Parameters
idID da meta
Atualizar meta › Request Body
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Maior que zero. Em CONTRACTS deve ser inteiro.
start_dateInício do período de apuração.
end_dateFim do período de apuração. Igual ou posterior ao início. O período não pode passar de 730 dias. Em meta recorrente, não pode ser alterado na atualização.
user_idID do coletor da unidade. Omita ou envie nulo para meta geral (toda a equipe).
debt_group_idID do grupo de dívidas da unidade. Omita ou envie nulo para todos os grupos.
is_recurringSó na criação; ignorado na atualização. true torna a meta recorrente: quando o período termina, uma nova meta com a mesma duração (em dias, de start_date a end_date) começa no dia seguinte. Veja POST /goals.
apply_to_followingSó na atualização de meta de uma série ativa. Verdadeiro aplica a alteração também à meta agendada seguinte e torna esta meta a meta-modelo da série. Falso (padrão) altera só esta meta. Editar a própria meta-modelo sempre vale para as próximas.
Atualizar meta › Responses
Meta atualizada com sucesso
idIdentificador unico da meta.
business_unit_idID da unidade de negocio da meta.
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Em VALUE é um valor em reais; em CONTRACTS é a quantidade de acordos (inteiro).
realizedRealizado no período da meta, na mesma unidade do alvo. Meta agendada retorna 0.
user_idID do coletor responsável. Nulo quando a meta vale para toda a equipe.
debt_group_idID do grupo de dívidas. Nulo quando a meta vale para todos os grupos.
start_dateInício do período de apuração.
end_dateFim do período de apuração.
closed_atInstante do encerramento, em UTC. Nulo enquanto a meta estiver aberta. No encerramento por prazo e o fim do ultimo dia do periodo, que em UTC cai no dia seguinte ao end_date.
statusSituação da meta: SCHEDULED (período ainda não começou), ACTIVE (em andamento) ou CLOSED (encerrada). Encerrar é irreversível. O prazo vencido também encerra a meta.
status_reasonPor que a meta foi encerrada: MANUALLY_CLOSED (alguém clicou) ou DEADLINE_REACHED (o período acabou). Nulo enquanto estiver aberta.
is_frozenIndica se a composição de acordos foi congelada (ao encerrar).
Série recorrente da qual a meta faz parte. Nulo em meta avulsa.
Diagnóstico da meta agora. Nulo se ainda estiver agendada.
created_atData e hora de criacao da meta, em UTC.
updated_atData e hora da ultima atualizacao da meta, em UTC.
Interromper recorrência
Interrompe a série recorrente da meta: nenhuma meta nova é criada. A meta em andamento continua até o fim, e a próxima, ainda agendada, é removida; se o id informado for o dessa meta agendada, a resposta traz os últimos dados dela. Meta avulsa retorna GOL_005; série já interrompida retorna GOL_004.
path Parameters
idID de qualquer meta da série
Interromper recorrência › Responses
Recorrência interrompida
idIdentificador unico da meta.
business_unit_idID da unidade de negocio da meta.
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Em VALUE é um valor em reais; em CONTRACTS é a quantidade de acordos (inteiro).
realizedRealizado no período da meta, na mesma unidade do alvo. Meta agendada retorna 0.
user_idID do coletor responsável. Nulo quando a meta vale para toda a equipe.
debt_group_idID do grupo de dívidas. Nulo quando a meta vale para todos os grupos.
start_dateInício do período de apuração.
end_dateFim do período de apuração.
closed_atInstante do encerramento, em UTC. Nulo enquanto a meta estiver aberta. No encerramento por prazo e o fim do ultimo dia do periodo, que em UTC cai no dia seguinte ao end_date.
statusSituação da meta: SCHEDULED (período ainda não começou), ACTIVE (em andamento) ou CLOSED (encerrada). Encerrar é irreversível. O prazo vencido também encerra a meta.
status_reasonPor que a meta foi encerrada: MANUALLY_CLOSED (alguém clicou) ou DEADLINE_REACHED (o período acabou). Nulo enquanto estiver aberta.
is_frozenIndica se a composição de acordos foi congelada (ao encerrar).
Série recorrente da qual a meta faz parte. Nulo em meta avulsa.
Diagnóstico da meta agora. Nulo se ainda estiver agendada.
created_atData e hora de criacao da meta, em UTC.
updated_atData e hora da ultima atualizacao da meta, em UTC.
Encerrar meta
Encerra uma meta ativa, congela a composição dos acordos e deixa de apurar novos. Encerrar é irreversível. Grava status_reason MANUALLY_CLOSED. Só é possível encerrar meta ativa — agendada ou já encerrada retornam GOL_002. O prazo vencido também encerra a meta automaticamente (DEADLINE_REACHED). A resposta é a mesma de GET /goals/{id}: como a composição acabou de ser congelada, ela já vem em contract_snapshots, sem precisar de uma segunda chamada.
path Parameters
idID da meta
Encerrar meta › Responses
Meta encerrada com sucesso
idIdentificador unico da meta.
business_unit_idID da unidade de negocio da meta.
nameNome da meta.
typeO que a meta mede: VALUE (valor negociado em R$) ou CONTRACTS (quantidade de acordos).
targetAlvo a ser atingido. Em VALUE é um valor em reais; em CONTRACTS é a quantidade de acordos (inteiro).
realizedRealizado no período da meta, na mesma unidade do alvo. Meta agendada retorna 0.
user_idID do coletor responsável. Nulo quando a meta vale para toda a equipe.
debt_group_idID do grupo de dívidas. Nulo quando a meta vale para todos os grupos.
start_dateInício do período de apuração.
end_dateFim do período de apuração.
closed_atInstante do encerramento, em UTC. Nulo enquanto a meta estiver aberta. No encerramento por prazo e o fim do ultimo dia do periodo, que em UTC cai no dia seguinte ao end_date.
statusSituação da meta: SCHEDULED (período ainda não começou), ACTIVE (em andamento) ou CLOSED (encerrada). Encerrar é irreversível. O prazo vencido também encerra a meta.
status_reasonPor que a meta foi encerrada: MANUALLY_CLOSED (alguém clicou) ou DEADLINE_REACHED (o período acabou). Nulo enquanto estiver aberta.
is_frozenIndica se a composição de acordos foi congelada (ao encerrar).
Série recorrente da qual a meta faz parte. Nulo em meta avulsa.
Diagnóstico da meta agora. Nulo se ainda estiver agendada.
created_atData e hora de criacao da meta, em UTC.
updated_atData e hora da ultima atualizacao da meta, em UTC.
Realizado de cada dia de start_date até o fim da apuração (measured_until limitado ao end_date). Dias sem acordo vêm com amount 0, e a soma fecha com realized. Vazio em meta agendada.
Acordos congelados na composição da meta. Vazio enquanto a composição não estiver congelada — como na meta ativa deste exemplo. Cada acordo tem os campos de GoalContractSnapshot.