APIs privadas

Comercial · oportunidades

Criar, atualizar e agir sobre oportunidades
View as Markdown

Comercial · oportunidades

Esta página concentra as operações privadas de escrita para oportunidades do Comercial.

Escopo atual:

  • POST /simplificav2/oportunidade
  • PUT /simplificav2/oportunidade/{id}
  • POST /simplificav2/oportunidade/{id}/ganho
  • POST /simplificav2/oportunidade/{id}/perda
  • POST /simplificav2/oportunidade/{id}/sdr
  • POST /simplificav2/oportunidade/{id}/closer
  • POST /simplificav2/oportunidade/{id}/reuniao
  • POST /simplificav2/oportunidade/{id}/duplicar
  • POST /simplificav2/oportunidade/{id}/venda

Autenticação

1Authorization: Bearer {{bearer_token}}
2Content-Type: application/json

Regras gerais

  • todas as chamadas usam JSON;
  • cada chamada opera em uma única oportunidade;
  • POST /oportunidade exige dados básicos e ao menos um item;
  • PUT /oportunidade/{id} faz atualização parcial;
  • campos omitidos continuam com o valor atual;
  • quando itens é enviado no PUT, a lista atual é substituída pela nova lista;
  • é possível atualizar somente os itens;
  • não existe rota de inativação por API para oportunidade.

Criar oportunidade

Rota

  • POST /simplificav2/oportunidade

Campos principais:

  • pessoa_id
  • etapa_negociacao_id
  • origem_id
  • data_oportunidade
  • data_previsao_fechamento
  • consultor_sdr_id
  • consultor_closer_id
  • itens

Campos opcionais:

  • endereco_entrega_id
  • observacao
  • observacao_interna
  • vl_acrescimo
  • vl_frete

Atualizar oportunidade

Rota

  • PUT /simplificav2/oportunidade/{id}

Observações:

  • atualiza somente os atributos enviados;
  • exige oportunidade ativa e pendente;
  • aceita atualizar dados básicos, totais adicionais e itens;
  • se itens for enviado, os itens atuais são substituídos pela nova lista.

Ações da oportunidade

Rotas

  • POST /simplificav2/oportunidade/{id}/ganho
  • POST /simplificav2/oportunidade/{id}/perda
  • POST /simplificav2/oportunidade/{id}/sdr
  • POST /simplificav2/oportunidade/{id}/closer
  • POST /simplificav2/oportunidade/{id}/reuniao
  • POST /simplificav2/oportunidade/{id}/duplicar
  • POST /simplificav2/oportunidade/{id}/venda

Observações:

  • ganho exige data_encerramento;
  • perda exige motivo_id e observacao;
  • sdr e closer trocam somente o responsável informado;
  • reuniao vincula uma reunião já existente;
  • duplicar cria uma nova oportunidade a partir da atual.
  • venda gera uma venda em aberto a partir da oportunidade, reaproveitando os itens ativos da negociação.

Resposta de sucesso

Todas as operações usam o mesmo retorno mínimo:

1{
2  "status": "sucesso",
3  "mensagem": "Solicitação executada com sucesso.",
4  "data": {
5    "id": 123
6  }
7}