Documentação técnica – Loja virtual

Acompanhe os passos necessários para a integração através de API entre o seu serviço de e-commerce e a loja virtual do Hiper.

Importante: Para que a integração com e-commerce via API seja completa, é necessário contar com o apoio de uma empresa que desenvolva a comunicação entre o serviço de e-commerce e o Hiper, com base na documentação abaixo.

GET - SEGURANÇA E AUTENTICAÇÃO

22/04/2020

O token de autenticação é utilizado para que possamos garantir a segurança da sua conexão ao nosso banco de dados. Para a geração do token, você deve acessar o seguinte endereço:

Observação: A chave de segurança é gerada automaticamente após a contratação do aplicativo “Loja virtual”. Para consultar sua chave, acesse o menu “Vendas” >> “Loja virtual”.

Parâmetros a serem passados na chamada:

chaveDeSeguranca:

  • É obrigatória para a geração do token de autenticação.
  • A chave de segurança é exclusiva por conta.

 

Parâmetros retornados na chamada:

chaveDeSeguranca:

  • A chave de segurança contém 64 caracteres.

token:

  • O token possui validade de 6 horas.
  • Será a autenticação de todas as chamadas da integração com a loja virtual.

Exemplo de resposta:

{

“chaveDeSeguranca”:

“31ccdc335b8a6825e28e032a4906fe5dd446ec9e99878012d66b8c77e066f0b9”,

“token”:

“eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiIyM2EzOTliOC1hM2JhLTRjMDEtYjllMi1kZWVjMzUyM2FiNTciLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMzFjY2RjMzM1YjhhNjgyNWUyOGUwMzJhNDkwNmZlNWRkNDQ2ZWM5ZTk5ODc4MDEyZDY2YjhjNzdlMDY2ZjBiOSIsIm5iZiI6MTU4NTYxNDYyNiwiZXhwIjoxNTg1NjM2MjI2LCJpYXQiOjE1ODU2MTQ2MjZ9.EVHIZbLHSC6tC7VM0OqnvY_95tfsFoHOBdRCcNTNbsE”,

“errors”: [],

“message”: null

}

GET - PRODUTOS

22/04/2020

A consulta de produto deve ser utilizada para a importação dos produtos em sua loja virtual.

Para o consumo da chamada, você deve utilizar o seguinte endereço:

Parâmetros a serem passados na chamada:

Authorization:

  • Deverá ser passado o Bearer Token de autenticação

pontoDeSincronizacao: 

  • O ponto de sincronização é utilizado para controlar as atualizações que ocorrem no sistema desde a última consulta realizada, ou seja, se o produto teve uma alteração será alterado automaticamente o ponto de sincronização.
    • Se você quiser todos os produtos, deverá ser enviado o ponto de sincronização igual 0.
    • Agora, se você quiser uma listagem de produtos que tiverem atualização, você deve enviar o número do ponto de sincronização retornado na última consulta realizada. Com isso, a integração retornará somente os produtos que tiverem atualização.

Parâmetros retornados na chamada:

altura:

  • A altura é utilizada para a embalagem no frete da mercadoria.
  • Tipo do campo: decimal (5,3).
  • Valor máximo: 99999.999 // Valor mínimo: 0.000.

ativo:

  • A situação do produto no Hiper.
  • Tipo do campo: boolean.
    • Se for true, o produto está ativo.
    • Se for false, o produto está inativo.

categoria:

  • O nome da categoria que pertence o produto cadastrado no Hiper.
  • Tipo do campo: string com o tamanho máximo de 40 caracteres.

comprimento:

  • O comprimento é utilizado para a embalagem no frete da mercadoria.
  • Tipo do campo: decimal (5,3).
  • Valor máximo: 99999.999 // Valor mínimo: 0.000.

cor (Solução transferida para o atributo “variacao” – Em breve, será removido):

  • O nome da grade com o tipo cor do produto cadastrado no Hiper.
  • Cores padrões: Azul, Amarelo, Vermelho, Laranja, entre outras.
  • Tipo do campo: string com o tamanho máximo de 80 caracteres.

descricao:

  • A descrição detalhada cadastrado no Hiper.
  • Tipo do campo: string com o tamanho máximo de 700 caracteres.

grade:

  • Indicação do produto com grade.
    • Se possui grade, será indicado como “true”.
      • Mesmo sendo o produto primário ou o produto filho.
    • Se não possui grade, será indicado como “false”.
  • Tipo do campo: booleano.

id:

  • O identificador único do produto cadastrado no Hiper.
  • Tipo do campo: uniqueidentifier com 36 caracteres.

imagem:

  • A imagem será exibida através de um link ao diretório da nossa estrutura de dados.
  • Tipo do campo: string com o tamanho máximo de 300 caracteres.

largura:

  • A largura é utilizada para a embalagem no frete da mercadoria.
  • Tipo do campo: decimal (5,3).
  • Valor máximo: 99999.999 // Valor mínimo: 0.000.

marca:

  • O nome da marca que pertence o produto cadastrado no Hiper.
  • Tipo do campo: string com o tamanho máximo de 60 caracteres.

nome:

  • O nome do produto ou grade cadastrado(a) no Hiper.
  • Tipo do campo: string com o tamanho máximo de 60 caracteres.

peso:

  • O peso do produto é utilizado para a embalagem no frete da mercadoria.
  • Tipo do campo: decimal (15,3).
  • Peso máximo: 999.999.999.999.999.999 // Peso mínimo: 0.000.

preco:

  • O preço de venda do produto cadastrado no Hiper.
    • O preço de venda do produto é exibido de acordo com a tabela de preço informada nas configurações da loja virtual.
  • Se o usuário não definir uma informação padrão, será exibido o preço definido no cadastro do produto.
  • Se o usuário definir uma informação padrão, será exibido o preço definido na tabela de preço do produto.
    • Preço máximo: 999.999.999.999.999.99 // Preço mínimo: 0.01.

produtoPrimarioId:

  • O identificador da grade do produto cadastrado no Hiper.
    • Se o produtoPrimarioId for vazia, o produto não possui grade.
    • Se o produtoPrimarioId possui uma informação, o produto possui grade.
  • Tipo do campo: uniqueidentifier com 36 caracteres.

quantidadeEmEstoque (Solução transferida para o objeto de estoque – Em breve, será removido):

  • A quantidade de estoque do produto no Hiper.
  • Tipo do campo: “decimal” (15,2).
  • Quantidade máxima: 999.999.999.999.999.99 // Quantidade mínima: -999.999.999.999.999.99.

quantidadeMinimaEmEstoque (Solução transferida para o objeto de estoque – Em breve, será removido):

  • A quantidade mínimo de estoque do produto no Hiper.
  • Tipo do campo: “decimal” (15,2).
  • Quantidade máxima: 999.999.999.999.999.99 // Quantidade mínima: 0.00.

tamanho (Solução transferida para o atributo “variacao” – Em breve, será removido):

  • O nome da grade com o tipo tamanho do produto cadastrado no Hiper.
  • Tamanhos padrões: P, M, G, GG, entre outros.
  • Tipo do campo: string com o tamanho máximo de 80 caracteres.

unidade:

  • A sigla da unidade de medida do produto.
  • Unidades padrões: “UN”, “KG”, “MT”, entre outras.
  • Tipo do campo: string com o tamanho máximo de 3 caracteres.

variacao:

  • O identificador, o tipo e a grade dos produtos.
    • id: O identificador do produto filho.
    • tipoVariacaoA: O nome do tipo da variação do produto.
      • Exemplo: “Cores”, “Tamanhos”, “Grãos”, entre outros.
    • nomeVariacaoA: O nome da variação do produto.
      • Exemplo: Azul, Amarelo, G, GG, entre outros.
    • tipoVariacaoB: O nome do tipo da variação do produto.
      • Exemplo: “Cores”, “Tamanhos”, “Grãos”, entre outros.
    • nomeVariacaoB: O nome da variação do produto.
      • Exemplo: Azul, Amarelo, G, GG, entre outros.
  • Se o produto possui grade e for produto principal, ou seja, o produto pai, serão exibidos: id, tipo e o nome do variação do produto filho.
  • Se o produto possui grade e for produto variação, ou seja, o produto filho, o campo “variacao” ficará vazio, pois o mesmo é a variação.
  • Tipo do campo: string com o tamanho máximo de 80 caracteres.

Exemplo de resposta do produto sem grade:

{

“pontoDeSincronizacao”: 1,

“produtos”: [

{

“altura”: 0,

“ativo”: true,

“categoria”: “VESTUÁRIO”,

“comprimento”: 0,

“cor”: “”,

“grade”: “true”,

“id”: “34852cf6-f222-4d61-86d1-045a1aee66f4”,

“imagem”: null,

“largura”: 0,

“marca”: “CHICCO”,

“nome”: “CAMISETA HEROIS – M – Marrom”,

“peso”: 0.000,

“preco”: 39.99,

“produtoPrimarioId”: “00000000-0000-0000-0000-000000000000”,

“quantidadeEmEstoque”: “99”,

“quantidadeMinimaEmEstoque”: “0.000000”,

“tamanho”: “M”,

“unidade”: “PC”,

“variacao”: []

},

],

“errors”: [],

“message”: null

}

Exemplo de resposta do produto com grade:

{

“pontoDeSincronizacao”: 1,

“produtos”: [

{

“altura”: 0.000,

“ativo”: true,

“categoria”: “ANEL”,

“comprimento”: 0.000,

“cor”: “”,

“descricao”: null,

“grade”: true,

“id”: “1cd76fcb-f4c2-406b-8da9-082c0311da19”,

“imagem”: null,

“largura”: 0.000,

“marca”: null,

“nome”: “Anel com ondas cravejadas – Semijoia”,

“peso”: 0.000,

“preco”: 49.90,

“produtoPrimarioId”: “00000000-0000-0000-0000-000000000000”,

“quantidadeEmEstoque”: 0,

“quantidadeMinimaEmEstoque”: 0,

“tamanho”: “”,

“unidade”: “UN”,

“variacao”: [

{

“id”: “e4987f9a-dddb-4207-9c91-0f2508a737ae”,

“tipoVariacaoA”: “Cores”,

“nomeVariacaoA”: “Dourado”,

“tipoVariacaoB”: “Tamanhos”,

“nomeVariacaoB”: “13”

},

]

},

],

“errors”: [],

“message”: null

},

{

“altura”: 0.000,

“ativo”: true,

“categoria”: “ANEL”,

“comprimento”: 0.000,

“cor”: “Dourado”,

“descricao”: null,

“grade”: true,

“id”: “e4987f9a-dddb-4207-9c91-0f2508a737ae”,

“imagem”: null,

“largura”: 0.000,

“marca”: null,

“nome”: “Anel com ondas cravejadas – Semijoia”,

“peso”: 0.000,

“preco”: 49.90,

“produtoPrimarioId”: “1cd76fcb-f4c2-406b-8da9-082c0311da19”,

“quantidadeEmEstoque”: 0,

“quantidadeMinimaEmEstoque”: 0,

“tamanho”: “13”,

“unidade”: “UN”,

“variacao”: []
}

],

“errors”: [],

“message”: null

}

GET - ESTOQUE

21/07/2020

A consulta do estoque do produto deve ser utilizada para a importação do saldo em estoque da sua loja virtual.

Para o consumo da chamada, você deve utilizar o seguinte endereço:

Parâmetros a serem passados na chamada:

Authorization:

  • Deverá ser passado o Bearer Token de autenticação.

pontoDeSincronizacao:

  • O ponto de sincronização é utilizado para controlar as atualizações que ocorrem no sistema desde a última consulta realizada, ou seja, se o estoque teve uma alteração será alterado automaticamente o ponto de sincronização.
    • Se você quiser, o saldo atual do estoque pode passar o ponto de sincronização igual a 0.
    • Para que a chamada não seja utilizada o tempo inteiro, deve ser armazenado o último ponto de sincronização para que num próximo retorne somente os produtos que tiverem atualização de estoque.

produtoId:

  • O identificador único do produto cadastrado no Hiper.
  • Tipo do campo: uniqueidentifier com 36 caracteres.

Parâmetros retornados na chamada:

quantidadeEmEstoque:
  • A quantidade mínimo de estoque do produto no Hiper.
  • Tipo do campo: “decimal” (15,2).
  • Quantidade máxima: 999.999.999.999.999.99 // Quantidade mínima: 0.00.
quantidadeMinimaEmEstoque:
  • A quantidade de estoque do produto no Hiper.
  • Tipo do campo: “decimal” (15,2).
  • Quantidade máxima: 999.999.999.999.999.99 // Quantidade mínima: -999.999.999.999.999.99.

Exemplo de resposta do estoque:

{
    “pontoDeSincronizacao”: 202,
    “produtoId”: “249acba9-ff35-5ad0-5065-35e6f588dbd8”,
    “quantidadeEmEstoque”: 10.000000,
    “quantidadeMinimaEmEstoque”: 0.000000,
    “errors”: [],
    “message”: null
}

POST - PEDIDO DE VENDA

22/04/2020

O pedido de venda realizado em sua loja virtual deverão ser enviados através dessa chamada. Com isso, o pedido de venda da sua loja virtual será cadastrado automaticamente para dentro do Hiper.

Para o consumo da chamada, você deve utilizar o seguinte endereço:

Parâmetros a serem passados na chamada:

Authorization:

  • Deverá ser passado o Bearer Token de autenticação.

Parâmetros a serem enviados na chamada:

cliente // documento:

  • O número do documento da pessoa física ou pessoa jurídica.
  • Tipo do campo: numérico com até 14 caracteres.
    • Deverá ser enviado o documento sem formatação, ou seja, sem caracteres especiais.
      • Se for enviado 14 caracteres será considerado pessoa jurídica.
      • Se for enviado 11 caracteres será considerado pessoa física.
  • O número do documento é uma informação obrigatória.

cliente // email:

  • O endereço de e-mail do cliente.
  • Tipo do campo: string com até 80 caracteres.
  • O endereço de e-mail é uma informação obrigatória.

cliente // inscricaoEstadual:

  • A número da inscrição estadual da pessoa física ou jurídica.
  • Tipo do campo: numérico com até 14 caracteres.
    • Deverá ser enviado o documento sem formatação, ou seja, sem caracteres especiais.

cliente // nomeDoCliente:

  • O nome completo do cliente ou razão social da empresa.
  • Tipo do campo: string com até 80 caracteres.
  • O nome do cliente ou razão social da empresa é uma informação obrigatória.

cliente // nomeFantasia:

  • O nome fantasia da pessoa jurídica.
  • Tipo do campo: string com até 60 caracteres.
  • O nome fantasia da empresa é uma informação obrigatória para pessoa jurídica.

enderecoDeCobranca // bairro:

  • O bairro do endereço de cobrança do cliente.
  • Tipo do campo: string com até 60 caracteres.
  • O bairro do endereço de cobrança do cliente é uma informação obrigatória.

enderecoDeCobranca // cep:

  • O CEP do endereço de cobrança do cliente.
  • Tipo do campo: numérico com 8 caracteres.
    • Deverá ser enviado o documento sem formatação, ou seja, sem caracteres especiais.
  • O CEP do endereço de cobrança é uma informação obrigatória.

enderecoDeCobranca // codigoIbge:

  • O código do IBGE da cidade do endereço de cobrança do cliente (mais informações disponível em: https://www.ibge.gov.br/explica/codigos-dos-municipios.php).
  • Tipo do campo: numérico com 7 caracteres.
  • O código do IBGE da cidade do endereço de cobrança do cliente é uma informação obrigatória.

enderecoDeCobranca // complemento:

  • O complemento do endereço de cobrança do cliente.
  • Tipo do campo: string com até 60 caracteres.

enderecoDeCobranca // logradouro:

  • O endereço de cobrança do cliente.
  • Tipo do campo: string com até 60 caracteres.
  • O endereço de cobrança do cliente é uma informação obrigatória.

enderecoDeCobranca // numero:

  • O número do endereço de cobrança do cliente.
  • Tipo do campo: string com até 10 caracteres.
  • O número do endereço de cobrança do cliente é uma informação obrigatória.

enderecoDeEntrega // bairro:

  • O bairro do endereço de entrega do cliente.
  • Tipo do campo: string com até 60 caracteres.
  • O bairro do endereço de entrega  é uma informação obrigatória.

enderecoDeEntrega // cep:

  • O CEP do endereço de entrega do cliente.
  • Tipo do campo: numérico com 8 caracteres.
    • Deverá ser enviado o documento sem formatação, ou seja, sem caracteres especiais.
  • O CEP do endereço de entrega é uma informação obrigatória.

enderecoDeEntrega // codigoIbge:

  • O código do IBGE da cidade do endereço de entrega do cliente (mais informações disponível em: https://www.ibge.gov.br/explica/codigos-dos-municipios.php).
  • Tipo do campo: numérico com 7 caracteres.
  • O código do IBGE da cidade do endereço de entrega do cliente é uma informação obrigatória.

enderecoDeEntrega // complemento:

  • O complemento do endereço de entrega do cliente.
  • Tipo do campo: string com até 60 caracteres.

enderecoDeEntrega // logradouro:

  • O endereço de entrega do cliente.
  • Tipo do campo: string com até 60 caracteres.
  • O endereço de entrega do cliente é uma informação obrigatória.

enderecoDeEntrega // numero:

  • O número do endereço de entrega do cliente.
  • Tipo do campo: string com até 10 caracteres.
  • O número do endereço de entrega do cliente é uma informação obrigatória.

itens // produtoId:

  • O identificador único do produto utilizado na venda.
    • Deverá ser enviado a identificação única utilizada no Hiper.
  • Tipo do campo: uniqueidentifier com 36 caracteres.
  • O produto utilizado na venda é uma informação obrigatória.

itens // quantidade:

  • A quantidade do produto utilizado na venda.
  • Tipo do campo: decimal (13,3).
  • A quantidade enviada deverá ser maior que 0.
  • Valor mínimo: 0.001 // Valor Máximo: 9999999999999.999.

meiosDePagamento // idMeioDePagamento:

  • O identificador do meio de pagamento da venda.
  • Tipo do campo: numérico com até 2 caracteres.
  • Boleto: 1 // Cartão de crédito: 4 // Cartão de débito: 5

meiosDePagamento // parcelas:

  • A quantidade de parcelas da venda.
  • Tipo do campo: numérico com até 2 caracteres.
  • A quantidade de parcelas enviada deverá ser maior que 0.
  • Se a venda realiza for à vista, deverá ser enviado como 1.

meiosDePagamento // valor:

  • O valor total líquido da venda.
  • Tipo do campo: decimal (12,2).
  • A quantidade enviada deverá ser maior que 0.
  • Valor mínimo: 0.01 // Valor Máximo: 999999999999.99.

valorDoFrete:

  • O valor do frete aplicado na venda.
  • Tipo do campo: decimal (12,2).
  • Valor mínimo: 0.01 // Valor Máximo: 999999999999.99.

 

Exemplo de requisição:

{

“cliente”:

{

“documento”: “19561920000”,

“email”: “clientedoecommerce@hotmail.com.br”,

“inscricaoEstadual”: “”,

“nomeDoCliente”: “Cliente do E-commerce”,

“nomeFantasia”: “”

},

“enderecoDeCobranca”: 

{

“bairro”: “Centro”,

“cep”: 88351001,

“codigoIbge”: 4202909,

“complemento”: “”,

“logradouro”: “Rua Principal”,

“numero”: “01”

},

“enderecoDeEntrega”: 

{

“bairro”: “Centro”,

“cep”: 88351001,

“codigoIbge”: 4202909,

“complemento”: “Sala 2”,

“logradouro”: “Rua Principal”,

“numero”: “22”

},

“itens”: 

[

{

“produtoId”: “34852cf6-f222-4d61-86d1-045a1aee66f4”,

“quantidade”: 1

}

],

“meiosDePagamento”:

[

{

“idMeioDePagamento”: 1,

“parcelas”: 1,

“valor” : 99.99

}

]

  “valorDoFrete”: 0,

}

 

Exemplo de resposta:

{

“id”: “158b044b-d887-4e47-b08c-e2b353b1c1d5”,

“errors”: [ ],

“message”: “Pedido recebido e em processamento.”

}

GET - PEDIDO DE VENDA

22/04/2020

Através da consulta de pedido do venda pode ser acompanhado o histórico de eventos do pedido de venda e informações como a situação do pedido de venda, o código de rastreio e o número do documento fiscal.

Para o consumo da chamada, você deve utilizar o seguinte endereço:

Parâmetros a serem passados na chamada:

Authorization:

  • Deverá ser passado o Bearer Token de autenticação.

id:

  • Deverá ser passado o identificador único do pedido de venda.

Parâmetros retornados na chamada:

cancelado:

  • A situação do pedido de venda no Hiper.
  • Tipo do campo: boolean.
    • Se for true, o pedido de venda está cancelado.
    • Se for false, o pedido de venda está ativo.

codigoDaSituacaoDeProcessamento:

  • A situação do processamento do pedido de venda no Hiper.
    • Em processamento: 1 // Processado com sucesso: 2 // Processado com erro: 3.
  • Tipo do campo: inteiro com até 2 caracteres.

codigoDoPedidoDeVenda:

  • O número do pedido de venda no Hiper.
  • Tipo do campo: string com até 40 caracteres.

data:

  • A data de criação do pedido de venda no Hiper.
  • Tipo do campo: data com o formato dd/MM/yyyy.

eventos // codigoDoTipoDeEvento:

  • O código do tipo de evento do pedido de venda no Hiper.
    • Processamento do pedido: 1 // Separação do produto em estoque: 2 // Emissão da nota fiscal: 3 // Entrega à transportadora: 4 // Cancelamento: 99.
  • Tipo do campo: interno com até 2 caracteres.

eventos // data:

  • A data que foi realizado o evento.
  • Tipo do campo: data com o formato dd/MM/yyyy.

eventos // observacao:

  • A observação do evento.
  • Tipo do campo: string.
  • A observação do evento pode retornar os detalhes de cada evento realizado no pedido de venda. Com a observação, será possível saber qual o número do documento fiscal, o código de rastreio da transportadora e qual o erro que ocorreu durante o processamento do pedido de venda.

pedidoDeVendaId:

  • O identificador único do pedido de venda cadastrado no Hiper.
  • Tipo do campo: uniqueidentifier com 36 caracteres.

Exemplo de resposta:

{

“cancelado”: true,

“codigoDaSituacaoDeProcessamento”: 2,

“codigoDoPedidoDeVenda”: null,

“data”: “27/03/2020 17:13:05”,

“eventos”: [

{

“codigoDoTipoDeEvento”: 99,

“data”: “27/03/2020 17:14:05”,

“observacao”: “Cancelamento efetuado pela integração com e-commerce.”

}

],

“pedidoDeVendaId”: “43a42deb-789f-4f67-a329-8172c1b0f611”,

“errors”: [ ],

“message”: null

}

PUT - PEDIDO DE VENDA

22/04/2020

A criação do pedido de venda reserva automaticamente o estoque da sua loja. Para manter seu estoque atualizado, é importante que os pedidos que foram canceladas em sua loja virtual seja cancelado no Hiper também.

Para o consumo da chamada, você deve utilizar o seguinte endereço:

Parâmetros a serem passados na chamada:

Authorization:

  • Deverá ser passado o Bearer Token de autenticação.

id:

  • A identificação única do pedido de venda no Hiper.

Exemplo de resposta:

{

“errors”: [],

“message”: “Cancelamento recebido e em processamento.”

}