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.

Para que serve

O recurso gera um arquivo XML com um <EXTRATO> 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.

Chave	O que informar	Exigido pelo componente
`P_DATA_INICIAL`	Início do período principal de vendas e aquisições.	Sim
`P_DATA_FINAL`	Fim do período principal. Também determina o mês/ano exibido no extrato e no nome do arquivo.	Sim
`P_ID_EMPRESA`	Empresa cujas notas serão consultadas.	Sim
`P_ID_ESPECIE`	Uma ou mais espécies de produto consideradas nas consultas.	Sim
`P_VENDAS_COOPERATIVA`	`1` para incluir o total anual de vendas da cooperativa; `0` para omitir esse bloco.	Sim
`P_VENDAS_COOPERADO`	`1` para incluir o total histórico de vendas de cada cooperado até a data final; `0` para omitir esse bloco.	Sim
`P_CAMINHO_ARQUIVO_LOCAL`	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
`P_DESCRICAO_ARQUIVO`	Texto que aparece em `<DESTAQUE><DESCRICAO>` 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 P_DATA_INICIAL e P_DATA_FINAL. 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 <EXTRATO>. 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 -.

O bloco COMPRAS10NOTAS 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

Opção	Período usado	Onde aparece
`P_VENDAS_COOPERATIVA = 1`	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.	`VENDASANUAL/VALORVENDASANUAL`, quando houver dados.
`P_VENDAS_COOPERADO = 1`	Histórico de vendas desde 01/01/1111 até a data final, apenas para cooperados que tiveram vendas no período principal.	`VENDASCOOPERADO/VALORVENDASCOOPERADO`, 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 compra_venda_MM-aaaa.xml, usando o mês e o ano de P_DATA_FINAL. 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 <DOCUMENTO> e contém a identificação da empresa e uma lista de extratos. As tags principais são:

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

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

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

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 API de execução de Smart Components. Consulte get-parameters-id/{idSmartComponent} para obter o cadastro e os formatos dos parâmetros da sua instalação. Depois chame execute-smart-component-id/{idSmartComponent} com input: null e as chaves desta página no objeto params.

Para P_ID_ESPECIE, 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 classeParametro e validado na sua instalação. Os dois indicadores de vendas usam os textos "0" e "1" no corpo JSON.

Informe P_CAMINHO_ARQUIVO_LOCAL 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 result.taskId, consulte GET /auth/async-tasks/get-task/{taskId} até COMPLETE e obtenha o XML por GET /auth/async-tasks/get-task-result-resource/{taskId}.

Solução de problemas

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	`COMPRAVALOR` mostra o total da nota; o ranking soma apenas os itens filtrados das espécies escolhidas.
O ranking anterior está vazio (`-`)	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 `compra_venda_MM-aaaa.xml`.
Falta o total histórico de um cooperado	O bloco depende de `P_VENDAS_COOPERADO = 1` e só é calculado para cooperados com vendas no período principal.

Referência técnica: SCExecArquivoXMLVendasCoosuiponte.

Smart Component Execucao/Geracao Arquivo XML Vendas