fast commerce a pi

5/24/2018 Fast Commerce a Pi

1/35

Lojas virtuais que vendem

Manual API

www.fastcommerce.com.br

Verso 2.0


2/35

CONTEDO | II

RUMO WEB INFORMTICA LTDA Manual API v2.0

1 Apresentao 1

2 Mtodos 2

2.1 Permisses de acesso aos mtodos . . . . . . . . . . . . . . . . . . . . 4

2.2 Controle de volume de acessos API . . . . . . . . . . . . . . . . . . . . 4

3 XML de produtos 5

3.1 Alterao de produtos . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2 Excluso de produtos. . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.3 Incluso de produtos . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 XML de pedidos 13

4.1 Alterao de pedidos. . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.2 Chaves do XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 Realizao de testes 16

5.1 Testes do mtodo "ReportView" . . . . . . . . . . . . . . . . . . . . . . 17

5.2 Testes do mtodo "UtilityExecute" . . . . . . . . . . . . . . . . . . . . . 20

5.3 Testes do mtodo "OrderUpdate" . . . . . . . . . . . . . . . . . . . . . 21

5.4 Testes do mtodo "ProductManagement" . . . . . . . . . . . . . . . . . 22

5.5 Exemplo de VBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

6 Dicionrio 24

7 Melhores prticas 31

Sumrio


3/35

CONTEDO | III


Controle de verso

Verso Data Seo Descrio

2.0 13/11/12 2 Insero:

- Par5, Par6, Par7, Par8- Page (Pgina que ser retornada) e QtRecords (Quantidade de registros retornados por pgina)- FromRecord (Registro inicial solicitado do relatrio) e ToRecord (Registro final solicitado do relatrio)

2.0 13/11/12 5.1 Insero: Campos retornados pela API na chave , Retorno fracionado e Seleo de campos retornados.

1.9 08/10/12 6 Insero: Novos campos em Produto, Clientes, Pedidos, Detalhes e Acessos.

1.8 24/05/12 2.2 e 7 Alterao: Limite de 60 para 300 acessos por hora.

1.8 24/05/12 6 Insero: Novo campo ChangeFlagProdAPI na tabela de campos de Produto.

1.7 14/03/12 4.2 Insero:

- Nova chave ChangeFlagAPI nos XMLs de exemplo de alterao de pedidos:

1.6 11/10/11 6 Alterao: Novas bandeiras no campo carto em Pedidos.

1.5 19/04/10 - Criao do documento


4/35


APRESENTAO | 1

1Apresentao

A API (Application Programming Interface) do FastCommerce permite a sistematizao remota de diversas tarefas realizadasregularmente pelos usurios atravs do site administrativo da loja virtual. Com esta API possvel integrar aplicativos externostais como ERPs, CRMs, sistemas de BI, gateways de pagamento etc, e atravs destes aplicativos executar mtodos da API paragerenciamento de produtos e pedidos, obter dados de relatrios e executar utilitrios do FastCommerce.

O acesso API ocorre sempre atravs do protocolo HTTPS (porta 443), com certificao EV SSL. A execuo de cada mtodo

inicia-se atravs de uma solicitao enviada via FORM POST e termina em seguida com uma nica resposta em XML. Cadaexecuo gera somente um pageview, mesmo que seu resultado contenha ou altere milhares de registros. Da mesma forma, umachamada que no retorne nem altere registro algum tambm contabilizar como um pageview.

A resposta execuo de cada mtodo sncrona e pode ocorrer de forma quase imediata ou pode demorar at alguns minutos,dependendo do mtodo e da quantidade de registros lidos ou alterados.

ATENO:

Acessos API no devem estar diretamente relacionados aos acessos a qualquer pgina da loja virtual, ou seja, cada acesso decliente da loja no deve corresponder a um acesso API. Para evitar que isto ocorra, existe uma limitao no volume de acessos porhora aos mtodos da API (ver 2.2 Controle de volume de acessos API).


5/35


MTODOS | 2

O mtodo informa qual a ao desejada na chamada API. Cada chamada deve obrigatoriamente conter um dos quatro mtodosabaixo:

ReportView Exportao de dados dos relatrios do FastCommerce em formato XML

UtilityExecute Alteraes realizadas pelos utilitrios administrativos

OrderUpdate Alteraes dos status, observaes curtas e objetos dos Correios dos pedidos.

ProductManagement Gerenciamento de produtos (alterao, excluso e incluso)

A comunicao se inicia atravs de um FORM POST para o seguinte endereo:

https://www.rumo.com.br/sistema/adm/APILogon.asp

Seguem abaixo os campos obrigatriosdeste POST:

StoreName Nome da loja

StoreID ID da loja

Username Nome do usurio administrativo

Password Senha do usurio administrativo

Method Mtodo que ser utilizado

Caso o mtodo seja ReportView ou UtilityExecute, os campos so:

ObjectID ID do relatrio (opcional de ObjectName for informado)

ObjectName Nome do relatrio (opcional de ObjectID for informado)

Par1 Parmetro 1 do relatrio ou utilitrio (ex.: data inicial)

Par2 Parmetro 2 do relatrio ou utilitrio (ex.: data final)

Par3 Parmetro 3 do relatrio ou utilitrio (ex.: nome do cliente)

Par4 Parmetro 4 do relatrio ou utilitrio (ex.: e-mail do cliente)

Par5 Parmetro 5 do relatrio ou utilitrio




Page Pgina que ser retornada

QtRecords Quantidade de registros retornados por pgina

FromRecord Registro inicial solicitado do relatrio

2Mtodos


6/35


MTODOS | 3

ToRecord Registro final solicitado do relatrio

Fields Campos que sero retornados (S mtodo ReportView)

OutputFormat Formato do retorno:

0 HTML

1 XML

2 AJAX

3 Excel

4 Word

5 XML API (formato default, se o campo no for informado)

Se passar os 4 parmetros de paginao, os preferenciais so Page e QtRecords. Neste caso, os dois parmetros devem ser passadospara que sejam considerados.

As opes de formato de retorno so as mesmas oferecidas na funcionalidade de relatrios do site administrativo. Na integrao deaplicativos, sugerimos que utilize a opo 5 (XML API), que o padro.

Exemplo de form:

- Se o ObjectIDfor informado, no necessrio informar o ObjectName

Obs: Para listar o ObjectIDe os parmetros dos relatrios e utilitrios, utilize o seguinte relatrio:

(FC) Lista de relatrios e utilitrios

Qualquer relatrio ou utilitrio pode ser executado, mas existem nove relatrios que foram criados especificamente para utilizaocom a API:

Lista de produtos para alteraes via API

Lista de pedidos para alteraes via API Lista de pedidos e dados de cartes de crdito

Lista de clientes para consultas via API

Lista de pedidos e detalhes para consultas via API

Lista de pedidos alterados para consultas via API

Lista de classes de produtos para cadastro via API

Categorias e IDs para cadastro de produtos via API

Log de acessos por API

XMLRecords Contedo do XML com todos os seus registros


7/35


MTODOS | 4

Caso o mtodo seja OrderUpdate ou ProductManagement,o campo obrigatrio que contm todos os registros o seguinte:

Exemplo de form:

2.1 Permisses de acesso aos mtodos

Para o acesso a API, necessrio que o usurio tenha permisses de acordo com cada mtodo:

Mtodo Permisso do usurio

OrderUpdate Acesso aos utilitrios de pedido

ProductManagement Acesso aos utilitrios de produto

ReportView acesso ao tipo do relatrio selecionado

UtilityExecute acesso ao tipo do utilitrio selecionado

Exemplo: Se o ObjectIDescolhido for um relatrio estatstico, o usurio precisa ter acesso aos relatrios estatsticos.

2.2 Controle de volume de acessos API

Cada loja poder fazer at 300 acessos API por hora (mdia de cinco acessos por minuto).

Se este limite for excedido, novas consultas sero bloqueadas at a prxima virada da hora. Por exemplo, se forem feitas mais de 300consultas entre 13h e 14h, somente aps as 14h ser possvel fazer novos acessos API, e assim por diante.

Quando o limite for excedido, o cdigo 20 ser retornado pela API, com a seguinte mensagem:

Reached limit of access per hour


8/35


XML DE PRODUTOS | 5

3XML de produtos

Estrutura do XML com todos os campos para incluso, alterao ou excluso de produtos:

Obs: possvel enviar mltiplosprodutos por vez.


9/35


XML DE PRODUTOS | 6

3.1 Alterao de produtosEstrutura do XML para alterao do cadastro de produtos:

(para alterao o comando deve ser Ae devem ser enviados somente os campos que forem alterados)

Neste exemplo, ser realizada somente a alterao do nome do produto.

Obs:Para alterar produtos, os campos Comandoe IDProdutoso obrigatrios. possvel alterar mltiplos produtos porvez.

O resultado desta operao ser retornado em XML. Segue o modelo:

0

OK

ChangeFlagProdAPI: esta chave utilizada para marcar os produtos que j foram recebidos pelo ERP, evitando que sejam nova-mente trazidos.

Pode conter valores de 1 a 255. Este campo ser automaticamente zerado sempre que ocorrerem alteraes no produto atravs daficha do produto no site administrativo ou via CSV.

Produtos novos so criados com ChangeFlagAPI=0.

Obs: Alteraes no estoque do produto quando este comprado ou quando o pedido contendo o produto for canceladono alteram este campo.

Os seguintes relatrios de produtos podem ser utilizados com o mtodo ReportView para trazer a lista de produtos da loja:

- Lista de produtos para alteraes via API

- Lista de estoque de produtos para alteraes via API

Nestes relatrios, possvel utilizar o filtro ChangeFlagAPI=0 para trazer somente os produtos novos ou alterados pela ficha do

produto no site administrativo ou via CSV. Aps a importao, utilize o mtodo ProductManagement para alterar o valor deChangeFlagProdAPI e evitar novas importaes redundantes.

Para alterar o estoque existente de um produto, coloque um sinal de + (mais) ou de - (menos) aps a quantidade, no campo Es-toque.


10/35


XML DE PRODUTOS | 7

Exemplos:

Utilize o seguinte XML para adicionar dois itens ao estoque existente do produto 999999. Se o produto estava com 50 itens noestoque, aps executar o XML abaixo passar a ficar com 52 itens:

Utilize o seguinte XML para retirar trs itens do estoque existente do produto 999999. Se o produto estava com 50 itens no es-toque, aps executar o XML abaixo passar a ficar com 47 itens:

Veja a lista com os possveis cdigos de erros () e suas descries ():

0 OK 11 Report/Utility error

1 Store not found 12 Invalid StoreID for this logon

2 Invalid user 13 StoreID not informed

3 No Password 14 Store suspended

4 Logon Error 15 Demonstration period is over

5 Blocked IP address 16 XMLRecords not informed

6 Too many retries. User suspended for 3 minutes 17 Access denied

7 Logon Error. Next invalid logon will suspend user for 3

minutes.

18 Invalid Product(s) in XMLRecords

8 Invalid method 19 Invalid Order(s) in XMLRecords

9 Report/Utility not found or access denied 20 Reached limit of access per hour

10 API Access denied

Se houver erros, o resultado desta operao ser retornado em XML da seguinte forma:

18

Invalid Product(s) in XMLRecords

111

Invalid eld:NOMEDOCAMPO Record:2

Sempre ser retornado os registros anteriores que obtiveram xito e por ltimo o registro no qual ocorreu o erro.


11/35


XML DE PRODUTOS | 8

Segue a lista com os possveis cdigos de erros () e suas descries ():

111 Campo invlido 121 IDProdutoPai no deve ser informado pois a loja no tem sub-produtos

112 Campo duplicado 122 IDProdutoPai no encontrado

113 Excedeu mximo de registros 123 IDProduto no encontrado114 Sem nome da categoria nem IDCategoria no registro para

incluso

124 IDProdutoPai no pode ser alterado

115 Comando invlido ou no informado 125 Problema na excluso

116 Atingiu mximo de produtos do plano 126 IDProduto no encontrado em UPDATE

117 NomeCat do sub-produto no existe 127 IDCategoria no encontrado

118 Tipo de campo invlido, nunca deveria ocorrer 128 No permite mudar o sub-produto de pai

119 Informado campo IDProduto na incluso 129 Mximo de sub-produtos no produto atingido

120 IDProduto no informado para alterao e excluso

Na tag so retornados os seguintes atributos:

Sent Nmero de registros

Valid Nmero de registros vlidos

Included Nmero de produtos includos

IncludedSub Nmero de sub-produtos includos

Changed Nmero de produtos alterados

ChangedSub Nmero de sub-produtos alterados

Deleted Nmero de produtos excludos

DeletedSub Nmero de sub-produtos excludos

ElapsedSeconds Tempo decorrido da operao

3.2 Excluso de produtos

Estrutura do XML para excluso do cadastro de produtos:

(para excluso o comando deve ser Ee devem ser enviados somente os campos Comandoe IDProduto)

Obs: Para realizar a excluso, os campos Comandoe IDProdutoso obrigatrios. possvel excluir mltiplos produtos por vez.


12/35


XML DE PRODUTOS | 9


0

OK










minutes.






18


123

IDProduto not found




112

Campo duplicado 122

IDProdutoPai no encontrado113 Excedeu mximo de registros 123 IDProduto no encontrado

114 Sem nome da categoria nem IDCategoria no registro para

incluso



13/35


XML DE PRODUTOS | 10













ChangedSub Nmero de sub-produtos alteradosDeleted Nmero de produtos excludos

DeletedSub Nmero de sub-produtos excludos


3.3 Incluso de produtos

Estrutura do XML para incluso do cadastro de produtos:

(para incluso o comando deve ser Ie deve ser enviado, somente os campos que for utilizar)

Obs:Para realizar a incluso, os campos Comandoe NomeCatso obrigatrios e o campo IDProdutoNOdeve ser utilizado. possvel incluir mltiplos produtos por vez.


14/35




0

OK

Obs:Note que o IDProdutogerado automaticamente pelo sistema retornado neste XML.










minutes.






18


119IDProduto should not be informed


15/35




Segue a lista com os possveis cdigos de erros () e suas descries ():


112 Campo duplicado 122 IDProdutoPai no encontrado

113 Excedeu mximo de registros 123 IDProduto no encontrado

114 Sem nome da categoria nem IDCategoria no registro para

incluso














ChangedSub Nmero de sub-produtos alterados

Deleted Nmero de produtos excludosDeletedSub Nmero de sub-produtos excludos



16/35


XML DE PEDIDOS | 13

Estrutura do XML com todos os campos que podem ser alterados na ficha do pedido.

Obs: possvel enviar multiplos pedidos por vez.

4.1 Alterao de pedidos

Estrutura do XML para alterao na ficha dos pedidos: (para alterao, o campo NumPedido obrigatrio)

4XML de pedidos


17/35


XML DE PEDIDOS | 14

Obs: Alm do campo NumPedido obrigatrio ter pelo menos mais um campo. possvel alterar mltiplos pedidos por vez.


0

OK

4.2 Chaves do XMLNumPedido- nico campo obrigatrio do XML de pedidos, que informa o nmero do pedido a alterar.

ObsCurta- campo para informar um pequeno texto de observao do pedido (at 10 caracteres). Em geral, a loja padroniza cdi-gos para este campo.

Exemplo: FP-3-ne - traduo: falta produto - item 3 do pedido - no enviado

Status- status para o qual o pedido ser alterado.

O status a enviar no mtodo OrderUpdate numrico, com os seguintes valores possveis:

1 Novo 3 Em aprovao 5 Aprovado 7 Remetido

2 Cancelado 4 Pendente 6 Liberado

ObjSedex- cdigo do objeto dos Correios, para acompanhamento da remessa pela loja e pelo cliente

ChangeFlagAPI- utilizado para marcar os pedidos que j foram recebidos pelo ERP, evitando que sejam novamente trazidos. Po-dem ser utilizados valores de 1 a 255. Este campo ser automaticamente zerado sempre que ocorrerem alteraes no pedido atravsda loja virtual ou do site administrativo, incluindo alteraes de status e informaes de pagamento retornadas por entidades exter-nas (Cielo, Redecard, PagSeguro etc). Pedidos novos so criados com ChangeFlagAPI=0

Os seguintes relatrios de pedidos podem ser utilizados com o mtodo ReportView para trazer a lista de pedidos da loja:

Lista de pedidos para alteraes via API

Lista de pedidos e detalhes para consultas via API Lista de pedidos alterados para consultas via API


18/35


XML DE PEDIDOS | 15

Nestes relatrios, possvel utilizar um filtro ChangeFlagAPI=0 para trazer somente os pedidos novos. Aps a importao, utilizeo mtodo OrderUpdate para alterar o valor de ChangeFlagAPI e evitar novas importaes redundantes.


0 OK 11 Report/Utility error1 Store not found 12 Invalid StoreID for this logon







minutes.






19

Invalid Order(s) in XMLRecords

53

NumPedido not found


Veja a lista com os possveis cdigos de erros () e suas descries ():51 Excedeu mximo de registros 55 Campo invlido

52 NumPedido no informado 56 Campo duplicado

53 NumPedido no encontrado 57 Sem campos para alterar

54 Status invlido 58 IDPedido no encontrado em UPDATE







19/35


REALIZAO DE TESTES | 16

5Realizao de testes

Disponibilizamos uma pgina de testes para facilitar a realizao de testes de integrao via navegador e assim conhecer melhor ofuncionamento da API. Segue o endereo:

https://www.rumo.com.br/sistema/adm/apitest.asp

Informe os campos obrigatrios StoreName, StoreID, Username e Passwordno quadro Login do usurio. Em seguida, selecioneo mtodo desejado. Preencha os campos que sero exibidos de acordo com o mtodo escolhido.


20/35



5.1 Testes do mtodo "ReportView"Neste teste, ser possvel ver todo o cadastro de produtos da loja no formato da API.

No campo Methodselecione a opo ReportView. No campo ObjectIDinforme 425(ObjectID=425 referente ao relatrioLista de produtos para alteraes via API) e clique em Entrar.

Campos retornados pela API na chave :

ObjectName Nome do relatrioStoreName Nome da lojaExecDate Data de execuo do relatrioFromRecord Registro inicial retornadoToRecord Registro final retornadoParName1, ParName2,ParName3, ParName4, Par-Name5, ParName6, ParName7, ParName8,

Nomes dos parmetros

ParValue1, ParValue2, ParValue3, ParValue4, ParValue5,ParValue6, ParValue7, ParValue8 Valores dos parmetros

Records Registros retornados

ReadRecords Registros lidos


21/35



Como resultado, teremos a seguinte estrutura:

[

Retorno fracionado

O XML de retorno da API do FastCommerce tem limite 4Mb. Quando este limite for atingido, o cdigo 11 ser retornado pela

API, com a seguinte mensagem:

Results page is bigger than 4Mb. Please try again, changing one or more parameters to restrict results.

Para restringir o resultado de relatrios que trazem muitas informaes (exemplo: Lista de produtos), deve-se utilizar os parmetrosdisponveis para o relatrio. Se mesmo utilizando os parmetros o resultado ainda for extenso, existem parmetros adicionais quepermitem fracionar o retorno:

- Page (Pgina)

- QtRecords (Quantidade de registros por pgina)

ou

- FromRecord (Registro inicial solicitado do relatrio)

- ToRecord (Registro final solicitado do relatrio)

Se passar os 4 parmetros os prefernciais so Page e QtRecords.

Na chave Report do retorno do XML, informada a quantidade de registros lidos "ReadRecords".

Por exemplo, se for solicitado o relatrio "Lista de produtos para alteraes via API" passando Page=1 e QtRecords=500, a chaveReport informar a quantidade total de registros em ReadRecords, como no exemplo abaixo:


22/35



Neste caso, a loja tem 3909 registros de produtos e foram retornados do registro 1 ao 500.

Paassando Page=2 e QtRecords=500, sero retornados do registro 501 at o registro 1000, e assim por diante. Ou seja, os parmet-ros Page=2 e QtRecords=500 equivalem a FromRecord=501 e ToRecord=1000.

Desta forma possvel programar um loop para ler os registros de forma fracionada, evitando assim atingir o limite de 4Mb doXML de retorno.

Seleo de campos retornados

Cada relatrio retorna uma conjunto especfico de campos. Entretanto, nem sempre todos estes campos so utilizados pela suaaplicao.

Atravs do parmetro Fields, possvel selecionar quais campos sero retornados pela API, para que o relatrio no retorne camposque no sero utilizados pela sua aplicao. Isto otimizar a gerao, o trfego e o processamento dos resultados.

Por exemplo, o relatrio "Lista de produtos para alteraes via API" possui dezenas de campos:

Comando,NomeCat,IDCategoria,IDProduto,CodProd,CodBarrasProd,NomeProd,Estoque,...,...,ProfundidadeProd,DataProdAlteracao,ChangeFlagProdAPI

Se a sua aplicao deseja receber apenas os campos IDProduto e Estoque, basta informar no parmetro Fields os campos entre

vrgulas: IDProduto,Estoque

O volume menor de dados otimizar o fluxo de dados entre as redes e o tempo de processamento.


23/35



5.2 Testes do mtodo "UtilityExecute"

Neste teste, ser possvel ver todo o cadastro de produtos da loja no formato da API.

No campo Methodselecione a opo UtilityExecute, no campo ObjectIDinforme 248. No campo Par4informe 15que serseu novo estoque de todos os produtos (ObjectID=248 referente ao utilitrio Alterao no estoque de produtos) e clique emEntrar.

Como resultado, teremos a seguinte estrutura, informando que 10 registros foram afetados:

0

OK

10


24/35



5.3 Testes do mtodo "OrderUpdate"


No campo Methodselecione a opo OrderUpdate. No campoXMLRecordsinforme o XML com os registros que deseja alterare clique em Entrar.


0

OK


25/35



5.4 Testes do mtodo "ProductManagement"


No campo Methodselecione a opo ProductManagement. No campoXMLRecordsinforme o XML com os registros quedeseja alterar e clique em Entrar.


0

OK


26/35



5.5 Exemplo de VBS

Segue exemplo de integrao em VBScript:

Option Explicit

DimoHTTP,sHTTP,sParam

'Exemplo de relatriosParam=""BuildParam "StoreName","SP Departamentos"BuildParam "StoreID",184BuildParam "Username","Paulo"BuildParam "Password","123456"BuildParam "method","ReportView"BuildParam "ObjectID",424 'ObjectID do relatrio "Lista de pedidos para alteraes via API"BuildParam "Par1",4BuildParam "OutputFormat",1ExecutaAPI

'Exemplo de alterao de um pedidosParam=""BuildParam "StoreName","SP Departamentos"BuildParam "StoreID",184BuildParam "Username","Paulo"BuildParam "Password","123456"BuildParam "method","OrderUpdate"BuildParam "XMLRecords",""ExecutaAPI

SubBuildParam(sName,sValue)sParam=sParam & sName &"="& URLEncode(sValue) &"&"

End SubFunctionURLEncode(sText)Dimi,char,sOut,AscCharFori=1 To Len(sText)char=Mid(sText,i,1)AscChar=Asc(char)IfAscChar=32 Then 'Converte espao para +sOut=sOut &"+"

ElseIf(AscChar122) OR (AscChar>57 AND AscChar90 AND AscChar


27/35


DICIONRIO | 24

6Dicionrio

Seguem os tipos, campos e descries da ficha do Produto:

Coluna/Campo Tipo/Opes Descrio

Comando I=Incluso

A=Alterao

E=Excluso

Indica a ao a ser realizada

NomeCat varchar(25) Nome da categoria

IDProduto int ID interno do banco de dados

CodProd varchar(15) Cdigo de referncia do produto, exibido ao visitante

NomeProd varchar(100) Nome do produtoPeso real Peso do produto. A unidade (gramas ou quilogramas) definida na pgina Dados da loja

Descricao varchar(200) Descrio curta do produto

DescrLonga varchar(1024) Descrio longa do produto

DescrURL varchar(100) URL para mais detalhes do produto

URLTarget bit Se TRUE, URL do campo DescrURL Ser exibida em uma nova janela

Estoque smallint Quantidade de itens do produto em estoque

EstoqueMinimo smallint Quantidade mnima de itens do produto em estoque. Quando estoque ficar menor, ser enviado e-mail para o

lojista. Se 0, no tem mnimo.

Disponivel bit Se TRUE, produto est disponvel no site

ICMS real Percentual de ICMS na origem do Produto, para gerao de nota fiscal

Custo money Custo do produto, nunca exibido ao visitante, utilizado para clculo nos relatrios de lucratividade.Preco money Preo de venda varejo (B2C)

PrecoProm money Preo promocional no varejo (B2C)

PrecoB2B money Preo de venda atacado (B2B)

PrecoB2BProm money Preo promocional no atacado (B2B)

DataPromInicio smalldatetime Data de inicio da promoo, pode-se informar a hora. Ex: 10/05/2002 10:30

DataPromFim smalldatetime Data de trmino da promoo, pode-se informar a hora. Ex: 10/05/2002 10:30

Lancamento bit Se TRUE, indica que o produto lanamento

EmDestaque bit Se TRUE, indica que o produto tem destaque no layout da loja. Ver tag

ImagemProd varchar(200) Nome do arquivo com a imagem principal do produto com extenso JPG, PNG, GIF ou SWF

ImagemDet varchar(200) Nome do arquivo com a imagem de detalhe do produto com extenso JPG, PNG, GIF ou SWF

ImagemAmp varchar(200) Nome do arquivo com a imagem ampliada do produto com extenso JPG, PNG, GIF ou SWF

Adicional1 varchar(1024) ID para informao adicional sobre o produto, indicado em

Descritor especial 1. Se multivalorado colocar entre vrgulas.





AdicionalD1 varchar(2048) Texto da informao adicional sobre o produto, indicado em

Descritor simples 1. Se multivalorado, colocar entre vrgulas.

AdicionalD2 varchar(2048) Texto da informao adicional sobre o produto, indicado em

Descritor simples 2. Se multivalorado, colocar entre vrgulas.

AdicionalD3 varchar(2048) Texto da informao adicional sobre o produto, indicado emDescritor simples 3. Se multivalorado, colocar entre vrgulas.

Cores varchar(1024) ID das cores disponveis no produto. Se multivalorado, colocar entre vrgulas.


28/35


DICIONRIO | 25

OrdemProd tinyint Indica a ordem de exibio do produto. Ordenao decrescente.

IDProdutoPai int Se preenchido, indica que este um sub-produto e qual o ID do produto Pai

RamoProd tinyint Indica o departamento no Shopping Virtuose.

MaisProd varchar(50) Indica termos de busca para produtos relacionados a estes entre vrgula. (cross-selling)

DataVencimento smalldatetime Indica a data de vencimento do produto, Quando ser enviado e-mail de alerta ao lojista

DiasAvisoVencimento smallint Nmeros de dias antes do vencimento do produto, quando ser enviado o primeiro e-mail de alerta para olojista

DiasReposicao smallint Nmero de dias, em mdia em que o produto novamente adquirido pelo cliente. Decorridos estes dias aps o

pedido, um e-mail ser enviado ao cliente para sugerir a reposio.

IDParceiroProd int Informe o ID do parceiro que ter exclusividade para o preo promocionaldo produto. Desta forma, possvel

criar promoes vlidas somente paravisitantes cujo acesso seja proveniente de um parceiro ou revendedor

especfico.

MaxParcelasProd tinyint Nmero mximo de parcelas para pedidos que incluam este produto.

IDCategoria int ID interno da categoria cadastrada. No CSV de produtos, ao incluir um produto, obrigatrio o campo Nome-

Cat (com o nome da categoria do produto), o sistema inclui o produto e cria a categoria caso ela no exista.

Na API, ao incluir produtos na loja, o campo NomeCat ou IDCategoria deve ser informado. Se a categoria for

existente pode ser informado o IDCategoria, sem passar o NomeCat.

XMLParcelasProd tinyint Infica o nmero de parcelas utilizadas para exibir o parcelamento na pgina que lista os produtos em XML

(XMLProdutos.asp). A lista de produtos em XML utilizado pelos portais de comparao de preos e shop-

ping virtuais, para capturar os produtos da loja.

Embalavel bit Se TRUE, indica o cliente pode solicitar que este produto seja embalado para presente. Deve-se informar

FALSE nos produtos que no podero ser embalados para presente devido ao seu tamanho (exemplo:

bicicleta) ou por alguma outra restrio. Este campo utilizado se a loja utilizar as opes (4), (5) ou (6) no

campo "Presente" da pgina "Envio & frete" do site administrativo onde o cliente tem a opo de informar

quais produtos do pedido deseja embalar para presente.

DescrHTM varchar(25) Indica o nome do arquivo HTML contendo descrio adicional do produto. O contedo do arquivo HTM ser

includo na posio da tag especial , caso esta tag exista no arquivo personalizado de exibio do

layout de produtos na loja (EstiloProduto.htm)

MetaKeywordsProd varchar(200) Palavras-chave (keywords) especficas para o produto. Os termos devemser separados por vrgula. Exemplo:nokia,celular com wi-fi,mp3,rede 3G,GPSSo inseridas em "meta tag keyword", no cdigo fonte da loja.

CodBarrasProd varchar(25) Cdigo de barras do produto

ChangeFlagProdAPI tinyint Utilizado para marcar os produtos que j foram recebidos pelo ERP, evitando que sejam novamente trazidos.

Veja mais detalhes na seo 3.1.

IsProdutoGrande bit Indica se o produto considerado grande para clculo de frete, usando peso cbico e tabela para frete grande.

DataProdAlteracao smalldatetime Data/hora da ltima alterao do produto (exceto o cancelamento e descancelamento de pedidos)

IDRamo int Indica o ID do ramo

NomeRamo varchar(80) Nome do Ramo. Ex: Beleza & Sade, Bermuda Infantil, Bonecos e Personagens, etc.

IDRamoPai int Indica o ID do ramo Pai, nulo se for o primeiro nvel

IDCategoria int ID interno do banco de dados

Categoria varchar(25) varchar(25)

Ordem tinyint Indica a ordem de exibio. Ordenao decrescente.

IDCategoriaPai int Se preenchido, indica que esta uma sub-categoria e qual o ID da categoria Pai.

Prods real Quantidade de produtosSeguem os tipos, campos e descries da ficha do Clientes:


Cadastro em smalldatetime Indica a data de cadastramento do cliente

Tipo Opes: PF ou PJ Indica se o cliente pessoa fsica ou jurdica

Empresa varchar(50) Nome da empresa, somente quando B2B

Contato varchar(50) Nome

E-mail varchar(50) E-mail

CNPJ/CPF varchar(14) CPF ou CNPJ


29/35


DICIONRIO | 26

IE/RG varchar(20) Inscrio estadual ou RG

Ramo varchar(30) Profisso do cliente ou ramo de atuao da empresa

% Desc real Percentual de desconto global nos produtos para o cliente.

Endereo varchar(70) Endereo

Bairro varchar(25) Bairro

Cidade varchar(20) CidadeEstado char(2) Estado

Pas varchar(20) Pas

CEP varchar(9) CEP

Telefone varchar(20) Telefone

FAX varchar(20) FAX

Obs curta varchar(10) Texto de apoio sobre o cliente, para uso interno da loja.

Data Nasc smalldatetime Data de nascimento

Pagtos varchar(80) Indica as formas de pagamento que este cliente pode utilizar, quando a loja tem formas de pagamento

por cliente.

Sexo Opes: PF ou PJ Sexo do cliente

ltima alterao smalldatetime Data/hora da ltima alterao do cliente

Logradouro varchar(70) Endereo do cliente

Endereo nmero varchar(70) Nmero do endereo

Endereo complemento varchar(70) Complemento do endereo

Celular varchar(20) Telefone mvel completo para contato e envio SMS (com DDD)

Campo 1 varchar(100) Campo adicional 1



Seguem os tipos, campos e descries da ficha do Pedidos:


Nome Cliente varchar(50) Nome do cliente

E-mail Cliente varchar(50) E-mail do cliente

Telefone varchar(20) Telefone do cliente

Cidade varchar(20) Cidade do cliente

Estado char(2) Estado do cliente

Nm Pedido int Nmero do pedido

Produto(s) do Pedido varchar(100) Nome do produto

Ref. varchar(15) Referncia do produto

Qtd smallint Quantidade de itens do produto

Total sem frete money Valor total do pedido, SEM o frete

Frete money Valor do frete

Total com frete money Valor total do pedido, COM o frete

Pagamento varchar(50) Opo de pagamento escolhida pelo cliente

Carto Opes:

AMEX, Diners, Mastercard, VISA,

Hipercard, Aura e Elo

Bandeira de carto de crdito

Status opes:

Novo, Cancelado, em aprovao,

Pendente, Aprovado, Liberado e

Remetido

Status do pedido

Feito em smalldatetime Data em que o pedido foi feito

Obs curta varchar(10) Texto de apoio sobre o pedido, para uso interno da loja


30/35


DICIONRIO | 27

Entregue Em smalldatetime Data de entrega do pedido ao destinatrio pela transportadora

Objeto SEDEX varchar(13) Cdigo fornecido pelos Correios para acompanhamento de remessas

MoipCodigo varchar(12) Cdigo da transao retornada pelo MoIP. Ex: 11202666

MoipStatus tinyint Status da transao retornada pelo MoIP. Ex: 5

Os valores possveis para o campo MoipStatus:

(1) Autorizado: Pagamento autorizado.

(2) Iniciado: Pagamento foi iniciado, porm sem confirmao de finalizao at o

momento

(3) BoletoImpresso: Boleto visualizado pelo cliente

(4) Concludo: Pagamento creditado em conta e disponvel para saque.

(5) Cancelado: Pagamento foi cancelado

(6) EmAnalise: Pagamento em anlise de risco

(7) Estornado: Pagamento foi estornado

(8) EmRevisao: Pagamento em reviso pelo Moip

(9) Reembolsado: Pagamento foi reembolsado

AkatusID varchar(36) O ID da transao na Akatus. Ex: cfbda716-906b-4f69-83f8-4cdae19cb3ee

AkatusStatus varchar(50) Status da transao na Akatus. Ex: CanceladoOs valores possveis para o campo AkatusStatus:

Aguardando Pagamento, Em Anlise, Aprovado e Cancelado.

ChangeFlagAPI tinyint Utilizado para marcar os pedidos que j foram recebidos pelo ERP, evitando que sejam

novamente trazidos.

Seguem os tipos, campos e descries da ficha do Detalhes:


Nm int Nmero do pedido

Feito em smalldatetime Data em que o pedido foi feitoNome varchar(50) Nome do cliente

E-mail varchar(50) E-mail do cliente

Empresa varchar(50) Nome da empresa, somente quando B2B

CPF/CNPJ varchar(14) CPF ou CNPJ

RG/IE varchar(20) Inscrio estadual ou RG

Endereo varchar(70) Endereo

Bairro varchar(25) Bairro

Cidade varchar(20) Cidade

Estado char(2) Estado

Pas varchar(20) Pas

CEP varchar(9) CEP

Telefone varchar(20) Telefone

FAX varchar(20) FAX

Nascido em smalldatetime Data de nascimento

Obs cliente varchar(10) Texto de apoio sobre o cliente, para uso interno da loja.

Nome Pedido varchar(50) Nome para entrega do pedido

E-mail Pedido varchar(50) E-mail para entrega do pedido

Endereo Pedido varchar(70) Endereo de entrega

Bairro Pedido varchar(25) Bairro de entrega

Cidade Pedido varchar(20) Cidade de entrega

Estado Pedido char(2) Estado de entrega

Pas Pedido varchar(20) Pas de entrega

CEP Pedido varchar(9) CEP de entrega

Telefone Pedido varchar(20) Telefone de entrega


31/35


DICIONRIO | 28

FAX Pedido varchar(20) FAX de entrega

Total sem frete money Valor total do pedido, SEM o frete

Frete money Valor do frete

Pagamento varchar(50) Opo de pagamento escolhida pelo cliente

Carto Opes:

AMEX, Diners, Mastercard,

VISA, Hipercard, Aura e Elo

Bandeira de carto de crdito

Parcelas tinyint Nmero de parcelas

Presente opes: S ou N Se para presente

Status opes:

Novo, Cancelado, em aprova-

o, Pendente, Aprovado,

Liberado e Remetido

Status do pedido

Obs Pedido varchar(10) Texto de apoio sobre o pedido, para uso interno da loja

Entregue em smalldatetime Data de entrega do pedido ao destinatrio pela transportadora

Obj SEDEX varchar(13) Cdigo fornecido pelos Correios para acompanhamento de remessas

Ref. Produto varchar(15) Referncia do produto

Nome Produto varchar(100) Nome do produto

Qtd smallint Quantidade de itens do produto

Preo unit money Preo unitrio do produto

Msg cliente varchar(255) Comentrios feitos pelo cliente

Local de entrega varchar(50) Local de entrega do pedido

Parceiro varchar(30) Quando o pedido foi feito atravs de um parceiro, informa o nome do parceiro

ThisfTransacao varchar(14) Cdigo de transao com carto de crdito recebido da Thisf, se a loja utiliza

Esp1 varchar(30) Informao adicional sobre o produto, indicado em Descritor especial 1



Simp1 varchar(30) Informao adicional sobre o produto, indicado em Descritor simples 1



DescontoTotalSF real Desconto em % aplicado no total do pedido SEM o frete

IDProduto int ID interno do produto no banco de dados

Valor embalagem smallmoney Valor para a embalagem de presente

Cor varchar(30) Cor solicitada do produto

Cod. barras varchar(25) Cdigo de barras do produto

ObsCurta varchar(10) Campo para informar um pequeno texto de observao do pedido

ccNum varchar(19) Nmero do carto de crditoccNome varchar(30) Nome gravado no carto de crdito

ccSeg varchar(4) Cdigo de segurana do carto de crdito

ccDataExp varchar(7) Ms/Ano em que o carto expira (Ex: 05/2001)

ccAuthCod varchar(10) Autorizao da administradora do carto

ccNumCV varchar(9) Nmero do comprovante de venda, emitido pela administradora do carto

ccNumAutent varchar(27) Nmero de autenticao da venda, emitido pela administradora do carto

ccNumPrg varchar(1) Retorno do Komerci SecureCode (0,1,2,3,4)

ccCodRet varchar(2) Cdigo de retorno do processo de autorizao da venda, informado pela administra-

dora do carto

ccORIGEM_BIN char(3) Cd pas emissor Komerci

ccEndereco varchar(100) Endereo reportado pela Redecard via AVS

VisaTID char(20) Identificao da transao na Cielo

VisaLR varchar(4) Cd de retorno da Cielo


32/35


DICIONRIO | 29

VisaARP varchar(6) Cd aprovao bancria informado pela Cielo, somente para pedidos autorizados.

VisaCOD varchar(4) Cdigo do resultado da captura do pedido informado pela Cielo

VisaAuth varchar(3) Indica se o pedido foi autenticado pelo banco emissor: 0 ou vazio=transao sem

autenticao 1=ok 2=negado 3=falha

VisaCAP money Valor capturado informado pela Cielo

VisaBank varchar(4) Cdigo do banco emissor do cartoThisfAutorizacao varchar(6) Cdigo de autorizao recebido pela Thisf da administradora do carto

MoipCodigo varchar(12) Cdigo da transao retornada pelo MoIP

MoipStatus tinyint Status da transao retornada pelo MoIP

AkatusID varchar(36) O ID da transao na Akatus.

AkatusStatus varchar(50) Status da transao na Akatus

Tipo Opes: PF ou PJ Indica se o cliente pessoa fsica ou jurdica


Endereo nmero varchar(70) Nmero do endereo

Endereo complemento varchar(70) Complemento do endereo

Celular varchar(20) Telefone mvel completo para contato e envio SMS (com DDD)




Logradouro Pedido varchar(70) Endereo

Endereo nmero Pedido varchar(70) Nmero do endereo

Endereo complemento Pedido varchar(70) Complemento do endereo

Campo 1 Pedido varchar(100) Campo adicional no pedido 1



ThisfAutorizacao varchar(6) Cdigo de autorizao recebido pela Thisf da administradora do carto

Embalar Produto Opes: S ou N Indica se produto deve ser embaladoValor embalagem produto smallmoney Valor para embalagem do produto

Desconto Cupom real Valor em $ do desconto no pedido

ChangeFlagAPI tinyint Utilizado para marcar os pedidos que j foram recebidos pelo ERP, evitando que

sejam novamente trazidos.

Alterado em smalldatetime Data da ltima alterao do pedido


Seguem os tipos, campos e descries da ficha de Acessos:

Method Opes:

ReportView, OrderUpdate, ProductManage-ment, NfeOperation, UtilityExecute.

Indica o mtodo

Nome varchar(80) Indica o nome do relatrio, utilitrio.

Data execuo datetime Data/hora de incio do processamento

Usurio varchar(20) Nome do usurio

Regs int Quantidade de registros lidos, includos, alterados ouexcludos

Parm 1 varchar(15) Legenda para o parmetro 1

Valor 1 varchar(100) Valor informado no parmetro 1






33/35


DICIONRIO | 30






Valor 6 varchar(100) Valor informado no parmetro 6Parm 7 varchar(15) Legenda para o parmetro 7





34/35


DICIONRIO | 31

7Melhores prticas

Seguem algumas dicas para melhor utilizao da API:

1)Para maximizar a performance na alterao de produtos, inclua no XML somente os campos obrigatrios Comando e ID-Produto e os campos que sero alterados. No inclua no XML campos que no sero alterados.

2)Existe um limite de at 300 chamadas API por hora. Cada acesso contabiliza um pageview, independente da quantidade deregistros includos, alterados ou removidos. Para maximizar o uso de cada chamada aos mtodos OrderUpdate e ProductManage-ment, possvel incluir mais de um registro que ser afetado em cada chamada. Por exemplo, possvel incluir, alterar e excluirvrios produtos em uma mesma chamada ao mtodo ProductManagement.

3)Nos mtodos UtilityExecute e ReportView, preencha os parmetros de data sempre que estes existirem no objeto chamado.Informe sempre o menor perodo de tempo possvel, para maximizar a performance e evitar timeouts.

4) possvel informar a hora nos parmetros de data. Se somente a data for informada, sem a hora, esta ser considerada 00:00(meia-noite).

Exemplo:Para obter todos os pedidos do dia 15/09/2011, informe De:15/9/2011 00:00 At:16/9/2011 00:00 ou, de forma equiva-lente, De:15/9/2011 At:16/9/2011.

5)Os relatrios do FastCommerce podem ser acessados via XML, atravs do mtodo ReportView. Frequentemente inclumos no-vos campos nas dezenas de relatrios do FastCommerce, sem aviso prvio. Por esta razo, os sistemas integrados ao FastCommerceno devem ser afetados por estas incluses de campos, independente da posio.

Uma programao bem feita de leitura de XML no deve ser "amarrada" com relao posio do campo, dentro da mesmahierarquia. Se acrescentarmos campos antes ou depois do campo desejado, sem alterar a estrutura do XML, seu programa deve sercapaz de acessar normalmente os ns pr-existentes.

O XML no deve ser lido como uma grande "string". Ao invs disto, seu programa deve manipular o XML como uma estruturahierrquica, com acesso direto e individualizado a qualquer n, independente dos ns anteriores e posteriores. Uma sugesto utili-zar objeto para leitura e "parse" do XML, como por exemplo, o Microsoft.XMLDOM, que usamos no FastCommerce.

XML DOM Reference

http://msdn.microsoft.com/pt-br/library/aa925430.aspx


35/35

Rumo Web Informtica, Av. Rouxinol, 1041. - So Paulo, SP - CEP 08040310 - So Paulo: (11) 5052-9339 Demais regies: 0800 774 016 www.fastcommerce.com.br

fast commerce a pi

Documents