Manual de Instruções para Implementar o Formulário de Inclusão de Pedidos via
Webservice – Projeto Carvalhaes
1.
Histórico de atualização
Versão Data Alteração Responsável
1.0 22/01/2013 Criação do documento Tércio Rodrigues 1.1 23/01/2013 Revisão Final e Aprovação Anderson Martins
1.2 24/01/2013
Alteração da documentação: substituição da
obrigatoriedade do campo C5_XMSGVEN que foi substituído pelo campo C5_XFATURA; inclusão dos seguintes campos na documentação: C5_TIPLIB, C5_TRANSP, C5_TPFRETE,
C6_PEDCLIeC6_CLASFIS.Demaisitensmantidosinalterados.
Ricardo Panaggio
1.3 24/01/2013 Revisão da versão 1.2 da documentação e Aprovação Anderson Martins
2.
Objetivo
Este documento tem por finalidade dar informações técnicas sobre como implementar o formulário web de inclusão de pedidos via sistema e webservices a fim de atender o Contrato de Prestação de Serviços 122/2012, bem como serve de instrumento de instrução aos analistas responsáveis pela implementação de sistemas da Carvalhaes para que possam tratar os códigos e mensagens de retorno do sistema/webservices.
3.
Produtos afetados
Não se aplica.
4.
Padrão dos campos do formulário de “Inclusão de Pedidos”
Para que a integração com o webservice possa ser efetivada e que através deste possa haver a inclusão de pedidos no Protheus, a nomenclatura dos campos do formulário web de “Inclusão de Pedidos” devem ser as seguintes:
Para o cabeçalho do pedido: Nome do
campo Descrição Obrigatório?
C5_TIPO Tipo do Pedido (Padrão: “N” = Normal) Sim
C5_CLIENTE Código do Cliente no Protheus Sim
Nome do
campo Descrição Obrigatório?
C5_Q_NOMEC Razão Social do Cliente Não
C5_CONDPAG Código da Condição de Pagamento do Protheus Sim C5_TABELA Tabela de Preço Praticada (Padrão Protheus) Sim C5_VEND1 Código do Vendedor (Verificar com a Carvalhaes que Código de Vendedor usar) Sim C5_XFATURA Informa se o pedido será faturado (S=Sim; N=Não) Sim C5_FILIAL Código da Filial do Protheus em que serão inseridos os dados Sim C5_CLIENT Código do Cliente para o qual será realizada a Entrega (se aplicável) Não C5_LOJAENT Código da Loja do Cliente para o qual será realizada a Entrega (se aplicável) Não C5_TIPOCLI Código do Tipo do Cliente (conforme constar no cadastro do Cliente) Sim C5_MENNOTA Mensagem que aparecerá na Nota Fiscal (cuidado com o uso deste campo) Não PAGE_THANKS Nome da página para a qual o sistema retornará após processamento dos dados Não C5_TIPLIB Critério de liberação do pedido (1=Libera por itens;2=Libera por pedido de venda) Sim C5_TRANSP Código de identificação da Transportadora Sim C5_TPFRETE Código do tipo de frete (C=CIF; F=FOB; T=Por conta de Terceiros; S=Sem frete) Sim
Para cada item do pedido: Nome do
campo Descrição Obrigatório?
C6_FILIAL Código da Filial do Protheus em que serão inseridos os dados Sim C6_ITEM Número do item (número inteiro ou varchar) Sim
C6_PRODUTO Código do Produto no Protheus Sim
C6_UM Unidade de Medida Primária (conforme o cadastro do produto no Protheus) Sim C6_QTDVEN Quantidade (referente a Unidade de Medida Primária) Sim C6_PRUNIT Preço unitário do Produto (conforme tabela genérica ou a tabela praticada) Sim C6_PRCVEN Preço de Venda do Produto (o preço que foi realmente praticado na venda) Sim C6_VALOR Valor Total do Item (Cálculo: C6_QTDVEN x C6_PRCVEN) Sim C6_SEGUM Unidade de Medida Secundária (conforme o cadastro do produto no Protheus) Sim C6_UNSVEN Quantidade (referente a Unidade de Medida Secundária) Sim C6_DESCRI Descrição do Item do Pedido (nome real do produto) Não C6_TES Código da TES relacionado ao item (ver regras pré-estabelecidas pelo Protheus) Sim
Nome do
campo Descrição Obrigatório?
C6_CLASFIS Classificação Fiscal do Produto Sim
Observações:
O campo “PAGE_THANKS” não é obrigatório. Contudo, se informado, deve ser um campo do tipo “hidden” e o seu valor deve estar no seguinte formato: http://dominio/page.xxx onde:
• http://: é obrigatório informar o tipo de protocolo, a saber: http:// ou https://.
• dominio: o domínio do produto com ou sem www. Exemplo: www.carvalhaes.net ou carvalhaes.net.
• page.xxx: página com qualquer nome e extensão que tratará os parâmetros repassados pelo sistema.
Importante: Caso não seja informado nenhum valor no campo “PAGE_THANKS” o sistema fará o retorno de dados para a página do formulário que originou a requisição.
5.
Submetendo os dados do formulário para os sistemas e webservices da RedeNet
O formulário deverá ser submetido para o endereço eletrônico: http://ws.portalsiga.com.br/carvalhaes.pedido.apw Todos os dados do formulário devem ser submetidos via método POST. Todas as requisições via GET são ignoradas por padrão.
Após o processamento de dados pelos sistemas e webservices da RedeNet e da Carvalhaes, serão retornados parâmetros ao serviço requisitante que conterão informações sobre o sucesso ou insucesso da operação, conforme tratado a seguir.
6.
Tratando o retorno do sistema no seu website
Após o processamento dos dados enviados via formulário de inclusão de pedidos, o sistema retornará de imediato e via POST dois parâmetros básicos que conterão o status de sucesso ou insucesso da transação, além de uma mensagem que especificará eventuais erros encontrados durante o processamento de dados. Caso haja sucesso na transmissão dos dados, esta mensagem conterá única e exclusivamente o código do processamento (número real ou provisório do pedido).
O sistema fará o retorno desses dados para a página do formulário que originou a requisição, caso não seja informado nenhum valor no campo “PAGE_THANKS”, conforme já detalhado nas observações do item 4. Padrão dos campos do formulário de “Inclusão de Pedidos”.
Os parâmetros de retorno do sistema estão mais bem detalhados na tabela a seguir.
Parâmetro Descrição
stt
Parâmetro que informa o status da transação.
Os únicos valores possíveis para esta variável são 0 (zero) e 1 (um). Se o valor retornado for igual a 1 (um) a operação foi realizada com sucesso, se for igual a 0 (zero) é porque houve algum erro durante o processo.
msg
Se o valor da variável “stt” for igual a 1 (um), esta variável conterá o código do processamento (número real ou provisório do pedido).
Se o valor da variável “stt” for igual a 0 (zero), esta variável conterá uma mensagem de erro amigável, informando ao usuário qual o problema que foi encontrado durante o
processamento dos dados. Recomendamos que esta mensagem de erro sempre seja mostrada para o usuário final, mas isto não é obrigatório e o desenvolvedor do sistema poderá decidir por mostrá-la ou ocultá-la a seus usuários.
Alguns exemplos de retorno do sistema:
Exemplo 1: Pedido incluído com sucesso, mas não transmitido on-line
URL: http://www.carvalhaes.net/br/pedidos?stt=1&msg=PVNE0ZIAA5WZ8V3K
Valor do Parâmetro “stt”: 1
Valor do Parâmetro “msg”: PVNE0ZIAA5WZ8V3K
Significado: O pedido foi criado com sucesso, mas não foi possível transmiti-lo on-line ao Protheus. O número provisório do mesmo é #PVNE0ZIAA5WZ8V3K. Um número de pedido de venda provisório sempre começará com a sigla “PVNE” e terá sempre 15 caracteres ou mais.
Exemplo 2: Pedido incluído com sucesso e transmitido on-line (em real-time)
URL: http://www.carvalhaes.net/br/pedidos?stt=1&msg=687632
Valor do Parâmetro “stt”: 1 Valor do Parâmetro “msg”: 687632
Significado: O pedido foi criado com sucesso e incluso em real time no Protheus. O número do mesmo é #687632. Exemplo 3: Problemas ao incluir o pedido no sistema
URL: http://www.carvalhaes.net/br/pedidos?stt=0&msg=H%C3%A1%20um%20ou%20mais%20dados%20incon sistententes%20em%20seu%20pedido,%20por%20favor,%20verifique%20os%20campos:%20quantidad e%20e%20condi%C3%A7%C3%A3o%20de%20pagamento. Valor do Parâmetro “stt”: 0 Valor do Parâmetro “msg”: H%C3%A1%20um%20ou%20mais%20dados%20inconsistententes%20em%20seu%20pedido,%20por%20favor ,%20verifique%20os%20campos:%20quantidade%20e%20condi%C3%A7%C3%A3o%20de%20pagamento.
Significado: Não foi possível incluir o pedido no sistema, pois segundo a mensagem de erro: “Há um ou mais dados inconsistentes em seu pedido, por favor, verifique os campos: quantidade e condição de pagamento.”.
Exemplo 4: Problemas ao incluir o pedido no sistema devido a uma indisponibilidade temporária do sistema
URL: http://www.carvalhaes.net/br/pedidos?stt=1&msg=Houve%20um%20erro%20ao%20processar%20os% 20dados%20devido%20a%20uma%20falha%20tempor%C3%A1ria%20em%20nossos%20sistemas.%20Por%20 favor,%20tente%20novamente%20mais%20tarde. Valor do Parâmetro “stt”: 0 Valor do Parâmetro “msg”: Houve%20um%20erro%20ao%20processar%20os%20dados%20devido%20a%20uma%20falha%20temporária %20em%20nossos%20sistemas.%20Por%20favor,%20tente%20novamente%20mais%20tarde.
dados devido a uma falha temporária em nossos sistemas. Por favor, tente novamente mais tarde.”.
Observações: Nos exemplos acima, tratamos os retornos em método GET com finalidade de mostrarmos os parâmetros de retornos de forma mais didática. Contudo, lembramos que o sistema sempre retornará dados via POST.
