Atualizar Estagio da Oportunidade

PATCH /external/v1/opportunities/:id/stage

Move uma oportunidade para outra etapa. Os timestamps de ciclo de vida (sent_at, accepted_at, qualifying_started_at, qualified_at, scheduled_at, won_at, lost_at) sao definidos automaticamente com base na etapa de destino.

Autenticacao

Requer permissao opportunities:write.

Parametros de Caminho

Parametro	Tipo	Obrigatorio	Descricao
id	string	Sim	Identificador unico da oportunidade

Corpo da Requisicao

Campo	Tipo	Obrigatorio	Descricao
stage_id	string	Sim	ID da etapa de destino (veja Listar Pipelines)
discard_reason_id	string	Nao	Motivo de perda, ao mover para uma etapa de perda

INFO

O timestamp de ciclo de vida e derivado do nome da etapa de destino. Etapas chamadas invite_sent, accepted, qualifying, qualified, scheduled, won e lost definem sent_at, accepted_at, qualifying_started_at, qualified_at, scheduled_at, won_at e lost_at respectivamente.

Requisicao

cURL

curl --request PATCH \
  --url "https://app.getraze.com/external/v1/opportunities/opp_abc123def456/stage" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: YOUR_API_KEY" \
  --data '{
    "stage_id": "stg_won"
  }'

Node.js

const axios = require('axios');

const opportunityId = 'opp_abc123def456';

const response = await axios.patch(
  `https://app.getraze.com/external/v1/opportunities/${opportunityId}/stage`,
  { stage_id: 'stg_won' },
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

opportunity_id = 'opp_abc123def456'

response = requests.patch(
    f'https://app.getraze.com/external/v1/opportunities/{opportunity_id}/stage',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'stage_id': 'stg_won'}
)

print(response.json())

Resposta

{
  "success": true,
  "data": {
    "id": "opp_abc123def456",
    "title": "Acme Inc - Plano Pro",
    "stage_id": "stg_won",
    "stage_name": "Ganho",
    "won_at": "2026-01-25T10:00:00Z",
    "contact_name": "John Doe",
    "owner_user_name": "Maria Silva",
    "updated_at": "2026-01-25T10:00:00Z"
  },
  "stage_change": {
    "from": { "id": "stg_proposal", "name": "Proposta" },
    "to": { "id": "stg_won", "name": "Ganho" }
  }
}

Campos de Resposta

Campo	Tipo	Descricao
data	object	A oportunidade atualizada
stage_change.from	object	Etapa anterior (id, name)
stage_change.to	object	Nova etapa (id, name)

Erros

Status	Codigo	Descricao
400	VALIDATION_ERROR	stage_id e obrigatorio
404	NOT_FOUND	Oportunidade nao encontrada