Documentação técnica – Loja virtual

Confira aqui 

A API personalizada do Hiper, permite com que qualquer plataforma de e-commerce ou loja virtual realize a integração com o Hiper Gestão. Para realizar a integração é necessário ter um conhecimento em desenvolvimento de sistemas e utilizar as credenciais disponíveis nas configurações da loja virtual dentro do próprio Hiper.

Novos campos e chamadas disponíveis

Nos últimos meses, a API personalizada do Hiper teve diversas atualizações e recebeu incrementos necessários para entregar mais informações aos e-commerces integrados com o Hiper. 

 

API de Produtos [GET]

Na API de produtos, são retornados todos os produtos que estão marcados no cadastro de produto do Hiper com a opção “Enviar produto para a loja virutal”. 

Nessa API, foram adicionados os seguintes campos:

• codigo
  • No campo “codigo” é exibido o código interno do Hiper (ex.: 3001, 3002, 3003).
• codigoDeBarras
  • No campo “codigoDeBarras” é exibido o código de barras do produto mais recente, nesse campo não será retornado mais de um código de barras, apenas o código de barras mais recente do produto.
  • Se o produto não tiver nenhum código de barras, o campo “codigoDeBarras” será retornado como vazio (“null”).
• descricao
  • No campo “descricao” é exibida a descrição do produto lançado no Hiper, a descrição possui o limite de 700 caracteres.
• grade
  • No campo “grade” é informado se o produto pertence ou não a uma grade. Se o produto tiver grade, sendo a grade pai ou a grade filha, será exibido como “true” (verdadeiro). Se o produto não possui grade, será exibido como “false” (falso).
• imagensAdicionais
  • No campo “imagensAdicionais” serão exibidas as imagens secundárias do produto, a imagem principal do produto, está disponíevel no campo “imagem”. Seguindo o padrão do Hiper, a API suporta até 5 imagens (uma principal + quatro adicionais).
• ncm
  • No campo “ncm”  será retornado o NCM do cadastro do produto com o seguinte padrão “0000.00.00”.
• variacao
  • No objeto “variacao” serão retornadas as grades do produto pai, com as seguintes informações do produto filho: o ID do produto filho, o nome da variação da grade e o tipo de variação da grade.

 

Na API de produtos, não devem ser mais utilizados os campos:

• tamanho
  • O campo “tamanho” foi migrado para o objeto “variacao”.
• cor
  • O campo “cor” foi migrado para o objeto “variacao”.
• quantidadeEmEstoque
  • O campo “quantidadeMinimaEmEstoque” foi migrado para a API de Estoque.
• quantidadeMinimaEmEstoque
  • O campo “quantidadeMinimaEmEstoque” foi migrado para a API de Estoque.

 

API de Estoque [GET]

Na API de estoque, é retornado o estoque individual do produto, o saldo do estoque é o local do estoque que foi definido nas configurações padrões da loja virtual no Hiper. Para que seja retornado o saldo em estoque do produto, deverá ser enviada na requisição o ID do produto.

Nessa API, foram adicionados os seguintes campos:

• pontoDeSincronizacao
  • No campo “pontoDeSincronizacao” é retornado o número último ponto de sincronização. Ao realizar uma nova requisição, deverá ser enviado o último ponto de sincronização e assim sucessivamente.
    • A cada atualização de estoque do produto, o ponto de sincronização recebe um incremento, isso representa que o saldo do produto foi atualizado.
• produtoId
  • No campo “produtoId” o identificador interno do Hiper.
• quantidadeEmEstoque
  • No campo “quantidadeEmEstoque” é retornada a quantidade de estoque do produto, sem descontar a reserva de estoque.
• quantidadeMinimaEmEstoque
  • No campo “quantidadeMinimaEmEstoque” é retornada a quantidade mínima em estoque do produto, essa informação é definida no cadastro de produto do Hiper.,

API de Pedido de venda [POST]

Na API de pedido de venda, deve ser enviado a venda realizada no e-commerce para o Hiper. No Hiper, a venda estará disponível na listagem de pedidos de venda.

Nessa API, foram adicionados os seguintes campos:

• precoUnitarioBruto
  • O valor unitário bruto do item do pedido de venda, sem descontos ou acréscimos.
• precoUnitarioLiquido
  • O valor unitário líquido do item do pedido de venda, o valor que foi realizada a venda do item.
• numeroPedidoDeVenda
  • O número do pedido de venda no e-commerce, o número pode ser utilizado como busca no Hiper, porém não será o número do pedido no Hiper. No Hiper, será mantido a numeração padrão: “LV + número do pedido”.
• observacaoDoPedidoDeVenda
  • A observação do pedido de venda no e-commerce.

API de eventos de Pedido de venda [GET]

Na consulta de eventos do pedido de venda são retornadas as informações de faturamento, número do pedido de venda no Hiper, entre outras informações.

Nessa API, foram adicionados os seguintes campos:

• chaveDocumentoFiscal
  • O número do documento fiscal, utilizado para a NF-e (nota fiscal eletrônica).
• tipoDocumentoFiscal
  • O tipo do documento fiscal, como por exemplo a NF-e, NFC-e, NF ou NFVC.
• urlArquivoXml
  • O arquivo XML da NF-e, através desse arquivo é possível realizar o download do XML.

 

A documentação completa da integração via API com o Hiper está disponível neste artigo.

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:

• http://ms-ecommerce.hiper.com.br/api/v1/auth/gerar-token/{chaveDeSeguranca}

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

}

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:

• http://ms-ecommerce.hiper.com.br/api/v1/produtos/pontoDeSincronizacao

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.

codigo:

• O código interno do produto disponível no Hiper.
  • Exemplo: 3001, 3002, 3003, entre outros.
• Tipo do campo: inteiro.
• Valor máximo: 99999999999999

codigoDeBarras:

• O código de barras do produto.
  • Exemplo: 7812381318321, 7812381311234, entre outros.
• Tipo de campo: string com o tamanho máximo de 36 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 – NÃO UTILIZAR!):

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.

imagensAdicionais:

• As imagens adicionais serão exibidas através de links ao diretório da nossa estrutura de dados.
  • As imagens adicionais são as imagens diferentes da principal do cadastro de produto, a imagem principal do produto está disponível no campo imagem.
• 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.

ncm:

• O NCM que pertence o produto cadastrado no Hiper.
• Tipo do campo: string com o tamanho máximo de 10 caracteres.
  • Formato: 0000.00.00

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 – NÃO UTILIZAR!):

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

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

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,

“codigo”: 3001,

“codigoDeBarras”: “7898935968974”,

“categoria”: “VESTUÁRIO”,

“comprimento”: 0,

“grade”: “true”,

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

“imagem”: null,

“imagensAdicionais”: [],

“largura”: 0,

“marca”: “CHICCO“,

“ncm”: “0101.29.00”,

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

“peso”: 0.000,

“preco”: 39.99,

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

“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,

“codigo”: 3100,

“codigoDeBarras”: “7898935964039”,

“descricao”: null,

“grade”: true,

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

“imagem”: null,

“imagensAdicionais”: [

{

“imagem”: “https://hiper-gestao.s3.amazonaws.com/30becddf-be6c-4c52-9492-587da40235e4/imagem-de-produto/244d5a3f-b899-4bc3-bcf7-770a60771355/original.jpeg”

},

{

“imagem”: “https://hiper-gestao.s3.amazonaws.com/30becddf-be6c-4c52-9492-587da40235e4/imagem-de-produto/f82365fb-50a0-4bf8-a29f-8bb53f9424cd/original.jpeg”

},

{

“imagem”: “https://hiper-gestao.s3.amazonaws.com/30becddf-be6c-4c52-9492-587da40235e4/imagem-de-produto/f92ff7a9-9d43-4722-b465-be4b2904fddf/original.jpeg”

},

{
“imagem”: “https://hiper-gestao.s3.amazonaws.com/30becddf-be6c-4c52-9492-587da40235e4/imagem-de-produto/14d1f2ee-e1da-48d8-8a4d-faa98c4eb77d/original.jpeg”

}

],

“largura”: 0.000,

“marca”: null,

“ncm”: “0101.29.00”,

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

“peso”: 0.000,

“preco”: 49.90,

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

“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”,

“codigo”: 3100,

“codigoDeBarras”: null,

“comprimento”: 0.000,

“descricao”: null,

“grade”: true,

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

“imagem”: null,

“imagensAdicionais”: [],

“largura”: 0.000,

“marca”: null,

“ncm”: “0101.29.00”,

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

“peso”: 0.000,

“preco”: 49.90,

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

“unidade”: “UN”,

“variacao”: [],

“errors”: [],

“message”: null

}

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:

• http://ms-ecommerce.hiper.com.br/api/v1/estoques/pontoDeSincronizacao?ProdutoId={ProdutoId}

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:

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:

• http://ms-ecommerce.hiper.com.br/api/v1/pedido-de-venda/

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: string 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: string 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.
  • Somente serão aceitos produtos cadastrados/originados do 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.

itens // precoUnitarioBruto:

• O valor bruto do produto utilizado na venda do e-commerce.
• Tipo do campo: decimal (12,2).
• A quantidade enviada deverá ser maior que 0.
• Valor: mínimo: 0.01 // Valor máximo: 999999999999.99.

itens // precoUnitarioLiquido:

• O valor líquido do produto utilizado na venda do e-commerce.
  • Se o produto tiver um desconto, o preço líquido deverá ser menor que o bruto.
  • Se o produto tiver um acréscimo, o preço líquido deverá ser maior que o bruto.
  • Se o produto produto não houver acréscimo ou desconto, o preço líquido deverá ser o mesmo do bruto.
• Tipo do campo: decimal (12,2).
• A quantidade enviada deverá ser maior que 0.
• Valor: mínimo: 0.01 // Valor máximo: 999999999999.99.
• Observação: Deverá ser enviado o valor unitário do produto, a multiplicação do total, ocorrerá de acordo com a quantidade.

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.

numeroPedidoDeVenda:

• O número do pedido de venda no e-commerce.
• Tipo do campo: string com até 20 caracteres.
• Observação: o pedido não será criado com esse número, apenas estará disponível para buscas nos pedidos de venda no Hiper.

observacaoDoPedidoDeVenda:

• A observação do pedido de venda no e-commerce.
• Tipo do campo: string com até 100 caracteres.

valorDoFrete:

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

Marketplace// CNPJ:

• CNPJ da Loja virtual que você está utilizando;
• Tipo do campo: numérico com até 14 caracteres.
• Campo Opcional de envio.
• Deve ser informado o campo, caso o estabelecimento seja do estado de SC;

Marketplace// Nome:

• Nome da Loja virtual que você está utilizando;
• Tipo do campo: string com até 44 caracteres.
• Campo Opcional de envio.
• Deve ser informado o campo, caso o estabelecimento seja do estado de SC;

 

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,

“precoUnitarioBruto”: 99.99,

“precoUnitarioLiquido”: 99.99

}

],

“meiosDePagamento”:

[

{

“idMeioDePagamento”: 1,

“parcelas”: 1,

“valor” : 99.99

}

]

  “numeroPedidoDeVenda”:””,

  “observacaoDoPedidoDeVenda”:””,

  “valorDoFrete”: 0

“Marketplace”: {
“Cnpj”:”12605982000124″,
“Nome”:”Hiper”
}

}

 

Exemplo de resposta:

{

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

“errors”: [ ],

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

}

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:

• http://ms-ecommerce.hiper.com.br/api/v1/pedido-de-venda/eventos/{id}

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.

chaveDocumentoFiscal:

• A chave completa da nota fiscal eletrônica (NF-e).
• Tipo do campo: string com 44 caracteres.

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 // chaveDocumentoFiscal:

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.

eventos // tipoDocumentoFiscal:

• O tipo de documento que foi realizado o faturamento do pedido de venda
  • Exemplos: NF, NF-e ou NFVC.
• Tipo do campo: string

eventos // urlArquivoXml:

• A URL com o link para download do arquivo XML da nota fiscal eletrônica (NF-e).
• Tipo do campo: string

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”: [

{

“chaveDocumentoFiscal”: “42201212605982000124552880000025701319587551”,

“codigoDoTipoDeEvento”: 3,

“data”: “17/12/2020 13:20:48”,

“observacao”: “Número da Nota Fiscal: 2570 – Série: 288”,

“tipoDocumentoFiscal”: “NFE”,

“urlArquivoXml”: “https://hiper-gestao.s3.amazonaws.com/30becddf-be6c-4c52-9492-587da40235e4/Xmls/2020_12/12605982000124/Emitidos/Saidas/Nfe/Autorizadas/42201212605982000124552880000025701319587551-Nfe.xml”

}

],

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

“errors”: [ ],

“message”: null

}

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:

• http://ms-ecommerce.hiper.com.br/api/v1/pedido-de-venda/cancelar/{id}

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.”

}

• Quantos produtos posso consultar pela requisição?
  Na requisição não existe um limite de produtos, porém como ainda não existe uma paginação de produtos, se torna inviável processar os dados quando se tem um numero muito grande de produtos no e-commerce (1000+ produtos).
• Estou tendo dificuldades para realizar a implementação, onde posso solicitar apoio?
  – Disponibilizamos o e-mail api@hiper.com.br para tratar situações de dúvida ou problemas com a implementação da integração via API.
• Como funciona o ponto de sincronização?
  – Cada alteração no Hiper gera um novo ponto de sincronização, dessa forma, para realizar a gestão das alterações, basta comparar o último ponto de sincronização registrado no e-commerce com o último ponto disponível na API.
• Existe paginação na rota de produtos e estoque?
  – Ainda não existe implementado a paginação das rotas de produto e estoque.
• Não conheço nenhum desenvolvedor mas quero ter um e-commerce, como posso proceder?
  – Existem diversas plataformas de e-commerce que já tem implementado a integração via API com o Hiper ( Haninger, Dooca, Wbuy e Loja Mestre)
• Quando realizo a consulta, não é retornado nenhuma informação, o que pode estar acontecendo?
  – Validar se no Hiper Gestão existem produtos com a flag “Enviar produto para a loja virtual” marcada. >Saiba mais<
• Ao realizar a consulta estou tendo o retorno de erro 404 Not Found, o que fazer?
  – Validar se a rota utilizada esta correta.
  (ex: http://ms-ecommerce.hiper.com.br/api/v1/produtos/pontoDeSincronizacao?pontoDeSincronizacao=0)
• Há alguma previsão de ser implementada a paginação na rota de produtos e estoque?
  – As rotas com paginação estão atualmente em testes e logo serão liberadas.