Manual de integração do FirstClass

Manual de integração do FirstClass De Documentação Interna Este manual define padrões do sistema enquanto exportando informações para sistemas externos a partir do FirstClass e importando informações de sistemas externos para dentro do FirstClass. Tabela de conteúdo 1 Introdução 2 Processos de importação 2.1 Importação de Estoque 2.1.1 Layout de Arquivo de Importação de Dados do Estoque (Padrão simples) 2.1.1.1 O arquivo 2.1.1.2 Os registros 2.1.1.3 Caminho 2.2 Importação de Produtos 2.3 Importação de Regiões 3 Processos de exportação 3.1 Exportação de Produtos 3.2 Exportação de Pedidos 3.2.1 O arquivo 3.2.2 Descrição dos formatos dos campos 3.2.3 O Conteúdo 3.2.4 Os registros 3.3 Exportação de Regoes 3.4 Exportação para o Buscapé 3.5 Exportação para o AdWord 3.6 Exportação de clientes 3.6.1 Exportação por meio de arquivos 3.6.2 Exportação Direta 3.6.2.1 Como funciona 3.6.2.2 Ativando a integração direta no FC 3.6.2.3 Os arquivos de configuração 3.6.2.3.1 Testando o arquivo 3.6.2.3.2 Parâmetro 3.6.2.3.3 Exemplo de um arquivo de configuações 3.6.2.4 Configurações necessárias no BNS Introdução Existem outras formas de integração com o sistema FirstClass que não são descritas neste manual, como p. ex., a integração com sistemas de formas de pagamento, como VisaNet. Este manual se restringe a esclarecer formas com que o sistema fornece informações de produtos e pedidos para serem utilizadas com outros programas para o intuito de integração com diversos outros sistemas. Alguns processos de importação e exportação aqui descritos podem ser automatizados, geralmente processos automatizados demandam de um middleware o qual deve ser construído de acordo com a instalação. Com as descrições deste documento é possível fazer um middleware que integre as funcionalidades do FirstClass diretamente com sistemas 1/14

legados, como ERPs e CRMs. Processos de importação Os processos de importação aqui descritos entregam informação de outros sistemas para o FirstClass. Não está aqui descito processos como integração com WebServices, Sockets, arquivos XMLs e outros possíveis, para estas situações recomendamos que o responsável para construir a integração entre os sistemas forneça as informações que ele precisa para que nossa equipe de profissionais possa auxiliar para que o processo de integração seja o mais simples e rápido possível. Importação de Estoque O sistema possibilita a integração com estoque, preços de vendas e situação do produto à partir de um middlewares (http://pt.wikipedia.org/wiki/middleware) desenvolvido especificamente para cada um dos clientes. Os programas de atualização de estoque são executáveis à partir de um cron (http://pt.wikipedia.org/wiki/cron) e devem possuir o seguinte formado de nome [loja]_estoque.php sendo estes disponíveis no diretório /middleware/estoque na estrutura padrão do FC. Existem atualmente diversos formatos de integração de estoque, estes são determinados de acordo com a necessidade de uso do cliente, a WB4B tem flexibilidade para aplicar outros formatos que não os descritos neste manual, porem para tanto é necessário que esta modificação seja requisitada preferencialmente com antecedência de alguns dias. Layout de Arquivo de Importação de Dados do Estoque (Padrão simples) Este formato é utilizado apenas quando o cliente quer integrar apenas a informação de quantidade de produtos em estoque, ele contem o básico, o código do produto no ERP do cliente e a quantidade de estoque disponível para uso. Este processo desconsidera a quantidade de produtos em pedidos no FirstClass para aplicar a quantidade de produtos do estoque, p. ex., se o FirstClass receber um arquivo informando que o ERP do cliente possui 10 produtos e existem no FC um pedido requisitando 2 destes produtos o sistema irá agregar na quantidade de estoque deste produto a quantidade de 8 que seriam os 10 produtos informados pelo cliente, menos os 2 produtos já vendidos no pedido. O arquivo É um arquivo de lote em um formato similar ao CSV; Os campos são separados por ; (ponto e virgula); Os registros são separados por " " (caractere Pipe) seguidos de um novo campo sendo este na mesma linha não havendo incidência de "\r\n" (caractere Line Feed seguido do caractere New Line) entre registros. O último registro do arquivo não pode conter " " (caractere pipe), pois não existe outro registro após o último registro. Os registros Campo Formato Descrição Campo 1 Campo 2 Texto Float É o código do produto no ERP do cliente, este código deve ser o mesmo disponível no campo referência no FirstClass. Total de determinado produto em estoque na loja. É o total de estoque que será utilizado pelo sistema. Caminho 2/14

O arquivo deve ser disponibilizado a partir de uma URL não necessáriamente no mesmo servidor onde se encontra o FirstClass, no exemplo abaixo este estaria em outro local que não no mesmo servidor. URL de exemplo: http://sample.com:80/soft/netnet/lvirtual.txt Importação de Produtos Acessível à partir do módulo de produtos na área Administrativa do sistema. Importação de Regiões Acessível à partir do módulo de regiões na área Administrativa do sistema. Processos de exportação Os processos de exportação aqui descritos entregam informação do FirstClass para outros sistemas, como ERPs e CRMs. Não está aqui descito processos como integração com WebServices, Sockets, arquivos XMLs e outros possíveis, para estas situações recomendamos que o responsável do sistema legado (ERP, CRM, outros) forneça as informações do ambiente em que o sistema legado está instalado para que nossa equipe de profissionais possa, se necessário, construir novas APIs de integração fazendo o processo de integração seja o mais simples e rápido possível. Exportação de Produtos A exportação de produtos pode ser acessada a partir do link "Exportar" disponível no módulo de produtos da área administrativa de sua instalação do FirstClass. Exportação de Pedidos Este item visa esclarecer o layout do arquivos a serem exportados pelo sistema FirstClass contendo informações de pedidos e produtos dos pedidos. O arquivo 1. É um arquivo de lote no formato texto simples sem formatação. 2. Os campos são de tamanho fixo. 3. As informações descritas em colunas de posição consideram a posição 1 como sendo o primeiro caracter na linha de dados. 4. Os seguintes caracteres devem ser apresentados em seu correspondente código em HTML: (Aspas duplas); ' (Aspas simples); & (e comercial); < (Menor que); e > (Maior que). 5. Valores nulos devem ser apresentados contendo espaços em brancos. Descrição dos formatos dos campos X: Indica caracteres alfanuméricos, representados pelos códigos do intervalo 32 à 126 da tabela ASCII. N: Campos do tipo numérico contendo apenas números (a formatação não apresenta os pontos e/ou virgula). Os espaços a esquerda devem ser substituídos pelo caractere 48 (número zero) da tabela ASCII. Será apresentado com até 2 parâmetros entre parênteses. O primeiro identifica o tamanho total do campo, e o segundo, caso seja informado, identificará quantas casas decimais existem dentro do campo. Quando o segundo parâmetro não for informado, o número não possuirá casas decimais e deve ser tratado como um valor inteiro. D: Representa um campo data, no formato AAAAMMDD. Os quatro primeiros dígitos representão o ano, os dois seguintes o mês e os dois finais o dia. O campo deve conter uma data válida para o calendário gregoriano. H: Representa um campo hora, no formato HH:MM. Os dois primeiros dígitos representão a hora e os dois seguintes, os minutos, O campo deve conter uma hora válida. 3/14

T: Telefones fixos e celulares, composto por 12 caracteres estritamente numéricos sem mascaras. É composto por 3 informações: código que identifica o pais, código que identifica a região da cidade e o código que identifica o telefone. Caso não exista a informação do pais a mesma deve ser suplementada por dois caracteres 48 (dois números zeros) da tabela ASCII. O Conteúdo 1. É formado por diversos tipos de registros. Cada linha iniciada com o código 20, significa que nessa linha estão descritas as informações do pedido propriamente dito. O código 25, identifica as informações do produto atrelado ao pedido. 1. O sistema não irá restringir a apresentação de nenhuma informação, por isto o arquivo conterá apenas as informações para apresentação, cuidando para que não sejam incluídas informações incorretas. Os registros Cabeçalho do arquivo: Descreve informação relativas ao arquivo no inicio do mesmo Nome do campo Formato Tamanho Posição Descritivo Tipo do registro N(02) 02 01 à 02 Contem apenas o valor 10. Identifica a versão do arquivo de pedidos Versão X(05) 05 03 à 07 Versão do arquivo de importação. Cabeçalho do pedido: Descreve informações singulares do pedido, como nome do cliente, código da cobrança e etc. Nome do campo Formato Tamanho Posição Descritivo Tipo do registro N(02) 02 01 à 02 Contem apenas o valor 20. Identifica a linha dos dados do pedido id_pedped N(10) 10 03 à 12 Código que identifica o Pedido ped_dta_compra DT 12 13 à 24 Data e Hora que a compra foi realizada ped_dta_atualizacao DT 12 25 à 36 ped_situacao X 9 37 à 45 Data e Hora que o pedido foi verificado pelo funcionário de atendimento da loja Situação normal do pedido: NOVO; APROVACAO; APROVADO; LIBERADO; REMETIDO; RECEBIDO id_clicli N(10) 10 46 à 55 Código que identifica o Cliente cob_nome X 50 cob_sobrenome X 50 cob_email X 50 cob_cpf_cgc X 20 cob_rg_ie X 20 cob_tipo_pessoa X 1 cob_contato X 50 56 à 105 106 à 155 156 à 205 206 à 225 226 à 245 246 à 246 247 à 296 Nome do cliente Sobrenome do cliente E-mail do cliente CPF/CNPJ do cliente RG/IE do cliente Tipo de Pessoa (Física ou Jurídica) do cliente Informação do contato responsável no caso de pessoa jurídica, qualquer informação que o cliente tenha digitado, um nome ou um telefone 4/14

cob_endereco X 50 cob_end_numero X 10 cob_end_comp X 50 cob_end_bairro X 50 cob_end_cidade X 50 cob_end_uf X 2 cob_end_cep N(11) 10 cob_end_provincia X 50 cob_end_pais X 50 cob_tel_a T 50 cob_tel_b T 50 ent_nome X 50 ent_sobrenome X 50 ent_endereco X 50 ent_end_numero X 10 ent_end_comp X 50 ent_end_bairro X 50 ent_end_cidade X 50 ent_end_uf X 2 ent_end_cep 10 ent_end_ref X 100 ent_end_provincia X 50 297 à 346 347 à 356 357 à 406 407 à 456 457 à 506 507 à 508 509 à 518 519 à 568 569 à 618 619 à 668 669 à 718 719 à 768 769 à 818 819 à 868 869 à 878 879 à 928 929 à 978 979 à 1028 1029 à 1030 1031 à 1040 1041 à 1140 1141 à 1190 ent_end_pais X 50 1191 à 1240 Endereço do comprador Campo número no endereço do comprador Campo complemento no endereço do comprador Campo bairro no endereço do comprador Campo cidade no endereço do comprador Campo UF no endereço do comprador Campo CEP no endereço do comprador Campo província no endereço do comprador (somente para entrega internacional) Campo país no endereço do comprador (somente para entrega internacional) Número de telefone principal do comprador Número de telefone de recado do comprador (não é obrigatório) Nome da pessoa que deverá ser feita a entrega da compra Sobrenome da pessoa que deverá ser feita a entrega da compra Endereço de entrega da compra Campo número no endereço de entrega da compra Campo Complemento no endereço de entrega da compra Campo bairro no endereço de entrega da compra Campo cidade no endereço de entrega da compra Campo UF no endereço de entrega da compra Campo CEP no endereço de entrega da compra Campo referência do endereço de entrega da compra Campo província no endereço de entrega da compra (somente para entrega internacional) Campo país no endereço de entrega da compra (somente para entrega internacional) 5/14

ent_tel_a X 50 1241 à 1290 ent_tel_b X 50 1291 à 1340 ped_observacao Z 220 ped_tipo_frete N(1) 1 ped_transportadora X 50 ped_prazo_entrega N(6) 6 ped_entrega_regiao X 50 ped_valor_subtotal N(10,2) 10 ped_valor_embalagem N(10,2) 10 ped_valor_frete N(10,2) 10 ped_valor_desconto N(10,2) 10 ped_valor_valecompra N(10,2) 10 ped_valor_total N(10,2) 10 pag_num_parcelas N(3) 3 pag_val_entrada N(10,2) 10 pag_val_parcela N(10,2) 10 pag_indexador N(10,2) 10 boleto_parcelado N(2) 2 ped_tipo_pagamento X 50 ped_forma_pagamento X 50 ped_origem X 15 ped_cupom X 15 ped_promocao X 15 1341 à 1560 1561 à 1561 1562 à 1611 1612 à 1617 1618 à 1667 1668 à 1677 1678 à 1687 1688 à 1697 1698 à 1707 1708 à 1717 1718 à 1727 1728 à 1730 1731 à 1740 1741 à 1750 1751 à 1760 1761 à 1762 1763 à 1812 1813 à 1862 1863 à 1877 1878 à 1892 Número de telefone principal da pessoa que deverá ser feita a entrega da compra Número de telefone de recado da pessoa que deverá ser feita a entrega da compra (não é obrigatório) Observação sobre a compra incluída pelo comprador na finalização do pedido Tipo do Frete desse pedido: 1 - Grátis; 2 Fixo; 3 - Transportadora Nome da transportadora que irá fazer a entrega definida de acordo com a região da compra Prazo de entrega do pedido definido de acordo com a região da compra Nome da Região de entrega do pedido Valor da soma dos produtos comprados no pedido Valor da embalagem, caso o cliente tenha escolhido comprar algum produto como presente. Valor do Frete de acordo com a região da compra. Frete com valor 0 (zero), significa grátis. Valor da soma do desconto que foi aplicado aos produtos caso exista Valor do vale-compra que foi aplicado aos produtos caso exista. Valo total do pedido que deve ser pago pelo cliente com todos os descontos e valores adicionais já calculados Número de parcelas para pagamento. O número 1 será utilizado no caso de pagamento à vista ou parceladas pelo banco. (Itaú Shopline, Financiamentos, etc) Valor de entrada. (Somente para boleto parcelado) Valor da parcela para o pagamento com cartões de crédito Valor do indexador aplicado as parcelas no caso de pagamento com juros cobrados do cliente Código que identifica se a compra está utilizando Boleto Parcelado (1) ou não (0). Valor padrão: ( 0 ) não utiliza boleto parcelado Código que identifica qual o tipo de pagamento do pedido. Código que identifica qual a forma de pagamento do pedido. Código que identifica a origem da compra. Usado para verificar o resultado dos canais de divulgação e relatórios. (pode ser vazio) Código que identifica o cupom de desconto da compra. (pode ser vazio) 1993 à Descrição da promoção ativa pela qual o cliente recebeu o 6/14

ent_cod_ibge X 11 1907 1908 à desconto. Descrição (pode da promoção ser vazio) ativa pela qual o cliente recebeu o 1918 desconto. (pode ser vazio) Produtos do pedido (Corpo do pedido): Contem informações relativas ao pedido Nome do campo Formato Tamanho Posição Descritivo Tipo N(02) 02 01 à 02 Contem apenas o valor 25. Identifica o tipo de ação à ser realizada com a linha no arquivo. id_pedped N(10) 10 03 à 12 Código que identifica o pedido relacionado a esse produto id_prdprd X 10 13 à 22 Código que identifica qual o produto comprado prd_qtd N(5) 5 23 à 27 Quantidade identificada no pedido prd_nome X 100 prd_referencia X 50 prd_categoria N(10) 10 prd_fornecedor X 50 prd_cor X 50 prd_tamanho X 50 prd_estilo X 100 prd_aro X 50 prd_peso N(10,2) 10 prd_cubagem N(10,2) 10 prd_pvreal N(10,2) 10 prd_pvpromocao N(10,2) 10 prd_pvtotal N(10,2) 10 prd_promo_ini D 8 prd_promo_fim D 8 prd_prazo_disp N(10) 10 prd_prazo_forn N(10) 10 28 à 127 128 à 177 178 à 187 188 à 237 238 à 287 288 à 337 338 à 437 438 à 487 488 à 497 498 à 507 508 à 517 518 à 527 528 à 537 538 à 545 546 à 553 554 à 563 564 à 573 Unidade de medida utilizada para contabilizar o produto. Referencia do produto. Identificação da categoria na loja online. Fornecedor do Produto Cor do Produto Tamanho do Produto Estilo do Produto Aro (Utilizado em casos de anéis, rodas, etc.) Peso total do produto no pedido Cubagem total do produto no pedido Preço normal do produto Preço em promocao do produto (valor vazio se o produto não estiver em promocao) Preço total do produto no pedido (valor do preço normal ou promoção x quantidade comprada) Data do inicio da promoção (caso exista) Data do final da promoção (caso exista) Prazo de disponibilidade do produto Prazo de entrega do Fornecedor 7/14

Rodapé do arquivo: Descreve informações em geral quanto ao arquivo sendo processado e marcando o final. Nome do campo Formato Tamanho Posição Descritivo Tipo N(02) 02 01 à 02 Quantidade de Pedidos Quantidade de Produtos Exportação de Regoes Contem apenas o valor 99. Identifica o fim do do arquivo de pedidos. N(10) 10 03 à 12 Informa a quantidade total de registros de pedidos do arquivo. N(10) 10 13 à 22 Informa a quantidade total de registros de produtos do arquivo. Para exportar regiões basta acessar a área administrativa do FirstClass e clicar em exportar. Exportação para o Buscapé O Buscapé requisita um tipo padrão de XML o qual já existe em sua instalação. O arquivo se encontra no diretório http://predefinição:seudomínio/middleware/buscape Exportação para o AdWord o AdWord possui uma integração padrão a qual já está disponível em sua instalação padrão. O arquivo do AdWord está disponível no diretório http://predefinição:seudomínio/middleware/buscape Exportação de clientes A exportação de clientes pode ser efetuada em dois modelos, integração direta e exportação por meio de arquivos a partir do administrativo. A exportação direta é a utilizada para integrar o BNS com o FirstClass. Exportação por meio de arquivos Funciona acessando-se o módulo de clientes, clicando na opção "exportar", para efetuar tal exportação é necessário que o usuário tenha autoridade de acesso ao módulo de clientes e autoridade para exportar a base de clientes. O arquivo exportado é no formato CSV simples com as colunas separadas por ; (ponto-e-virgula). O arquivo contém praticamente todas as informações existentes de clientes e exporta apenas um dos endereços do cliente. O endereço relacionado ao cliente e apresentado no arquivo exportado é o endereço padrão do cliente. Neste formato é possível exportar apenas clientes da base de dados, com a exportação dirta podemos não só exportar clientes como também pessoas que efetuaram comentários sobre produtos. Exportação Direta Para facilitar a explicação do processo descrevemos abaixo este como sendo uma integração com o sistema BNS, porem você pode utilizar esta mesma configuração para qualquer sistema, a única restrição é que uma vez integrado com um sistema você não poderá fazer uma integração com um segundo sistema, ou seja, se você decidir utilizar a integração direta com o BNS você não poderá efetuar integração com seu ERP e vice-versa. A exportação direta foi construída para possibilitar com que o FirstClass se integrasse de maneira mais efetiva com o BNS, 8/14

sóftware de email marketing da WB4B/C', este formato de integração possibilita com que todo cliente cadastrado no FirstClass e que tenham marcado a opção para receber novidades da loja por meio de email seja automaticamente cadastrado no BNS sem a interação manual, sendo totalmente automática. Esta integração pode ocorrer tanto no cadastro e atualização dos dados do cliente quanto no momento em que este efetua um comentário sobre o produto. A integração também só ocorre se o cliente tiver explicitamente marcado opções como "desejo receber o email" nos respectivos formulários de cadastro e opiniões. Como funciona O processo é feito por meio do método POST simples do protocolo HTTP, ou seja, o sistema simplesmente interpreta o que recebe dos formulários e encaminha a informação para o BNS por meio de um POST, como se fosse uma pessoa qualquer preenchendo um formulário, seria o mesmo que sempre que alguma pessoa preencher um cadastro no FirstClass alguém fosse no cadastro de clientes e preenchesse o formulário de captação para você no BNS, este alguém é o FirstClass. Para saber quais campos postar e como informar o BNS o FirstClass carrega um arquivo de configuração, com isto ele pode se integrar com o BNS, independente de quais campos (atributos dinâmicos) você criou no BNS. A integração é ativada e configurada no arquivo config.php e explicamos abaixo o funcionamento dos itens a serem criados no FirstClass. Ativando a integração direta no FC A integração direta é ativada por meio de definições no arquivo /config/config.php, independente da versão que você estiver utilizando no FirstClass você deve configurar a definição BNS_INTEGRADO como verdadeira para ativar a integração, a partir dai você deve informar o arquivo de configurações para o formulário de clientes (BNS_XMLPOSTCLIENTES) e/ou o arquivo de configurações para o formulário de comentários (BNS_XMLPOSTOPINIOES). Se seu FirstClass for de uma Release anterior a 19.0.1 então é necessário também configurar as definições BNS_HEADERNAME e BNS_CODESUCCESS, também explicadas abaixo. Um exmplo de como ficaria o sistema com a integração apenas na parte de opiniões é o seguinte: // este define deve sempre ser marcado como verdadeiro para indicar que a integração por POST está ativa. define("bns_integrado", true); // indica o diretório e o nome do arquivo que deve conter o XML. define("bns_xmlpostopinioes", '/bns.formulario.opinioes.xml'); // caso você esteja utilizando o sistema para integrar com o BNS você deve // configurar o parametro abaixo para indicar ao BNS que ele está trabalhando // com outro computador. É um campo obrigatório. define("bns_headername", "X-BNS"); // o define abaixo indica para qual página o BNS irá encaminhar o usuário caso // o cadastro tenha sido bem sucedido. É um campo obrigatório. define("bns_codesuccess", "bnscadsucesso"); Abaixo explicações sobre cada parâmetro de configuração: BNS_INTEGRADO Define se o FirstClass deve ou não ser integrado com outro sistema. Deve conter apenas uma das opções, True ou False, sendo: True: A integração está ativa; False: A integração NÃO está ativa, este é o valor padrão. BNS_XMLPOSTCLIENTES Indica o diretório e o nome do arquivo de configurações que deve conter o XML descrevendo os procedimentos 9/14

utilizados para integrar o cadastro de clientes do sistema. Apenas o endereço preenchido no formulário de cadastro e atualização estará disponível para ser encaminhado ao BNS. Se esta definição não for configurada no sistema então o sistema não irá integrar os formulários de cadastro de clientes, mesmo que o parâmetro BNS_INTEGRADO estiver configurado e ativo. Para maiores detalhes sobre o formato e o conteúdo veja "arquivos de configuração" abaixo BNS_XMLPOSTCLIENTESDEL Indica o diretório e o nome do arquivo de configurações que deve conter o XML descrevendo os procedimentos utilizados para integrar o cadastro de clientes do sistema porem fazendo o "descadastro" do cliente, ou seja, se este arquivo estiver configurado e o cliente estiver previamente cadastrado em sua base de dados no BNS e não selecionar a opção "desejo receber o email" ele será repassado para a segmentação "descadastrados". Se esta definição não for configurada no sistema então o sistema não irá integrar os formulários de cadastro de clientes para fazer o descadastro, mesmo que o parâmetro BNS_INTEGRADO estiver configurado e ativo. A configuração deste arquivo não é obrigatório, você pode configurar a opção BNS_XMLPOSTCLIENTES enão configurar este parâmetro, tratando assim apenas a entrada de clientes no sistema. Para maiores detalhes sobre o formato e o conteúdo veja "arquivos de configuração" abaixo BNS_XMLPOSTOPINIOES Indica o diretório e o nome do arquivo de configurações que deve conter o XML descrevendo os procedimentos utilizados para integrar as opiniões do sistema. A integração de opiniões não possui a opção de excluir (descadastrar) o cliente caso ele não tenha marcado a caixa de "desejo receber o email", como o BNS_XMLPOSTCLIENTESDEL que faz este serviço para o parâmetro BNS_XMLPOSTCLIENTES. Caso você esteja utilizando o BNS como o sistema que irá receber a informação você pode inclusive fazer com que o sistema encaminhe para o BNS o conteúdo do formulário postado de forma com que o BNS encaminhe para o responsável pelo cadastro o texto escrito no formulário de opiniões. Para tanto você deve construir um captador com a opção "Quero ter um campo para receber mensagens dos clientes" marcada. Para maiores explicações sobre como fazer esta configuração veja a sessão Configurações necessárias no BNS abaixo. Se esta definição não for configurada no sistema então o sistema não irá integrar os formulários de opiniões, mesmo que o parâmetro BNS_INTEGRADO estiver configurado e ativo. Para maiores detalhes sobre o formato e o conteúdo veja "arquivos de configuração" abaixo BNS_HEADERNAME Caso você esteja utilizando o sistema para integrar com o BNS você deve configurar este parâmetro para que o FirstClass possa identificar o código de retorno do BNS, este é um recurso técnico onde o sistema BNS encaminha nos cabeçalhos de comunicação entre as máquinas um "cabeçalho X" indicando se o cadastro ocorreu ou se teve algum problema e o cadastro não foi salvo. É um campo obrigatório e seu valor deve sempre ser "X-BNS" quando trabalhando com o BNS. BNS_CODESUCCESS Deve conter a Indica para qual página o BNS irá encaminhar o usuário caso o cadastro tenha sido bem sucedido. 10/14

É um campo obrigatório e seu valor deve sempre ser "bnscadsucesso". Os arquivos de configuração O arquivo de configurações é um arquivo ao estilo DE/PARA, onde você informa qual campo no formulário origem (formulário no FC) deve ser transportado para qual campo no formulário destino (em nosso exemplo o formulário de captação do BNS). O arquivo possui o formato XML versão 1.0 com codificação UTF-8 contendo a indicação de quais campos do formulário de clientes você gostaria de encaminhar para o outro domínio e com qual nome de campo ele deve ser entregue, desta forma você pode receber o campo "email" do formulário de clientes e entregar ele para o destino com um outro nome, como p. ex., "cliente_email", facilitando ainda mais integração com outros sistemas. O formato do arquivo XML (quantidade de campos) irá variar de acordo com sua necessidade, você não precisa utilizar todos os campos disponíveis, você pode construir uma integração que receba apenas o email do cliente, ou uma que receba seu nome, seu telefone e cidade em que reside. Para manter uma harmonia na instalação é interessante que este arquivo esteja no diretório /config da instalação. Testando o arquivo Para efetuar testes sobre o formato do arquivo, se ele está corretamente montado disponibilizamos o aplicativo testa_integracao_bns.php em /fc/tools, este arquivo é um arquivo de exmplo e como cada integração é específica para cada instalação do FC recomenda-se copiar o arquivo de teste para o diretório [www]/middleware/tools, renomeando este de forma que comece com o nome original do arquivo (que seria testa_integracao_bns ) seguido de um ponto, do cliente, e da extensão.php, como p. ex., o script da sepha ficaria como testa_integracao_bns.sepha.php Parâmetro Você pode ter apenas uma arquivo de configuração XML para cada procedimento (Sendo eles o procedimento de opiniões, de clientes e descadastro de clientes), isto significa que você não poderá efetuar uma integração direta por este meio com mais de um sistema. É obrigatório o uso de "<![CDATA[" e de "]]>" para abrir e fechar o conteúdo do valor em uma TAG no XML de integração. Algumas TAGs do arquivo XML são necessárias, outras não, recomendo ver o exemplo de conteúdo do arquivo XML utilizado para integração com o sistema BNS e algumas observações quanto a seu conteúdo logo abaixo. Vale observar as seguintes TAGs: cadastrobns host url Neste exemplo vemos que a TAG principal do arquivo XML possui o nome cadastrobns, este nome não é obrigatório, você pode altera-lo para documentar o motivo do arquivo diretamente no conteúdo deste. Elo obrigatório de existir no arquivo, sem este o aplicativo não sabe como continuar o processo. Abrindo o formulário de destino temos o parâmetro target na TAG >form> do HTML do formulário de destino, nesta TAG do XML colocamos apenas o nome do host descrito no formulário, ele é utilizado para compor o target do formulário no domínio destino. Exemplo de parâmetro a ser configurado: www.wb4b.com.br ou ainda www.sepha.com.br Elo obrigatório de existir no arquivo, sem este o aplicativo não sabe como continuar o processo. Completa o campo host para formar a URL do destinatário que irá receber o post das informações. 11/14

Campos campo name comentario value nameform default É o restante do parâmetro target na TAG >form> do HTML do formulário de destino. P. ex., /forms/formulario.captacao.assinantes.php Elo obrigatório de existir no arquivo, sem este o aplicativo não sabe como continuar o processo. Esta TAG diferencia as demais TAGs que são referentes aos campos do formulário das TAGs anteriores que configuram a comunicação entre os servidores. É uma TAG obrigatória que separa estruturalmente o XML dos elos únicos como >host> e >url; possibilitando termos múltiplos elos do tipo >campo>. Para cada campo que se deseja entregar ao servidor destinatário deve haver uma TAG >campo>, filha da TAG >Campos>. Nesta TAG indicamos as configurações dos campos em ambos os lados das transações. É uma TAG obrigatória que separa estruturalmente o XML. Obrigatóriamente deve existir apenas um elo >name> para cada elo >campo> e a existencia deste é obrigatória. Obrigatóriamente deve existir apenas um dos elos >value>, ou >nameform>, ou ainda >default> e quando houver um não pode haver o outro, com isto o sistema identifica qual procedimento a ser executado ao encaminhar o campo. Nome do campo no formulário destino. Se você quiser passar o campo nome no formulário origem para o campo Nome e Sobrenome no formulário destino esta TAG conterá o nome do campo Nome e Sobrenome. Obrigatóriamente deve existir apenas um elo >name> para cada elo >campo> e a existencia deste é obrigatória. Caso você deseje pode inclusive incluir um comentário no arquivo XML sobre o campo sendo criado. Esta TAG é ignorada pelo FC, sendo assim se não existir nenhum erro de sintaxe do XML este campo será ignorado. TAG utilizada para virtualizar campos de conteúdo fixo que podem ser necessários encaminhar no post para o servidor de destino. Utilizamos eles para encaminhar, p. ex., o campo "versao" que determina a versão da integração em uso no momento do post para o BNS. Digamos que você tem um campo no formulário destino e quer que sempre que a integração ocorrer este campo no formulário destino receba um valor específico, você deve utilizar este parâmetro e informar o valor específico. P. ex, digamos que você tenha um campo Observações no formulário destino e sempre que o cadastro de clientes acontecer você quer que este campo receba o valor Cadastrado pelo cadastro de clientes na loja virtual, você deixa esta frase como conteúdo desta TAG. Nome do campo utilizado no formulário de origem (pode ser um campo no formulário de clientes ou no formulário de opiniões). Este deve ser utilizado para campos do tipo text ou textarea, para os demais campos veja a TAG >default>. Em conjunto com a TAG >name> indica ao sistema qual campo do formulário de cliente do FirstClass será encaminhado e qual nome este deve possuir para o servidor destino. É uma TAG utilizada para tratar campos do tipo Radio ou Checkbox que podem possuir um valor no formulário de clientes do FirstClass e outro valor no formulário do servidor. 12/14

fields Este deve ser utilizado para campos do tipo select, radio ou checkbox, para os demais campos veja a TAG >nameform>. Um campo do tipo radio box pode contem várias opções de seleção, esta TAG indica ao FirstClass quais opções devem ser entregues ao cliente. É uma TAG que deve estar dentro da TAG >default> podendo haver múltiplas TAGs >fields> para cada >default> Caso você esteja encaminhando um campo do tipo Checkbox também pode utilizar esta TAG para entregar ao servidor de destino um outro valor que não o originalmente utilizado pelo FirstClass. Neste exemplo, sempre que o cliente selecionar o campo sexo como sendo do tipo masculino o sistema irá encaminhar para o sistema destinatário o valor "16985", não o valor "1" originalmente entregue pelo FirstClass. Exemplo de um arquivo de configuações <?xml version="1.0" encoding="utf-8"?> <cadastrobns> <host><![cdata[registro.ibns.com.br]]></host> <url><![cdata[/feedback/cadastro.php]]></url> <Campos> <campo> <name><![cdata[versao]]></name> <value><![cdata[2008.01]]></value> </campo> <campo> <name><![cdata[testebns]]></name> <value><![cdata[0]]></value> </campo> <campo> <name><![cdata[16982_nome_1]]></name> <nameform><![cdata[opiniao_cliente_nome]]></nameform> </campo> <campo> <name><![cdata[email]]></name> <nameform><![cdata[email]]></nameform> </campo> <campo> <name><![cdata[16983_sexo_0]]></name> <default> <fields> <nameform><![cdata[opiniao_cliente_sexo]]></nameform> <formvalue>1</formvalue> <value>16985</value> <comentario><![cdata[sexo Masculino]]></comentario> </fields> <fields> <nameform><![cdata[opiniao_cliente_sexo]]></nameform> <formvalue>2</formvalue> <value>16984</value> </fields> </default> </campo> </Campos> </cadastrobns> Configurações necessárias no BNS Agora que você compreende como funciona a integração vamos exemplificar como construir uma com o BNS Caso você esteja utilizando o BNS você deve providenciar neste um formulário de captação contendo os campos que você deseja serem recebidos do FirstClass. Obtida de 13/14

"http://intranet.wb4b.com.br/empresa/intranet/soft/wiki/index.php/manual_de_integra%c3%a7%c3%a3o_do_firstclass" Esta página foi modificada pela última vez às 14h59min de 1 de julho de 2011. Esta página foi acessada 183 vezes. 14/14