para Integração por Webservices

Transcrição

1 Documentação para Integração por Webservices EDI Webservices - Compradores Plataforma Bionexo Projeto: Guia de Integração de Sistemas para Compradores (EDI) Preparado por: Saincler Silva Data Criação: 21 de Julho de 2009 Data última modificação: 06 de março de 2017 Número do Documento: Versão: 2.4

2 Índice de Versões Versão Data Autor Revisor Descrição /07/2009 Daniel Rocha Daniel Rocha /06/2010 Daniel Rocha Daniel Rocha /11/2011 Daniel Rocha Daniel Rocha /04/2011 Daniel Rocha Daniel Rocha /12/2012 Danielle Pestana Daniel Rocha /02/2014 Saincler Silva /03/2014 Saincler Silva /04/2014 Glauber Fernando Saincler Silva /11/2014 Carina Nagano Preparo do template e tradução de especificação funcional. Criação de índice de versão, revisão bloco de retorno e parâmetros. Criação da operação WIP e revisão de ortografia. Criação das operações WOP, WMG e WFG, Atualização da operação WAU. Criação das operações WMU e WFU. Atualização das demais operações. Revisão de ortografia. Remoção dos layouts XML descritos. A informação consta apenas nos arquivos XMLs. Atualização do layout WA, novas tags adicionadas: Tipo_Cotacao, Requisicao para o item, id_contrato para reposição por contrato. Adicionado ao layout WD, tags no item para indicar informações de compra das empresas individuais com retorno da requisição do item. Atualização de nomes dos layouts XML, para novo modelo. Atualização do layout dentro dos parâmetros da operação WFU para layout WF /11/2014 Patricia Vicente Esquaiella Saincler Silva Inclusão de Testes Online na documentação, cap /06/2015 Patricia Vicente Esquaiella Saincler Silva Inclusão da tag Descricao_Detalhada no layout WI (xml e xsd) /12/2015 Carina Nagano Saincler Silva Inclusão da observação do parâmetro ID para download automático na operação WEG.

3 Adicionado ponto nas considerações do layout WE. Adicionado ponto nas considerações do layout WD /03/2016 Carina Nagano Ambiente Homolog para o Sandbox /03/2017 Marco Quezada Atualização URLs - Sandbox /03/2017 Saincler Silva Adicionado informações para reposição por contrato e como baixá-los da fila automaticamente.

4 Índice INTRODUÇÃO Objetivo Definição... 6 ESPECIFICAÇÃO TÉCNICA Métodos e Retornos Método POST Método REQUEST Bloco Padrão de Retorno Operações e Parâmetros Operação WAS (post) - Cria Pedido de Cotação (PDC) Direto Operação WASE (post) - Cria Pedido de Cotação (PDC) em Espera Operação WAU (post) - Altera pedido de cotação já publicado, em análise ou confirmado Layout WA Operação WBS (post) - Cria Pedido de Compra (Confirmação de PDC) Operação WBSC (post) - Cria carrinho de compras (pré-pedido) Layout WB Operação WCG (request) - Recupera respostas (itens e cotações) Layout WC Operação WDG (request) - Recupera carrinho de compras (pré-pedido) Layout WD Operação WEG (request) - Recupera pedido de compras (PDC Confirmado) Layout WE Operação WIP (post) - Cadastro e manutenção de produtos Layout WI Operação WMG (request) - Recupera cadastro de fornecedor Operação WMU (post) - Bloqueio de fornecedor Layout WM Operação WFG (request) - Recupera contratos Operação WFU (post) - Atualização de contrato Layout WF Operação WOP (post) - Registra ocorrência para fornecedor Layout WO Reposição de contrato AMBIENTES Homologação... 38

5 6.2. Produção CONVENÇÕES, TERMOS E ABREVIAÇÕES... 39

6 INTRODUÇÃO 1. OBJETIVO Definir tecnologia utilizada para troca eletrônica de informações. Especificar métodos utilizados para a comunicação entre os sistemas envolvidos e identificar possíveis retornos para os métodos consumidos. Apontar e demonstrar operações disponíveis. Definir ambientes para homologação da tecnologia, assim como determinar o ambiente de produção que será utilizado. 2. DEFINIÇÃO A tecnologia a ser utilizada para a integração do sistema local do cliente com a Plataforma Bionexo é baseada em SOAP WebService utilizando métodos e parâmetros a serem invocados pelos protocolos HTTP (porta 80) e HTTPS (porta 443) para a comunicação.

7 ESPECIFICAÇÃO TÉCNICA 3. MÉTODOS E RETORNOS O webservices Bionexo é baseado em serviços para troca de informações síncronas em métodos POST (envio) e REQUEST (resgate). Utiliza protocolo seguro Thawte SSL 256 bits e autenticação de usuários para o consumo dos serviços mediante a invocação de operações. Abaixo, descrição dos métodos e retornos disponíveis para a comunicação com a Plataforma Bionexo. 3.1 Método POST Método genérico para todas as operações de envio (POST). Os parâmetros devem ser passados no formato padrão HTTP ou HTTPS. O arquivo XML de envio pode ser único em uma string ou um objeto DataHandler. Seu retorno é feito por meio de um bloco padrão que varia de acordo com a operação e parâmetros passados, que estarão comentados abaixo. STRING POST (STRING USER, STRING PASSWORD, STRING OPERATION, STRING PARAMETERS, STRING XML) Parâmetros: STRING POST (USER, PASSWORD, STRING OPERATION, STRING PARAMETERS, STRING XML) Exemplo: STRING POST (TESTE,1234,WAS,LAYOUT=WA,<XML FILE/>) 3.2 Método REQUEST Método genérico para todas as operações de busca de informações (GET). Os parâmetros devem ser passados no formato padrão HTTP ou HTTPS. Seu retorno é feito por meio de um bloco padrão que varia de acordo com a operação e parâmetros passados, que estarão comentados abaixo. STRING REQUEST (STRING USER, STRING PASSWORD, STRING OPERATION, STRING PARAMETERS Como montar o método: STRING REQUEST (USER, PASSWORD, STRING OPERATION, STRING PARAMETERS) Exemplo: STRING REQUEST (TESTE,1234,WAS,LAYOUT=WE;TOKEN=1234) 3.3 Bloco Padrão de Retorno O retorno para os métodos consiste em uma string que separa cada valor contido por ponto e vírgula (;) com as seguintes informações: Status: É o sinalizador do resultado para o método que foi invocado. Se o valor for menor que zero, significa que ocorreu algum erro. Se o valor for igual à zero, significa que foi bem processado, porém não foi encontrado nenhum dado. Se o valor for maior que zero, significa que foi bem processado e que os dados foram encontrados. Data e Hora: Data e hora da ocorrência do evento. Mensagem: Varia de acordo com a operação chamada, podendo conter uma ou diversas informações distintas. No caso de erro (status < 0) a mensagem trará sempre um texto de erro (exemplos abaixo) ou exceções do sistema. No caso de nenhum dado encontrado (status = 0), trará um sinal de retorno, porém sem nenhuma informação (vazio) no lugar do XML. Os valores de retorno contidos no campo da mensagem estão descritos junto às operações.

8 Exemplos: 1;12356;<XML/> 1;05/12/ :25:05;<XML/> 0;05/12/ :25:05;NULL 0;12356;NULL -1;05/12/ :25:05;CONNECTION IS CLOSED Erros: -1;05/12/ :25:05;INCORRECT LOGIN/PASSWORD -1;05/12/ :25:05;NÚMERO DE ACESSOS POR MINUTO ULTRAPASSADO -1;05/12/ :25:05;NULL - NULLPOINTEREXCEPTION -1;05/12/ :25:05;CONNECTION IS CLOSED -1;05/12/ :25:05;UNSUPPORTED OPERATION EXCEPTION (tentativa de chamar método não suportado para operação) -1;05/12/ :25:05;OPERATION [WDD] NOT FOUND (quando o parâmetro da operação não foi encontrado) 4. OPERAÇÕES E PARÂMETROS As operações devem ser passadas no momento da invocação do método como uma das strings aceitas pelo serviço. Os parâmetros estão diretamente relacionados às operações. Um método somente pode conter uma operação e uma operação pode ter múltiplos parâmetros. Webservices Bionexo Métodos Operações Parâmetros As operações do webservices Bionexo relativas ao processo de compra são: WAS : Cria pedido de cotação direto; WASE : Cria pedido de cotação em estado de espera; WAU : Altera/Cancela 1 pedido de cotação já publicado, vigente ou confirmado; WCG : Recupera respostas (cotações) efetuadas pelos vendedores; WDG : Recupera carrinho de compra (pré-pedido) montado pelo comprador, após, ou antes, da alçada; WEG : Recupera itens confirmados (pedido de compra); WBS : Envia a confirmação dos itens (cria pedido de compras); WBSC : Cria carrinho de compras; As operações do webservices Bionexo disponíveis para manutenções adicionais são: WIP : Cadastro, atualização e inativação de produto; WMG : Recupera todos os dados cadastrais do fornecedor; WMU : Ativa ou bloqueia fornecedor a responder PDCs; WFG : Recupera contrato gerado na plataforma; WFU : Altera contrato na plataforma; 1 Para PDCs já confirmados, será possível cancelar a confirmação dos itens. Para PDCs em espera, será possível exclui-los.

9 WOP : Cria registro de ocorrência para um fornecedor

10 4.1 Operação WAS (post) - Cria Pedido de Cotação (PDC) Direto Criação de pedido de cotação direto, que é publicado assim que o método e parâmetros são passados Parâmetros Separador: Quando indicados, os parâmetros deverão ser separados por ponto e vírgula (;). Exemplo de envio de múltiplos parâmetros: LAYOUT=WA;XML LAYOUT Determina o layout que os dados (XML) serão enviados WA WA String XML Dados gerados conforme esquema WA Obrigatório - Enviado separadamente schema (upload_pdc_com_contrato_reposicao_wa.xsd) e arquivo exemplo (upload_pdc_com_contrato_reposicao_wa.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; ID do PDC Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;12/12/ :44:47; Operação realizada com sucesso. 0;10/12/ :59:28;null -1;12/12/ :48:20;Incorrect login/password

11 4.2 Operação WASE (post) - Cria Pedido de Cotação (PDC) em Espera Criação de pedido de cotação sem sua publicação imediata. Os pedidos ficarão aguardando validação do comprador e envio ao mercado pela plataforma Parâmetros Separador: Quando indicados, os parâmetros deverão ser separados por ponto e vírgula (;). Exemplo de envio de múltiplos parâmetros: LAYOUT=WA;XML LAYOUT Determina o layout que os dados (XML) serão enviados WA WA String XML Dados gerados conforme esquema WA Obrigatório - Enviado separadamente schema (upload_pdc_com_contrato_reposicao_wa.xsd) e arquivo exemplo (upload_pdc_com_contrato_reposicao_wa.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; ID do PDC Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;12/12/ :55:43; Operação realizada com sucesso. 0;10/12/ :59:28;null -1;12/12/ :48:20;Incorrect login/password

12 4.3 Operação WAU (post) - Altera pedido de cotação já publicado, em análise ou confirmado Alteração do pedido de cotação já publicado, em análise ou confirmado. O layout XML a ser enviado é igual ao do envio do pedido de cotação (layout WA). As alterações possíveis serão regidas pelas seguintes regras: QUANTO À PEDIDO DE COTAÇÃO PUBLICADO PDC já publicado (status Pendente): Pedidos de cotação, assim que publicados, assumem o status de pendente. Durante este momento do processo é possível efetuar alteração do vencimento da cotação, para mais ou para menos da data e horário originais. Porém a nova data e hora deverão ser maiores que a data e horário atual da atualização (ou seja: data de vencimento > sysdate). PDC em análise (status Encerrado): Após o vencimento do pedido de cotação, seu status torna-se encerrado. Durante este momento do processo é possível efetuar a alteração do vencimento da cotação, para mais ou para menos da data e horário originais; também é possível alterar a quantidade e programação de entrega dos itens. A alteração do vencimento deverá considerar data e hora maiores que a data e horário atual da atualização (ou seja: data de vencimento > sysdate). A alteração da quantidade do item e/ou da programação de entrega sempre devem estar condizentes entre o total programado e a quantidade do item (total programado = quantidade). PDC confirmado (status Confirmado): Durante este momento do processo é possível cancelar a confirmação de um item ou alterar a programação de entrega. Para cancelar a confirmação de um item, a quantidade do mesmo deverá ser enviada com ZERO. Assim, a plataforma irá interpretar o cancelamento total da confirmação do item. Para a alteração da programação de entrega, será obrigatório que o total das quantidades programadas seja igual à quantidade confirmada do item. Para PDCs confirmados, não será possível alterar seu vencimento. QUANTO À PEDIDO DE COTAÇÃO EM ESPERA PDC em espera: Pedidos de cotação em espera ficarão aguardando validação do comprador para o posterior envio ao mercado. Enquanto em espera, é possível excluir o PDC da plataforma enviando a quantidade com ZERO de TODOS os itens do PDC Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WA;ID=123456;XML LAYOUT Determina o layout que os dados (XML) serão enviados WA WA String ID Especifica qual ID gerado na Bionexo será afetado Obrigatório

13 Conjunto de números positivos (> 0) Number XML Dados gerados conforme esquema WA Obrigatório - Enviado separadamente schema (upload_pdc_com_contrato_reposicao_wa.xsd) e arquivo exemplo (upload_pdc_com_contrato_reposicao_wa.xml) Retorno Informações a serem respondidas pelo server após a execução do método. Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK = 1, data time e ID do PDC. Quando Status Vazio = 0, data time. Quando Status ERROR = -1, data time e mensagem de erro do sistema. Exemplos = 1;12/12/ :27:08; ;10/12/ :59:28;null -1;12/12/ :08:12;Obrigatório indicar o número do PDC para alterações ou cancelamentos. -1;12/12/ :35:57;A data/horário de vencimento da cotação deve ser posterior a da solicitação -1;12/12/ :36:38;Número de PDC inexistente na Bionexo.

14 4.4 Layout WA O layout WA será adotado como o XML padrão para as operações WAS, WASE e WAU. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações Este schema poderá aceitar dois parâmetros, a saber: LAYOUT e ID. O parâmetro LAYOUT é facultativo para as três operações (WAS, WASE e WAU). O parâmetro ID deverá ser utilizado apenas pela operação WAU. Para este XML será exigido o envio do ID da condição de pagamento da Bionexo. Para tal, faz-se necessário um de/para deste dado no sistema de gestão o cliente entre os códigos utilizados na Bionexo e os códigos utilizados pelo sistema ERP. A relação das condições de pagamento da Bionexo será enviada em complemento a este documento. A tag <requisicao> equivale à solicitação de compra no sistema de gestão. O código do produto contido na tag <codigo> equivale ao código do item no sistema de gestão, que será o mesmo adotado pela Plataforma Bionexo. Serão permitidas, no máximo, 24 (vinte e quatro) programações de entrega por item. A tag <Campo_Extra> deste XML poderá ser utilizada para transmitir dados relevantes ao sistema de gestão do cliente, e poderão ser retornadas na ocasião do resgate do XML de retorno gerado pela Plataforma Bionexo. Poderá ser indicado neste XML o número do contrato gerado previamente na plataforma, a fim de que possa ser gerado um Pedido de Reposição de Contrato. Este dado deverá ser enviado em tag <Campo_Extra>, conforme exemplificado abaixo. Conclui-se, portanto, que estes contratos estejam também armazenados no sistema de gestão, e esta integração poderá ser realizada por webservices através da operação WFG, descrita neste documeto. <Campo_Extra> <Nome>id_contrato</Nome> <Valor>9999</Valor> </Campo_Extra> Poderá ser indicado neste XML o ID do usuário na plataforma, a fim de que o PDC seja criado associado a este usuário, e não ao usuário de webservices. Este dado deverá ser enviado em tag <Campo_Extra>, conforme exemplificado abaixo. A relação dos Ids de usuários na Bionexo será enviada em complemento a este documento. <Campo_Extra> <Nome>cdComprador</Nome> <Valor>99999</Valor> </Campo_Extra>

15 4.5 Operação WBS (post) - Cria Pedido de Compra (Confirmação de PDC) Após o pedido de cotação ter sido gerado no sistema local do cliente, e suas respostas (cotações) efetivadas, o pedido de compra deverá ser enviado ao fornecedor pela plataforma através desta operação Parâmetros Separador: Quando indicados, os parâmetros deverão ser separados por ponto e vírgula (;). Exemplo de envio de múltiplos parâmetros: LAYOUT=WB;ID= ;XML LAYOUT Determina o layout que os dados (XML) serão enviados WB WB String ID Especifica qual ID gerado na Bionexo será afetado. devido o envio de este dado estar contido no arquivo XML. Conjunto de números positivos (> 0) Number XML Dados gerados conforme esquema WB Obrigatório - Enviado separadamente schema (upload_itens_confirmacao_wb.xsd) e arquivo exemplo (upload_itens_confirmacao_wb.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; ID da confirmação Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;12/12/ :35:02; ;10/12/ :59:28;null -1;12/12/ :37:27;Não é possível realizar a confirmação, o PDC não está encerrado. -1;12/12/ :42:10;O produto 348 esta com a quantidade divergente. Quantidade correta é 20.0

16 4.6 Operação WBSC (post) - Cria carrinho de compras (pré-pedido) As respostas (cotações) efetuadas para um pedido de cotação poderão ser resgatadas pelo sistema de gestão do cliente. Num segundo momento, o sistema de gestão poderá, através desta operação, gerar o carrinho de compra na plataforma (pré-pedido), que passará por uma avaliação do comprador, antes do pedido de compra ser confirmado na plataforma Parâmetros Separador: Quando indicados, os parâmetros deverão ser separados por ponto e vírgula (;). Exemplo de envio de múltiplos parâmetros: LAYOUT=WB;ID= ;XML LAYOUT Determina o layout que os dados (XML) serão enviados WB WB String ID Especifica qual ID gerado na Bionexo será afetado. Obrigatório Conjunto de números positivos (> 0) Number XML Dados gerados conforme esquema WB Obrigatório - Enviado separadamente schema (upload_itens_confirmacao_wb.xsd) e arquivo exemplo (upload_itens_confirmacao_wb.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; 0 Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;12/12/ :40:11;0 0;10/12/ :59:28;null -1;12/12/ :39:21;Parâmetro [ID] é obrigatório

17 4.7 Layout WB O layout WB será adotado como o XML padrão para as operações WBS e WBSC. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações Este schema poderá aceitar dois parâmetros, a saber: LAYOUT e ID. O parâmetro LAYOUT é facultativo para as duas operações (WBS e WBSC). O parâmetro ID será obrigatório para a operação WBSC. O envio do CNPJ do fornecedor é obrigatório (tag CNPJ_Fornecedor), bem como do ID do item na Bionexo (tag Id_Artigo). Ambos os dados poderão ser recuperados a partir do resgate do XML gerado pelo plataforma.

18 4.8 Operação WCG (request) - Recupera respostas (itens e cotações) As respostas (cotações) realizadas para um Pedido de Cotação na plataforma poderão ser retornadas para o sistema de gestão a partir desta operação Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WC;ID= ;ISO=1 LAYOUT Determina o layout que os dados (XML) serão enviados WC WC String ID Especifica qual ID gerado na Bionexo corresponde às cotações que serão baixadas Obrigatório Conjunto de números positivos (> 0) Number ISO Determina o tipo de encoding que os dados (XML) serão gerados ISO = 1 (ISO ) ISO = 0 dados em encoding UTF-8 ISO = 1 dados em encoding ISO Number Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; XML Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;12/12/ :37:33;<?xml version="1.0" encoding="iso "?> 0;10/12/ :59:28;null -1;12/12/ :39:21;Connection is closed O XML mencionado acima seguirá o formato enviado separadamente conforme schema download_respostas_com_programacao_entrega_wc.xsd e arquivo de exemplo download_respostas_com_programacao_entrega_wc.xml

19 4.9 Layout WC O layout WC será adotado como o XML padrão para a operação WCG. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações A tag requisicao equivale à solicitação de compra no sistema de gestão, que será retornada neste XML caso o valor tenha sido enviado anteriormente no arquivo layout WA. Neste XML será enviado o ID da condição de pagamento da Bionexo (tag Id_Forma_Pagamento). Para a correta importação deste dado, faz-se necessário um de/para no sistema de gestão do cliente entre os códigos utilizados na Bionexo e os códigos utilizados pelo sistema ERP. A relação das condições de pagamento da Bionexo será enviada em complemento a este documento. O código do produto contido na tag Cod_Produto equivale ao código do item no sistema de gestão, que será o mesmo adotado pela Plataforma Bionexo. A tag Campo_Extra deste XML poderá retornar dados que anteriormente foram enviados à partir do layout WA. Também a partir das tags Campo_Extra, outros dados serão retornados, como a descrição da condição de pagamento escolhida pelo fornecedor, a justificativa de compra feita pelo comprador e a quantidade por embalagem do produto.

20 4.10 Operação WDG (request) - Recupera carrinho de compras (pré-pedido) Após as respostas (cotações) terem sido realizadas para um Pedido de Cotação, o sistema de gestão poderá baixar o carrinho de compras (pré-pedido) montado pelo comprador na plataforma. Para este layout, a equivalência entre fornecedores e itens poderá ser de 1x1 ou de 1xn, a depender Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WD;ID= ;ISO=1 LAYOUT Determina o layout que os dados (XML) serão enviados WD WD String ID Especifica qual ID gerado na Bionexo corresponde ao carrinho que será baixado Conjunto de números positivos (> 0) Number Observação: Quando este parâmetro é enviado, o XML retornado será o equivalente ao PDC indicado. Quando este parâmetro é suprimido, o XML retornado será o equivalente ao PDC que estiver na fila para consumo. Essa fila é alimentada à medida que o usuário comprador monta um carrinho de compra e o sinaliza para download automático. ISO Determina o tipo de encoding que os dados (XML) serão gerados ISO = 1 (ISO ) ISO = 0 dados em encoding UTF-8 ISO = 1 dados em encoding ISO Number Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; XML Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;13/12/ :41:27;<?xml version="1.0" encoding="iso "?> 0;13/12/ :41:54;null -1;13/12/ :42:13;Incorrect login/password

21 O XML mencionado acima seguirá o formato enviado separadamente conforme schema download_carrinho_mais_respostas_com_programacao_entrega_wd.xsd e arquivo de exemplo download_carrinho_mais_respostas_com_programacao_entrega_wd.xml

22 4.11 Layout WD O layout WD será adotado como o XML padrão para a operação WDG. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML. A depender de parametrização para o usuário de webservices do cliente, o XML retornado pela Bionexo poderá conter, para cada item, todas as suas cotações, e não apenas àquela mantida no carrinho de compras. Abaixo, segue exemplo do XML cuja equivalência entre itens e fornecedores é de 1xn Considerações A tag requisicao equivale à solicitação de compra no sistema de gestão, que será retornada neste XML caso o valor tenha sido enviado anteriormente no arquivo layout WA. Neste XML será enviado o ID da condição de pagamento da Bionexo (tag Id_Forma_Pagamento). Para a correta importação deste dado, faz-se necessário um de/para no sistema de gestão do cliente entre os códigos utilizados na Bionexo e os códigos utilizados pelo sistema ERP. A relação das condições de pagamento da Bionexo será enviada em complemento a este documento. O código do produto contido na tag Cod_Produto equivale ao código do item no sistema de gestão, que será o mesmo adotado pela Plataforma Bionexo. A tag Campo_Extra deste XML poderá retornar dados que anteriormente foram enviados à partir do layout WA. Também a partir das tags Campo_Extra, outros dados serão retornados, como a quantidade por embalagem do produto e o ID na Bionexo do comprador quem montou o carrinho. A relação dos IDs de usuários na Bionexo será enviada em complemento a este documento. Para os casos em que cada item poderá ter várias respostas (relacionamento entre itens e fornecedores de 1xn), a tag Campo_Extra servirá para sinalizar se a resposta está ou não selecionada para o carrinho de compras. Caso a operação WDG seja realizada sem o parâmetro ID do pedido (PDC), o sistema de gestão local deve desenvolver uma consulta sem o parâmetro, como um robô que realize esta consulta de tempos em tempos que vai recuperar os pedidos que esta disponível em uma fila para o consumo de cada cliente dependendo do status do pedido. Exemplo de envio sem o parâmetro de ID do pedido: <parameters></parameters>

23 4.12 Operação WEG (request) - Recupera pedido de compras (PDC Confirmado) Após a confirmação do pedido de cotação na plataforma, o pedido de compra poderá ser recuperado por esta operação Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WE;ID= ;ISO=1 LAYOUT Determina o layout que os dados (XML) serão enviados WE WE String ID Especifica qual ID gerado na Bionexo corresponde ao pedido de compra que será recuperado Obrigatório Number Observação: Quando este parâmetro é enviado, o XML retornado será o equivalente ao PDC indicado. Quando este parâmetro é suprimido, o XML retornado será o equivalente ao PDC que estiver na fila para consumo (download automático). Essa fila é alimentada à medida que o usuário comprador confirma os itens do pedido (PDC). ISO Determina o tipo de encoding que os dados (XML) serão gerados ISO = 1 (ISO ) ISO = 0 dados em encoding UTF-8 ISO = 1 dados em encoding ISO Number Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; XML Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;13/12/ :52:34;<?xml version="1.0" encoding="iso "?>

24 0;13/12/ :53:13;null -1;13/12/ :53:33;Parâmetro[ID] é obrigatório. O XML mencionado acima seguirá o formato enviado separadamente conforme schema download_itens_confirmados_com_programacao_entrega_we.xsd e arquivo de exemplo download_itens_confirmados_com_programacao_entrega_we.xml

25 4.13 Layout WE O layout WE será adotado como o XML padrão para a operação WEG. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações A tag requisicao equivale à solicitação de compra no sistema de gestão, que será retornada neste XML caso o valor tenha sido enviado anteriormente no arquivo layout WA. Neste XML será enviado o ID da condição de pagamento da Bionexo (tag Id_Forma_Pagamento). Para a correta importação deste dado, faz-se necessário um de/para no sistema de gestão do cliente entre os códigos utilizados na Bionexo e os códigos utilizados pelo sistema ERP. A relação das condições de pagamento da Bionexo será enviada em complemento a este documento. O código do produto contido na tag Cod_Produto equivale ao código do item no sistema de gestão, que será o mesmo adotado pela Plataforma Bionexo. A tag Campo_Extra deste XML poderá retornar dados que anteriormente foram enviados à partir do layout WA. Também a partir das tags Campo_Extra, outros dados serão retornados, como a justificativa de compra inserida pelo comprador, a quantidade por embalagem do produto e o login na Bionexo do aprovador quem confirmou o pedido de cotação. A relação dos logins de usuários na Bionexo será enviada em complemento a este documento. Caso a operação WEG seja realizada sem o parâmetro ID do pedido (PDC), o sistema de gestão local deve desenvolver uma consulta sem o parâmetro, como um robô que realize esta consulta de tempos em tempos que vai recuperar os pedidos que esta disponível em uma fila para o consumo de cada cliente dependendo do status do pedido. Exemplo de envio sem o parâmetro de ID do pedido: <parameters></parameters>

26 4.14 Operação WIP (post) - Cadastro e manutenção de produtos Essa operação deve ser utilizada para o cadastro de novos produtos ou atualização dos já cadastrados. Para ambas as situações, o XML adotado será o mesmo. O cadastro do novo produto será feito com base nas informações contidas no XML, onde o código será o atributo que o identificará como único. Caso o código (chave) já esteja cadastrado na plataforma, o sistema irá atualizar as demais informações, não sendo permitida a alteração de: Código e Unidade de Medida (sujeito a avaliação) Parâmetros Separador: Quando indicados, os parâmetros deverão ser separados por ponto e vírgula (;). Exemplo de envio de múltiplos parâmetros: LAYOUT=WE;ID= ;ISO=1 LAYOUT Determina o layout que os dados (XML) serão enviados WI WI String XML Dados gerados conforme esquema WI Obrigatório - Enviado separadamente schema (upload_cadastro_produto_marcas_homologadas_wi.xsd) e arquivo exemplo ( upload_cadastro_produto_marcas_homologadas_wi.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; 0 Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;13/12/ :28:21;0 0;13/12/ :53:13;null -1;13/12/ :44:32;Não é possível cadastrar o produto: Código da Categoria inexistente -1;13/12/ :45:03;Não é possível cadastrar o produto: Código da Unidade de Medida inexistente

27 4.15 Layout WI O layout WI será adotado como o XML padrão para a operação WIP. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações do layout WI A tag ativo servirá para ativar (S) ou desativar (N) o produto já cadastrado na plataforma. O código do produto contido na tag Codigo equivale ao código do item no sistema de gestão, que será o mesmo adotado pela Plataforma Bionexo. Este XML contempla o enviado do ID da unidade de medida e o ID da categoria de produtos adotados na Bionexo (tags Id_Unidade_Medida e Id_Categoria, respectivamente). Para tal, faz-se necessário um de/para no sistema de gestão do cliente entre os códigos utilizados na Bionexo e os códigos utilizados pelo sistema ERP. As relações das unidades de medida e categorias da Bionexo serão enviadas em complemento a este documento. A partir da tag Marca_Padrao, as marcas homologadas pelo cliente poderão ser cadastradas, atualizadas ou excluídas na plataforma. Quando a tag Ativo estiver igual a "S", a marca (produto filho) deverá ser inserida (se não existir) ou ter sua descrição atualizada (quando já existir). Quando Ativo estiver igual a "N", a marca (produto filho) deverá ser excluída. Através da operação WIP, poderão ser alterados os seguintes atributos do cadastro de produtos: Status (ativo ou inativo); Nome do Produto, Marca Preferida, Embalagem, Quantidade por Embalagem, Categoria do Produto, Alternativa (S ou N) e a Descrição da Marca Homologada, quando existir. Não poderão ser alterados os seguintes atributos do cadastro de produtos: Código e Unidade de Medida. Este último, em particular, poderá ser permitida a alteração apenas sob a avaliação e aceite do responsável pelo Cadastro de Produtos.

28 4.16 Operação WMG (request) - Recupera cadastro de fornecedor Essa operação deve ser utilizada para recuperar o cadastro de fornecedor(es) quando existir a necessidade de cadastro ou atualização do mesmo no sistema de gestão Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WM;ISO=1; CNPJ= / , / LAYOUT Determina o layout que os dados (XML) serão enviados WM WM String CNPJ Determina qual(is) fornecedor(es) deve(m) ser retornado(s) no XML Obrigatório - O CNPJ indicado poderá ou não estar com máscara de formatação ISO Determina o tipo de encoding que os dados (XML) serão gerados ISO = 1 (ISO ) ISO = 0 dados em encoding UTF-8 ISO = 1 dados em encoding ISO Number Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; XML Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;14/12/ :33:50;<?xml version="1.0" encoding="iso "?> 0;13/12/ :53:13;null -1;14/12/ :51:51;Nenhuma empresa foi encontrada para os CNPJ's informados.

29 4.17 Operação WMU (post) - Bloqueio de fornecedor Essa operação deve ser utilizada para bloquear ou desbloquear o fornecedor ao acesso dos pedidos de cotação do cliente Parâmetros LAYOUT Determina o layout que os dados (XML) serão enviados WM WM String XML Dados gerados conforme esquema WM Obrigatório - Enviado separadamente schema (download_dados_cadastrais_clientes_wm.xsd) e arquivo exemplo (download_dados_cadastrais_clientes_wm.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; mensagem Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;14/12/ :50:04;Operacao realizada com sucesso. 0;13/12/ :53:13;null -1;14/12/ :54:04;Incorrect login/password

30 4.18 Layout WM O layout WM será adotado como o XML padrão para as operações WMG (request) e WMU (post). O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações do layout WM Para a operação WMU, a tag Status é obrigatória (conforme consta no XSD) e poderá assumir dois valores A ou X. Quando A, o fornecedor será desbloqueado ao acesso dos PDCs. Quando X, o fornecedor será bloqueado ao acesso dos PDCs.

31 4.19 Operação WFG (request) - Recupera contratos Essa operação deve ser utilizada para recuperar os contratos cadastrados na plataforma. Essa operação suporta a chamada do método sem enviar parâmetros, sinalizando assim para a plataforma que é desejado receber todos os contatos sinalizados para download automático Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WF;ID=0;TIPO=P;DT_END_SOLICITACAO=31/12/ :00:00 LAYOUT Determina o layout que os dados (XML) serão enviados WF WF String ISO Determina o tipo de encoding que os dados (XML) serão gerados ISO = 1 (ISO ) ISO = 0 dados em encoding UTF-8 ISO = 1 dados em encoding ISO Number CNPJ Determina quais os contratos de um determinado fornecedor devem ser retornados no XML - O CNPJ indicado deverá estar com máscara de formatação DT_BEGIN Filtra os contratos que deverão ser retornados por sua data de vigência inicial Data DD/MM/YYYY HH:MM:SS DT_END Filtra os contratos que deverão ser retornados por sua data de encerramento da vigência Data DD/MM/YYYY HH:MM:SS

32 ID Determina um contrato especifico que deverá ser retornado no XML. Para recuperar todos os contratos cadastrados ou alterados nas últimas 24hrs, deve-se informar ID=0. Para essa condição, os contratos CANCELADOS também serão retornados no XML se estiverem dentro do prazo das 24hs. Maior ou igual a zero Number DT_BEGIN_SOLICITACAO Filtra os contratos que deverão ser retornados por sua data inicial de solicitação Data DD/MM/YYYY HH:MM:SS DT_END_SOLICITACAO Filtra os contratos que deverão ser retornados por sua data final de solicitação Data DD/MM/YYYY HH:MM:SS TIPO Filtra os contratos que deverão ser retornados por seu status C à Aceito pelo Fornecedor/Confirmado X à Cancelado A à Contratado P à Pendente R à Recusado String Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; XML Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;14/12/ :33:50;<?xml version="1.0" encoding="iso "?> 0;13/12/ :53:13;null -1;14/12/ :37:43;Não há contratos cadastrados ou alterados nas últimas 24h -1;14/12/ :38:56;Não há contratos para download automático.

33 4.20 Operação WFU (post) - Atualização de contrato Essa operação deve ser utilizada para atualização de contrato, vigente ou não. Apenas os atributos data de vigência final e status do contrato serão passíveis de edição. Para a data de vigência final do contrato, apenas poderá ser alterada para outro valor igual ou maior à data atual. Para o status do contrato, será permito alterálo para A (para aceita-lo) ou para X (para cancelá-lo) Parâmetros LAYOUT Determina o layout que os dados (XML) serão enviados WF WF String XML Dados gerados conforme esquema WF Obrigatório - Enviado separadamente schema (download_contratos_wf.xsd) e arquivo exemplo (download_contratos_wf.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; mensagem Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;14/12/ :07:38;Contratos atualizados com sucesso 0;13/12/ :53:13;null -1;14/12/ :08:02;Preencha o status do Id contrato: corretamente -1;14/12/ :08:27;Preencha o campo ID_Contrato corretamente -1;14/12/ :10:54;A data de vigência fim do Id contrato: precisa ser igual ou maior que a data atual

34 4.21 Layout WF O layout WF será adotado como o XML padrão para as operações WFG (request) e WFU (post). O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML.

35 4.22 Operação WOP (post) - Registra ocorrência para fornecedor Essa operação deve ser utilizada para registrar ocorrências referente a um fornecedor Parâmetros Separador: Quando mais de um parâmetro for indicado, estes deverão ser separados por ponto e vírgula (;). A ordem do envio dos parâmetros não afeta o resultado final da operação. Exemplo de envio de múltiplos parâmetros: LAYOUT=WO;ID=??? LAYOUT Determina o layout que os dados (XML) serão enviados WO WO String CNPJ Determina qual(is) fornecedor(es) deve(m) ser retornado(s) no XML - O CNPJ indicado poderá ou não estar com máscara de formatação ISO Determina o tipo de encoding que os dados (XML) serão gerados ISO = 1 (ISO ) ISO = 0 dados em encoding UTF-8 ISO = 1 dados em encoding ISO Number XML Dados gerados conforme esquema WO Obrigatório - Enviado separadamente schema (upload_registro_ocorrencia_wo.xsd) e arquivo exemplo (upload_registro_ocorrencia_wo.xml) Retorno Informações a serem respondidas pelo Server após a execução do método: Status = Number (> 0 = OK, = 0 = Vazio, < 0 = ERROR). Mensagem = Quando Status OK : 1; data time; ID do registro de ocorrência Quando Status Vazio : 0; data time Quando Status ERROR : -1; data time; mensagem de erro ou exceção do sistema Exemplos = 1;14/12/ :33:39; ;13/12/ :53:13;null -1;14/12/ :51:51;Nenhuma empresa foi encontrada para os CNPJ's informados.

36 4.23 Layout WO O layout WO será adotado como o XML padrão para as operações WOP. O schema (XSD) deste layout deverá ser enviado separadamente, onde constarão quais os tipos de dados de cada tag (string ou number), sua obrigatoriedade quando houver, bem como a quantidade de ocorrências dentro do XML Considerações do layout WO A tag ID_PDC poderá estar sem conteúdo ou ser utilizada para indicar qual pedido de cotação estará associado ao registro de ocorrência em questão. O CNPJ da tag CNPJ_Fornecedor poderá ou não estar com máscara de formatação. Os valores possíveis para a tag Visao_Ocorrencia são: V (para registros privados) e P (para registros públicos). Obrigatoriamente, os registros de ocorrência deverão ser cadastrados como privados. Os valores possíveis para a tag Id_Tipo_Ocorrencia são: Código Descrição 1 Condição Comercial: Não cumprimento do acordo (preço ou prazo de pagamento), cotação incorreta dos itens confirmados, entre outros aplicáveis. 2 Cancelamento: Cancelamento do pedido parcial ou total sem justificativa. 3 Entrega: atraso, entrega parcial sem justificativa, quantidade em desacordo, horário de entrega fora do estabelecido, avarias em geral. 4 Nota Fiscal: CNPJ incorreto, preço em desacordo, impostos e tributos incorretos, frete em desacordo, entre outros aplicáveis. 5 Preço: Cotação incorreta de itens confirmados 6 Outros: Situações não previstas nas justificativas descritas. 5. REPOSIÇÃO DE CONTRATO Integração Contratos BIOnexo Sistemas ERP s Compradores Necessidade Realizar compras por contrato na BIOnexo através de integração web services Desenvolvimentos/Configurações necessários Utilizar layout WA, operação WAS para reposições automáticas e diretas Layout: upload_pdc_com_contrato_reposicao_wa.xml Informar o id de contrato por item: </Item_Requisicao> <Campo_Extra> <!-- Para realizar reposição por contrato, pode-se enviar o ID_Contrato no momento do upload --> <Nome>id_contrato</Nome> <Valor>28376</Valor> <!-- ID do Contrato pararesposição> </Campo_Extra> </Item_Requisicao>

37 Quando uma única requisição possui itens de contratos distintos e/ou itens que não possuem contrato (itens para cotação), ao publicar na plataforma, é gerado mais de um ID_PDC para a mesma requisição. Desta forma, é gerado um ID para cada contrato que possuía itens para reposição e outro os itens que não possuemcontratos (itens que foram para cotação). Exemplo: Imagem da operação WASE cenário itens com e sem contrato: Quando ocorre multiplicação dos PDCs para a mesma requisição, o sistema local (Comprador), não consegue resgatar todos os PDCs criados nas operações WEG (retorno dos itens confirmados) ou WDG (download de carrinho), pois é retornado apenas um ID PDC para o sistema local (comprador), não sendo os demais IDs PDCs referenciados na requisição do sistema local (comprador). Com a utilização desta forma de consumo pelo ERP, na Bionexo, para todos os PDCs que se encontram nos cenários de: Download de carrinho, operação (WDG), Download de itens confirmados operação (WEG) e Download de respostas operação (WCG), os pedidos são enviados para uma FILA, onde deverá aguardar seu consumo sem o envio do parâmetro ID_PDC. Para utilizar o modelo sugerido acima, o sistema local comprador deverá habilitar uma consulta automática dos pedidos de cotações disponibilizados em um dos fluxos citados acima: download de carrinho ou download de respostas ou download de itens confirmados. Esta automação deverá consumir de tempo em tempo os pedidos de cotações, sem passar o parâmetro de consulta ID_PDC. a. Operação WEG (request) Recupera pedido de compras (PDC Confirmado) b. Utilizar operação WFG layout WF para baixar os contratos válidados na plataforma para atender a necessidade do ponto anterior Layout: download_contratos_wf.xml

38 6. AMBIENTES 6.1 Homologação Ambiente com acesso restrito, somente utilizado para homologação do desenvolvimento efetuado, com prazo de utilização previamente acordado. Ambiente utilizado também para homologar pacotes de desenvolvimento interno, que poderá ter indisponibilidade ou instabilidade momentânea. O usuário e senha para acesso a este ambiente será enviado separadamente após todos os trâmites comerciais serem cumpridos. URL (SSL) WSDL (SSL) : : URL WSDL : : Testes Online : Produção Ambiente com acesso restrito e somente disponibilizado após homologação ser aceita e documentada por ambas as partes. Ambiente real de alta disponibilidade. Toda e qualquer informação imputada nele é de total responsabilidade de seu autor. O usuário e senha para acesso a este ambiente será passado separadamente após homologação efetuada e os trâmites comerciais serem cumpridos. URL (SSL) WSDL (SSL) : :

39 7. CONVENÇÕES, TERMOS E ABREVIAÇÕES Termo EDI HTTP HTTPS PDC Pedido de Compra Pedido de Cotação Pré-Pedido SOAP WSDL XML XSD Descrição Electronic Data Interchange Hypertext Transfer Protocol HyperText Transfer Protocol Secure Pedido de Cotação Pedido de cotação já confirmado na Plataforma Bionexo. Geralmente, equivale à Ordem de Compra no sistema de gestão do cliente Objeto que representa um pedido para a solicitação de cotação pelos fornecedores Nome comumente adotado pelo sistema de gestão do cliente para representar uma intenção de compra. Equivalente ao carrinho de compra na Plataforma Bionexo Simple Object Access Protocol WebServices Description Language Extensible Markup Language XML Schema Definition