Fastcommerce Developers Center

Sobre a API

A API (Application Programming Interface) do Fastcommerce permite a sistematização remota de diversas tarefas realizadas regularmente pelos usuários através do site administrativo da loja virtual. Com esta API é possível integrar aplicativos externos tais como ERPs, CRMs, sistemas de BI, gateways de pagamento etc, e através destes aplicativos executar métodos da API para gerenciamento de produtos e pedidos, obter dados de relatórios e executar utilitários do Fastcommerce.

1 - Acessando a API

O acesso à API ocorre sempre através do protocolo HTTPS (porta 443), com certificação EV SSL. A execução de cada método inicia-se através de uma solicitação enviada via FORM POST e termina em seguida com uma única resposta em XML.

A resposta à execução de cada método é síncrona e pode ocorrer de forma quase imediata ou pode demorar até alguns minutos, dependendo do método e da quantidade de registros lidos ou alterados.

ATENÇÃO:

Existe um limite no volume de acessos por hora aos métodos da API. Veja os detalhes no parágrafo 2 do item Melhores Práticas).

2 - Histórico de Versões

A versão atual da API é 2.3.

3 - Loja para testes

O Fastcommerce não tem um ambiente de sandbox para realizar testes. Sugerimos portanto que crie uma loja para testes para desenvolver com a API.

Acesse o endereço http://novaloja.fastcommerce.com.br para criar sua loja de testes. Após cadastrá-la, avise-nos qual é o nome e o ID desta nova loja através do e-mail comercial@fastcommerce.com.br para que possamos deixar a loja em implantação e a mesma não seja cancelada após o prazo de avaliação.

4 - Usuário para testes

O usuário que vai consumir a API precisa basicamente de acesso aos relatórios e utilitários da loja, pois é através dele que as consultas e alterações são feitas.

Essa etapa deve ser realizada por um usuário da loja com permissão para criar novos usuários.

Acesse a administração da loja e no menu "Usuários" clique na opção "Incluir usuário".

O cadastro pode ser preenchido como no exemplo abaixo.

5 - Melhores Práticas

Seguem algumas dicas para melhor utilização da API:

• 5.1) Para maximizar a performance na alteração de produtos, inclua no XML somente os campos obrigatórios Comando e IDProduto e os campos que serão alterados. Não inclua no XML campos que não serão alterados.

• 5.2) Existe um limite de até 300 chamadas à API por hora. Para maximizar o uso de cada chamada aos métodos OrderUpdate e ProductManagement, é possível incluir mais de um registro que será afetado em cada chamada. Por exemplo, é possível incluir, alterar e excluir vários produtos em uma mesma chamada ao método ProductManagement. Se este limite for excedido, novas consultas serão bloqueadas até a próxima virada da hora. Por exemplo, se forem feitas mais de 300 consultas entre 13h e 14h, somente após as 14h será possível fazer novos acessos à API, e assim por diante. Quando o limite for excedido, o código 20 será retornado pela API, com a seguinte mensagem: Reached limit of access per hour.

• 5.3) Nos métodos UtilityExecute e ReportView, preencha os parâmetros de data sempre que estes existirem no objeto chamado. Informe sempre o menor período de tempo possível, para maximizar a performance e evitar timeouts.

• 5.4) É possível informar a hora nos parâmetros 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 equivalente, De: 15/9/2011 Até: 16/9/2011.

• 5.5) Os relatórios do Fastcommerce podem ser acessados via XML, através do método ReportView. Frequentemente incluímos novos campos nas dezenas de relatórios do Fastcommerce, sem aviso prévio. Por esta razão, os sistemas integrados ao Fastcommerce não devem ser afetados por estas inclusões de campos, independente da posição.

• 5.6) Uma programação bem feita de leitura de XML não deve ser "amarrada" com relação à posição do campo, dentro da mesma hierarquia. Se acrescentarmos campos antes ou depois do campo desejado, sem alterar a estrutura do XML, seu programa deve ser capaz de acessar normalmente os nós pré-existentes.

• 5.7) O XML não deve ser lido como uma grande "string". Ao invés disto, seu programa deve manipular o XML como uma estrutura hierárquica, com acesso direto e individualizado a qualquer nó, independente dos nós anteriores e posteriores. Uma sugestão é utilizar objeto para leitura e "parse" do XML, como por exemplo, o Microsoft.XMLDOM.

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

• 5.8) O XML de envio da API do FastCommerce tem limite de 1Mb.

6 - Métodos da API

O método informa qual a ação desejada na chamada à API. Cada chamada deve obrigatoriamente conter um dos quatro métodos abaixo:

• ReportView - Exportação de dados dos relatórios do Fastcommerce em formato indicado em OutputFormat (padrão é XML)
• UtilityExecute - Alterações realizadas pelos utilitários administrativos
• OrderUpdate - Alterações dos status, observações curtas e objetos dos Correios dos pedidos.
• ProductManagement - Gerenciamento de produtos (alteração, exclusão e inclusão)

A comunicação se inicia através de um FORM POST para o seguinte endereço:
https://www.rumo.com.br/sistema/adm/APILogon.asp

Seguem abaixo os campos obrigatórios deste POST:

Caso o método seja ReportView ou UtilityExecute os campos são:

Se passar os 4 parâmetros de paginação, os preferenciais são Page e QtRecords. Neste caso, os dois parâmetros devem ser passados para que sejam considerados.

As opções de formato de retorno são as mesmas oferecidas na funcionalidade de relatórios do site administrativo. Na integração de aplicativos, sugerimos que utilize a opção 5 (XML API), que é o padrão.

Exemplo de FORM:

                
<form name="Logon" action="https://www.rumo.com.br/sistema/adm/APILogon.asp" method="POST">
  <input type="text" name="StoreName" value="Nome da loja">
  <input type="text" name="StoreID" value="99999">
  <input type="text" name="Username" value="Admin">
  <input type="password" name="Password" value="******">
  <input type="text" name="method" value="ReportView">
  <input type="text" name="ObjectID" value="425"> <!-- *** -->
  <input type="text" name="ObjectName" value="Lista de produtos para alterações via API"> <!-- *** -->
  <input type="text" name="Par1" value="Nome da categoria"> <!-- opcional -->
  <input type="text" name="Par2" value="Ref/Nome/Descr"> <!-- opcional -->
  <input type="text" name="Par3" value="false"> <!-- opcional -->
  <input type="text" name="Par4" value="false"> <!-- opcional -->
  <input type="text" name="Par5" value="11/05/2016"> <!-- opcional -->
  <input type="text" name="Par6" value="12/05/2016"> <!-- opcional -->
  <input type="text" name="Par7" value="1"> <!-- opcional -->
  <input type="text" name="Page" value="1"> <!-- opcional -->
  <input type="text" name="QtRecords" value="100"> <!-- opcional -->
</form>
                
              

Se o ObjectID for informado, não é necessário informar o ObjectName.

Para ver a lista completa de relatórios e utilitários disponíveis, seus respectivos ObjectID e os parâmetros de cada um deles, utilize o relatório (FC) Lista de relatórios e utilitários.

Qualquer relatório ou utilitário pode ser executado, mas existem relatórios que foram criados especificamente para utilização com a API:

• Lista de produtos para alterações via API
• Lista de pedidos para alterações via API
• Lista de pedidos e dados de cartões de crédito
• 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
• Dados da loja para consultas via API

Caso o método seja OrderUpdate ou ProductManagement, o campo obrigatório que contém todos os registros é o seguinte:

Exemplo de FORM:

                
<form name="Logon" action="https://www.rumo.com.br/sistema/adm/APILogon.asp" method="POST">
 <input type="text" name="StoreName" value="Nome da loja">
 <input type="text" name="StoreID" value="99999">
 <input type="text" name="Username" value="Admin">
 <input type="password" name="Password" value="******">
 <input type="text" name="method" value="OrderUpdate ou ProductManagement">
 <input type="text" name="XMLRecords" value="Conteúdo em XML com todos os registros">
</form>
                
              

7 - Permissões de acesso

Para o acesso a API, é necessário que o usuário tenha permissões de acordo com cada método:

Exemplo: Se o ObjectID escolhido for um relatório estatístico, o usuário precisa ter acesso aos relatórios estatísticos.

Atenção:

Acessos à API não devem estar diretamente relacionados aos acessos a qualquer página da loja virtual, ou seja, cada acesso de cliente da loja não deve corresponder a um acesso à API. Para evitar que isto ocorra, existe uma limitação no volume de acessos por hora aos métodos da API.

Obs: É extramente recomendado criar um usuário específico para cada aplicação que for utilizar a API. Este usuário deve ter nome de usuário e senha fortes e únicas. Insira as permissões de acordo com que a aplicação irá utilizar. Por exemplo, se a aplicação irá apenas acessar os dados de produtos, basta inserir acesso a relatórios de produtos e em todos os demais campos deixar sem acesso.

8 - Exemplos de XML

8.1 - Inclusão de produtos

Estrutura do XML para inclusão do cadastro de produtos:

Para inclusão o comando deve ser I e devem ser enviados somente os campos que for utilizar.

                
<Records>
  <Record>
    <Field Name="Comando" Value="I" />
    <Field Name="NomeCat" Value="Camisetas" />
    <Field Name="CodProd" Value="ABC0001" />
    <Field Name="NomeProd" Value="Polo Seleção Brazil" />
    <Field Name="ChangeFlagProdAPI" Value="1" /> 
  </Record>
  <Record>
    <Field Name="Comando" Value="I" />
    <Field Name="NomeCat" Value="Camisetas" />
    <Field Name="CodProd" Value="ABC0002" />
    <Field Name="NomeProd" Value="Polo Seleção Italiana" />
    <Field Name="ChangeFlagProdAPI" Value="1" />
  </Record>
</Records>
                
              

Obs: Para realizar a inclusão, os campos Comando e NomeCat são obrigatórios e o campo IDProduto NÃO deve ser utilizado.

É possível incluir múltiplos produtos por vez.

O resultado desta operação será retornado em XML. Segue o modelo:

                
<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="I" />
    <Field Name="NOMECAT" Value="Camisetas" />
    <Field Name="CODPROD" Value="ABC0001" />
    <Field Name="NOMEPROD" Value="Polo Seleção Brazil" />
    <Field Name="CHANGEFLAGPRODAPI" Value="1" />
    <Field Name="IDPRODUTO" Value="888888" />
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="I" />
    <Field Name="NOMECAT" Value="Camisetas" />
    <Field Name="CODPROD" Value="ABC0002" />
    <Field Name="NOMEPROD" Value="Polo Seleção Italiana" />
    <Field Name="CHANGEFLAGPRODAPI" Value="1" />
    <Field Name="IDPRODUTO" Value="999999" />
  </Record>
  <ErrCode>0</ErrCode>
  <ErrDescr>OK</ErrDescr>
  <Stats Sent="2" Valid="2" Included="2" IncludedSub="0" Changed="0" ChangedSub="0" Deleted="0" DeletedSub="0" ElapsedSeconds="0,000"/>
</API>
                
              

Obs: Note que o IDProduto gerado automaticamente pelo sistema é retornado neste XML.

Veja a lista com os possíveis códigos de erros (<ErrCode>) e suas descrições (<ErrDescr>):

Se houver erros, o resultado desta operação será retornado em XML da seguinte forma:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="I" />
    <Field Name="NOMECAT" Value="Camisetas" />
    <Field Name="CODPROD" Value="ABC0001" />
    <Field Name="NOMEPROD" Value="Polo Seleção Brazil" />
    <Field Name="CHANGEFLAGPRODAPI" Value="1" />
    <Field Name="IDPRODUTO" Value="888888" />
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="I" />
    <Field Name="NOMECAT" Value="Camisetas" />
    <Field Name="CODPROD" Value="ABC0002" />
    <Field Name="NOMEPROD" Value="Polo Seleção Italiana" />
    <Field Name="CHANGEFLAGPRODAPI" Value="1" />
    <Field Name="IDPRODUTO" Value="999999" />
  </Record>
  <ErrCode>18</ErrCode>
  <ErrDescr>Invalid Product(s) in XMLRecords</ErrDescr>
  <IntCode>119</IntCode>
  <IntDescr>IDProduto should not be informed</IntDescr>
  <Stats Sent="2" Valid="1" Included="1" IncludedSub="0" Changed="0" ChangedSub="0" Deleted="0" DeletedSub="0" ElapsedSeconds="0,000"/>
</API>
              

Sempre será retornado os registros anteriores que obtiveram êxito e por último o registro no qual ocorreu o erro. Neste caso, no segundo produto foi enviado o campo IDProduto indevidamente para uma inclusão de produto.

Segue a lista com os possíveis códigos de erros (<IntCode>) e suas descrições (<IntDescr>):

Na tag <Stats> são retornados os seguintes atributos:

8.2 - Alteração de produtos

Estrutura do XML para alteração do cadastro de produtos:

Para alteração o comando deve ser A e devem ser enviados somente os campos que forem alterados.

<Records>
  <Record>
    <Field Name="Comando" Value="A" /> 
    <Field Name="IDProduto" Value="999999" /> 
    <Field Name="NomeProd" Value="Polo Seleção Brazil" />
    <Field Name="ChangeFlagProdAPI" Value="1" />
  </Record>
  <Record>
    <Field Name="Comando" Value="A" />
    <Field Name="IDProduto" Value="888888" /> 
    <Field Name="NomeProd" Value="Polo Seleção Italiana" />
    <Field Name="ChangeFlagProdAPI" Value="1" />
  </Record>
</Records>
              

Neste exemplo, será realizada somente a alteração do nome do produto.

Obs: Para alterar produtos, os campos Comando e IDProduto são obrigatórios. É possível alterar múltiplos produtos por vez.

O resultado desta operação será retornado em XML. Segue o modelo:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="A" /> 
    <Field Name="IDPRODUTO" Value="999999" />
    <Field Name="NOMEPROD" Value="Polo Seleção Brazil" />
    <Field Name="CHANGEFLAGPRODAPI" Value="1" />
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="A" /> 
    <Field Name="IDPRODUTO" Value="888888" />
    <Field Name="NOMEPROD" Value="Polo Seleção Italiana" />
    <Field Name="CHANGEFLAGPRODAPI" Value="1" />
  </Record>
  <ErrCode>0</ErrCode>
  <ErrDescr>OK</ErrDescr>
  <Stats Sent="2" Valid="2" Included="0" IncludedSub="0" Changed="2" ChangedSub="0" Deleted="0" Deleted-Sub="0" ElapsedSeconds="0,000"/>
</API>
              

ChangeFlagProdAPI: esta chave é utilizada para marcar os produtos que já foram recebidos pelo ERP, evitando que sejam novamente trazidos.

Pode conter valores de 1 a 255. Este campo será automaticamente zerado sempre que ocorrerem alterações no produto através da ficha do produto no site administrativo ou via CSV.

Produtos novos são criados com ChangeFlagAPI=0.

Obs: Alterações no estoque do produto quando este é comprado ou quando o pedido contendo o produto for cancelado não alteram este campo.

Os seguintes relatórios de produtos podem ser utilizados com o método ReportView para trazer a lista de produtos da loja:

• Lista de produtos para alterações via API
• Lista de estoque de produtos para alterações via API

Nestes relatórios, é possível utilizar o filtro ChangeFlagAPI=0 para trazer somente os produtos novos ou alterados pela ficha do produto no site administrativo ou via CSV. Após a importação, utilize o método ProductManagement para alterar o valor de ChangeFlagProdAPI e evitar novas importações redundantes.

Para alterar o estoque existente de um produto, coloque um sinal de + (mais) ou de - (menos) após a quantidade, no campo Estoque.

Exemplos:

Utilize o seguinte XML para adicionar dois itens ao estoque existente do produto 999999. Se o produto estava com 50 itens no estoque, após executar o XML abaixo passará a ficar com 52 itens:

<Records>
  <Record>
    <Field Name="Comando" Value="A" /> 
    <Field Name="IDProduto" Value="999999" /> 
    <Field Name="Estoque" Value="2+" />
    <Field Name="ChangeFlagProdAPI" Value="1" />
  </Record>
</Records>
              

Utilize o seguinte XML para retirar três itens do estoque existente do produto 999999. Se o produto estava com 50 itens no estoque, após executar o XML abaixo passará a ficar com 47 itens:

<Records>
  <Record>
    <Field Name="Comando" Value="A" /> 
    <Field Name="IDProduto" Value="999999" /> 
    <Field Name="Estoque" Value="3-" />
    <Field Name="ChangeFlagProdAPI" Value="1" />
  </Record>
</Records>
              

Veja a lista com os possíveis códigos de erros (<ErrCode>) e suas descrições (<ErrDescr>):

Se houver erros, o resultado desta operação será retornado em XML da seguinte forma:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="A" />
    <Field Name="IDPRODUTO" Value="999999" /> 
    <Field Name="NOMEPROD" Value="Polo Seleção Brazil" /> 
    <Field Name="CHANGEFLAGPRODAPI" Value="1" /> 
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="A" /> 
    <Field Name="IDPRODUTO" Value="888888" /> 
    <Field Name="NOMEPROD" Value="Polo Seleção Italiana" /> 
    <Field Name="CHANGEFLAGPRODAPI" Value="1" /> 
  </Record>
  <ErrCode>18</ErrCode>
  <ErrDescr>Invalid Product(s) in XMLRecords</ErrDescr>
  <IntCode>111</IntCode>
  <IntDescr>Invalid field:NOMEDOCAMPO Record:2</IntDescr>
  <Stats Sent="2" Valid="1" Included="0" IncludedSub="0" Changed="1" ChangedSub="0" Deleted="0" DeletedSub="0" ElapsedSeconds="0,000"/>
</API>
              

Segue a lista com os possíveis códigos de erros (<IntCode>) e suas descrições (<IntDescr>):

Na tag <Stats> são retornados os seguintes atributos:

8.3 - Exclusão de produtos

Estrutura do XML para exclusão do cadastro de produtos:

Para exclusão o comando deve ser D ou E e devem ser enviados somente os campos Comando e IDProduto.

Comando D: efetua a exclusão do cadastro do produto, as imagens e arquivo html de descrição.

Comando E: efetua apenas a exclusão do cadastro do produto. As imagens e arquivo html de descrição permanecem no gerenciador de arquivos da loja.

<Records>
  <Record>
    <Field Name="Comando" Value="D" />
    <Field Name="IDProduto" Value="999999" />
  </Record>
  <Record>
    <Field Name="Comando" Value="E" />
    <Field Name="IDProduto" Value="888888" /> 
  </Record>
</Records>
              

Obs: Para realizar a exclusão, os campos Comando e IDProduto são obrigatórios.É possível excluir múltiplos produtos por vez.

O resultado desta operação será retornado em XML. Segue o modelo:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="D" /> 
    <Field Name="IDPRODUTO" Value="999999" /> 
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="E" /> 
    <Field Name="IDPRODUTO" Value="888888" /> 
  </Record>
  <ErrCode>0</ErrCode>
  <ErrDescr>OK</ErrDescr>
  <Stats Sent="2" Valid="2" Included="0" IncludedSub="0" Changed="0" ChangedSub="0" Deleted="2" DeletedSub="0" ElapsedSeconds="0,000"/>
</API>
              

Veja a lista com os possíveis códigos de erros (<ErrCode>) e suas descrições (<ErrDescr>):

Se houver erros, o resultado desta operação será retornado em XML da seguinte forma:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="E" />
    <Field Name="IDPRODUTO" Value="999999" />
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="E" />
    <Field Name="IDPRODUTO" Value="888888" />
  </Record>
  <ErrCode>18</ErrCode>
  <ErrDescr>Invalid Product(s) in XMLRecords</ErrDescr>
  <IntCode>123</IntCode>
  <IntDescr>IDProduto not found</IntDescr>
  <Stats Sent="2" Valid="1" Included="0" IncludedSub="0" Changed="0" ChangedSub="0" Deleted="1" DeletedSub="0" ElapsedSeconds="0,000"/>
</API>
              

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

Veja a lista com os possíveis códigos de erros (<IntCode>) e suas descrições (<IntDescr>):

Na tag <Stats> são retornados os seguintes atributos:

8.4 - Alteração de pedidos

Estrutura do XML para alteração na ficha dos pedidos:

Para alteração, o campo NumPedido é obrigatório.

<Records>
  <Record>
    <Field Name="NumPedido" Value="999999" />
    <Field Name="ObsCurta" Value="abcdefg" />
    <Field Name="Status" Value="4" />
    <Field Name="ObjSedex" Value="a9b9c9d9e9" />
    <Field Name="NumNFe" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DataEntrega" Value="10/10/2018" />
    <Field Name="ObsLog" Value="Alteração de pedido. Status para aprovado mediante pagamento via PIX código xxxx" />
    <Field Name="ChangeFlagAPI" Value="98" />
  </Record>
  <Record>
    <Field Name="NumPedido" Value="888888" />
    <Field Name="ObsCurta" Value="ijlmopq" />
    <Field Name="Status" Value="7" />
    <Field Name="ObjSedex" Value="a8b8c8d8e8" />
    <Field Name="NumNFe" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DataEntrega" Value="10/10/2018" />
    <Field Name="ObsLog" Value="Alteração de pedido. Status para aprovado mediante pagamento via PIX código xxxx" />
    <Field Name="ChangeFlagAPI" Value="99" />
  </Record>
</Records>
              

Obs: Além do campo NumPedido é obrigatório ter pelo menos mais um campo. É possível alterar múltiplos pedidos por vez.

O resultado desta operação será retornado em XML. Segue o modelo:

<API>
  <Record Num="1">
    <Field Name="NUMPEDIDO" Value="999999" />
    <Field Name="OBSCURTA" Value="abcdefg" />
    <Field Name="STATUS" Value="6" />
    <Field Name="OBJSEDEX" Value="a9b9c9d9e9" />
    <Field Name="NUMNFE" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DATAENTREGA" Value="10/10/2018" />
    <Field Name="OBSLOG" Value="Alteração de pedido. Status para aprovado mediante pagamento via PIX código xxxx" />
    <Field Name="CHANGEFLAGAPI" Value="98" />
  </Record>
  <Record Num="2">
    <Field Name="NUMPEDIDO" Value="888888" />
    <Field Name="OBSCURTA" Value="ijlmopq" />
    <Field Name="STATUS" Value="5" />
    <Field Name="OBJSEDEX" Value="a8b8c8d8e8" />
    <Field Name="NUMNFE" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DATAENTREGA" Value="10/10/2018" />
    <Field Name="OBSLOG" Value="Alteração de pedido. Status para aprovado mediante pagamento via PIX código xxxx" />
    <Field Name="CHANGEFLAGAPI" Value="99" />
  </Record>
  <ErrCode>0</ErrCode>
  <ErrDescr>OK</ErrDescr>
  <Stats Sent="2" Valid="2" Changed="2" ElapsedSeconds="0,000"/>
</API>
              

8.5 - Chaves do XML

NumPedido - Único campo obrigatório do XML de pedidos, que informa o número do pedido a alterar.

ObsCurta - Campo para informar um pequeno texto de observação do pedido (até 10 caracteres). Em geral, a loja padroniza códigos para este campo. Exemplo: FP-3-ne - tradução: falta produto - item 3 do pedido - não enviado

ObsLog - Campo para informar mais detalhes sobre a observação do pedido (até 255 caracteres).

Status - Status para o qual o pedido será alterado.

O status a enviar no método OrderUpdate é numérico, com os seguintes valores possíveis:

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

NumNFe - Número/Chave da nota fiscal eletrônica com 44 posições

DataEntrega - Utilizado para informar a data da entrega do pedido

ChangeFlagAPI - Utilizado para marcar os pedidos que já foram recebidos pelo ERP, evitando que sejam novamente trazidos. Podem ser utilizados valores de 1 a 255. Este campo será automaticamente zerado sempre que ocorrerem alterações no pedido através da loja virtual ou do site administrativo, incluindo alterações de status e informações de pagamento retornadas por entidades exter- nas (Cielo, Redecard, PagSeguro etc). Pedidos novos são criados com ChangeFlagAPI=0

Os seguintes relatórios de pedidos podem ser utilizados com o método ReportView para trazer a lista de pedidos da loja:

• Lista de pedidos para alterações via API
• Lista de pedidos e detalhes para consultas via API
• Lista de pedidos alterados para consultas via API

Nestes relatórios, é possível utilizar um filtro ChangeFlagAPI=0 para trazer somente os pedidos novos. Após a importação, utilize o método OrderUpdate para alterar o valor de ChangeFlagAPI e evitar novas importações redundantes.

Veja a lista com os possíveis códigos de erros (<ErrCode>) e suas descrições (<ErrDescr>):

Se houver erros, o resultado desta operação será retornado em XML da seguinte forma:

<API>
  <Record Num="1">
    <Field Name="NUMPEDIDO" Value="999999" />
    <Field Name="OBSCURTA" Value="abcdefg" />
    <Field Name="STATUS" Value="9" />
    <Field Name="OBJSEDEX" Value="a9b9c9d9e9" />
    <Field Name="NUMNFE" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DATAENTREGA" Value="10/10/2018" />
  </Record>
  <Record Num="2">
    <Field Name="NUMPEDIDO" Value="8888881" />
    <Field Name="OBSCURTA" Value="ijlmopq" />
    <Field Name="STATUS" Value="9" />
    <Field Name="OBJSEDEX" Value="a8b8c8d8e8" />
    <Field Name="NUMNFE" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DATAENTREGA" Value="10/10/2018" />
  </Record>
  <ErrCode>19</ErrCode>
  <ErrDescr>Invalid Order(s) in XMLRecords</ErrDescr>
  <IntCode>53</IntCode>
  <IntDescr>NumPedido not found</IntDescr>
  <Stats Sent="2" Valid="1" Changed="1" ElapsedSeconds="0,000"/>
</API>
              

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

Veja a lista com os possíveis códigos de erros (<IntCode>) e suas descrições (<IntDescr>):

Na tag <Stats> são retornados os seguintes atributos:

9 - Realizando Testes

Disponibilizamos um arquivo com a coleção de requisições dos métodos da API para o aplicativo Postman.

O ambiente possui um conjunto de variáveis que são armazenadas como pares chave/valor com os dados para acesso à API que podem ser alterados para os dados da loja em que os testes serão feitos (StoreName, StoreId, Username e Password).

Clique aqui para acessar o Postman (Obs: acentos só funcionam se codificados em ISO-8859-1 e o Postman só usa UTF-8)

Clique nos nomes dos arquivos para baixar as coleções:

API_Fastcommerce.postman_collection.json

API_Fastcommerce.postman_environment.json

Disponibilizamos também uma página para facilitar a realização de testes de integração via navegador e assim conhecer melhor o funcionamento da API. Segue o endereço:

API Test

Informe os campos obrigatórios StoreName, StoreID, Username e Password no quadro Login do usuário. Em seguida, selecione o método desejado. Preencha os campos que serão exibidos de acordo com o método escolhido.

9.1 Método ReportView

Neste teste, será possível ver todo o cadastro de produtos da loja no formato da API.

No campo Method selecione a opção ReportView. No campo ObjectID informe 425 (ObjectID=425 é referente ao relatório Lista de produtos para alterações via API) e clique em Entrar.

Campos retornados pela API na chave <Report>:

Como resultado, teremos a seguinte estrutura:

<Report ObjectName="Lista de produtos para alterações via API" StoreName="Perfumes.com.br" ExecDate="05/10/2012 19:25:49" FromRecord="1" ToRecord="500" ParName1="Categoria" ParValue1="" ParName2="Ref/Nome/Descr" ParValue2="" ParName3="Disponível" ParValue3="" ParName4="Promoção" ParValue4="" ParName5="De" ParValue5="" ParName6="Até" ParValue6="" ParName7="API Flag" ParValue7="" Records="500" ReadRecords="500" >
  <Record>
    <Field Name="Comando" Value="A" />
    <Field Name="NomeCat" Value="Acessórios" />
    <Field Name="IDCategoria" Value="999999" />
    <Field Name="IDProduto" Value="999999" />
    <Field ...... />
    <Field ...... />
    <Field ...... />
  </Record>
  <Record>
    <Field Name="Comando" Value="A" />
    <Field Name="NomeCat" Value="Jóias" />
    <Field Name="IDCategoria" Value="888888" />
    <Field Name="IDProduto" Value="777777" />
    <Field ...... />
    <Field ...... />
    <Field ...... /> 
  </Record>
</Report>
              

Retorno Fracionado

O XML de retorno da API do FastCommerce tem limite de 4Mb. Quando este limite for atingido, o código 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 relatórios que trazem muitas informações (exemplo: Lista de produtos), deve-se utilizar os parâmetros disponíveis para o relatório. Se mesmo utilizando os parâmetros o resultado ainda for extenso, existem parâmetros adicionais que permitem fracionar o retorno:

• Page (Página)
• QtRecords (Quantidade de registros por página)

• FromRecord (Registro inicial solicitado do relatório)
• ToRecord (Registro final solicitado do relatório)

Se passar os 4 parâmetros os preferênciais são Page e QtRecords.

Na chave Report do retorno do XML, é informada a quantidade de registros retornados em "ReadRecords"

Por exemplo, se for solicitado o relatório "Lista de produtos para alterações via API" passando Page=1 e QtRecords=500, a chave Report informará a quantidade de registros retornados em ReadRecords, como no exemplo abaixo:

<Report ObjectName="Lista de produtos para alterações via API" StoreName="Perfumes.com.br" ExecDate="02/03/2016 13:26:56" FromRecord="1" ToRecord="500" ParName1="Categoria" ParValue1="" ParName2="Ref/Nome/Descr" ParValue2="" ParName3="Disponível" ParValue3="" ParName4="Promoção" ParValue4="" ParName5="De" ParValue5="" ParName6="Até" ParValue6="" ParName7="API Flag" ParValue7="" Records="500" ReadRecords="500">
              

No exemplo acima, foram retornados 500 registros de produtos e foram retornados do registro 1 ao 500. Solicitando Page=2 e QtRecords=500, serão retornados do registro 501 até o registro 1000, e assim por diante.

A dupla de parâmetros Page=2 e QtRecords=500 equivalem aos parâmetros FromRecord=501 e ToRecord=1000.

Se forem solicitados 500 registros e retornarem menos do que 500 registros em ReadRecords, a página retornada foi a última. Exemplo:

<Report ObjectName="Lista de produtos para alterações via API" StoreName="Perfumes.com.br" ExecDate="02/03/2016 13:29:37" FromRecord="4501" ToRecord="5000" ParName1="Categoria" ParValue1="" ParName2="Ref/Nome/Descr" ParValue2="" ParName3="Disponível" ParValue3="" ParName4="Promoção" ParValue4="" ParName5="De" ParValue5="" ParName6="Até" ParValue6="" ParName7="API Flag" ParValue7="" Records="26" ReadRecords="26">
              

Desta forma é possível programar um loop para ler os registros de forma fracionada, evitando assim atingir o limite de 4Mb do XML de retorno.

9.2 Seleção de campos retornados

Cada relatório retorna uma conjunto específico de campos. Entretanto, nem sempre todos estes campos são utilizados pela sua aplicação.

Através do parâmetro Fields, é possível selecionar quais campos serão retornados pela API, para que o relatório não retorne campos que não serão utilizados pela sua aplicação. Isto otimizará a geração, o tráfego e o processamento dos resultados.

Por exemplo, o relatório "Lista de produtos para alterações via API" possui dezenas de campos:

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

Se a sua aplicação deseja receber apenas os campos IDProduto e Estoque, basta informar no parâmetro Fields os campos entre vírgulas: IDProduto,Estoque

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

9.3 Método UtilityExecute

Neste teste, o estoque de todos os produtos serão alterados para 15.

No campo Method selecione a opção UtilityExecute, no campo ObjectID informe 248. No campo Par4 informe 15 que será seu novo estoque de todos os produtos (ObjectID=248 é referente ao utilitário Alteração no estoque de produtos) e clique em Entrar.

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

<API>
  <ErrCod>0<ErrCod>
  <ErrDescr>OK<ErrDescr>
  <Regs>10<Regs>
</API>
              

9.4 Método OrderUpdate

Neste teste, serão alterados dois pedidos

No campo Method selecione a opção OrderUpdate. No campo XMLRecords informe o XML com os registros que deseja alterar e clique em Entrar.

Como resultado, teremos a seguinte estrutura:

<API>
  <Record Num="1">
    <Field Name="NUMPEDIDO" Value="99999" />
    <Field Name="OBSCURTA" Value="Fraude" /> 
    <Field Name="STATUS" Value="5" /> 
    <Field Name="OBJSEDEX" Value="a1b2c3d4" /> 
    <Field Name="NUMNFE" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DATAENTREGA" Value="10/10/2018" /> 
  </Record>
  <Record Num="2">
    <Field Name="NUMPEDIDO" Value="88888" />
    <Field Name="OBSCURTA" Value="Exemplo" />
    <Field Name="STATUS" Value="5" />
    <Field Name="OBJSEDEX" Value="sh5552223333" />
    <Field Name="NUMNFE" Value="12345678901234567890123456789012345678901234" />
    <Field Name="DATAENTREGA" Value="10/10/2018" /> 
  </Record>
  <ErrCode>0</ErrCode>
  <ErrDescr>OK</ErrDescr>
  <Stats Sent="2" Valid="2" Changed="2" ElapsedSeconds="0,000"/>
</API>
              

9.5 Método ProductManagement

Neste teste, serão alterados dois produtos.

No campo Method selecione a opção ProductManagement. No campo XMLRecords informe o XML com os registros que deseja alterar e clique em Entrar.

Como resultado, teremos a seguinte estrutura:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="A" />
    <Field Name="NOMECAT" Value="Camisetas" />
    <Field Name="IDCATEGORIA" Value="2222" />
    <Field Name="IDPRODUTO" Value="99999" />
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="A" />
    <Field Name="NOMECAT" Value="Bermudas" />
    <Field Name="IDCATEGORIA" Value="3333" />
    <Field Name="IDPRODUTO" Value="88888" />
  </Record>
  <ErrCode>0</ErrCode>
  <ErrDescr>OK</ErrDescr>
  <Stats Sent="2" Valid="2" Included="0" IncludedSub="0" Changed="2" ChangedSub="0" Deleted="0" DeletedSub="0" ElapsedSeconds="0,000"/>
</API>
              

10 - Exemplos

VB Script

Segue exemplo de integração em VBScript:

Option Explicit

Dim oHTTP,sHTTP,sParam

'Exemplo de relatório
sParam=""
BuildParam "StoreName","SP Departamentos"
BuildParam "StoreID",184
BuildParam "Username","Paulo"
BuildParam "Password","123456"
BuildParam "method","ReportView"
BuildParam "ObjectID",424 'ObjectID do relatório "Lista de pedidos para alterações via API"
BuildParam "Par1",4
BuildParam "OutputFormat",1
ExecutaAPI

'Exemplo de alteração de um pedido
sParam=""
BuildParam "StoreName","SP Departamentos"
BuildParam "StoreID",184
BuildParam "Username","Paulo"
BuildParam "Password","123456"
BuildParam "method","OrderUpdate"
BuildParam "XMLRecords","<Records><Record><Field Name=""NumPedido"" Value=""25013""/><Field 
Name=""ObsCurta"" Value=""Cheque OK""/><Field Name=""Status"" Value=""6""/><Field Name=""ObjSedex"" 
Value=""SDX0002999""/></Record></Records>"
ExecutaAPI

Sub BuildParam(sName,sValue)
  sParam=sParam & sName &"="& URLEncode(sValue) &"&"
End Sub

Function URLEncode(sText)
  Dim i,char,sOut,AscChar
  For i=1 To Len(sText)
    char=Mid(sText,i,1)
    AscChar=Asc(char)
    If AscChar=32 Then 'Converte espaço para +
      sOut=sOut &"+"
    ElseIf (AscChar<48 OR AscChar>122) OR (AscChar>57 AND AscChar<65) OR (AscChar>90 AND AscChar<97) Then
      sOut=sOut &"%"& FormatZeros(Hex(AscChar),2)
    Else
      sOut=sOut & char
    End If
  Next
  URLEncode=sOut
End Function

Function FormatZeros(Num,nz)
'Retorna string formatada com nz zeros à frente
  Dim sNum,iTrunc,LenNum
  sNum=Trim(Num)
  LenNum=Len(sNum)
  If LenNum>Int(nz) Then
    iTrunc=LenNum
  Else
    iTrunc=nz
  End If
  FormatZeros=Right(String(nz,"0")& sNum,iTrunc)
End Function

Sub ExecutaAPI
  Set oHTTP=CreateObject("WinHttp.WinHttpRequest.5.1")
  oHTTP.Open "POST","https://www.rumo.com.br/sistema/adm/APILogon.asp",False
  oHTTP.Option(0)="FastCommerce API Interface" 'Alterar o UserAgent, para evitar filtragem do FC
  oHTTP.SetRequestHeader "Content-type","application/x-www-form-urlencoded"
  oHTTP.Send sParam
  WScript.echo oHTTP.ResponseText
  Set oHTTP=Nothing
End Sub
              

11 - Dicionário de Dados

ObjectID 510

Relatório Dados da loja para consultas via API

ObjectID 425

Relatório Lista de produtos para alterações via API

ObjectID 429

Relatório Categorias e IDs para cadastro de produtos via API

ObjectID 426

Relatório Lista de clientes para consultas via API

ObjectID 427

Relatório Lista de pedidos e detalhes para consultas via API

ObjectID 248

Relatório Lista de classes de produtos para cadastro via API

ObjectID 393

Relatório Lista de descritores especiais de produtos

ObjectID 530

Relatório Lista de filtros de produtos

12 - Tratamento de Erros

Se for enviado um XML com múltiplos registros e existir erro em um dos registros, a API irá processar até ocorrer o erro, retornando os registros onde a execução ocorreu sem problema e por último o registro que causou o erro.

No exemplo abaixo existem 5 registros. O erro está no registro 3. Foi definido o comando U, que é um comando inexistente. Os dois primeiros registros foram processados (Deleted="2") e os dois últimos não foram. O erro ocorreu no terceiro registro:

<Records>
  <Record>
    <Field Name="Comando" Value="E" />
    <Field Name="IDProduto" Value="5206796" />
  </Record>
  <Record>
    <Field Name="Comando" Value="E" />
    <Field Name="IDProduto" Value="5206797" />
  </Record>
  <Record>
    <Field Name="Comando" Value="U" />
    <Field Name="IDProduto" Value="5206798" />
  </Record>
  <Record>
    <Field Name="Comando" Value="E" />
    <Field Name="IDProduto" Value="5206799" />
  </Record>
  <Record>
    <Field Name="Comando" Value="E" />
    <Field Name="IDProduto" Value="5206800" />
  </Record>
</Records>
              

Retorno da API:

<API>
  <Record Num="1">
    <Field Name="COMANDO" Value="E"/>
    <Field Name="IDPRODUTO" Value="5206796"/>
  </Record>
  <Record Num="2">
    <Field Name="COMANDO" Value="E"/>
    <Field Name="IDPRODUTO" Value="5206797"/>
  </Record>
  <Record Num="3">
    <Field Name="COMANDO" Value="U"/>
    <Field Name="IDPRODUTO" Value="5206798"/>
  </Record>
  <ErrCod>18</ErrCod>
  <ErrDescr>Invalid Product(s) in XMLRecords</ErrDescr>
  <IntCod>115</IntCod>
  <IntDescr>Invalid command</IntDescr>
  <Stats Sent="5" Valid="2" Included="0" IncludedSub="0" Changed="0" ChangedSub="0" Deleted="2" DeletedSub="0" ElapsedSeconds="0,092"/>
</API>