MANUAL DE INTEGRAÇÃO. Padrão de envio e recebimento de dados. Contato suporte@gtplan.com.br

Transcrição

1 MANUAL DE INTEGRAÇÃO Padrão de envio e recebimento de dados Contato suporte@gtplan.com.br

2 Índice Introdução... 2 Garantia de Funcionamento... 2 Envio de dados pelo cliente... 2 Layouts de integração... 2 Especificação dos Campos dos layouts... 3 Tratamentos Específicos... 9 Cadastro de itens... 9 de Compra... 9 Solicitações de compra... 9 Envio dos dados Dados de conexão Funções WebService Descrição dos parâmetros Retorno Recebimento de dados pelo cliente Passo a passo Informações Web service Dados de conexão Funções WebService Detalhamento da Requisição Exemplo: Detalhamento da Resposta Exemplo: Parâmetro cabeçalho Exemplo: Parâmetro itens... 15

3 Introdução O documento a seguir tem objetivo especificar os layouts de envio de dados para o PLANNEXO assim como a devolução da solicitação de compra gerada pela ferramenta Modelo de Integração dos dados O Plannexo disponibiliza um modelo de integração de dados baseado em webservice em um servidor in cloud. O cliente deverá enviar os dados através de um layout pré-determinado. Garantia de Funcionamento Para o correto funcionamento da ferramenta, é indispensável que a equipe de infraestrutura do hospital garanta a confiabilidade dos dados e o envio das informações nas frequências pré-determinadas negociadas entre as partes. Envio de dados pelo cliente Layouts de integração Constam abaixo os layouts necessários de integração para seu correto funcionamento Layouts Obrigatórios ERP_SKU o Layout disponibiliza a base cadastral de Item x Estabelecimento ERP_INVENTORY o Saldo em estoque do item por local de estoque ERP_TRANSACTION_OUT_DAY o As movimentações de consumo agrupadas por dia são utilizadas para composição do cálculo estatístico o Carga inicial de 180 dias de histórico o Deverão ser incluídos no layout apenas as movimentações que são consideradas como consumo (Padrão: Saídas Paciente+Setor, Devoluções Paciente+Setor). (ver Questionário Inicial de Negócios tópico Regras de consumo) Layout Não Obrigatórios - Altamente recomendáveis ERP_PURCHASE_ORDER o Ordens de compra em aberto o O layout deve incluir informações de x Item x Parcelas ERP_PURCHASE_REQ o Solicitações de compra em Aberto o O layout deve incluir informações de Solicitação x Item x Parcelas ERP_TRANSACTION_OUT_MONTH o Movimentações de consumo agrupadas por mês o Utilizadas para composição do cálculo estatístico de longo prazo.

4 o o Carga inicial de 3 anos de histórico. Isso permite análise de sazonalidade e aumenta a acuracidade da previsão estatística Deverão ser incluídos no layout apenas as movimentações que são consideradas como consumo (Padrão: Saídas Paciente+Setor, Devoluções Paciente+Setor). (ver Questionário Inicial de Negócios tópico Regras de consumo) Layouts Não obrigatórios ERP_TRANSACTION_IN o Movimentações de entrada o O layout deve incluir registros de 180 dias de histórico o Utilizado para como indicadores ao usuário ERP_INVENTORY_REQ_CIR o Cronograma Futuro de cirurgias o Utilizado para integrar em previsões estatísticas ERP_SUPPLIER o Cadastro de Fornecedores o Descrição do Fornecedor, Nome de Contato, para utilização em indicadores e followup ERP_LOCAL o Cadastro de Locais de estoque o Integração necessária caso haja necessidade de exibição de descrição Especificação dos Campos dos layouts O envio de dados difere para cada layout de integração. Dependendo da função chamada do servidor, ela vai aceitar dados diferentes com parâmetros diferentes, ou seja, uma função usará campos diferentes de uma função DELETE. Funções DELETE utilizam-se apenas das chaves primárias de cada tabela de integração, enquanto as funções do tipo utilizam-se de todos os campos do layout. Segue abaixo a especificação dos layouts *Obs: Todos os campos de data devem ser enviados como string no formato DDMMYYYY. **Obs: O campo ID_WES, que está presente em todas as tabelas de integração, é o número retornado pelo webservice em caso de erro ou sucesso de integração. ERP_SKU ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 Y INTEGER /DELETE COD_ITEM_PK 3 2 N VARCHAR2 (255 Byte) Código do Item /DELETE COD_ESTAB_PK 4 3 N VARCHAR2 (255 Byte) Código do estabelecimento /DELETE DESC_ITEM 5 Y VARCHAR2 (255 Byte) Descrição do Item DESC_ESTAB 6 Y VARCHAR2 (255 Byte) Descrição do Estabelecimento

5 VAL_UNIT_SKU 7 N FLOAT (126) Valor unitário do item QTY_LAST_ARR 8 Y FLOAT (126) Quantidade da última entrada (deve ser convertido para unidade padrão do item) VAL_LAST_ARR 9 Y FLOAT (126) Valor da última entrada DATE_LAST_ARR 10 Y DATE* Data da última entrada CURVE_ABC 11 N CHAR (1 Byte) CURVE_XYZ 12 N CHAR (1 Byte) Curva ABC do ERP (Utilizar C caso não exista) Curva XYZ do ERP (utilizar X caso não exista) QTY_MAX 13 Y FLOAT (126) Máximo cadastrado no ERP QTY_MIN 14 Y FLOAT (126) Mínimo Cadastro no ERP QTY_PP 15 Y FLOAT (126) Ponto de pedido cadastrado no ERP QTY_AVG_CONS 16 Y FLOAT (126) Consumo Médio cadastrado no ERP YN_SKU_ACTIVE 17 N CHAR (1 Byte) Item Ativo? Y (sim) / N (Não) COD_STD_UNIT 18 N VARCHAR2 (30 Byte) Código da unidade padrão do item DESC_STD_UNIT 19 N VARCHAR2 (255 Byte) Descrição da unidade padrão do item DATE_ADDED 20 N DATE* Data adicionado no ERP YN_PARENT 21 N CHAR (1 Byte) COD_ITEM_PARENT 22 Y VARCHAR2 (255 Byte) COD_ITEM_RANK 23 Y INTEGER Item Mestre? Y (sim) / N (Não). Se não houver controle utilizar 'N' Item Mestre caso seja item filho (Pode ser nulo) Caso seja item filho, ranking de importância (Se não existir o controle utilizar 1) COD_GROUP1 24 N VARCHAR2 (255 Byte) Reservado. Utilizar '#' COD_GROUP2 25 N VARCHAR2 (255 Byte) COD_GROUP3 26 N VARCHAR2 (255 Byte) Código da Espécie do Material ou equivalente (Por exemplo: 1- Medicamentos / 2-Materiais / 3- Diversos). É a categoria mais abrangente do ERP Código da Classe do material ou equivalente. Possui um nível de detalhamento maior que a espécie. Muitas vezes é estruturada de maneira hierárquica no ERP. Nesse caso, devemos concatenar o código EX: 1->11 COD_GROUP4 27 N VARCHAR2 (255 Byte) COD_GROUP5 28 N VARCHAR2 (255 Byte) COD_GROUP6 29 N VARCHAR2 (255 Byte) COD_GROUP7 30 N VARCHAR2 (255 Byte) COD_GROUP8 31 N VARCHAR2 (255 Byte) COD_GROUP9 32 N VARCHAR2 (255 Byte) COD_GROUP10 33 N VARCHAR2 (255 Byte) Código da Sub Classe do Material ou equivalente. É o nível mais alto de detalhamento. Caso esteja em nível hierárquico de códigos, devemos concatená-los EX: 1->11->6

6 COD_GROUP11 34 N VARCHAR2 (255 Byte) COD_GROUP12 35 N VARCHAR2 (255 Byte) DESC_GROUP1 36 N VARCHAR2 (400 Byte) Reservado. Utilizar '#' DESC_GROUP2 37 N VARCHAR2 (400 Byte) DESC_GROUP3 38 N VARCHAR2 (400 Byte) DESC_GROUP4 39 N VARCHAR2 (400 Byte) DESC_GROUP5 40 N VARCHAR2 (400 Byte) DESC_GROUP6 41 N VARCHAR2 (400 Byte) DESC_GROUP7 42 N VARCHAR2 (400 Byte) DESC_GROUP8 43 N VARCHAR2 (400 Byte) DESC_GROUP9 44 N VARCHAR2 (400 Byte) DESC_GROUP10 45 N VARCHAR2 (400 Byte) DESC_GROUP11 46 N VARCHAR2 (400 Byte) DESC_GROUP12 47 N VARCHAR2 (400 Byte) Descrição da Espécie do Material ou equivalente. Incluir o código. EX: 1- Medicamentos Descrição da Classe do material ou equivalente. Incluir o código. EX: 1->11- Medicamentos Psicotrópicos Descrição da Sub Classe do Material ou equivalente. Incluir o código. EX: 1->11- >6 - Medicamentos Psicotrópicos Especiais SIT_SUPPLIER_AVAIL 48 N INTEGER Indica se o item está disponível no fornecedor (0-Não/1-Sim). Caso a informação esteja cadastrada no ERP, caso contrário utilizar o valor 1. Se o valor for 0, o usuário não conseguirá aprovar sugestões de compra geradas pela ferramenta QTY_MULT_ORDER 49 N FLOAT (126) COD_ORDER_UNIT 50 N VARCHAR2 (30 Byte) DESC_ORDER_UNIT 51 N VARCHAR2 (255 Byte) DEFAULT_LOCAL 52 N VARCHAR2 (255 Byte) Quantidade múltipla da ordem. Se for igual unidade padrão do item adotar 1 Código da unidade da ordem. Se for igual unidade padrão adotar mesmo valor do campo COD_STD_UNIT. Descrição da unidade da ordem. Se for igual unidade padrão adotar mesmo valor do campo DESC_STD_UNIT. Depósito padrão para emissão da solicitação (Verificar questionário de negócios). Se não existir adotar '#'. LAST_PURCHASE_ORDER 53 Y INTEGER Código da última ordem de compra LAST_PURCHASE_SUPPLIER 54 Y VARCHAR2 (30 Byte) Código do último fornecedor de compra LAST_PURCHASE_DATE 55 Y DATE* Data da última ordem

7 LAST_PURCHASE_PRICE 56 Y FLOAT (126) Preço da última ordem LAST_PURCHASE_QTY 57 Y FLOAT (126) Quantidade da ùltima ordem ERP_INVENTORY ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE COD_ITEM_PK 3 2 N VARCHAR2 (255 Byte) Código do Item /DELETE COD_ESTAB_PK 4 3 N VARCHAR2 (255 Byte) Código do estabelecimento /DELETE COD_LOCAL_PK 5 4 N VARCHAR2 (255 Byte) Código do local de estoque /DELETE QTY_INV 6 N NUMBER (22) SIT_MIX 7 Y NUMBER (22) QTY_MIN 8 Y NUMBER (22) QTY_MAX 9 Y NUMBER (22) ERP_PURCHASE_ORDER Quantidade de estoque disponível (deve ser convertido para unidade padrão do item) Caso deva ser somado Mínimo e Máximo do local de estoque do ERP ao gerado pela ferramenta, utilizar 1, senão 0 (padrão=0) Quantidade Mínima cadastrada no ERP para o local (deve ser convertido para unidade padrão do item) Quantidade Máxima cadastrada no ERP para o local (deve ser convertido para unidade padrão do item) ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE ID_ORDER_PK 3 2 N VARCHAR2 (100 Byte) Id da ordem /DELETE NUM_ORDER 4 N NUMBER (22) Número da ordem COD_ITEM 5 N VARCHAR2 (255 Byte) Código do Item COD_ESTAB 6 N VARCHAR2 (255 Byte) Código do estabelecimento DATE_ORDER 7 N DATE* Data da ordem QTY_PARC 8 N NUMBER (22) QTY_REC 9 N NUMBER (22) DATE_EXP 10 N DATE* DATE_REAL 11 Y DATE* Quantidade da parcela (se não existir parcela, deverá ser quantidade do item convertida na unidade padrão do item) Quantidade Recebida (se não existir parcela, deverá quantidade do item convertida na unidade padrão do item) Data esperada de chegada (se não existir parcela, deverá ser do item) Data da chegada (se não existir parcela, deverá ser do item). Caso o recebimento seja parcial, a primeira data de chegada deverá ser utilizada ID_SUPPLIER 12 N VARCHAR2 (255 Byte) Código do fornecedor da ordem NUM_REQ 13 Y NUMBER (22) DATE_REQ 14 Y DATE* Número da solicitação de compras correspondente Data da solicitação de compras correspondente VAL_UNIT 15 Y FLOAT (22) Valor de compra ERP_PURCHASE_REQ ID_WES 1 N INTEGER Código de integração /DELETE

8 ID_COMPANY_FK 2 1 N INTEGER /DELETE ID_REQ_PK 3 2 N VARCHAR2 (122 Byte) ID da solicitação /DELETE NUM_REQ 4 N NUMBER (22) Número da solicitação NUM_ITEM_REQ 5 N NUMBER (22) Número do item na solicitação NUM_PARC_REQ 6 N NUMBER (22) Número da parcela COD_ITEM 7 N VARCHAR2 (255 Byte) Código do Item COD_ESTAB 8 N VARCHAR2 (255 Byte) Código do estabelecimento COD_LOCAL 9 Y VARCHAR2 (255 Byte) Código do local QTY_PARC 10 N NUMBER (22) DATE_EXP 11 N DATE* Quantidade da parcela (deve ser convertida na unidade padrão do item) Data esperada de chegada da parcela (se não existir parcela deverá ser do item) DATE_REQ 12 Y DATE* Data da solicitação ERP_TRANSACTION_IN ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE COD_TRANS_PK 3 2 N NUMBER (22) Código da transação /DELETE COD_ITEM 4 N VARCHAR2 (255 Byte) Código do Item COD_ESTAB 5 N VARCHAR2 (255 Byte) Código do estabelecimento DATE_TRANS 6 N DATE* Data da transação QTY_TRANS 7 N FLOAT (22) TYPE_TRANS 8 N Char(1) ERP_TRANSACTION_OUT_DAY Quantidade da transação (deve ser convertida na unidade padrão do item) Tipo de entrada N Entradas notas fiscal T Entradas transferência E Entradas empréstimo O Outras Entradas ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE COD_ITEM_PK 3 2 N VARCHAR2 (255 Byte) Código do Item COD_ESTAB_PK 4 3 N VARCHAR2 (255 Byte) Código do estabelecimento COD_LOCAL_PK 5 4 N VARCHAR2 (255 Byte) Utilizar -1 COD_LOCAL_DEST_PK 6 5 N VARCHAR2 (255 Byte) Utilizar -1 COD_SECTOR_PK 7 6 N VARCHAR2 (255 Byte) Utilizar -1 TYPE_TRANS_PK 8 7 N VARCHAR2 (4 Byte) Utilizar -1 DATE_TRANS_PK 10 8 N DATE* Data da transação QTY_TRANS 9 N FLOAT (22) Quantidade da Saída (deve ser convertida na unidade padrão do item). Além disso saída deve ser identificado por número negativo, caso seja devolução utilizar o sinal positivo YN_CONS 11 Y CHAR (1 Byte) Utilizar Y

9 ERP_TRANSACTION_OUT_MONTH ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE COD_ITEM_PK 3 2 N VARCHAR2 (255 Byte) Código do Item /DELETE COD_ESTAB_PK 4 3 N VARCHAR2 (255 Byte) Código do estabelecimento /DELETE COD_LOCAL_PK 5 4 N VARCHAR2 (255 Byte) Utilizar -1 /DELETE COD_LOCAL_DEST_PK 6 5 N VARCHAR2 (255 Byte) Utilizar -1 /DELETE COD_SECTOR_PK 7 6 N VARCHAR2 (255 Byte) Utilizar -1 /DELETE TYPE_TRANS_PK 8 7 N VARCHAR2 (2 Byte) Utilizar -1 /DELETE MONTH_TRANS_PK 9 8 N DATE* QTY_TRANS 10 N FLOAT (22) Mês da transação (Deve estar no formato de data sendo o dia sempre igual a 1) Quantidade da transação (deve ser convertida na unidade padrão do item) YN_CONS 11 Y CHAR (1 Byte) Y ERP_INVENTORY_REQ_CIR /DELETE ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE COD_ITEM_PK 3 2 N VARCHAR2 (255 Byte) Código do Item /DELETE COD_ESTAB_PK 4 3 N VARCHAR2 (255 Byte) Código do estabelecimento /DELETE DATE_REQ_PK 5 4 N DATE* Data da requisição futura /DELETE QTY_REQ 6 N FLOAT (14) ERP_SUPPLIER Quantidade da transação (deve ser convertida na unidade padrão do item) ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE ID_SUPPLIER_PK 3 2 N VARCHAR2 (255 Byte) Código do fornecedor /DELETE COD_SUPPLIER 4 N VARCHAR2 (255 Byte) CNPJ do fornecedor DESC_SUPPLIER 5 N VARCHAR2 (255 Byte) Descrição do fornecedor SUPPLIER_CONTACT_NAME 6 Y VARCHAR2 (255 Byte) Nome de contato no fornecedor _SUPPLIER 7 Y VARCHAR2 (60 Byte) do fornecedor ERP_LOCAL ID_WES 1 N INTEGER Código de integração /DELETE ID_COMPANY_FK 2 1 N INTEGER /DELETE COD_ESTAB_PK 3 2 N VARCHAR2 (255 Byte) Código do estabelecimento /DELETE COD_LOCAL_PK 4 3 N VARCHAR2 (255 Byte) Código do local de estoque /DELETE DESC_LOCAL 5 N VARCHAR2 (255 Byte) Descrição do local de estoque

10 Tratamentos Específicos Cadastro de itens No cadastro de itens devemos garantir a cláusula restritiva WHERE para que apenas itens ativos integrados na ferramenta. Além disso, deverão ser filtradas as espécies especificadas no documento Questionário Inicial de Negócios de Compra Para a correta leitura das ordens de compra, suponha a seguinte estrutura As informações acima deverão ser estruturadas para que gerem o seguinte resultado Note que o campo ID_ORDER_PK é um campo único. Dessa forma precisará ser uma concatenação da chave das três tabelas Caso haja um recebimento parcial, o campo DATE_REAL deverá identificar a data Solicitações de compra Analogamente a ordem, teremos a mesma lógica de preenchimento para o layout de solicitações

11 Envio dos dados O Envio dos dados deverá ser realizado através do WEBSERVICE com os parâmetros a serem enviados pela PLANNEXO. Dados de conexão WSDL do servidor de testes: Funções WebService Função Parâmetros Descrição Plannexo integratesupplier $token,$dados,$action Fornecedores Plannexo integratesku $token,$dados,$action Base cadastral de itens Plannexo integratelocal $token,$dados,$action Local de estoque Plannexo integrateinventory $token,$dados,$action Saldo Estoque Plannexo integratepurchaseorder $token,$dados,$action Ordens de compra Plannexo integratepurchaseorderreq $token,$dados,$action Solicitações de compra Plannexo integratetransoutday $token,$dados,$action Movimentações de consumo agrupadas por dia Plannexo integratetransin $token,$dados,$action Movimentaçõe de entrada Plannexo integratetransoutmonth $token,$dados,$action Movimentações de consumo agrupadas por mês Plannexo integrateinvreqcir $token,$dados,$action Cronograma de cirurgias Descrição dos parâmetros Parâmetro $token $dados $action Descrição Autenticador da empresa. Este valor é fornecido pela PLANNEXO. Se você não possui o autenticador da sua empresa no Plannexo, favor entrar em contato com o responsável técnico. Os dados que serão enviados para o webservice. Vide próximo capítulo (Envio de dados) para maiores descrições Ação a ser executada, este campo pode ter apenas dois valores: e DELETE. Quando o valor for, o webservice irá buscar dados para a inserção, caso contrário o sistema irá procurar dados para a remoção das tabelas. Note que UPDATES deverão ser gerados como uma vez que o plannexo gera delete antes do insert excluindo a possibilidade de chave duplicada

12 Retorno O webservice tem um retorno baseado em arrays, uma vez enviado, o sistema irá processar os registros e retornar um array com uma série de outros arrays contendo: ID s com sucesso, ID s com falha e Mensagens de erro. Array [Retorno] Array [ID_WES_SUCCESS] Array [ID_WES_ERRORS] Array [ID_WES_FAILED] ID_WES_SUCCESS: É o índice de um array contendo todos os ID s de fila que retornaram sucesso e foram integrados com perfeição. ID_WES_ERRORS: Caso o registro retorne como erro, este índice armazena um array com todas as mensagens de erro, ordenadas seguindo a mesma ordem do array ID_WES_FAILED. ID_WES_FAILED: Este índice armazena um array de ID s de fila que retornaram erros. Suas respectivas mensagens se encontram no mesmo índice do array ID_WES_ERRORS.

13 Recebimento de dados pelo cliente Será disponibilizado um layout padrão em XML com as solicitações a serem integradas, no qual o cliente deverá ler, realizar a integração na base de dados e retornar logs Passo a passo 1 - Usuário seleciona itens que deseja aprovar e clica em Processar 2- O usuário deverá preencher os dados da capa da solicitação e então deverá clicar em atualizar 3 Uma vez confirmada, as solicitação receberá o status Aguardando ERP conforme imagem abaixo

14 4 O cliente deverá consultar a base plannexo de 5 em 5 minutos através de um link web service para obter os registros com o status Aguardando ERP 5 Deverá então gerar a solicitação internamente no ERP e retornar o número da mesma em caso de sucesso. Em caso de erro deverá retornar os erros ocorridos (será detalhado o layout a seguir) 6 Uma vez aprovado ficará com o status Aprovado ERP, caso contrário ficará como Reprovado ERP 7 Caso ocorra aprovação da solicitação no ERP, o cliente deverá enviar ao plannexo os registros de solicitação gerados através do layout ERP_PURCHASE_REQ Informações Web service Dados de conexão WSDL do servidor de testes: Funções WebService Função Parâmetros Descrição Plannexo purchasereq $v_cod_company Requisição.Verifica a existência de solicitações de compra a serem integradas no ERP (disponiblização do XML) Plannexo setiderp $ v_cod_company,$header,$item Resposta. Retorna o código da solicitação após a integração das mesmas, ou os logs de erro Detalhamento da Requisição Ao acessar a função Plannexo purchasereq, será disponibilizado um XML para que o cliente tenha acesso a todos os dados necessários da solcitação gerada. Segue abaixo um exemplo Exemplo:

15 Detalhamento da Resposta Após serem realizadas todas as funções e suas respectivas integrações, o WebService deverá chamar a função Plannexo setiderp, que é responsável pelo retorno do cliente com o número da solcitação gerada ou o log de erro do web service

16 Parâmetro Descrição Id da empresa Este número sequencial é o registro da sua empresa no Plannexo (solicite o código com a equipe de desenvolvimento) Cabeçalho Consiste em um array que deverá possuir: ID Plannexo, Cód. Solic. ERP, Log do cabeçalho, Status da requisição (2 para aprovado e 3 para reprovado) Itens Consiste em um array de itens que deverão possuir os seguintes campos: ID Plannexo, Código do item, Log do item. Precisamente nesta ordem (Veja próximo anexo para melhor entendimento). Exemplo: Parâmetro cabeçalho Exemplo: Parâmetro itens

17 OBS: É importante ressaltar que, caso tenha ocorrido erro em pelo menos um dos itens, toda solicitação deverá será reprovada. Nesse caso o cabeçalho da solicitação deverá ser enviada com status reprovado com motivo Erro no item e também deverá ser retornado o detalhamento do erro no nível item