A entidade Oportunidades do Funil permite gerenciar as oportunidades de vendas de um funil no Mercos. Cada oportunidade representa uma possível venda associada a um cliente e posicionada em uma etapa do funil.
O limite de registros enviados por requisição é de 300.
Atenção as regras:
- Apenas oportunidades com status 1 (ABERTA) podem ser movidas entre etapas
- Apenas oportunidades com status 1 (ABERTA) podem ser marcadas como 2 (GANHA) ou 3 (PERDIDA)
- Apenas oportunidades com status 1 (ABERTA) podem ter um pedido vinculado
Estrutura da Resposta (GET)
| Campo | Tipo | Descrição |
|---|---|---|
| id | Integer | Identificador único. |
| titulo | String: 150 | Título da oportunidade. |
| status | Integer | 1 - ABERTA, 2 - GANHA ou 3 - PERDIDA. |
| fase_id | Integer | Identificador da etapa/fase onde a oportunidade está posicionada. |
| cliente_id | Integer | Identificador do cliente associado. |
| colaborador_id | Integer | Identificador do colaborador associado. |
| valor | Decimal: 2 casas decimais | Valor da oportunidade. |
| pedido_id | Integer | Identificador do pedido vinculado (se houver). |
| motivo_perda_id | Integer | Identificador do motivo de perda (quando status é 3 - PERDIDA). |
| observacao_resultado | String | Observação sobre o resultado da oportunidade. |
| uuid | String | UUID único da oportunidade. |
| origem | String | Origem da oportunidade (ex: "MANUAL", "API_EXTERNA") |
| data_de_criacao | DateTime | Data e hora da criação desta oportunidade no Mercos. |
| ultima_alteracao | DateTime | Data e hora da última modificação desta oportunidade no Mercos. |
| excluido | Boolean | Indica se a oportunidade está excluída. |
Parâmetros de Envio - UPSERT em Lote (POST)
Este endpoint recebe uma lista de objetos. Cada objeto pode criar ou atualizar uma oportunidade:
- Sem
id: Cria uma nova oportunidade - Com
id: Atualiza a oportunidade existente
Campos para CRIAR (sem id):
| Campo | Tipo | Descrição |
|---|---|---|
| titulo (obrigatório) | String: 150 | Título da oportunidade. |
| fase_id (obrigatório) | Integer | Identificador da etapa do funil. |
| cliente_id (obrigatório) | Integer | Identificador do cliente associado. |
| colaborador_id (obrigatório) | Integer | Identificador do colaborador associado. |
| status | Integer | 1 - ABERTA, 2 - GANHA ou 3 - PERDIDA. O valor padrão é 1. |
| valor | Decimal | Valor da oportunidade. |
| pedido_id | Integer | Identificador do pedido vinculado. |
| motivo_perda_id | Integer | Identificador do motivo de perda. |
| observacao_resultado | String | Observação sobre o resultado. |
Campos para ATUALIZAR (com id):
| Campo | Tipo | Descrição |
|---|---|---|
| id (obrigatório) | Integer | Identificador da oportunidade a atualizar. |
| titulo | String: 150 | Título da oportunidade. |
| fase_id | Integer | Identificador da etapa do funil. |
| cliente_id | Integer | Identificador do cliente associado. |
| colaborador_id | Integer | Identificador do colaborador associado. |
| status | Integer | 1 - ABERTA, 2 - GANHA ou 3 - PERDIDA. |
| valor | Decimal | Valor da oportunidade. |
| pedido_id | Integer | Identificador do pedido vinculado. |
| motivo_perda_id | Integer | Identificador do motivo de perda. |
| observacao_resultado | String | Observação sobre o resultado. |
| excluido | Boolean | Indica se a oportunidade deve ser excluída. |