> For the complete documentation index, see [llms.txt](https://desenvolvedores.skyhub.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://desenvolvedores.skyhub.com.br/perguntas-e-respostas-americanas/perguntas-e-respostas.md). # Perguntas e Respostas (Q\&A) 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:** {% hint style="success" %} 200 - Success \[OK]: Haverá um response body com o Bearer JWT: {% endhint %} ``` { "token": "eyJhbGciOiJIUzI1NiIsInR...........Fy0yaf08cfM" } ``` {% hint style="info" %} 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). {% endhint %} ## **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 \ | **Request body**: ``` { "webhook": "https://urlparacallback.site", "version": 2 } ``` {% hint style="info" %} **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. {% endhint %} **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**: {% hint style="success" %} 204 - Success \[No content] {% endhint %} {% hint style="danger" %} 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"*. {% endhint %} ### **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: {% hint style="info" %} É importante ressaltar que apenas a **v2** possui as notificações do "*Already Answered*" (pergunta já respondida). {% endhint %} ``` { "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 \ | **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." }' ``` {% hint style="info" %} 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. {% endhint %} ## **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 \ | **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:** {% hint style="success" %} 204 - Success \[No content] {% endhint %} {% hint style="danger" %} 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"*. {% endhint %}