Como implementar as APIs para lojistas

Como implementar as APIs para lojistas


 

A leitura deste tutorial é extremamente recomendável pra você (lojista/plataforma) que irá iniciar sua integração com as APIs do Buscapé.

 

1. Fluxo de telas para o processo de autenticação

As plataformas deverão disponibilizar uma tela de configuração para seus clientes (lojistas). Nesta tela o cliente deverá:

  • Encontrar/visualizar o appToken da plataforma (previamente homologado pelo suporte técnico do Buscapé), pois o lojista precisará saber para gerar o authToken.
  • Poderá cadastrar o authToken que é gerado pelo lojista na Central de Negócios do Buscapé. Para ser utilizado posteriormente pela plataforma na integração/requisições com a API.

Para gerar o app-token é necessário realizar o cadastro no Developer (através do link "ACESSAR" no topo superior direito) e estar logado, após isso aparecerá um link "Meus Aplicativos", clique em "Nova Aplicação" crie a aplicação do tipo API Loja.

Para gerar o authToken o lojista precisará saber qual é o appToken da plataforma (precisa estar previamente homologado pelo suporte técnico do Buscapé - Solicitar homologação), por isso sugerimos a criação desta tela para que o processo fique mais transparente tanto para a plataforma quanto para o lojista. E a plataforma precisará saber qual é o authToken da loja para realizar as requisições na API. Para mais informações sobre o processo de autenticação da API clique aqui.

Esta tela deverá disparar a carga de produtos do lojista (mais detalhes abaixo) quando o mesmo cadastrar o authToken.

Este fluxo de tela foi idealizada preferencialmente para plataformas, lojistas com plataformas próprias poderão utilizar o entendimento do fluxo para adaptar da melhor forma em seu processo interno.

 

2. Implementando a API para publicação de produtos no Buscapé/Lomadee.

Esta API foi criada para realizar 2 funções:

O método para Atualização de inventário foi idealizado para que você (lojista/plataforma) atualize o estoque e o preço do produto toda vez que houver alteração do mesmo no seu site, porém é possível que você envie um lote de atualização seguindo as regras a seguir:

Formas de utilização Período máximo de defasagem no envio
Pode ser enviado 1 produto de cada vez (modelo ideal) sempre que houver qualquer mudança no preço ou estoque do produto.  on-line
Pode ser enviado em lotes de produtos (isto é, você poderá acumular atualizações e enviar de uma só vez), porém não pode ultrapassar o período de 2 minutos do momento em que o preço ou estoque foi alterado. 2 minutos

O método para Carga de produtos foi idealizado para que você (lojista/plataforma) cadastre ou atualize os produtos no Buscapé, essa API processa a solicitação on-line, e quando conseguimos categorizar sistemicamente (ou já categorizado previamente) o produto pode ser publicado em até 2 horas. Veja abaixo as regras para o uso dessa API:

Formas de utilização
Deve ser utilizado para fazer a carga inicial de produtos (limitado a 1000 produtos por requisição). Não recomendado para lojas com mais de 500k produtos (para estes casos entre em contato no nosso suporte). Para as plataformas recomendamos que essa carga seja realizada quando o lojista fizer o cadastro do authToken (descrito no item 1).
Deve ser utilizado para atualizar produtos que sofreram alterações nos seus dados (descrição, atributos técnicos, imagens, etc). Não recomendado para atualizar preço e estoque de um produto, para esta fim deve utilizar a API Atualização de inventário descrita acima.
Deve ser utilizado para cadastrar novos produtos que não foram enviados na carga inicial. Esse diferencial pode ser processado on-line, isto é, enviado junto do processo de cadastro de produto ou em lote onde a plataforma deverá guardar todas os novos cadastros e enviar de uma só vez num período máximo de 1 vez por dia.

O desenvolvimento da integração com a API deverá ser realizado no nosso ambiente de sandbox que não necessita de authToken e o appToken deverá ser gerado pelo próprio desenvolvedor através de cadastro no site.

Qualquer dúvida que o desenvolvedor tiver durante a implementação desta integração o mesmo deverá utilizar nosso canal de suporte.

E após conclusão do desenvolvimento o desenvolvedor deverá enviar outra solicitação de suporte (canal de suporte) para que possamos homologar a implementação. Sugerimos fortemente que o processo acima seja seguido para que a homologação seja mais rápido, caso queira implementar outro fluxo diferente do descrito neste tutorial sugerimos que seja acertado previamente com o time de suporte. 

 

3. Implementando as tags do E-bit (Banner e Selo)

As tags do E-bit são de suma importância para avaliação da loja junto ao consumidor e ao Buscapé, pois as lojas bem avaliadas possuem preferência no processo de ordenação dos produtos no site do Buscapé, trazendo mais exposição para a loja junto ao usuário final.

Apesar da implementação ser bem simples, atenção aos detalhes nas informações enviadas que são fundamentais para evitarmos equivocos que podem prejudicar o lojista e o consumidor.

São necessários duas integrações, o Selo e o Banner e Lightbox.

Após realizar a integração com o banner e selo utilize nossa ferramenta de validação. Para isso será necessário fazer todos os passos até o checkout da venda até que o banner seja carregado. Após isso acesse a página Validar Integração e insira o seu ID E-bit. Caso esteja tudo correto, basta solicitar a homologação através do formulário de suporte.

 

4. Integração da API de pedidos

A API de pedidos deverá ser integrada para disponibilizar o botão comprar agora no site do Buscapé (Entre em contato com o suporte comercial para mais informações sobre esse modelo comercial).

Para esta API a plataforma ou lojista com plataforma própria deverão criar os seguintes processos:

  • Disponibilizar API para receber o evento callback de um novo pedido. Após recebimento do evento a plataforma deverá tratar internamente de acordo com o status recebido.
    • Quando o status for "new" a plataforma deverá recuperar os dados do pedido para criar o pedido internamente (lembrando que nesse status o pagamento ainda não foi confirmado, porém o produto deverá ser reservado)
    • Quando o status for "approved" a plataforma deverá confirmar internamente o pagamento do pedido e encaminha-lo para o processo de entrega (lembrando que o pagamento do pedido foi realizado pelo consumidor direto no banking do lojista no bcash ou pagseguro, de acordo com a configuração realizada pelo lojista na Central de Negócios do Buscapé. O ID do pedido no banking é o mesmo ID enviado pelo buscapé no evento de callback)
    • Quando o status for "cancelled" a plataforma deverá retirar a reserva do produto e cancelar o produto internamente.
  • Deverá criar um processo alternativo para minimizar possíveis erros/indisponibilidade do evento de callback. Esse processo deverá buscar todos os pedidos com status "new" e "approved" para identificar pedidos que não foram criados pelo evento de callback, esses pedidos deverão ser criados seguindo as regras descritas acima no evento de callback.
  • Após envio do pedido e recebimento do mesmo pelo consumidor a plataforma deverá informar o Buscapé através da API de Atualizar status de um pedido.
    • Quando o pedido for enviado a plataforma deverá atualizar o status do pedido para "sent".
    • Quando o pedido for entregue a plataforma deverá atualizar o status do pedido para "delivered".
    • Quando o pedido for cancelado por algum motivo pelo lojista a plataforma deverá atualizar o status do pedido para "canceled", informando o motivo do cancelamento.

A plataforma poderá criar uma tela (ou um filtro) onde o lojista poderá consultar os pedidos realizados através do Buscapé.

Após implementação da integração com essa API o desenvolvedor deverá solicitar a homologação.