# Cotações

# CotacaoService — Web Service SOAP de Cotações

## Visão Geral

O `CotacaoService` é um Web Service SOAP que expõe operações para integração de cotações com sistemas externos. Ele permite criar cotações com seus respectivos itens, listar registros aprovados e notificar o resultado de uma integração ao banco de dados.

* **URL Base:** `{base_url}/api/cotacaoservice`
* **WSDL:** `{base_url}/api/cotacaoservice?wsdl`
* **Encoding:** `UTF-8`

## Autenticação

Todos os métodos expostos exigem obrigatoriamente o parâmetro de validação `token`.

* Chamadas efetuadas com um token inválido retornam o código numérico `'0'`.
* Chamadas originadas de contas sem permissão de acesso à funcionalidade retornam o código `'35'`.

## Envio de Parâmetros

> **IMPORTANTE:** Sempre envie todas as chaves mapeadas no envelope SOAP, mesmo que o valor de determinado campo seja vazio (nulo). A omissão de uma chave estrutural pode causar comportamentos inesperados ou falhas na interpretação dos parâmetros pelo servidor.

## Métodos

###  `gravaCotacao`

Responsável por persistir uma nova cotação com seus itens associados. Se o parâmetro `cotacao` for populado e corresponder a um registro já existente, o sistema gera automaticamente uma nova versão incremental do documento.

### Parâmetros de Entrada

| **Parâmetro** | **Tipo** | **Obrigatório** | **Descrição** |
|-----------|------|-------------|-----------|
| `token`   | `string` | **Sim**     | Token de autenticação de API. |
| `cotacao` | `string` | Não         | Número de uma cotação existente (gera nova versão). Se omitido/vazio, o sistema gera uma nova cotação. |
| `emitente` | `string` | **Sim**     | Código numérico identificador do emitente. |
| `empresa` | `string` | **Sim**     | Código numérico identificador da filial. |
| `responsavel` | `string` | **Sim**     | Código numérico identificador do responsável. |
| `oportunidade` | `string` | **Sim**     | Código numérico da oportunidade vinculada. Deve existir, estar com status aberto e pertencer ao mesmo emitente. |
| `data`    | `string` | Não         | Data da cotação em qualquer formato reconhecido pelo PHP (ex.: `2024-01-31`). Se vazio, adota a data atual. |
| `obs`     | `string` | Não         | Observações gerais textuais da cotação. |
| `tipo_desconto` | `string` | **Condicional** | Tipo do desconto: `'P'` (percentual) ou `'V'` (valor fixo). Obrigatório se `desconto` for informado. Padrão: `'P'`. |
| `desconto` | `string` | Não         | Valor numérico do desconto a ser aplicado. |
| `tab_preco` | `string` | **Sim**     | Nome literal da tabela de preços. Deve constar na base e estar ativa. |
| `forma_pagamento` | `string` | **Sim**     | Código numérico da forma de pagamento escolhida. |
| `qtd_parcelas` | `string` | **Sim**     | Quantidade de parcelas. Deve ser numérico e respeitar o teto permitido pela forma de pagamento. |
| `itens`   | `CotacaoItemArray` | **Sim**     | Array estruturado contendo os itens. Mínimo de 1 item. Códigos duplicados são consolidados automaticamente. |

### Estrutura de cada item

| **Campo** | **Obrigatório** | **Descrição** |
|-------|-------------|-----------|
| `codigo` | **Sim**     | Código do item. Deve existir e estar associado à tabela de preços informada. |
| `quantidade` | **Sim**     | Quantidade solicitada. Deve ser maior que zero. Aceita frações conforme configuração do item. |
| `preco` | **Sim**     | Preço unitário praticado. Deve ser numérico e maior que zero. |
| `preco_original` | Não         | Preço original de tabela antes do desconto. Deve ser numérico. |
| `unidade` | Não         | Unidade de medida associada. |
| `desc_perc` | Não         | Percentual de desconto específico para este item. |
| `narrativa_item` | Não         | Descrição detalhada ou narrativa adicional do produto/serviço. |
| `obs_item` | Não         | Observações internas do item. |

### Códigos de Retorno

| **Código** | **Significado / Causa** |
|--------|---------------------|
| `**'0'**` | Token inválido      |
| `**'1'**` | Sucesso — cotação gravada com êxito |
| `**'2'**` | Emitente inválido: não informado, não numérico ou não encontrado |
| `**'3'**` | Filial (empresa) inválida: não informada, não numérica ou não encontrada |
| `**'4'**` | Responsável inválido: não informado ou não numérico |
| `**'5'**` | Oportunidade inválida: não informada, não numérica ou não encontrada |
| `**'6'**` | Oportunidade com status diferente de aberto |
| `**'7'**` | Emitente informado não pertence à oportunidade indicada |
| `**'8'**` | `tipo_desconto` inválido — deve ser `'V'` ou `'P'` |
| `**'9'**` | Tabela de preços não informada ou não encontrada |
| `**'10'**` | Tabela de preços inativa |
| `**'11'**` | Forma de pagamento inválida: não informada, não numérica ou não encontrada |
| `**'12'**` | Quantidade de parcelas não informada ou não numérica |
| `**'14'**` | Quantidade de parcelas excede o limite máximo da forma de pagamento |
| `**'15'**` | Número de cotação informado não é numérico |
| `**'16'**` | Nenhum item informado no array de itens |
| `**'17'**` | Um dos itens não possui código informado |
| `**'19'**` | Código de item não encontrado na tabela de preços informada |
| `**'20'**` | Quantidade do item inválida: não numérica, zero ou negativa |
| `**'21'**` | Preço do item inválido: não numérico, zero ou negativo |
| `**'25'**` | Valor de desconto não numérico |
| `**'35'**` | Conta sem acesso à funcionalidade |
| `**'99'**` | Erro interno inesperado |

### Exemplos de Comunicação XML

**Requisição:**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
  <SOAP-ENV:Body>
    <tns:gravaCotacao>
      <token>SEU_TOKEN</token>
      <cotacao></cotacao>
      <emitente>123</emitente>
      <empresa>1</empresa>
      <responsavel>45</responsavel>
      <oportunidade>789</oportunidade>
      <data>2024-01-31</data>
      <obs>Observação da cotação</obs>
      <tipo_desconto>P</tipo_desconto>
      <desconto>10</desconto>
      <tab_preco>TABELA PADRÃO</tab_preco>
      <forma_pagamento>2</forma_pagamento>
      <qtd_parcelas>3</qtd_parcelas>
      <moeda></moeda>
      <situacao></situacao>
      <itens SOAP-ENC:arrayType="tns:CotacaoItem[2]" xsi:type="tns:CotacaoItemArray">
        <item xsi:type="tns:CotacaoItem">
          <codigo>PROD001</codigo>
          <unidade></unidade>
          <quantidade>5</quantidade>
          <preco_original></preco_original>
          <preco>120.00</preco>
          <desc_perc></desc_perc>
          <narrativa_item></narrativa_item>
          <obs_item></obs_item>
        </item>
        <item xsi:type="tns:CotacaoItem">
          <codigo>PROD002</codigo>
          <unidade></unidade>
          <quantidade>2</quantidade>
          <preco_original></preco_original>
          <preco>350.50</preco>
          <desc_perc></desc_perc>
          <narrativa_item></narrativa_item>
          <obs_item></obs_item>
        </item>
      </itens>
    </tns:gravaCotacao>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

**Resposta de Sucesso:**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns1:gravaCotacaoResponse xmlns:ns1="{base_url}/api/cotacaoservice?wsdl">
      <return xsi:type="xsd:string">1</return>
    </ns1:gravaCotacaoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

##  `listaCotacao`

Realiza a listagem de todas as cotações que possuem status de aprovação sistêmica a partir de uma determinada data/hora de corte fornecida.

### Parâmetros de Entrada

| **Parâmetro** | **Tipo** | **Obrigatório** | **Descrição** |
|-----------|------|-------------|-----------|
| `token`   | `string` | **Sim**     | Token de autenticação de API. |
| `dt_aprovacao` | `string` | Não         | Data/hora limite de corte (ex.: `2024-01-31 10:00:00`). Se omitido, retorna o histórico completo de aprovados. |

### Estrutura do Retorno

O retorno mapeado é composto estritamente por um array indexado contendo duas posições:

| **Índice** | **Tipo** | **Descrição** |
|--------|------|-----------|
| `**[0]**` | `string` \| `null` | Código indicador de erro. O valor `null` explicita uma execução com **Sucesso**. |
| `**[1]**` | `CotacaoArray` \| `null` | Array tipado com as cotações encontradas. Retorna `null` se houver erros. |

### Códigos de Retorno

| **Código** | **Significado** |
|--------|-------------|
| `**null**` | Sucesso — O índice `[1]` conterá a coleção de dados mapeada. |
| `**'0'**` | Token de autenticação inválido. |
| `**'9'**` | Nenhuma cotação localizada para o filtro de data especificado. |
| `**'35'**` | Conta sem acesso habilitado à funcionalidade. |

### Exemplos de Comunicação XML

**Requisição:**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
  <SOAP-ENV:Body>
    <tns:listaCotacao>
      <token>SEU_TOKEN</token>
      <dt_aprovacao>2024-01-01 00:00:00</dt_aprovacao>
    </tns:listaCotacao>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

**Resposta de Sucesso:**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns1:listaCotacaoResponse xmlns:ns1="{base_url}/api/cotacaoservice?wsdl">
      <mensagem xsi:type="xsd:string"></mensagem>
      <return xsi:type="tns:CotacaoArray">
        <item xsi:type="tns:Cotacao">
          <cotacao>1001</cotacao>
          <versao>1</versao>
          <emitente>123</emitente>
          <empresa>1</empresa>
          <nome_emitente>Empresa Exemplo LTDA</nome_emitente>
          <responsavel>45</responsavel>
          <oportunidade>789</oportunidade>
          <processo_venda>Processo A</processo_venda>
          <estagio_venda>Proposta</estagio_venda>
          <data>2024-01-31</data>
          <obs></obs>
          <tipo_desconto>P</tipo_desconto>
          <desconto>10</desconto>
          <valor_total>1107.00</valor_total>
          <tab_preco>5</tab_preco>
          <forma_pagamento>2</forma_pagamento>
          <qtd_parcelas>3</qtd_parcelas>
          <moeda>1</moeda>
          <situacao>1</situacao>
          <itens_cotacao xsi:type="tns:CotacaoItem2Array">
            <item xsi:type="tns:CotacaoItem2">
              <codigo>PROD001</codigo>
              <nome>Produto Exemplo 1</nome>
              <unidade>UN</unidade>
              <quantidade>5</quantidade>
              <preco_original></preco_original>
              <preco>120.00</preco>
              <preco_total>600.00</preco_total>
              <desc_perc></desc_perc>
              <narrativa_item></narrativa_item>
              <obs_item></obs_item>
            </item>
            <item xsi:type="tns:CotacaoItem2">
              <codigo>PROD002</codigo>
              <nome>Produto Exemplo 2</nome>
              <unidade>UN</unidade>
              <quantidade>2</quantidade>
              <preco_original></preco_original>
              <preco>350.50</preco>
              <preco_total>701.00</preco_total>
              <desc_perc></desc_perc>
              <narrativa_item></narrativa_item>
              <obs_item></obs_item>
            </item>
          </itens_cotacao>
        </item>
      </return>
    </ns1:listaCotacaoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

## `gravaDtIntegracao`

Registra no banco de dados o resultado da tentativa de processamento da cotação no ecossistema externo. Se não houver mensagens de erro associadas, a data da integração é persistida no documento. Caso ocorram falhas impeditivas, o sistema armazena a stack de erro no log.

### Parâmetros de Entrada

| **Parâmetro** | **Tipo** | **Obrigatório** | **Descrição** |
|-----------|------|-------------|-----------|
| `token`   | `string` | **Sim**     | Token de autenticação de API. |
| `num_cotacao` | `string` | **Sim**     | Número de identificação da cotação alvo. |
| `versao`  | `string` | **Sim**     | Código da versão da cotação a ser atualizada. |
| `mensagem_erro` | `string` | Não         | Texto descritivo da falha retornada pelo parceiro. Se vazio, assume-se sucesso e grava o timestamp. |

### Códigos de Retorno

| **Código** | **Significado / Causa** |
|--------|---------------------|
| `**'0'**` | Token inválido      |
| `**'1'**` | Sucesso — Registro da data ou log de erro efetuado com êxito |
| `**'2'**` | Cotação não localizada com o par Número/Versão fornecido |
| `**'3'**` | Falha interna ao tentar persistir o estado da data de integração |
| `**'35'**` | Conta sem acesso habilitado à funcionalidade |
| `**'99'**` | Erro interno inesperado |

## Exemplos de Comunicação XML

**Requisição (Cenário de Sucesso da Integração):**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
  <SOAP-ENV:Body>
    <tns:gravaDtIntegracao>
      <token>SEU_TOKEN</token>
      <num_cotacao>1001</num_cotacao>
      <versao>1</versao>
      <mensagem_erro></mensagem_erro>
    </tns:gravaDtIntegracao>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

**Requisição (Cenário com Registro de Log de Erro):**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:tns="{base_url}/api/cotacaoservice?wsdl">
  <SOAP-ENV:Body>
    <tns:gravaDtIntegracao>
      <token>SEU_TOKEN</token>
      <num_cotacao>1001</num_cotacao>
      <versao>1</versao>
      <mensagem_erro>Falha ao localizar cliente no ERP: código 123 não encontrado</mensagem_erro>
    </tns:gravaDtIntegracao>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

**Resposta Padrão do Servidor:**

```javascript
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Body>
    <ns1:gravaDtIntegracaoResponse xmlns:ns1="{base_url}/api/cotacaoservice?wsdl">
      <return xsi:type="xsd:string">1</return>
    </ns1:gravaDtIntegracaoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

---

**Documents**

- [Changelog](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/changelog-Zm8YRaLsX2)
- [Comercial e Vendas](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/comercial-e-vendas-mLzQaeyoTV)
- [Configurações Gerais](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/configuracoes-gerais-J7dm490z1m)
- [Gestão de Relacionamento (CRM)](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/gestao-de-relacionamento-crm-74VyXWo680)
- [Integrações](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/integracoes-zJfkJOXdix)
- [Operações e Produtividade](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/operacoes-e-produtividade-k2U2Vd3Fk8)
- [Projetos](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/projetos-jaD6SWGAB9)
- [Relatórios](https://hub.procedo.dev/s/1deab281-1e68-456b-841a-f04b2c82b04d/doc/relatorios-uab6Sta2qa)