# 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://desenvolvedores.skyhub.com.br/perguntas-e-respostas-americanas/perguntas-e-respostas.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.