Introdução

Nossa API permite que fornecedores e canais de vendas se conectem a nossa plataforma, podendo assim vender e fornecer produtos dentro ecossistema da Epicom.

Conceitos importantes

Fornecedor: Parceiro que vende produtos na plataforma da Epicom.

Canal de Vendas: Parceiro que vende produtos da plataforma da Epicom.

Produto: Item do catálogo do fornecedor que é disponibilizado para venda nos canais.

Sku: Variação do produto. Um exemplo de uma variação de uma camisa seria uma camisa - amarela - p. Caso não haja nenhuma variação para o produto existirá somente um sku associado.

Gestão do Catálogo de Produtos

Uma vez que o fornecedor tem seu catálofgo de produtos integrado a Epicom sempre que houver uma alteração em algum item do catálogo nossa plataforma faz toda a gestão dessas alterações junto aos canais de venda mantendo as informções sobre as ofertas sempre atualizadas.

Pedidos

Nossa plataforma faz toda a gestão de pedidos desde a reserva no canal de venda até as informações de despacho e entrega no fornecedor. Esse gestão é feita com base nas seguintes etapas:

Realização de pedido no canal de vendas

Reserva de pedidos junto aos fornecedores

Confirmação do pedido pelo canal de vendas

Aprovação do pedido pelo fornecedor

Despacho do pedido

Entrega do pedido

Cancelamento do pedido

Autenticação

Nossa API utiliza o padrão “HTTP Basic Authentication” W3C, que consiste em usar o cabeçalho Authorization com um valor no formato Basic chave:token, onde chave:valor deve ser codificado em base64.

Tanto a chave quanto o token de acesso para sua conta estão disponíveis no painel do parceiro.

Importante: O cabeçalho de autenticação deve ser informado em todas as requisições enviadas para a API.

Paginação

A API MHub utiliza paginação para requisições que retornam uma lista de resultados. Para retornar os registros da página desejada, você pode combinar os parâmetros offset e limit. A resposta da requisição incluirá os headers X-Total-Count e Link com informações sobre a paginação.

Offset

Você pode informar o índice do primeiro registro da página desejada através do parâmetro ?offset. Por exemplo, para obter a segunda página considerando páginas de tamanho 10: ?offset=10&limit=10
Importante: o parâmetro offset é zero-based

Limit

O tamanho padrão de página é 30, mas você pode configurar o tamanho desejado através do parâmetro ?limit, podendo solicitar no máximo 100 registros por página. Por exemplo: https://sandboxmhubapi.epicom.com.br/v1/fornecedor/pedidos?limit=50

Headers de Resposta

As informações de paginação são incluídas no Header de resposta. O total de registros que satisfazem a requisição está contido no header X-Total-Count e os links para páginas relacionadas estão no header Link. Por exemplo:

X-Total-Count: 61
Link: <https://sandboxmhubapi.epicom.com.br/v1/fornecedor/pedidos?offset=0&limit=10>; rel=first,
<https://sandboxmhubapi.epicom.com.br/v1/fornecedor/pedidos?offset=10&limit=10>; rel=previous,
<https://sandboxmhubapi.epicom.com.br/v1/fornecedor/pedidos?offset=30&limit=10>; rel=next,
<https://sandboxmhubapi.epicom.com.br/v1/fornecedor/pedidos?offset=60&limit=10>; rel=last

O header Link poderá conter um ou mais links de relação com outras páginas. Recomendamos que utilize estes links de response para navegar pelas páginas, ao invés de construí-los manualmente.

Respostas

A MHub Api utiliza o HTTP status code para a resposta de toda requisição.

Resposta com campos filtrados

A API MHub responde por padrão a representação completa do recurso referente à requisição. Mas, você pode informar à API quais desses campos deseja que ela inclua na resposta para uma melhor performance na comunicação desses dados, por exemplo. Para retornar somente os campos que deseja, você pode informar o parâmetro fields.

O parâmetro fields pode ser utilizado em qualquer requisição GET, seja a resposta dessa requisição um recurso ou uma lista de recursos.

Exemplos

Requisição sem o parâmetro:

{
    "nome": "Nome do Produto - Modelo",
    "nomeReduzido": "Nome do Produto",
    "codigo": "COD123",
    "descricao": "Descrição do Produto",
    "codigoCategoria": "1234",
    "codigoMarca": "Marca",
    "palavrasChave": "promoção de produto, produto em promoção",
    "grupos": [
        {
            "id": 1,
            "nome": "Características",
            "atributos": [
                {
                    "nome": "Cor",
                    "valor": "Azul"
                },
                {
                    "nome": "Tamanho",
                    "valor": "G"
                }
            ]
        }
    ]
}

Requisição com o parâmetro:

{
    "nome": "Nome do Produto - Modelo",
    "codigo": "COD123"
}

Formato do parâmetro fields

O parâmetro fields suporta o seguinte formato:

• Use vírgula para separar vários campos. Ex. "?fields=codigo,nome"
• Use parênteses para definir sub-campos. Ex. "?fields=codigo,nome,grupos(id,nome)"
  O uso de parênteses também pode ser aplicado a sub-campos de sub-campos. Ex "?fields=codigo,nome,grupos(id,nome,atributos(nome))"

Ambientes

A Epicom disponibiliza aos desenvolvedores um ambiente totalmente dedicado a testes, o Sandbox. Caso você ainda não tenha acesso ao Sandbox ele pode ser solicitado através de integracao@epicom.com.br. Ao utilizar o Sandbox em suas integrações você deverá utilizar a seguinte URL: https://sandboxmhubapi.epicom.com.br/v1

Cada ambiente possui a sua própria base de dados assim você não precisa se preocupar com transações de teste em seu ambiente de produção. Para que você tenha acesso à sua URL de produção será necessária homologação prévia da sua integração.

Fique atento às suas credenciais de autenticação pois cada ambiente possui suas próprias credenciais.