Ver código fonte para Smart Component Execucao/Geracao Arquivo XML Vendas

[[Smart_Component_Execucao]]
= Arquivo XML de vendas =

''Smart Component de execução que gera extratos de relacionamento dos cooperados em XML, com vendas, aquisições, ranking e totais por linha de produto.''

__TOC__

== Para que serve ==

O recurso gera um arquivo XML com um <code>&lt;EXTRATO&gt;</code> para cada cooperado que tenha vendas da empresa no período e nas espécies selecionadas. Cada extrato reúne dados do cooperado, posição no ranking, notas recentes, valores por subespécie e informações gerais da cooperativa. O arquivo pode ser usado por outro sistema para montar ou distribuir os extratos.

O resultado é um arquivo para download na tarefa de '''Executar Smart Component'''. Ele é salvo em uma pasta do servidor do ERP; este componente não possui envio por FTP.

== Antes de executar ==

* Confira o cadastro dos cooperados e o vínculo de cada cooperado com seu cliente. Vendas a clientes sem cooperado vinculado não geram extrato individual.
* Confira as notas fiscais próprias da empresa no período, a classificação de receita de venda do CFOP e a espécie dos produtos.
* Confira as notas fiscais de terceiros se os valores de aquisição da cooperativa também forem usados pelo sistema de destino.
* Verifique o número de matrizes no cadastro dos cooperados. O XML calcula valores por matriz dividindo por essa quantidade.
* Prepare uma pasta existente no '''servidor do ERP''' com permissão de escrita. O caminho não é uma pasta do computador do usuário.
* Restrinja o acesso ao arquivo: ele contém nomes de cooperados e informações financeiras, como compras e limite de crédito.

== Parâmetros ==

Os nomes exibidos na tela dependem do cadastro do Smart Component. Para integração por API, use as chaves abaixo.

{| class="wikitable"
! Chave !! O que informar !! Exigido pelo componente
|-
| <code>P_DATA_INICIAL</code> || Início do período principal de vendas e aquisições. || Sim
|-
| <code>P_DATA_FINAL</code> || Fim do período principal. Também determina o mês/ano exibido no extrato e no nome do arquivo. || Sim
|-
| <code>P_ID_EMPRESA</code> || Empresa cujas notas serão consultadas. || Sim
|-
| <code>P_ID_ESPECIE</code> || Uma ou mais espécies de produto consideradas nas consultas. || Sim
|-
| <code>P_VENDAS_COOPERATIVA</code> || <code>1</code> para incluir o total anual de vendas da cooperativa; <code>0</code> para omitir esse bloco. || Sim
|-
| <code>P_VENDAS_COOPERADO</code> || <code>1</code> para incluir o total histórico de vendas de cada cooperado até a data final; <code>0</code> para omitir esse bloco. || Sim
|-
| <code>P_CAMINHO_ARQUIVO_LOCAL</code> || Pasta em que o XML será gravado no servidor do ERP. Se enviada como texto vazio, a rotina usa a pasta temporária do servidor. Para uso regular, informe uma pasta existente. || Não validado como obrigatório
|-
| <code>P_DESCRICAO_ARQUIVO</code> || Texto que aparece em <code>&lt;DESTAQUE&gt;&lt;DESCRICAO&gt;</code> em cada extrato. Não altera o nome do arquivo. || Não validado como obrigatório
|}

Informe um período coerente, com a data inicial anterior ou igual à final. O componente não realiza uma validação específica dessa ordem antes da consulta.

== Quais dados entram no XML ==

=== Vendas do período principal ===

As vendas são obtidas das '''notas fiscais próprias''' da empresa com data de emissão entre <code>P_DATA_INICIAL</code> e <code>P_DATA_FINAL</code>. Entram apenas notas em situação fiscal válida, com itens cujo CFOP esteja marcado como receita de venda e produtos das espécies selecionadas. Notas canceladas e denegadas não entram nessa consulta.

Os valores dos itens são somados por subespécie e por cooperado. Apenas cooperados com vendas nesse período recebem um <code>&lt;EXTRATO&gt;</code>. O total geral de vendas e os totais por linha são repetidos dentro de cada extrato, pois representam os dados consolidados da cooperativa.

=== Aquisições da cooperativa ===

O bloco de aquisições é calculado a partir das '''notas fiscais de terceiros''' da empresa, pela data de entrada no mesmo período e pelas espécies selecionadas. Os valores são agrupados por subespécie. Essa consulta não aplica o filtro de situação fiscal nem o filtro de CFOP usados para as vendas; confira os totais antes de disponibilizar o arquivo.

=== Ranking e notas recentes ===

O ranking atual ordena os cooperados pelo '''valor total dos itens de venda selecionados no período principal''', do maior para o menor. O ranking anterior usa o '''mês calendário imediatamente anterior à data inicial''', mesmo que o período principal tenha mais de um mês. A mobilidade é a posição anterior menos a atual: valor positivo indica subida; valor negativo, queda. Se não houver posição anterior, o XML usa <code>-</code>.

O bloco <code>COMPRAS10NOTAS</code> mostra até dez notas fiscais próprias do cooperado, ordenadas pela data de emissão mais recente, dentre as notas selecionadas no período. O valor mostrado para cada uma é o '''total da nota'''; ele pode ser diferente da soma dos itens das espécies filtradas usada no ranking.

O extrato também mostra o número de matrizes, o valor de compras por matriz, o limite de crédito e a data de admissão quando ela estiver disponível no histórico do cooperado.

=== Totais opcionais ===

{| class="wikitable"
! Opção !! Período usado !! Onde aparece
|-
| <code>P_VENDAS_COOPERATIVA = 1</code> || De 1º de janeiro a 31 de dezembro do '''ano da data final'''. É o ano inteiro, não apenas o intervalo principal nem necessariamente o acumulado até a data final. || <code>VENDASANUAL/VALORVENDASANUAL</code>, quando houver dados.
|-
| <code>P_VENDAS_COOPERADO = 1</code> || Histórico de vendas desde 01/01/1111 até a data final, apenas para cooperados que tiveram vendas no período principal. || <code>VENDASCOOPERADO/VALORVENDASCOOPERADO</code>, quando houver dados.
|}

Os blocos opcionais só são gravados quando o respectivo cálculo retorna dados. Desmarcar essas opções não exclui os totais e rankings do período principal.

== Como executar ==

# Abra '''Executar Smart Component''' no módulo de Business Intelligence e selecione o componente de arquivo XML de vendas da Coosuiponte.
# Informe o período, a empresa e as espécies de produto.
# Defina se deseja incluir o total anual da cooperativa e o total histórico por cooperado.
# Informe uma pasta existente no servidor para o arquivo e, se necessário, o texto de destaque dos extratos.
# Execute o componente e acompanhe a tarefa até a conclusão.
# Baixe o XML e confira a quantidade de extratos, os totais, o ranking, as linhas de produto e os dados dos cooperados antes de entregá-lo ao destino.

O arquivo segue o padrão <code>compra_venda_MM-aaaa.xml</code>, usando o mês e o ano de <code>P_DATA_FINAL</code>. '''Executar novamente para o mesmo mês e na mesma pasta substitui o arquivo anterior.''' Guarde uma cópia se precisar preservar versões anteriores.

== Estrutura do arquivo ==

O XML declara codificação UTF-8, tem a raiz <code>&lt;DOCUMENTO&gt;</code> e contém a identificação da empresa e uma lista de extratos. As tags principais são:

{| class="wikitable"
! Bloco !! Conteúdo
|-
| <code>IDENTIFICACAO</code> || Nome, razão social, endereço, CNPJ, inscrição estadual, título do relatório e cidade/data.
|-
| <code>EXTRATOS/EXTRATO</code> || Um extrato por cooperado com vendas nas condições selecionadas.
|-
| <code>DADOSCOOPERADO</code> || Nome, código do cooperado e mês/ano de referência.
|-
| <code>RANK</code> || Número de matrizes, total de compras, posições atual e anterior, mobilidade, compras por matriz, limite de crédito e admissão.
|-
| <code>COMPRAS10NOTAS</code> || Dia/mês e valor total das até dez notas mais recentes do cooperado.
|-
| <code>COMPRALINHAPORMATRIZ</code> || Valor de compras do cooperado por subespécie e valor por matriz.
|-
| <code>AQUISICAO</code>, <code>VENDAS</code> || Totais gerais da cooperativa no período principal.
|-
| <code>COMPRALINHA</code>, <code>VENDALINHA</code> || Totais da cooperativa por subespécie.
|-
| <code>DESTAQUE</code> || Texto informado em <code>P_DESCRICAO_ARQUIVO</code>.
|-
| <code>VENDASANUAL</code>, <code>VENDASCOOPERADO</code> || Totais opcionais controlados pelos dois parâmetros de vendas.
|}

Exemplo reduzido da hierarquia; os valores são apenas ilustrativos:

<pre>
&lt;DOCUMENTO&gt;
  &lt;IDENTIFICACAO&gt;
    &lt;NOME&gt;Cooperativa exemplo&lt;/NOME&gt;
    &lt;RELATORIO&gt;EXTRATO DE RELACIONAMENTO&lt;/RELATORIO&gt;
  &lt;/IDENTIFICACAO&gt;
  &lt;EXTRATOS&gt;
    &lt;EXTRATO&gt;
      &lt;DADOSCOOPERADO&gt;
        &lt;NOME&gt;Cooperado exemplo&lt;/NOME&gt;
        &lt;CODIGO&gt;123&lt;/CODIGO&gt;
        &lt;MES&gt;Setembro/2026&lt;/MES&gt;
      &lt;/DADOSCOOPERADO&gt;
      &lt;RANK&gt;
        &lt;RANKATUAL&gt;2&lt;/RANKATUAL&gt;
        &lt;RANKANTERIOR&gt;3&lt;/RANKANTERIOR&gt;
        &lt;MOBILIDADE&gt;1&lt;/MOBILIDADE&gt;
      &lt;/RANK&gt;
      &lt;AQUISICAO&gt;&lt;VALORAQUISICAO&gt;1.000,00&lt;/VALORAQUISICAO&gt;&lt;/AQUISICAO&gt;
      &lt;VENDAS&gt;&lt;VALORVENDAS&gt;2.000,00&lt;/VALORVENDAS&gt;&lt;/VENDAS&gt;
    &lt;/EXTRATO&gt;
  &lt;/EXTRATOS&gt;
&lt;/DOCUMENTO&gt;
</pre>

O exemplo omite várias tags obrigatoriamente geradas pelo componente; serve para mostrar a organização do documento. Os valores monetários são formatados com duas casas decimais no padrão brasileiro.

== Integração por API ==

A chamada usa a [[Executar Smart Component#6. Integração por API|API de execução de Smart Components]]. Consulte <code>get-parameters-id/{idSmartComponent}</code> para obter o cadastro e os formatos dos parâmetros da sua instalação. Depois chame <code>execute-smart-component-id/{idSmartComponent}</code> com <code>input: null</code> e as chaves desta página no objeto <code>params</code>.

Para <code>P_ID_ESPECIE</code>, envie identificadores numéricos e confira o formato de seleção múltipla informado pelo cadastro do parâmetro antes de enviar várias espécies. Para as datas, use o formato configurado em <code>classeParametro</code> e validado na sua instalação. Os dois indicadores de vendas usam os textos <code>"0"</code> e <code>"1"</code> no corpo JSON.

Informe <code>P_CAMINHO_ARQUIVO_LOCAL</code> como uma pasta existente no '''servidor do ERP'''. Se quiser usar a pasta temporária, envie a chave com texto vazio; não omita a chave da requisição.

Após o aceite, guarde <code>result.taskId</code>, consulte <code>GET /auth/async-tasks/get-task/{taskId}</code> até <code>COMPLETE</code> e obtenha o XML por <code>GET /auth/async-tasks/get-task-result-resource/{taskId}</code>.

== Solução de problemas ==

{| class="wikitable"
! Sintoma !! O que verificar
|-
| O arquivo não foi gerado || Período, empresa, espécies e existência/permissão de escrita da pasta do servidor.
|-
| O XML não tem extratos || Há cooperados vinculados aos clientes? As notas próprias estão no período, em situação válida, com CFOP de receita de venda e produtos das espécies selecionadas?
|-
| O total de uma nota difere do valor usado no ranking || <code>COMPRAVALOR</code> mostra o total da nota; o ranking soma apenas os itens filtrados das espécies escolhidas.
|-
| O ranking anterior está vazio (<code>-</code>) || O cooperado não teve posição no mês anterior à data inicial.
|-
| O total anual parece maior que o período escolhido || A opção anual consulta todo o ano civil da data final.
|-
| O arquivo anterior desapareceu || Execuções do mesmo mês na mesma pasta reutilizam o nome <code>compra_venda_MM-aaaa.xml</code>.
|-
| Falta o total histórico de um cooperado || O bloco depende de <code>P_VENDAS_COOPERADO = 1</code> e só é calculado para cooperados com vendas no período principal.
|}

''Referência técnica: <code>SCExecArquivoXMLVendasCoosuiponte</code>.''