Objetivo
Este documento tem como objetivo explicar o funcionamento da API de Retorno de Vendas
Pré-Requisitos e Restrições
- Necessário a instalação do serviço winthor-venda. Para realizar a instalação desse serviço, segue link com as devidas explicações:
Comece por aqui -> Parametrizações WTA
POST /winthor/venda/v0/status-venda/list?page=1&pagesize=10
A API de Retorno de Vendas executa os seguintes passos em sua execução:
- Consulta o cabeçalho de venda através da VIEW VW_API_RET_STATUS_VENDA_CAB
- Consulta o cabeçalho de venda através da VIEW VW_API_RET_STATUS_VENDA_ITEM
Exemplos de funcionamento da API:
Descrição de campos de cabeçalho de venda:
Body Response
dataPedido = Data de inclusão do pedido idMovimentacao = ID de movimentação codigoCliente = Código do cliente no Winthor codigoFilial = Código da filial codigoFilialNf = Código da filial virtual importado = Situação do pedido em código. 1 = Não importado / 2 = Importado com sucesso / 3 = Rejeitado / 4 = Em processamento / 9 = Cancelado pela importação observacaoPc = Observações de processamento do pedido numeroPedidoRca = Número do pedido no FV atendido = Indica se o pedido foi atendido total ou parcialmente codigoRca = Código do vendedor dataAberturaPedidoRca = Data da abertura do PALM no FV dataFechamentoPedidoRca = Data de fechamento do PALM no FV numeroPedido = Número do pedido no Winthor codigoCobranca = Código da cobrança codigoPlanoPagamento = Código do plano de pagamento valorAtendido = Valor atendido do pedido no Winthor dataLiberacaoPedido = Data de liberação do pedido posicaoPedido = Posição do pedido dentro do Winthor. L = Liberado / P = Pendente / B = Bloqueado / M = Montado / F = Faturado / C = Cancelado numeroCarregamento = Número do carregamento do pedido dataCancelamento = Data de cancelamento dataFaturamento = Data de faturamento dataEntrega = Data prevista de entrega numeroNota = Número da nota fiscal numeroTransacao = Número da transação de venda chaveNfe = Chave da nota fiscal serieNfe = Série da nota fiscal dataSaidaNfe = Data de saída da nota fiscal idFv = Campo que identifica o pedido do força de vendas
Descrição de campos de itens de venda:
Body Response
situacaoImportacaoPedido = Indica a situação atual do pedido em texto. 1 = Não importado / 2 = Importado com sucesso / 3 = Pedido rejeitado / 4 = Em processamento / 9 = Cancelado pela importação numeroPedidoRca = Número do pedido no FV codigoRca = Código do vendedor dataAberturaPedidoRca = Data da inclusão do pedido no FV importado = Indica a situação atual do pedido em código, conforme campo situacaoImportacaoPedido observacaoPc = Observações do processamento do pedido numeroPedido = Número do pedido no Winthor codigoProduto = Código do produto no Winthor precoVenda = Preço de venda do produto precoTabela = Preço de tabela do produto precoBaseMovContaCorrente = Preço base para conta corrente do RCA percentualDesconto = Percentual de desconto do item codigoFilial = Código da filial codigoFilialNf = Código da filial virtual codigoFilialRetira = Código da filial retira numeroSequencia = Sequencial do item dentro do pedido descricaoProduto = Descrição do produto no Winthor ncm = Código NCM do produto codAuxiliar = Código de barras situacaoImportacaoItem = Situação atual do item dentro do pedido. Sem importação = Ainda não foi importado / Sem itens importados = Pedido já importado, mas o item foi cortado na Integração / Total = Quantidade total atendida / Parcial = Quantidade parcial atendida posicaoItem = Posição do item dentro do Winthor. L = Liberado / P = Pendente / B = Bloqueado / M = Montado / F = Faturado / C = Cancelado quantidadeOriginalPedida = Quantidade solicitada pelo FV quantidadeImportada = Quantidade importada pelo Winthor tipoDescontoItem = Tipo da campanha de desconto dataCancelamento = Data do cancelamento do pedido motivoCancelamento = Motivo do cancelamento do pedido idFv = Campo que identifica o pedido do força de vendas
Exemplo do envio da requisição:
Body Request
method: 'POST'
url: '/winthor/venda/v0/status-venda/list?page=1&pagesize=10'
Exemplo de JSON de request:
{
"numPedRca": "575",
"dataAberturaPedidoRca": "2023-12-14",
"dataFechamentoPedidoRca": "2024-12-14",
"codigoRca": "1",
"codCliente": 10,
"importado": 2,
"posicaoPedido": "L",
"codFilial": "2",
"idFv": "01234567890987654321"
}
A API de Retorno de Vendas requer que as requisições sigam um das regras abaixo:
- Devem ser enviados os campos numPedRca e codigoRca no body da requisição
- Devem ser enviados os campos codigoRca, dataAberturaPedidoRca e dataFechamentoPedidoRca no body da requisição
- Deve ser enviado o campo idFv no body da requisição
As requisições podem ser enviadas usando uma das regras, e opcionalmente os demais campos contidos no JSON de exemplo acima
Caso o Json da requisição não atenda uma das regras acima, a API retornara o status code 400(Bad Request) com a mensagem:
Body Response
"Caso os parâmetros numPedRca e codigoRca não forem enviados, os parâmetros codigoRca, dataAberturaPedidoRca e dataFechamentoPedidoRca são obrigatórios caso não forem enviados, o parâmetro idFv deve ser enviado no body da requisição"
Exemplo JSON de resposta de consulta realizada com sucesso:
Body Response
{
"first": false,
"items": [
{
"dataPedido": "2024-05-09T15:30:00",
"idMovimentacao": 12345,
"codigoCliente": 67890,
"codigoFilial": "001",
"codigoFilialNf": "002",
"importado": 1,
"observacaoPc": "OBS 123",
"numeroPedidoRca": 1234,
"atendido": "Sim",
"codigoRca": 987,
"dataAberturaPedidoRca": "2024-05-08T09:00:00",
"dataFechamentoPedidoRca": "2024-05-08T18:00:00",
"numeroPedido": 4321,
"codigoCobranca": "1",
"codigoPlanoPagamento": 5,
"valorAtendido": 1500.75,
"dataLiberacaoPedido": "2024-05-09T10:00:00",
"posicaoPedido": "L",
"numeroCarregamento": "123",
"dataCancelamento": "2024-05-09T10:00:00",
"dataFaturamento": "2024-05-09T14:00:00",
"dataEntrega": "2024-05-10T08:00:00",
"numeroNota": "123",
"numeroTransacao": "123",
"chaveNfe": "123",
"serieNfe": "123",
"dataSaidaNfe": "2024-05-09T14:30:00",
"idFv": "01234567890987654321",
"items": [
{
"situacaoImportacaoPedido": "2",
"numeroPedidoRca": 1234,
"codigoRca": 987,
"dataAberturaPedidoRca": "2024-05-08T09:00:00",
"importado": 1,
"observacaoPc": "OBS 123",
"numeroPedido": 4321,
"codigoProduto": 1001,
"precoVenda": 500.25,
"precoTabela": 550.00,
"precoBaseMovContaCorrente": 500.25,
"percentualDesconto": 10.0,
"codigoFilial": "001",
"codigoFilialNf": "002",
"codigoFilialRetira": "003",
"numeroSequencia": 1,
"descricaoProduto": "Produto A",
"ncm": "12345678",
"codAuxiliar": 1,
"situacaoImportacaoItem": "Sem importação",
"posicaoItem": "L",
"quantidadeOriginalPedida": 10,
"quantidadeImportada": 10,
"tipoDescontoItem": "Promocional",
"dataCancelamento": null,
"motivoCancelamento": "",
"idFv": "01234567890987654321"
}
]
}
],
"hasNext": false
}
Caso a API não encontre dados conforme os filtros enviados no body da requisição, será retornado o status code 404 com a seguinte mensagem:
Body Response
"Status da venda não encontrado para os filtros informados"
Caso algum campo esteja fora de conformidade com relação a tipo, a API retornará um status code 400 (Bad Request) informando que houve um erro na requisição.
Exemplo JSON da resposta de erro de requisição com campos inválidos,
Body Response
{
"code": "UNK-ERR",
"message": "Erro de Requisição",
"detailedMessage": "Erro ao consultar status de venda",
"details": []
}
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas