Perguntas e Respostas (Q&A)

Recurso disponibilizado para interação via API entre clientes e sellers através de webhook

Perguntas e Respostas (Questions and Answers) é o recurso destinado à interação de sellers e clientes pré-venda. Através do endpoint disponibilizado (/qna) é possível receber via API as perguntas realizadas pelo potencial cliente nos sites de venda e oferecer uma resposta capaz de auxiliá-lo antes da realização da compra.

POST - Solicitar credenciais

O recurso de Perguntas e Respostas utilizará a rota do rehub, sendo assim, o primeiro passo para a integração é a solicitação do token Bearer JWT através de um POST no seguinte endpoint:

https://api.skyhub.com.br/auth

Request headers:

Name	Type
Accept	application/json
Content-Type	application/json
X-Accountmanager-Key	token_account único de cada Plataforma/ERP

Request body:

{
	"user_email": "email_de_usuario",
	"api_key": "token_de_integracao"
}

Example request:

curl --location --request POST 'https://api.skyhub.com.br/auth' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Accountmanager-Key: token_account_da_plataforma' \
--data-raw '{
	"user_email": "email_de_usuario",
	"api_key": "token_de_integracao"
}'

Response esperado:

200 - Success [OK]: Haverá um response body com o Bearer JWT:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR...........Fy0yaf08cfM"
}

A validade do Bearer JWT é de 6 horas e solicitamos que, para manter a integridade da API, não seja solicitado um novo token antes do vencimento deste prazo (6 horas).

POST - Cadastro do webhook

Para que seja possível receber notificações quando uma nova pergunta é realizada pelo cliente é necessário cadastrar a URL de um webhook para a transmissão de informações entre a API e a plataforma/ERP.

O cadastro será realizado a partir do POST no endpoint a seguir:

https://api.skyhub.com.br/rehub/qna/enable

Request headers:

Name	Type
Accept	*/*
Content-Type	application/json
X-Accountmanager-Key	token_account único de cada Plataforma/ERP
Authorization	Bearer <token JWT disponibilizado na requisição anterior>

Request body:

{
  "webhook": "https://urlparacallback.site",
  "version": 2
}

A requisição para o cadastro do webhook conta com um campo para definição do versionamento da API de Q&A.

As principais diferenças entre as versões consistem nas notificações recebidas:

• Versão 1 (v1): Possui as notificações de nova pergunta e resposta rejeitada;

• Versão 2 (v2): Conta com as notificações de nova pergunta, resposta rejeitada e pergunta já respondida.

Além dos tipos de notificações, a v2 conta com mais informações no payload encaminhado para o webhook cadastrado para cada conta. Todos os exemplos disponibilizados neste guia tratam as notificações da v2.

Example request:

curl --location --request POST 'https://api.skyhub.com.br/rehub/qna/enable' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...........Fy0yaf08cfM' \
--data-raw '{
  "webhook": "https://urlparacallback.site",
  "version": 2
}'

Response esperado:

204 - Success [No content]

As contas de teste não possuem vínculo com o marketplace e por este motivo o retorno pode ser de status 422 com a mensagem "An error ocurred while updating QnA data, please try again later".

Notificações

Após cadastro do webhook, a API da Americanas será capaz de encaminhar notificações para a plataforma/ERP através da URL registrada (cadastrada), cabendo ao sistema (plataforma/ERP) o consumo das informações direcionadas pela API para a referida URL.

Em caso de haverem novos questionamentos, a notificação contará com os seguintes dados:

{
  "type": "question",
  "question": {
    "text": "Queria saber se a bicleta tem pedal equilibrado",
    "id": "6ccc1119ac8b628167245e6501346740",
    "created_at": "2023-05-10T10:02:41Z"
  },
  "product": {
    "sku": "00112233",
    "name": "Bicicleta Alumínio Aro 29"
  },
  "customer": {
    "name": "Customer Name",
    "id": "02-00060710-1"
  },
  "channel": "Lojas Americanas"
}

Para respostas rejeitadas, as notificações seguirão o padrão disponibilizado a seguir:

{
  "type": "rejected_answer",
  "question": {
    "id": "6ccc1119ac8b628167245e6501346740"
  },
  "product": {
    "sku": "00112233",
    "name": "Bicicleta Alumínio Aro 29"
  },
  "partner": {
    "name": "Getulio",
    "id": "17619304000000"
  },
  "customer": {
    "name": "Customer Name",
    "id": "02-03000002-1"
  },
  "channel": "Lojas Americanas",
  "answer": {
    "text": "Tem verde e amarelo!",
    "id": "62e441dfa28489a8460139b42a54a399",
    "date": "2023-05-20T10:02:41Z"
  }
}

Já as notificações de pergunta já respondida, terão o seguinte formato:

É importante ressaltar que apenas a v2 possui as notificações do "Already Answered" (pergunta já respondida).

{
  "type": "already_answered",
  "question": {
    "id": "6ccc1119ac8b628167245e6501346740"
  },
  "product": {
    "sku": "00112233",
    "name": "Bicicleta Alumínio Aro 29"
  },
  "partner": {
    "name": "Getulio",
    "id": "17619304000000"
  },
  "customer": {
    "name": "Customer Name",
    "id": "02-03000002-1"
  },
  "channel": "Lojas Americanas",
  "answer": {
    "text": "Exemplo da resposta",
    "id": "e230c1fbf98ecf17a6677c2ee0435075",
    "date": "2023-05-21T20:49:51.289785Z"
  }
}

POST - Respondendo uma pergunta

O response mencionado acima trará informações sobre a estrutura da questão recebida. A partir dele será disponibilizado o ID da questão e este deverá ser utilizado para a interação do seller com o cliente.

A interação deverá ocorrer por intermédio de um POST no endpoint abaixo:

https://api.skyhub.com.br/rehub/qna/{question_id}/answer 

Request headers:

Name	Type
Accept	application/json
Content-Type	application/json
X-Accountmanager-Key	token_account único de cada Plataforma/ERP
Authorization	Bearer <token JWT disponibilizado na requisição anterior>

Request body:

{
  "answer": "Sim! Este modelo apresenta pedal equilibrado."
}

Example request:

curl --location --request POST 'https://api.skyhub.com.br/rehub/qna/6ccc1119ac8b628167245e6501346740/answer' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...........Fy0yaf08cfM' \
--data-raw '{
  "answer": "Sim! Este modelo apresenta pedal equilibrado."
}'

Num cenário em que mais de um seller responda a questão apresentada, a primeira a ser recebida e aceita pelo portal será disponibilizada nos sites de venda.

POST - Cancelando o cadastro

É possível desabilitar um parceiro para que não sejam mais recebidas notificações naquela conta.

Para realizar a inativação será necessário executar um POST no endpoint descrito abaixo:

https://api.skyhub.com.br/rehub/qna/disable

Request headers:

Name	Type
Accept	*/*
X-Accountmanager-Key	token_account único de cada Plataforma/ERP
Authorization	Bearer <token JWT disponibilizado na requisição anterior>

Example request:

curl --location --request POST 'https://api.skyhub.com.br/rehub/qna/disable' \
--header 'Accept: */*' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...........Fy0yaf08cfM'

Response esperado:

204 - Success [No content]

As contas de teste não possuem vínculo com o marketplace e por este motivo o retorno pode ser de status 422 com a mensagem "An error ocurred while updating QnA data, please try again later".