Olá Desenvolvedor(a)!

Seja bem vindo à nossa Base de Conhecimento. Aqui você vai encontrar tudo o que precisa para integrar seu sistema ao Hub Flip Market. São mais de 50 canais de venda para que seu cliente possa vender online nos maiores Canais de Marketplaces e Plataformas de e-commerce.

Nesta Base, você terá uma demonstração dos primeiros passos à seguir no processo de integração entre sua Solução e nossa API. Para acessar todos os endpoints e a documentação completa, consulte nossa documentação técnica.

Sumário

1. Ambientes

2. Autenticação da API

2.1 Token de acesso (accessToken)

2.2 Token de renovação (refreshToken)

3. Produtos

3.1 Preparando o seu Software

3.2 Canais de Venda

3.3 Cadastro de produto 

3.4 Cadastro da foto do produto

3.5 Atualizando o produto

4. Pedidos

4.1 Buscar Pedidos

4.2 Confirmação de pedido

4.3 Notificação de Faturamento

4.4 Notificação de Despacho/Envio

4.5 Confirmação de Entrega

5. Documentação Técnica

1. Ambientes

Ao integrar sua Solução com nossa API, você terá acesso aos ambientes de Sandbox e Produção. Para ter acesso ao ambiente final, de Produção, será necessário, antes, realizar todos os passos em Sandbox, que é nosso ambiente de testes.

O acesso à cada ambiente será realizado através das URL’s abaixo:

Sandbox:

https://api.sandbox.flipmarket.com.br/

Produção:

https://api.flipmarket.com.br/

2. Processo de Autenticação da API

Para se autenticar na API e começar a integrar seus produtos e recebimento de vendas nos marketplaces é necessário ter os tokens de acesso. São dois tokens, o accessToken e o refreshToken que devem ser solicitados à nossa equipe de Suporte.

Note que você deve usar os dois tokens conforme abaixo

{
"accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"refreshToken": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

2.1 Token de acesso (accessToken) 

Este é o token que deverá ser enviado em todas as requisições para nossa API.

Você deverá passar esse token através do header “Authorization“, conforme abaixo:

Authorization: Bearer <token>
// exemplo:
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Este token tem validade de 24 horas, então será necessário renovar ele periodicamente, como sugestão a cada 23 horas. Para renovação deste token é aconselhável possuir o seu token de atualização, denominado refreshToken. 

2.2 Token de renovação (RefreshToken)

Este é nosso token de atualização, você deverá armazená-lo seguramente em seu sistema/banco de dados, pois com ele você poderá criar uma rotina para atualização do seu token de acesso à API, caso contrário será necessário fazer a geração manualmente via painel do FlipMarket. 

Este token é gerado sempre com um token de acesso, é único por accessToken, ou seja, a cada renovação de accessToken haverá um novo refreshToken. 

A renovação do accessToken se dá através da rota POST /auth/refresh, onde no body deverá ser enviado o refreshToken.

Para esta rota não há necessidade de informar o header Authorization.

// POST /auth/refresh
{
 "refreshToken": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

O retorno desta requisição será novamente um par de tokens, accessToken e refreshToken. Armazene o par e utilize nas suas próximas requisições e renovação.

3. Produtos

O gerenciamento de produtos em nossa API é feita através do endpoint  “/products“. Através deste endpoint é possível realizar o cadastro, envio de imagem, atualização de preços, estoque e entre outros campos.

Importante frisar que os canais de venda (marketplaces e ecommerces) não respondem de maneira síncrona, ou seja, ao enviar um produto (seja novo ou uma atualização) para o FlipMarket não significa que o mesmo foi aceito pelos canais de venda. 

Formato de imagem que o FlipMarket aceita:

GIF, JPG e PNG

3.1 Preparando o seu software

Antes de realizar a integração com o FlipMarket é necessário que seu software esteja preparado. Isto por que necessitamos de alguns dados previamente configurados, sendo eles dados fixos onde deverá ser informado apenas o id do dado, que é o caso de categorias, cores, tamanhos, voltagem e sabores.

Para isso, disponibilizaremos os dados para download e posteriormente você fazer a importação em seu software. 

Importante frisar que receberemos apenas os IDs dos respectivos dados. Clique para realizar o download:

Categorias

Obrigatório em todos os produtos, sendo utilizado para categorização dentro dos marketplaces. Uma dica é tornar este campo obrigatório no cadastro de produto de seu software.

Cores

Recomendado em produtos que tem variação por cor (tênis, blusas, calças, produtos do vestuário em geral…)

Tamanhos

Recomendado em produtos que tem variação por tamanho (tênis, blusas, calças, produtos do vestuário em geral…)

Voltagem

Recomendado em produtos que tem variação por voltagem (eletrodomésticos)

Sabores

Recomendado em produtos que tem variação por sabores (produtos alimentícios)

Caso você ou seu cliente encontre valores não mapeados nestes arquivos, entre em contato conosco para realizarmos a homologação destes valores junto aos marketplaces do mercado.

3.2 Canais de Venda

Canais de venda, é como chamamos ecommerces e marketplaces, você irá ouvir falar muito por aqui. Atualmente estamos com 56 canais de vendas disponíveis para integrarmos através de uma única integração. Veja abaixo quais são:

É importante que você tenha essa lista em seu sistema/banco de dados, pois ao receber uma venda ela virá com o ID do canal de venda que a originou, assim você conseguirá fazer o devido cruzamento de dados.

3.3 Cadastrando um novo produto

O cadastro de produto é um POST, para nossa API, contendo os campos que deseja ser informado. Neste exemplo será cadastrado um tênis, ou seja, um produto que contém variação (cor e tamanho), porém há cenários que não existe, ou o cliente não deseja trabalhar com variações, como, por exemplo, peças automobilísticas. 

URL

POST https://api.sandbox.flipmarket.com.br/products

Body

{
 "productId": "2013",
 "productName": "Camiseta Beach Tenis",
 "sku": "2013-1",
 "name": "Camiseta Beach Tenis Vermelha",
 "categoryId": "5d420cb3e2f97a00163d677f",
 "brand": "HBX",
 "model": "Beach Tenis",
 "description": "CAMISETA HPBX BEACH TENNIS. Com tecido leve, tem caimento perfeito e alta resistência para garantir que nada tire seu foco do movimento",
 "images": [
   "https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_17.jpg",
   "https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_18.jpg",
   "https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_19.jpg",
   "https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_20.jpg"
 ],
 "width": 100,
 "height": 24,
 "length": 37,
 "weight": 13,
 "stock": 10,
 "price": 129.99,
 "warranty": 60,
 "origin": "nacional",
 "metafields": [
   {
    "key": "Linha",
    "value": "Beach Tenis"
   }
 ],
 "color": "5bb9210d3495e60001587624",
 "size": "5c0ef9f0452cfa0001eb24ac"
}

Campos em vermelho são campos obrigatórios.

Note que alguns campos não recebem valores literais, no caso dos campos categoryId, color e size, os quais recebem apenas ID’s, que servem para a normatização entre os variados marketplaces.

3.4 Cadastrando imagem para um produto

É inegavel que imagens são pontos decisivos para a compra de produtos na internet. Por isso é importante que seu cliente capriche nas imagens, fornecendo imagens de boa qualidade e boa resolução (Cerca de 1000px é o ideal).

Assim sendo temos API’s para envio de imagens onde existem atualmente dois formatos para cadastrar imagens em produtos.

A maneira mais indicada é informar no próprio body do cadastro de produto, no FlipMarket, uma URL pública da imagem. Assim basta uma requisição para que o produto já está sendo disponibilizado para marketplaces, como no exemplo abaixo extraído do passo anterior.

"images": [
"https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_17.jpg",
"https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_17.jpg",
"https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_17.jpg",
"https://www.hopeboxstore.com.br/media/catalog/product/cache/0d1d10420ab3eb730879c2513d6b071b/F/R/FRENTE_17.jpg"
],

Caso este ainda não seja um processo viável no seu software, é possível a realização do envio do binário da imagem, mas para isso é necessário fazer uma imagem de cada vez após a criação do produto.

URL

POST https://api.sandbox.flipmarket.com.br/products/{SKU do Produto}/images

Body

{
 "base64Image": "{base64 da imagem}"
}

3.5 Atualizando um produto

Esta com toda certeza será uma das rotas que seu software mais terá interação. Isto por que esta é rota para atualização de produtos, sendo os principais campos atualizados estoque, preço, e disponibilidade.

URL

PUT https://api.sandbox.flipmarket.com.br/products/{SKU do Produto}

Body

{
 "stock": 35,
 "price": 129.99
}

Neste exemplo, apenas os campos informados serão atualizados, sendo o quantidade de estoque e o preço. Porém é possível atualizar grande parte dos campos, para isto consulte nossa documentação técnica.

4. Pedidos

Este conjunto de endpoints permite a busca e atualização de pedidos através do seu sistema. Dentre as operações permitidas através de API estão a busca de pedidos, a confirmação do recebimento no seu sistema, o faturamento do pedido, o despacho/envio das mercadorias e a confirmação de entrega.

Para facilitar a integração da API, é importante também você ter seu sistema preparado, é importante que você faça um mapeamento dos canais de venda conforme a tabela no item 4.1.1 Canais de Venda.

“Os pedidos em SANDBOX devem ser solicitados para o time de CT”

4.1 Buscando pedidos

A busca de pedidos é através da requisição GET para o endpoint “orders”. 

Indicamos que sejam criadas rotinas para verificação automática de tempos em tempos, por exemplo, a cada 15 minutos irá realizar esta requisição para obter os pedidos novos. 

Lembrando que o FlipMarket só aceita 100 request (rate limit) por minuto. 

GET https://api.sandbox.flipmarket.com.br/v1/orders

Exemplo Response: 

{
	"data": [
		{
			"id": "955df2f1-5f43-4493-9a80-f3fadb90772a",
			"saleChannelId": "7",
			"orderSaleChannelId": "TESTE_$998547491949",
			"status": "APPROVED",
			"amount": 1564,
			"integratedStore": false,
			"invoice": null,
			"shipments": null,
			"orderIdStore": null,
			"createdAt": "2022-12-26T20:31:49.726Z",
			"updatedAt": "2022-12-26T20:31:49.763Z",
			"note": null,
			"storeOrderId": null
		},
		{
			"id": "bc5330b3-1e64-45e2-b37b-47bcfe3ee375",
			"saleChannelId": "7",
			"orderSaleChannelId": "TESTE_$675864564473",
			"status": "APPROVED",
			"amount": 9825,
			"integratedStore": false,
			"invoice": null,
			"shipments": null,
			"orderIdStore": null,
			"createdAt": "2022-12-26T20:12:47.862Z",
			"updatedAt": "2022-12-26T20:12:47.903Z",
			"note": null,
			"storeOrderId": null
		},
		{
			"id": "18726989-0ee9-4669-9483-cd251ccacb40",
			"saleChannelId": "7",
			"orderSaleChannelId": "TESTE_$657454030912",
			"status": "APPROVED",
			"amount": 9825,
			"integratedStore": false,
			"invoice": null,
			"shipments": null,
			"orderIdStore": null,
			"createdAt": "2022-12-26T20:11:58.082Z",
			"updatedAt": "2022-12-26T20:11:58.117Z",
			"note": null,
			"storeOrderId": null
		}

4.2 Confirmação de pedido

Esta etapa do processo consiste em confirmar para o FlipMarket que o produto foi integrado em seu software. Isso garante uma maior segurança na integração e você ao acessar nosso hub, consegue saber a qual pedido em seu software corresponde o pedido em nossa plataforma. 

Para realizar a confirmação basta enviar o ID/Número do pedido em seu software, conforme exemplo abaixo:

URL:

POST https://api.sandbox.flipmarket.com.br/v1/orders/{id do pedido no FlipMarket}/confirm

Body:

{
 "orderIdStore": "string",
}

4.3 Notificação de Faturamento

Para atendimento da legislação tributária, é necessário fazer o envio da Nota Fiscal para os canais de venda, assim que emitida. Deverá ser enviado as seguintes informações:

• Número da Nota Fiscal
• Série da Nota Fiscal
• Chave de Acesso da Nota Fiscal
• XML da Nota Fiscal (enviar em ‘string’ somente o conteúdo)
• Data-hora de emissão da Nota Fiscal

URL:

POST https://api.sandbox.flipmarket.com.br/v1/orders/{id do pedido no FlipMarket}/invoice

Body:

{
 "nfeDate": "{Data e hora da Nota Fiscal}",
 "nfeNumber": "{Número da Nota Fiscal}",
 "nfeSerialNumber": "{Série da Nota Fiscal}",
 "nfeAccessKey": "{Chave de Acesso da Nota Fiscal}",
 "xml": "{XML da Nota Fiscal}"
}

Este é o cenário considerando que não está sendo utilizado Mercado Livre Full, caso seja o caso da loja de seu cliente, desconsidere esta etapa, pois será o próprio Mercado Livre que realizará esta notificação.

4.4 Notificação de Despacho/Envio

 O envio dos dados de rastreamento do pedido deve ser feito quanto antes, geralmente após a emissão da NF-e já se tem essas informações. Segue a mesma linha do envio da nota fiscal.

Os dados necessários nesta etapa são:

• Código de Rastreio
• URL de Rastreio
• Transportadora

URL:

POST https://api.sandbox.flipmarket.com.br/v1/orders/{id do pedido no FlipMarket}/shipment

Body:

{
 "trackingNumber": "{Código de Rastreio}",
 "shippingCarrier": "{Transportadora}",
 "trackingUrl": "{URL de rastreio}"
}

Este é o cenário considerando que não está sendo utilizado Mercado Livre Full, caso seja o caso da loja de seu cliente, desconsidere esta etapa, pois será o próprio Mercado Livre que realizará esta notificação.

4.5 Confirmação de entrega

Essa é a última etapa a ser executada. Em casos que não possuímos integração com uma transportadora, é necessário fazer a notificação da entrega do pedido. Para tal, basta enviar qual a data/hora onde a entrega foi realizada. 

Este é um processo que marketplaces que não possuem sistema de rastreamento de encomendas integrado solicitam, muitas vezes sendo essencial para recebimento dos valores.

URL:

POST https://api.sandbox.flipmarket.com.br/v1/orders/{id do pedido no FlipMarket}/delivered

Body:

{
 "deliveredAt": "{Data-hora da entrega}"
}

Este é o cenário considerando que não está sendo utilizado Mercado Livre Full, caso seja o caso da loja de seu cliente, desconsidere esta etapa, pois será o próprio Mercado Livre que realizará esta notificação.

5. Documentação Técnica

Nossa documentação técnica é destinada para entender das particularidades dos campos e seus tipos existentes em cada um dos endpoints.

Por isso acesse a página de nossa documentação técnica clicando aqui.

Anexos: