API de Atendimento v2

A API de atendimento do Via Marketplace permite que o lojista tenha uma ótima comunicação com o cliente final para que tenham ótimos resultados com o atendimento e que agilize toda a operação do pós-venda do lojista, automatizando e otimizando as recorrências de vendas e findelizando o cliente.

O conceito desta API é oferecer ao lojista soluções pré-prontas para que consigam interagir com o cliente escolhendo sempre a melhor solução para um determinado atendimento.

Soluções

Uma das vantagens de usar a API de atendimento é que ela permite ao lojista oferecer soluções personalizadas e adequadas para cada situação. As soluções são formas de resolver os problemas ou dúvidas dos clientes, e podem ser desde uma troca, um reembolso ou uma informação. Com a API de atendimento, o lojista pode consultar as soluções disponíveis para cada incidente e escolher a melhor opção para o cliente.

Além disso, nesta nova versão da API, o lojista também pode selecionar uma solução na hora de criar um incidente preventivo. Isso significa que o lojista pode antecipar-se às necessidades do cliente e oferecer uma solução proativa, aumentando a satisfação e a fidelização. Assim, as soluções na API de atendimento são essenciais para o lojista conseguir interagir com o cliente de forma eficiente e satisfatória.

Abaixo listaremos todas elas:

Contagem	ID Solução	Soluções
1	1549	Aprovar o cancelamento da compra
2	1691	Cancelar a venda do produto
3	4111	Comunicar envio de nova peça ou acessório
4	4239	Confirmar endereço com o cliente
5	3775	Converse com o(a) cliente
6	2684	Finalizar atendimento ao cliente
7	4177	Informar cliente sobre busca de produto
8	3849	Informar data para retirar o produto
9	3891	Informar expedição do produto
10	3657	Informar nova data de entrega
11	4139	Informar o código de Postagem
12	2711	Pedir ajuda da Via
13	4343	Pedir carta de cancelamento
14	2710	Recusar cancelamento
15	4201	Solicitar fotos do produto ao cliente
16	4200	Solicitar fotos do produto com mais qualidade

URLs

Disponibilizamos um ambiente de homologação para a realização do desenvolvimento de todas as funcionalidades.

Abaixo informaremos os padrões tanto da base da URL em PRD quanto HLG:

BASE HLG

Quebrar linhas

>https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/

Collection Postman

A collection do Postman já está com os endpoints e bodys montados com a documentação completa explicando cada endpoint para que facilite ainda mais o desenvolvimento.

• Link BASE HLG e PRD:

Headers

Para o funcionamento da API, é obrigatório que preencham os headers com as chaves de acessos que seriam: access_token e client_id em todos os endpoints.

O "client_id” e “access_token” para o ambiente de HLG são gerados na criação da App através do portal para que seja possível realizar as chamadas com sucesso.

Para obter o acesso para o ambiente de PRD, é preciso que solicitem a homologação através do e-mail que será compartilhado ao final da documentação.

Caso não saiba como criar uma App, clique aqui.

Incidentes

Neste primeiro bloco vamos ver como usar os endpoints de consultas dos incidentes do Via Marketplace. Esses endpoints permitem que o lojista consulte os incidentes abertos pelos clientes que compraram seus produtos na plataforma da Via, e também que interaja com eles através de comentários. Os endpoints de incidentes são:

GET /incidents?page=1&pageSize=20&quickQuery=1&sort=asc

GET /incidents/idIncident

GET /incidents/idIncident/comments

Consulta de Incidentes Páginado

Neste endpint o lojista conseguirá obter todos os incidentes/protocolos abertos para ele onde damos a possibilidade de oferecerem vários filtros para que realizem a busca na aplicação que será desenvolvida.

• Método: : GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents?page=1&pageSize=20&quickQuery=1&sort=asc

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents?page=1&pageSize=20&quickQuery=1&sort=asc

SUGESTÃO

Para o retorno com sucesso das consultas, é muito importante aplicar um filtro que reduza a busca, com essa redução o retorno também será mais rápido. dimuindo o tempo de espera para obter o resultado da consulta.

Sugerimos aplicar os seguintes conjuntos de filtros: createdStart e createdEnd, slaStart e slaEnd, page e pageSize.

Filtros e querys disponíveis

Campo	Valor	Descrição	Obrigatório
closedEnd	YYYY-MM-DD	Filtro pelo range de data de encerramento do incidente	Não, porém recomendado
closedStart	YYYY-MM-DD	Filtro pelo range de data de encerramento do incidente	Não, porém recomendado
createdEnd	YYYY-MM-DD	Filtro pelo range de data de criação do incidente	Não, porém recomendado
createdStart	YYYY-MM-DD	Filtro pelo range de data de criação do incidente	Não, porém recomendado
updatedStart	YYYY-MM-DD	Filtro pelo range de data de atualização	Não, porém recomendado
updatedEnd	YYYY-MM-DD	Filtro pelo range de data de atualização	Não, porém recomendado
order	integer	Filtro por número do pedido relacionado ao incidente (9 digitos)	Não
page	1,2,3 etc	Página atual que esta sendo requisitada	Sim
pageSize	20,25 etc	Quantidade de elementos por página utilizado paginação	Sim
protocol	230215-002517	Filtro por número do protocolo relacionado ao incidente	Não
quickQuery	1, 2 ou 3	1 - Minhas pendências (filtro por: Status = 1 e Queue = Lojista) 2 - Consultas (filtro por: Status != Resolvidos, Queue != Lojista e Created >= D-30) 3 - Resolvidos (filtro por: Status = Resolvidos e Closed >= D-30	Não
reason	3632	Filtro por identificador do motivo relacionado ao incidente	Não
slaEnd	YYYY-MM-DD	Filtro pelo range de vencimento do incidente	Não, porém recomendado
slaStart	YYYY-MM-DD	Filtro pelo range de vencimento do incidente	Não, porém recomendado
sort	asc	Define o tipo de ordenação utilizada. asc ou dsc	Não, porém recomendado
sortBy	protocol, order, created, closed ou sla	Utilizado para indicar o campo a ser ordenado.	Não
status	1, 2 ou 3	1-Não resolvido; 2-Resolvido; 3-Aguardando	Não
summary	boolean	Exibe as informações de sumarização dos incidentes.	Não

Body Response da Chamada

Quebrar linhas

{
  "incidents": [
      {
          "id": 48654926,
          "protocol": "231213-000852",
          "organization": {
              "id": 8,
              "name": "B2C Casas Bahia"
          },
          "recontact": 0,
          "createdAt": "2023-12-13T10:50:31+00:00",
          "createdBy": "LUDMILLA DE OLIVEIRA MARTINS",
          "updatedAt": "2023-12-13T10:56:21+00:00",
          "sla": "2023-12-15T10:56:19+00:00",
          "order": 402373712,
          "delivery": 40237371201,
          "sku": 1556683331,
          "situation": "Solicitação / Troca e Cancelamento / Arrependimento (MKT)",
          "levels": [
              {
                  "id": 1051,
                  "name": "Solicitação"
              },
              {
                  "id": 3629,
                  "name": "Troca ou Cancelamento*"
              },
              {
                  "id": 3632,
                  "name": "Arrependimento*"
              }
          ],
          "status": "Não Resolvido",
          "queue": "Lojista",
          "type": "OV - Reclame Aqui Site",
          "channel": {
              "name": "Telefone",
              "special": true,
              "createdAt": "2023-12-13T03:00:00+00:00"
          }
      },
      {
          "id": 48653572,
          "protocol": "231212-021922",
          "organization": {
              "id": 8,
              "name": "B2C Casas Bahia"
          },
          "recontact": 2,
          "createdAt": "2023-12-13T01:08:40+00:00",
          "createdBy": "Robô Genérico",
          "updatedAt": "2023-12-13T11:42:32+00:00",
          "sla": "2023-12-15T15:08:40+00:00",
          "order": 404976296,
          "delivery": 40497629602,
          "sku": 0,
          "situation": "Reativo / Entrega / Atraso da entrega (MKT)",
          "levels": [
              {
                  "id": 1050,
                  "name": "Reclamação"
              },
              {
                  "id": 1099,
                  "name": "Entrega"
              },
              {
                  "id": 3592,
                  "name": "Reclamação sobre atraso*"
              }
          ],
          "status": "Não Resolvido",
          "queue": "Lojista",
          "type": "Reativo",
          "channel": {
              "name": "Meus Pedidos - Android",
              "special": false
          }
      },
      {
          "id": 48654356,
          "protocol": "231213-000282",
          "organization": {
              "id": 1,
              "name": "B2C Ponto Frio"
          },
          "recontact": 2,
          "createdAt": "2023-12-13T08:28:00+00:00",
          "createdBy": "Robô Genérico",
          "updatedAt": "2023-12-13T10:56:23+00:00",
          "sla": "2023-12-15T10:20:11+00:00",
          "order": 404751420,
          "delivery": 40475142001,
          "sku": 0,
          "situation": "Solicitação / Troca e Cancelamento / Arrependimento (MKT)",
          "levels": [
              {
                  "id": 1051,
                  "name": "Solicitação"
              },
              {
                  "id": 3629,
                  "name": "Troca ou Cancelamento*"
              },
              {
                  "id": 3632,
                  "name": "Arrependimento*"
              }
          ],
          "status": "Não Resolvido",
          "queue": "Lojista",
          "type": "Reativo",
          "channel": {
              "name": "Meus Pedidos - mSite",
              "special": false
          }
      }

Consulta detalhe de um incidente específico

Este serviço permite que o lojista consulte um incidente específico e obtenha informações detalhadas sobre o mesmo, como data, hora, motivo e status. Isso pode ajudar o lojista a acompanhar o andamento do incidente e tomar as medidas necessárias para resolvê-lo. Para usar este serviço, é preciso informar o "idIncident" do incidente desejado, que pode ser obtido no endpoint páginado que lista todos os incidentes.

O serviço retorna um objeto JSON com os dados do incidente consultado.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}

Body Response da Chamada

Quebrar linhas

{
  "id": 48626260,
  "protocol": "231211-017858",
  "organization": {
      "id": 8,
      "name": "B2C Casas Bahia"
  },
  "recontact": 0,
  "createdAt": "2023-12-11T20:15:39+00:00",
  "createdBy": "ALAN SENHOR",
  "updatedAt": "2023-12-11T20:17:17+00:00",
  "sla": "2023-12-13T20:17:17+00:00",
  "order": 404059373,
  "delivery": 40405937301,
  "sku": 1556226437,
  "situation": "Reativo / Entrega / Atraso da entrega (MKT)",
  "levels": [
      {
          "id": 1050,
          "name": "Reclamação"
      },
      {
          "id": 1099,
          "name": "Entrega"
      },
      {
          "id": 3592,
          "name": "Reclamação sobre atraso*"
      }
  ],
  "status": "Não Resolvido",
  "queue": "Lojista",
  "type": "Reativo",
  "channel": {
      "name": "Telefone",
      "special": false
  }
}  ```
</CodeWrapper>

## Consulta comentários

Uma das funcionalidades mais importantes do nosso sistema é a possibilidade de consultar as integrações realizadas em um incidente específico. Essa consulta permite que a loja acompanhe todas as conversas que ocorreram entre os envolvidos na resolução de um problema.
Assim, a loja pode verificar o histórico de comunicação e o responsável por cada interação. Essa transparência ajuda a melhorar a confiança e a satisfação dos clientes. Para realizar essa consulta, basta acessar o endpoint que disponibilizamos na nossa API. Nesse endpoint, você pode informar o código do incidente que deseja consultar e receberá uma lista de todas as integrações realizadas.

• **Método:**<Paint text='GET' color='info' />

• **Endpoint:**

<Paint text='BASE HLG' color='success'/>

<CodeWrapper>

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/comments

</CodeWrapper>

<Paint text='BASE PRD' color='success'/>

<CodeWrapper>

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/comments

</CodeWrapper>

<CodeWrapper>
  ```json
{
    "comments": [
        {
            "id": 100594609,
            "createdAt": "2023-02-15T19:37:17+00:00",
            "createdBy": "HENRIQUE FLORIANO",
            "userType": "Atendimento Via",
            "comment": "<div>\n<div>Caro lojista conforme o seu retorno fora infomado que o Pedido será mantido e seguirá fluxo padrão conforme solicitado - mas houve o cancelamemnto em 15/02, desta forma poderia averiguar o ocorrido e nos respaldar. Obrigado pelo retorno</div>\n</div>"
        },
        {
            "id": 100573692,
            "createdAt": "2023-02-15T15:41:16+00:00",
            "createdBy": "Integracao Lojista",
            "userType": "Atualização Automática",
            "comment": "Leonardo - Boa tarde!<br>Pedido será mantido e seguirá fluxo padrão conforme solicitado.<br><span style=\"background-color: transparent;\">Atenciosamente,</span><span style=\"background-color: transparent;\">Equipe Drogaria Araujo</span><br>"
        },
        {
            "id": 100553599,
            "createdAt": "2023-02-15T11:58:41+00:00",
            "createdBy": "HENRIQUE FLORIANO",
            "userType": "Atendimento Via",
            "comment": "<div>\n<div>Caro lojista, conforme o protocolo 230214-023881, cliente se equivocou e não requer mais o cancelamento e deseja seguir com o reenvio. Por gentileza dar andamento ao reenvio das mercadorias  Fralda Pampers Supersec Tamanho XXG 34 Fraldas Descartáveis  no valor total de R$ R$ 109,24</div>\n</div>"
        }
    ],
    "pagination": {
        "page": 1,
        "pageSize": 20,
        "totalElements": 3,
        "totalPages": 1
    }
}

Incidente - Criar

Neste bloco iremos mostrar o fluxo de criação de incidentes e todos os requisitos para que possam deixar todas as opções em tela para o lojista conseguir escolher no momento da abertura do incidente. Ter essa funcionalidade bem mapeada significa que o lojista pode antecipar-se às necessidades do cliente e oferecer uma solução proativa, aumentando a satisfação e a fidelização.

Neste fluxo estão disponíveis os seguintes endpoints:

BASE HLG /incidents/new?deliveryId=37234727601&orderId=372347276&reasonId=4315

BASE HLG /incidents/new

IMPORTANTE

Para a abertura de um incidente preventivo é preciso se atentar com os status atual do pedido quando selecioado os motivos para essa criação. Abaixo falaremos um pouco mais sobre essa regra de status:

Preventivo Lojista>Entrega>Problema na entrega: permindo abrir incidente apenas quando o pedido já tenha sido pago e que não estejam com status de cancelado ou entregue.

Preventivo Lojista>Separação de Pedidos>Mercadoria Indisponível: apenas para entregas enVVias, permitindo abrir somente quando o pedido já tenha sido pago e que não estejam com status de cancelado (CAN, DVC) ou entregue (ENT).

Preventivo Lojista>FInanceiro>Carta de Cancelamento de Venda: apenas para entregas enVVias e Fulfillment, permitindo abrir somente quando o pedido estiver cancelado nos pontos de (CAN, DVC, CMS ou RDV).

Preventivo Lojista>FInanceiro>Devolução de Produto pelo Cliente: apenas para entregas enVVias e Fulfillment, permitindo abrir somente quando o pedido estiver cancelado nos pontos de (CAN ,DVC ou RDV).

Consulte aqui o link com a documentação de todos os motivos da árevore de preventivo: clique aqui.

Consulta parametros para criar um Incidente

Neste serviço oferecemos a possíbilidade de consultar os parâmetros necessários para criação de um incidente. Esses parâmetros serão utilziados para o preenchimento correto do bodyresquest da requisição.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/new?deliveryId=37234727601&orderId=372347276&reasonId=4315

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/new?deliveryId=37234727601&orderId=372347276&reasonId=4315

Para essa consulta é necessário os seguintes parâmetros para a consulta:

Campo	Valor	Descrição	Obrigatório
orderId	372347276	Filtro por número da entrega (09 digitos)	Sim
deliveryId	37234727601	Filtro por número do pedido (11 digitos)	Sim
reasonId	4315	Motivos consultados no endpoint GET /reasons	Sim

Body response da chamada

Quebrar linhas

{
  "solutions": [
      {
          "description": "Aqui, você comunica o cliente sobre a nova data de entrega do pedido.",
          "fields": [
              {
                  "name": "annotation",
                  "type": "string",
                  "required": true,
                  "minLength": 20
              },
              {
                  "name": "newDeliveryDate",
                  "type": "date",
                  "format": "yyyy-mm-dd",
                  "required": true
              }
          ],
          "id": 3657,
          "name": "Informar nova data de entrega"
      }
  ]
}

IMPORTANTE

Os parâmetros vão ser alterados conforme informação buscada no reasonId através do endpoint de GET /reasons que veremos mais a frente da documentação. Cada motivo tem informações e soluções específicas para serem escolhidas na hora da abertura do incidente pelo lojista.

Criação de um incidente

Aqui vamos ver o fluxo de criação de um incidente na prática usando como base a consulta realizada no tópico acima para identificar quais os parâmetros deveremos usar para preencher o bodyrequest da requisição.

IMPORTANTE

Para utilizar esse serviço é preciso que façam a consulta dos parâmetros para preenchimento adequado do bodyequest, a consulta preisa ser feita seguindo as instruições do conteúdo, Consulta parametros para criar um Incidente.

• Método:POST

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/new

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/new

Body Request da chamada

Quebrar linhas

{
  "orderId": 0,
  "deliveryId": 0,
  "reasonId": 0,
  "solution": {
      "id": 0,
      "annotation": "string",
      "attachments": [
          {
              "temporaryId": "string",
              "fileName": "string",
              "contentType": "string",
              "size": 0
          }
      ]
  }
}

Campo	Formato	Descrição	Obrigatório
oderId	integer	Número do pedido com 9 digitos	SIM
deliveryId	integer	Número do pedido com 11 digitos	SIM
reasonId	integer	Código obtido no GET /reasons	SIM
solution	-	array	Sim
id	integer	id solução retornado no GET /incidents/new	SIM
annotation	string	integração com o cliente máx 1000 caracteres	SIM
attachments	-	array	Não
temporaryId	string	id do anexo novo	SIM
fileName	string	nome do arquivo	SIM
contentType	string	Tipo do arquivo anexado	Não
size	integer	Tamanho do arquivo anexado (Em bytes)	Não

IMPORTANTE

Caso não for anexado nenhum arquivo na criação do incidente, podem remover o array "attachments" pois o mesmo não é obrigatório para a criação de incidentes.

Body response da chamada

200

Quebrar linhas

{
  "id": 43645042,
  "protocol": "230406-000055",
  "organization": {
      "id": 1,
      "name": "B2C Ponto Frio"
  },
  "recontact": 0,
  "createdAt": "2023-04-06T19:50:21+00:00",
  "createdBy": "Robô Monitoramento",
  "order": 372347276,
  "delivery": 37234727601,
  "sku": 1545855230,
  "situation": "Preventivo lojista / Entrega / Alteração da data de entrega (MKT)",
  "levels": [
      {
          "id": 3659,
          "name": "Preventivo lojista"
      },
      {
          "id": 3660,
          "name": "Entrega"
      },
      {
          "id": 4315,
          "name": "Alteração da data de entrega"
      }
  ],
  "status": "Não Resolvido",
  "type": "Preventivo",
  "channel": {
      "name": "Integração",
      "special": false
  }
}

Incidentes - Anexos

Neste bloco veremos todos os serviços responsáveis pelo fluxo de anexos na API de Atendimento. Essa funcionalidade permite que o lojista consiga anexar arquivos, facilitando a troca de informações entre a loja e o cliente ou entre a loja e o Via Marketplace, como evidências de entrega, documentos fiscais, fotos de produtos, etc.

Os serviços de anexos na API de Atendimento são:

GET /incidents/incidentid/attachments

GET/incidents/incidentId/attachments/attachmentId

GET /incidents/incidentId/attachments/attachmentId/download

POST /attachments/new

Consulta de todos os anexos encontrados

Este serviço é responsável por realizar a consulta de todos os anexos encontrados em um incidente específico. Muito utilizado para que o lojista consiga acessar arquivos anexados pelo cliente em um determinado momento das interações do atendimento.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{incidentid}}/attachments

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{incidentid}}/attachments

Body response da chamada

200

Quebrar linhas

{
  "attachments": [
      {
          "id": 4923740,
          "fileName": "tela em branco.png",
          "contentType": "image/x-png",
          "size": 3299
      }
  ],
  "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalElements": 1,
      "totalPages": 1
  }
}

IMPORTANTE

O campo "id", representando o id do anexo, será utilizado nos endpoints a seguir como parâmetro na URI da rquisição, dentro do campo "attachmentId".

Consulta anexo em Base64

Esse serviço está dinsponível para ajudar na obteção dos dados também em base64 para aqueles que preferirem obter neste formato. A consulta é bem simples, abaixo veremos o que é retornado entre outras informações:

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{incidentId}}/attachments/{{attachmentId}}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{incidentId}}/attachments/{{attachmentId}}

Body response da chamada

200

Quebrar linhas

{
  "id": 4923740,
  "fileName": "tela em branco.png",
  "contentType": "image/x-png",
  "size": 3299
}

Sumário do retorno da chamada

Campo	Descrição
id	Id do anexo
fileName	Nome do arquivo em base64
contentType	Tipo do arquivo
size	Tamanho do arquivo

Consulta anexo em Base64 Download

Neste serviço damos a opção do download do arquivo de forma unitária para que a loja consiga realizar o download do mesmo e visualiza-lo.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{incidentId}}/attachments/{{attachmentId}}/download}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{incidentId}}/attachments/{{attachmentId}}/download

Body Response de sucesso da chamada

IMPORTANTE

O retorno desse campo será o anexo do arquivo existente dentro do incidente para download e visualização.

Incluir novos anexos

Este serviço é o responsável por dar a possíbilidade de a loja conseguir incluir novos anexos dentro de um determinado incidente já existente quando necessário.

• Método:POST

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/attachments/new

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/attachments/new

Body Response de sucesso da chamada

Utlizar o formato do body em form-data

Campo	Formato	Descrição	Obrigatório?
iles	file	Anexar um arquivo no computador	Sim
Content-Type	multipart/form-data	formato da chamada	Sim

Body response de sucesso da chamada

Quebrar linhas

{
  "attachments": [
      {
          "temporaryId": "df8bc8ad-478c-4bd5-88be-0e52ad1d3354",
          "fileName": "Erro_500.png",
          "contentType": "image/png",
          "size": 42565
      }
  ]
}

O nome do arquivo não deve conter caracteres especiais

Incidentes - Soluções

Neste bloco apresentaremos o fluxo mais importante da API de Atendimento, que são as parametrizações para a interação com o cliente final onde nessa nova versão ficou super dinâmico e fácil de desenvolver pois diminuímos a gama de serviços que disponibilizamos na versão anterior.

Os serviços de anexos na API de Atendimento são:

GET /incidents/idIncident/solutions

GET /incidents/idIncidents/solutions/solutionId

PATCH /incidents/idIncidents/solutions/solutionId

Listagem de Soluções - Incidente

Esse serviço tem como objetivo listar todas as soluções disponíveis para um incidente específico. É de extrema importância que seja utilizado para mostrar ao lojista quais as soluções que ele pode escolher para seguir com a trativa do atendimento, escolhendo a melhor opção para o cenário do seu pedido e que melhor atenda o cliente final.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions

Body response de sucesso da chamada

Quebrar linhas

[
  {
      "description": "Aqui, você aprova o pedido de cancelamento feito pelo cliente. Antes de confirmar, verifique se não despachou o pedido e ou se ele já foi entregue, porque a mensagem de estorno é enviada na hora.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          }
      ],
      "id": 1691,
      "name": "Cancelar a venda do produto"
  },
  {
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          }
      ],
      "id": 4239,
      "name": "Confirmar endereço"
  },
  {
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          }
      ],
      "id": 3850,
      "name": "Entrega liberada"
  },
  {
      "description": "Aqui, você comunica o cliente sobre a nova data de entrega do pedido.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          },
          {
              "name": "newDeliveryDate",
              "type": "date",
              "format": "yyyy-mm-dd",
              "required": true
          }
      ],
      "id": 3657,
      "name": "Informar nova data de entrega"
  },
  {
      "description": "Aqui, você informa o código para o/a cliente fazer a postagem do produto. A gente acompanha este protocolo até a confirmação da devolução.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          },
          {
              "name": "trackingCode",
              "type": "string",
              "required": true
          }
      ],
      "id": 4139,
      "name": "Informar o código de Postagem"
  },
  {
      "description": "Aqui, você envia uma mensagem direta para o cliente. Tenha atenção com as palavras que vai usar. Seja transparente e tenha objetividade.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          }
      ],
      "id": 3775,
      "name": "Converse com o(a) cliente"
  },
  {
      "description": "Aqui, nós comunicamos quando você vai retirar o produto no endereço do cliente.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          },
          {
              "name": "collectDate",
              "type": "date",
              "format": "yyyy-mm-dd",
              "required": true
          }
      ],
      "id": 3849,
      "name": "Informar data para retirar o produto"
  },
  {
      "description": "Aqui, você informa o/a cliente que ele(a) precisa buscar o produto em um lugar específico.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          },
          {
              "name": "trackingCode",
              "type": "string",
              "required": true
          }
      ],
      "id": 4177,
      "name": "Informar cliente sobre busca de produto"
  }
]

Retorna o Body a ser utilizado na chamada de interação

Este serviço tem como objetivo retornar o body a ser utilizado no endpoint de interação, onde deve ser consultado utilizando a solução escolhida e o incidente escolhido para o atendimento.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions/{{idSolution}}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions/{{idSolution}}

Body response de sucesso da chamada

Quebrar linhas

{
  "cancellation": {
      "product": "Maca 3 Posições Reclinável Bellacom Preto For-Ty",
      "availableQuantity": 1,
      "requestedQuantity": 1
  },
  "solution": {
      "description": "Aqui, você aprova o pedido de cancelamento feito pelo cliente. Antes de confirmar, verifique se não despachou o pedido e ou se ele já foi entregue, porque a mensagem de estorno é enviada na hora.",
      "fields": [
          {
              "name": "annotation",
              "type": "string",
              "required": true,
              "minLength": 20
          }
      ],
      "id": 1691,
      "name": "Cancelar a venda do produto"
  }
}

Interação efetiva através da solução escolhida

Esse serviço é o único e principal endpoint para o lojista realizar as interações com o cliente final e quando necessário com o Via Marketplace. Nele será preenchido sempre a solução e formato de body escolhido utilizando a solução escolhida.

O lojista pode escolher entre diferentes soluções e formatos de body para integrar seu sistema ao Via Marketplace, porém, sempre utilizando apenas uma solução por cada interação em um determinado incidente. Cada solução tem suas vantagens e desvantagens, dependendo das necessidades e preferências do lojista. O formato de body é a estrutura dos dados que serão enviados ou recebidos pelo endpoint e é preciso obte-los nos endpoits de consultas apresentados nesse bloco.

• Método:PATCH

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions/{{idSolution}}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions/{{idSolution}}

Body Request da chamada

Quebrar linhas

{
"solutionId": 4114,
"annotation": "Mensagem para registro do histórico no incidente",
"attachments": [
  {
    "temporaryId": "07ebc62d-442e-4bd4-b34e-a46b9c4b410d",
    "fileName": "NomeArquivo.pdf",
    "contentType": "application/pdf",
    "size": 1354
  }
]
}

Campo	Tipo	Obrigatório	Descrição
solutionId	integer	Sim	Id da solução escolhida
annotation	string	Sim	Interação em texto do lojista
attachments	array	Não	informações sobre o anexo

IMPORTANTE

O body da chamada desse endpoint sempre será preenchido com base na consulta de quais parâmetros devem utilizar para preenchimento do corpo da requisição com base na solução escolhida pelo lojista.

Sigam sempre o que é informado nos seguintes endpoints: Método: GET https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions

Método:* GET https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/incidents/{{idIncident}}/solutions/{{idSolution}}

Caso queiram realizar a inclusão de um anexo em um incidente aberto, será necessário preencher o body a seguir que é retornado no endpoint de inclusão de anexo, caso queira saber como ele funciona, clique aqui.

Quebrar linhas

"attachments": [
  {
    "temporaryId": "07ebc62d-442e-4bd4-b34e-a46b9c4b410d",
    "fileName": "NomeArquivo.pdf",
    "contentType": "application/pdf",
    "size": 1354
  }
]
}

Configurações

Nesse bloco veremos funcionalidades importantes para as configurações necessárias das interações. Aqui veremos todas as consultas que auxiliam na configuração visual do que o desenvolvedor mostrará para o lojista na tela desenvolvida para realizar o atendimento.

Estamos muito animados em compartilhar com vocês as novidades que preparamos para facilitar e otimizar o seu trabalho. Com as funcionalidades que vamos apresentar, você poderá personalizar a interface do seu aplicativo, escolher os recursos que melhor atendem às suas necessidades e garantir uma comunicação eficiente e satisfatória.

Os serviços de anexos na API de Atendimento são:

GET /reasons

GET /solutions

GET /solutions/solutionId

Consulta motivos para criação de incidente

Esse serviço tem como objetivo retornar todas as razões/motivos disponíveis para o lojista escolher na abertura de um incidente. Ou seja, com ele será possível listar no momento da abertura do incidente todas as opções que a loja tem para escolher o que melhor se encaixa para um pedido específico, além disso, nessa nova versão disponíbilizamos soluções específicas para que o lojista escolha no momento da abertura.

Abaixo listaremos cada motivo existente e quais as soluções disponíveis para cada um e o que acontecerá com o incidente aberto após a escolha:

Contagem	ID Motivo	Motivo	Soluções	Resultado Fila
1	4367	Problema na entrega	- Cancelar a venda do produto - Confirmar endereço - Informar cliente sobre busca de produto - Informar nova data de entrega - Converse com o(a) cliente	- Fila de monitoramento financeiro - Fila bkoffice Marketplace - Finalizador - Finalizador - Finalizador
2	4368	Devolução de produto pelo cliente	- Informar data para retirar o produto - Informar o código de Postagem - Converse com o(a) cliente	- Fila bkoffice Marketplace - Fila bkoffice Marketplace - Finalizador
3	4370	Carta de cancelamento	- Pedir carta de cancelamento	- Fila CSC CAR
4	4310	Mercadoria indisponível	- Cancelar a venda do produto	- Fila de monitoramento financeiro

Parametros

Campo	Valor	Descrição	Obrigatório
deliveryId	37234727601	Filtro por número do pedido (11 digitos)	Sim
orderId	372347276	Filtro por número da entrega (09 digitos)	Sim

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/reasons?{{deliveryId}}&{{orderId}}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/reasons?{{deliveryId}}&{{orderId}}

Body response de sucesso da chamada

Quebrar linhas

[
  {
      "id": 3659,
      "name": "Preventivo lojista",
      "reasons": [
          {
              "id": 3660,
              "name": "Entrega",
              "reasons": [
                  {
                      "id": 4331,
                      "name": "Devolução de produto pelo cliente"
                  },
                  {
                      "id": 4327,
                      "name": "Problema na Entrega"
                  }
              ]
          },
          {
              "id": 4329,
              "name": "Financeiro",
              "reasons": [
                  {
                      "id": 4330,
                      "name": "Carta de cancelamento de venda"
                  }
              ]
          },
          {
              "id": 4309,
              "name": "Separação de Pedidos",
              "reasons": [
                  {
                      "id": 4310,
                      "name": "Mercadoria indisponível"
                  }
              ]
          }
      ]
  }
]

Lista todas as soluções possíveis

Este serviço oferece uma visão geral das diferentes soluções disponíveis para os lojistas e as informações relevantes sobre cada uma delas. Assim, os lojistas podem comparar as vantagens e desvantagens de cada solução e escolher a mais adequada para suas necessidades. Além disso, o serviço também fornece confirmações importantes que devem ser apresentadas aos lojistas quando eles optarem por uma solução específica.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/solutions

BASE PRD

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/solution

Lista todas as soluções possíveis (Unitário)

Este serviço oferece uma visão unitária das soluções disponíveis para os lojistas e as informações relevantes de uma opção específica. Assim, caso saibam quais as soluções existentes no marketplace, podem utilizar este para diminuir o volume de soluções existentes reduzindo a busca e deixando a mesma mais assertiva com base na sua consulta.

• Método:PATCH

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/solutions/{{solutionId}}

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/solutions/{{solutionId}}

Body response da chamada

Quebrar linhas

{
  "description": "Resolveu todos os pontos com o cliente? Então é aqui que vamos finalizar o atendimento.",
  "fields": [
      {
          "name": "annotation",
          "type": "string",
          "required": true,
          "minLength": 20
      }
  ],
  "id": 2684,
  "name": "Finalizar atendimento ao cliente"
}

Relatórios

Este bloco é uma ferramenta que permite ao lojista obter relatórios detalhados sobre os protocolos que estão na sua fila de atendimento. O objetivo é facilitar a exportação desses dados para outros sistemas ou arquivos. O lojista pode filtrar os protocolos por data, status, tipo e origem, e visualizar as informações mais relevantes de cada um. Além disso, o lojista pode baixar os relatórios em formato CSV ou PDF, conforme sua preferência.

Os serviços de anexos na API de Atendimento são:

POST /reports/incidents

GET /reports/reportId/status

GET /reports/reportId/download

Geração de relatório

Através deste endpoint é iniciado o processo de criação de um CSV contendo o relatório dos incidentes de acordo com parâmetros informados através do corpo da requisição. Após a inicialização é necessário aguardar até o fim do processamento e realizar o download através do endpoint **/reports/download/id. Para saber a situação do processamento é necessário consultar através do endpoint **/reports/status/id.

• Método:POST

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/reports/incidents

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/reports/incidents

Quebrar linhas

{
"createdStart": "2019-08-24T14:15:22Z",
"createdEnd": "2019-08-24T14:15:22Z",
"closedStart": "2019-08-24T14:15:22Z",
"closedEnd": "2019-08-24T14:15:22Z",
"reasonId": 0,
"status": 0,
"order": 0,
"protocol": "string"
}

Campo	Valor	Tipo	Obrigatório	Descrição
createdStart	2019-08-24T14:15:22Z	string	Sim	Data inicial do incidente
createdEnd	2019-08-24T14:15:22Z	string	Sim	Data final do incidente
closedStart	2019-08-28T14:15:22Z	string	Sim	Data inicio de fechamento
closedEnd	2019-08-31T14:15:22Z	string	Sim	Data final de fechamento
reasonId	Motivo (opcional)	integer	Não	Identificador único do motivo
status	1 , 2 ou 3	integer	Sim	Identificador do tipo (1 = Pendente, 2 = Consulta e 3 = Resolvido)
order	123569874	integer	Não	Número do pedido com nove digitos

ATENÇÃO

É preciso escolher o filtro de datas que gostariam de utilizar, exemplo:

createdStart": "2019-08-24T14:15:22Z - createdEnd": "2019-08-24T14:15:22Z

closedStart": "2019-08-24T14:15:22Z - closedEnd": "2019-08-24T14:15:22Z

Consulta status do relatório

Este endpoint permite consultar a situação da emissão do relatório de incidentes, que é um documento que contém informações sobre os problemas ocorridos durante o processo de venda ou entrega de um produto ou serviço. Para acessar este endpoint, é necessário fazer uma requisição na rota /reports/incidents e receber um objeto com os dados do relatório, como o status, a data, o número e o tipo de incidente.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/reports/reportId/status

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/reports/reportId/status

Para saber como é o retorno dessa chamada, clique aqui e vá para Responses body.

Download do relatório

Este endpoint permite que você baixe um relatório de incidentes em formato CSV. O relatório contém informações sobre os incidentes registrados no sistema, como data, hora, local, tipo e descrição. Você pode usar esse relatório para analisar os padrões e as causas dos incidentes e tomar medidas preventivas ou corretivas.

• Método:GET

• Endpoint:

BASE HLG

Quebrar linhas

https://api-mktplace-hlg.viavarejo.com.br/customer-services/v2/reports/reportId/download

BASE PRD

Quebrar linhas

https://api-mktplace.viavarejo.com.br/customer-services/v2/reports/reportId/download

Importante

Pedimos que ao final do desenvolvimento ou em caso de dúvidas, para que possamos auxiliar na homologação e tirar todas as dúvidas, entre em contato com nosso time de integração através do seguinte endereço de e-mail: integracao.mktp@viavarejo.com.br.

Marketplace

Sobre o Marketplace

Certifica

Primeiros Passos

Integração Passo a Passo

Fulfillment

Serviços Assíncronos

Modelagem

Termos de Uso

Artigos

CB Entrega (Envvias)

API de Atendimento v2

Soluções

URLs

Collection Postman

Headers

Incidentes

Consulta de Incidentes Páginado

SUGESTÃO

Filtros e querys disponíveis

Consulta detalhe de um incidente específico

Incidente - Criar

IMPORTANTE

Consulta parametros para criar um Incidente

IMPORTANTE

Criação de um incidente

IMPORTANTE

IMPORTANTE

Incidentes - Anexos

Consulta de todos os anexos encontrados

IMPORTANTE

Consulta anexo em Base64

Consulta anexo em Base64 Download

IMPORTANTE

Incluir novos anexos

Incidentes - Soluções

Listagem de Soluções - Incidente

Retorna o Body a ser utilizado na chamada de interação

Interação efetiva através da solução escolhida

IMPORTANTE

Configurações

Consulta motivos para criação de incidente

Parametros

Lista todas as soluções possíveis

Lista todas as soluções possíveis (Unitário)

Relatórios

Geração de relatório

ATENÇÃO

Consulta status do relatório

Download do relatório

Importante