Metas

List sales goals

crm.goals.list

Lists the sales goals (targets) of the org, newest period first, paginated by cursor (limit up to 200): metric (revenue_won, deals_won, deals_created, activities_logged, calls_made, meetings_held), target, period with its start and end dates (calendar periods in UTC) and is_active (today falls inside it), team or individual owner with user_name, optional pipeline with pipeline_name, and the current value with when it was last computed. Whoever cannot see everyone's performance only gets the team goals and their own.

Escopo

crm:read

Permissão

Ver o módulo

Tool do MCP

crm_goals_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.goals.list".

Custo declarado: até 202 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a sales goal

crm.goals.create

Creates a sales goal: metric, positive target, period (monthly, quarterly or yearly; the bounds snap to the calendar period that contains start_date, today by default), team_scope team or individual (individual needs user_id, a member of the org; a team goal has no owner and any user_id sent is ignored), optional pipeline_id and name. The current value is computed right away. The dry run runs the same checks (same errors: goal_owner_required, goal_owner_not_member) and its preview computes the value the goal would start with (counts goals, current_value, target and percent, the % of the target with one decimal) and says the metric, the period with its dates and the scope. Requires manage_goals (CRM admins).

Escopo

crm:write

Permissão

Editar no módulo · Ação do CRM: manage_goals

Tool do MCP

crm_goals_createNa superfície completa; na compacta, mb_execute_operation com id: "crm.goals.create".

Custo declarado: até 10000 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "team_scope": "individual",
  "metric": "revenue_won",
  "target": 0,
  "period": "monthly"
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/crm/goals" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "team_scope": "individual",
  "metric": "revenue_won",
  "target": 0,
  "period": "monthly"
}'

Update a sales goal

crm.goals.update

Updates a goal's name, metric, target, team scope, owner (user_id), pipeline (null = all pipelines) or period; with none of them it answers no_changes (crm.goals.refresh recomputes the value). A team goal has no owner: moving a goal to team (or saving any change on a team goal that still kept one) clears user_id, so its progress counts the whole team. An individual goal needs an owner: a change to the scope or the owner that would leave it individual without user_id is goal_owner_required, and user_id must be a member (goal_owner_not_member). Changing the period moves the bounds to the calendar period of today. The current value is recomputed after saving. The dry run runs the same checks (same errors) and its preview computes the value with the change (counts goals, current_value, target, percent and previous_value, the value saved today), says the resulting metric, period dates and scope, and warns when the owner is cleared or the dates move. Requires manage_goals.

Escopo

crm:write

Permissão

Editar no módulo · Ação do CRM: manage_goals

Tool do MCP

crm_goals_updateNa superfície completa; na compacta, mb_execute_operation com id: "crm.goals.update".

Custo declarado: até 10001 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X PATCH "https://api.mb-suite.com/v1/crm/goals/{goal_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X PATCH "https://api.mb-suite.com/v1/crm/goals/{goal_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete a sales goal

crm.goals.delete

Deletes a goal for good: goals have no trash, so it cannot be restored (the deals and activities it measured are untouched). Use crm.goals.update to change a goal instead of deleting and recreating it. Requires manage_goals.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write e «Permitir exclusões» (crm:delete no OAuth)

Permissão

Editar no módulo · Ação do CRM: manage_goals

Tool do MCP

crm_goals_deleteNa superfície completa; na compacta, mb_execute_operation com id: "crm.goals.delete".

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Recompute a goal's current value

crm.goals.refresh

Recomputes a goal's current value now from the deals or activities of its period (a daily job already does it for every goal) and returns it. Safe to repeat. The dry run computes the value without saving it (counts goals, current_value, target, percent and previous_value, the value saved today; the text says the metric and the period dates). Anyone with access to the CRM can refresh, as in the goals panel; it does not change the goal itself.

Escopo

crm:write

Permissão

Ver o módulo

Tool do MCP

crm_goals_refreshNa superfície completa; na compacta, mb_execute_operation com id: "crm.goals.refresh".

Custo declarado: até 10001 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/refresh" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/crm/goals/{goal_id}/refresh" \
  -H "Authorization: Bearer $MB_TEST_KEY"