Manual de Integrao Mar2016 Ateno Este manual sofre

Manual de Integração Mar/2016

Atenção Este manual sofre constantes alterações. Por favor consulte a versão mais recente em: http: //developers. anymarket. com. br/manual. html

Entenda a API A versão 2 da API ANYMARKET é um passo a frente no sentido de facilitar a integração de nossos parceiros aos diversos Marketplaces disponíveis. A criação da API permite que aplicações existentes ou novas aplicações estendam suas operações de venda de forma simples. Uma vez que você tenha solicitado seu Token de acesso ao nosso suporte, é fácil começar a integração com o ANYMARKET. Todos as URLs são acessíveis através do host: sandbox-api. anymarket. com. br. Por exemplo: você pode recuperar todas as suas categorias acessando a URL com o seu TOKEN de acesso (substitua TOKEN pelo seu próprio): http: //sandbox-api. anymarket. com. br/v 2/categories? gumga. Token=TOKEN É necessário informar o seu Token de acesso para todas as URLs que serão acessadas. Além de utilizá-lo como parâmetro na URL, é possível passá-lo como cabeçalho da requisição. O nome gumga. Token deve ser utilizado para ambas as formas.

Paginação A grande maioria das requisições que retornam uma coleção de recursos são paginadas, como por exemplo, a consulta de categorias principais. Toda resposta paginada é retornada no seguinte formato: { "links": [ { "rel": "prev", "href": "http: //sandbox-api. anymarket. com. br/v 2/categories? offset=0" }, { "rel": "next", "href": http: //sandbox-api. anymarket. com. br/v 2/categories? offset=4 } ], "content": [. . . ], "page": { "size": 2, "total. Elements": 6, "total. Pages": 3, "number": 1 } }

Primeiros Passos: • • • Nossa API utiliza a tecnologia RESTful. São utilizados métodos padrão da tecnologia: GET - POST - PUT - DELETE Nosso Token (gumga. Token) deve ser passado como parâmetro no Header da chamada Todos os testes devem ser realizados no Ambiente Sandbox do ANYMARKET Utilizar somente a API V 2 Todos os endpoints e mais detalhes podem ser encontrados em: http: //www. developers. anymarket. com. br

Tópicos de integração: • • • Estratégias de Integração Ferramentas Úteis Callback Feeds Fluxos de Integração • • • Autenticação Produtos Pedidos Feed´s Imagem

Estratégia de Integração: Há duas possibilidades previstas para o fluxo de Pedido e Produto na integração com o ANYMARKET: Centralizado em seu ERP ou Centralizado no ANYMARKET.

Centralizador ERP: Produtos Nessa situação geralmente os Produtos são enviados para o ANYMARKET através do endpoint “Produtos(LINK)”. Pedidos Os pedidos devem ser obtidos do ANYMARKET. Recomendase utilizar o “Callback” para um melhor rendimento e performance. Há ainda a opção de se utilizar o “Feed de Pedidos” para o gerenciamento de pedidos.

Estoque Geralmente quem controla o estoque é quem está importando os pedidos, ou seja, o estoque deve ser enviado do ERP para o ANYMARKET. Assim, existe um parâmetro que deve ser desmarcado para o correto funcionamento:

Centralizador ANYMARKET: Produtos Nessa situação geralmente os Produtos são obtidos do ANYMARKET. Recomenda-se o uso de “Transmissões para Ecommerce” junto com o “Callback”. Existe também a possibilidade de ser utilizado juntamente com o “Feed de Transmissão”. Pedidos Os pedidos devem ser enviados para o ANYMARKET utilizando o endpoint de “Pedidos(LINK)”.

Estoque Geralmente quem controla o estoque é quem está importando os pedidos, ou seja, o estoque deve ser enviado do ANYMARKET para o Ecommerce ou ERP. Nesse caso há um parâmetro que deve desmarcado para o correto funcionamento:

Ferramentas Úteis: Há algumas ferramentas que podem auxiliar na integração com nossa API, uma delas é o Postman é um app que utiliza o Chrome. Acessando nossa documentação em: http: //developers. anymarket. com. br/tools. html e indo na aba “API V 2: Explorador” pode ser encontrado um botão igual a este Neste botão é possível importar imediatamente uma Collection para o seu Postman que contém todos os endpoints da nossa API com exemplos reais de uso.

Postman: O ANYMARKET aconselha o uso da ferramenta Postman para realizar os testes. Como a ferramenta é um app do Chrome, é necessário o mesmo para utilizá-la. O download pode ser encontrado em “Chrome Web Store”.

Dicas de uso: • Ao importar nossa collection será criado em seu Postman(caso ele já esteja instalado), com isso ira criar uma Aba chamada “ANYMARKET” onde é possível encontrar todos os endpoints disponíveis com exemplos de JSON reais:

• Todos os endpoints contém parâmetros que podem ser configurados no próprio Postman, evitando assim erros ou retrabalhos: Este menu se localiza no canto superior direito. O único parâmetro que é comum em todos os endpoints é o Token, porém cada endpoit tem um específico, por ex: {{ID_PRODUCT}} , {{ID_ORDER}}

• Todos os parâmetros (inclusive Tests) podem ser configurados nas seguintes opções: • Clicando em “Generate Code” é possível obter exemplos em várias linguagens com os parâmetros atuais da página.

Callback: O callback tem o objetivo de notificar uma URL passada como Parâmetro toda vez que existir alguma alteração ou inserção de Pedido, Produto ou Transmissão. O ANYMARKET tenta a comunicação com a URL três vezes, durante 15 minutos, ou seja, uma tentativa a cada 5 minutos. Caso ainda não seja possível a notificação, o item é enviado para o feed correspondente.

Recomendações de uso Callback: Quando é necessário manter um item atualizado constantemente (Produto, Transmissão ou Pedido) é extremamente recomendado o uso de Callback no lugar do “Feed”. Isso garante uma precisão maior e mais produtividade, deixando o Feed apenas como um Backup caso o Callback falhe por algum motivo. Mais informações você pode encontrar em: http: //developers. anymarket. com. br/tools. html - aba “Notificações”.

Fluxo - Envio ao Callback: A notificação é enviada ao parceiro quando a opção URL Callback está preenchida no painel de parâmetros do ANYMARKET.

Feeds: Quando não há uma URL de Callback configurada qualquer alteração em Pedido, Produto ou Transmissão para o Ecommerce gera um registro no Feed. Esse registro pode ser obtido através do endpoint do seu respectivo Feed. Cada item fica armazenado ppr 30 dias antes de ser retirado do Feed pelo sistema.

Fluxo - Envio ao Feed: A notificação é enviada ao Feed quando a opção URL Callback não está preenchida no painel de parâmetros do ANYMARKET ou quando o serviço do parceiro está indisponível por um período maior que 15 minutos.

Autenticação: • Nossa autenticação é feita através do parâmetro “gumga. Token” passado no Header de cada chamada • Para ter acesso a esse Token entre em contato conosco através do email: anymarketsup@db 1. com. br • Os Token´s são diferentes para cada ambiente, isso quer dizer que seu Token de produção não irá funcionar em Sandbox.

Produtos: O Anymarket trabalha com dois tipos de produtos: • Sem Variação Produto simples que não tem “grade” de Cor, Tamanho ou outro atributo. • Com Variação Produto que possui variação de Cor, Tamanho ou qualquer outro atributo.

Regras Comuns (utilizado para produtos com/sem variação): • As imagens enviadas para o ANYMARKET devem respeitar o limite de 350 x 350 px e com o limite máximo de 4 MB. • Limite máximo de 30 Características por Produto. • Limite de 120 Caracteres no título do Produto. • Existe um atributo chamado partner. Id onde deve ser informado o código de controle interno do ERP ou Ecommerce.

Sem Variação: É o tipo de produto mais simples, sendo necessário apenas enviar os atributos exigidos pelo ANYMARKET. Imagem: É necessário apenas informar a URL e se a foto é a principal ou não. Sku: Não é necessário informar mais do que um item nesse atributo.

Com Variação: Produto possui grade. O ANYAMRKET permite apenas um atributo com variação visual. As variações devem estar previamente cadastradas no ANYMARKET. Imagem: É necessário informar de qual variação aquela imagem pertence. Caso não seja passado esse atributo a imagem será cadastrada sem Variação.

Pedidos: Status Disponíveis: Concluido (CONCLUDED) Pendente (PENDING) Faturado (INVOICED) Enviado (PAID_WAITING_DELIVERY) Pago (PAID_WAITING_SHIP) Cancelado (CANCELED) Um pedido pode ser cadastrado com qualquer Status disponibilizado pelo ANYAMRKET, desde que seja enviado juntamente os dados correspondentes.

Fluxo Pedido:

• Pendente: informar apenas os atributos padrões. • Pago: apenas informar o Status. { } "order_id": "ID_PEDIDO", "status": "PAID_WAITING_SHIP" "order_id": "ID_PEDIDO", "status": “INVOICED, "invoice": { "series": "3", "number": "431", "access. Key": “ 0000000000", "date": "2016 -03 -09 T 19: 01: 58 Z" }

• Enviado (Em Transito) "order_id": "ID_PEDIDO", "status": "PAID_WAITING_DELIVERY", "tracking": { "date": "2016 -03 -11 T 11: 42: 53 Z", "shipped. Date": "2016 -03 -11 T 11: 42: 53 Z", "estimate. Date": "2016 -03 -16 T 11: 42: 53 Z", "carrier": "Correios-Sedex", "number": "99998880000111", "url": "http: //www. example. com. vr" } • Enviado (Entregue) "tracking": { "date": "2016 -03 -11 T 11: 42: 53 Z", "delivered. Date": "2016 -03 -11 T 11: 42: 53 Z", "carrier": "Correios-Sedex", "number": "99998880000111", "url": "http: //www. example. com. vr" }

• Pago: apenas informar o Status. { } "order_id": "ID_PEDIDO", "status": "CONCLUDED" • Pago: apenas informar o Status. { } "order_id": "ID_PEDIDO", "status": "CANCELED"

Tipos Feed: • Produtos (Products) • Pedidos (Order) • Transmissão (Transmissions) Todos os endpoints de Feeds por padrão exibem 10 itens por vez, ou seja, se há 30 itens no Feed, vai ter que ser consumido de 10 em 10 até dar o número máximo de itens. OBS: Caso um item não apareça na primeira chamada é possível que o mesmo esteja em outras páginas, sendo necessário consumir os itens até chegar no desejado.

Pode ser passado como parâmetro um limite afim de aumentar a quantidade de itens exibidos por chamada. Para isso é necessário fazer a chamada da seguinte maneira: http: //sandbox-api. anymarket. com. br/v 2/transmissions/feeds? limit=100 • Os itens são exibidos ordenados pelo ID do mesmo. • O ID do Feed equivale ao ID do item, por exemplo: Feed Produto: ID Feed é igual ao ID Produto Feed Pedido: ID Feed é igual ao ID Pedido Feed Transmissão: ID Feed é igual ao ID do SKU

Imagem: • As imagens de um produto podem ser Criadas ou Deletadas, mas a Atualização não é permitida. • Na URL deve ser passado apenas o ID do produto, a variação e demais atributos da imagem devem ser passados no BODY da chamada.

Fluxos de Integração: Cadastro de Produtos:

Fluxo - Pedido Criado:

Fluxo - Pedido Alterado:

Fluxo - Pedido Enviado:

Fluxo - Pedido Entregue:

Exemplo de Integração Produtos: Exemplos mais detalhados podem ser encontrados aqui. Para sincronizarmos um produto é necessário que tenhamos previamente cadastrados Categoria, Marca e Variações. • Para cadastrar uma categoria deve ser chamado o Endpoint de Categories fazendo um POST: http: //sandbox-api. anymarket. com. br/v 2/categories? gumga. Token=TOKEN • Para cadastrar uma marca deve ser chamado o Endpoint de Brands fazendo um POST: http: //sandbox-api. anymarket. com. br/v 2/brands? gumga. Token=TOKEN

Tendo esses códigos em mãos, basta seguir com o processo normal para o cadastro de um Produto. • Produto Simples Mais detalhes pode ser encontrado aqui. • Produto com Variação Os mesmos atributos de um produto simples devem ser informados, porém acrescentando alguns atributos próprios das variações, como por exemplo: "variations": {"Color": "RED"} - no atributo SKU, para informar qual variação aquele sku pertence. "variation": "RED" - nas Imagens, para indicar de qual variação é aquela imagem. Para atualização do produto basta informar o mesmo JSON com as alterações necessárias e passando o ID do Produto na chamada.

Para a primeira integração de um produto (cadastro do produto), o estoque e preço são considerados do próprio JSON. Para atualizar esse estoque e/ou preço devemos chamar o seguinte Endpoint: http: //sandbox-api. anymarket. com. br/v 2/stocks? gumga. Token=TOKEN Passando em seu BODY um JSON que deve informar a Quantidade, Preço, o ID Produto ou o partner. ID. [{ "id": 0, "partner. Id": "00000001013", "quantity": 150, "cost": 144 }] Lembrando que essa operação pode ser feita em lote, ou seja, podem ser passados vários stocks para o processamento.

Exemplo de Integração Pedidos: Exemplos mais detalhados podem ser encontrados aqui. Em relação aos Pedidos é necessário seguir um determinado fluxo que pode ser encontrado a partir daqui. • Para cadastrar um Pedido Novo deve ser chamado o Endpoint de Orders fazendo um POST, mas para isso os produtos devem estar cadastrados (veja mais aqui): http: //sandbox-api. anymarket. com. br/v 2/orders? gumga. Token=TOKEN • Os pedidos criados via API são categorizados como ECOMMERCE no ANYMARKET. • Para criar um pedido pela API o(s) produto(s) devem estar transmitidos para o Ecommerce.