> For the complete documentation index, see [llms.txt](https://docs.troqueedevolva.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.troqueedevolva.com.br/configuracoes/plugins-customizados.md).

# Plugins customizados

### Plugins de rastreamento

**A data de entrega é o que destrava suas automações.** É a partir dela que a Troque & Devolva conta os prazos de troca, devolução e garantia, e autoriza ou nega a solicitação sem intervenção da sua equipe.

Normalmente essa informação vem da sua plataforma de e-commerce, do seu ERP ou das transportadoras já integradas. Mas se você trabalha com uma transportadora regional, um sistema próprio de rastreio ou um serviço que ainda não integramos, o **plugin de rastreamento** permite que você mesmo faça essa ligação.

Na prática, você ensina à Troque & Devolva duas coisas: **onde consultar** o rastreio e **como ler a resposta**. É exatamente isso que as duas etapas do cadastro pedem: **Conectar** e **Mapear**.

{% hint style="info" %}
Este é um recurso técnico. Para configurá-lo você vai precisar da documentação da API da sua transportadora, normalmente com o apoio de quem cuida da parte técnica da sua operação.
{% endhint %}

### Antes de começar

Você vai precisar de três informações, todas fornecidas pela sua transportadora:

* **O endereço de consulta (URL)** que retorna o rastreio de um código de postagem
* **As credenciais de acesso**, se a consulta exigir token ou chave de API
* **Um código de rastreamento real**, de um pedido que você sabe que já foi entregue, para testar

### Onde encontrar

No painel, acesse **Configurações > Plugins Customizados**. Na área **Plugins de rastreamento**, clique em **Adicionar**.

<figure><img src="/files/VxaXIlQXvscCOtFtezV4" alt=""><figcaption><p>Área de Plugins Customizados, com a listagem de plugins de rastreamento</p></figcaption></figure>

### Etapa 1: Conectar

Aqui você descreve a consulta que a Troque & Devolva vai fazer na sua transportadora.

Em **Nome**, informe como o plugin será chamado, normalmente o nome da transportadora. Esse nome aparece no histórico das solicitações sempre que o plugin encontrar uma entrega, então use algo que sua equipe reconheça.

Em seguida, escolha o **Método** (GET ou POST) e informe a **URL** de consulta.

<figure><img src="/files/nsE547gsNv4HHrPY7eSg" alt=""><figcaption><p>Etapa Conectar: nome, método e URL da consulta</p></figcaption></figure>

#### Usando os dados da solicitação na consulta

Para que a mesma configuração funcione em qualquer solicitação, você usa **placeholders**: marcações que a Troque & Devolva troca pelo dado real do pedido no momento da consulta.

**Digite `{` em qualquer campo para ver a lista de placeholders disponíveis.** Os principais são:

* `{tracking_code}`: código de rastreamento do pedido
* `{order_number}`: número do pedido
* `{buyer_email}`: e-mail do cliente
* `{buyer_document}`: CPF ou CNPJ do cliente

Uma URL típica fica assim:

```
https://api.suatransportadora.com.br/v1/rastreio/{tracking_code}
```

{% hint style="warning" %}
A URL precisa conter pelo menos um placeholder. Sem isso, não é possível testar a configuração com um dado real na etapa seguinte.
{% endhint %}

#### Opções avançadas

Se a consulta exigir autenticação ou parâmetros extras, abra **Opções avançadas**.

Em **Headers**, informe o cabeçalho e o valor exigidos pela transportadora, é aqui que entra o token de acesso. Use **+ adicionar header** para incluir quantos precisar. Em **Query params**, informe os parâmetros que vão na URL, no formato chave e valor.

<figure><img src="/files/HDtcZCzVRmFLbrkhxgiY" alt=""><figcaption><p>Opções avançadas: headers e parâmetros de consulta</p></figcaption></figure>

#### Quando o método for POST

Ao escolher **POST**, aparecem dois campos adicionais: **Body**, onde você monta o conteúdo que será enviado (também aceita placeholders), e **Formato**, onde você indica como esse conteúdo deve ser transmitido.

<figure><img src="/files/4ySBCx71rLyi1yJX8HyL" alt=""><figcaption><p>Configuração do corpo da requisição quando o método é POST</p></figcaption></figure>

#### Dados de exemplo pra mapear

Antes de avançar, informe um **código de rastreamento real** de um pedido já entregue. A Troque & Devolva usa esse código para consultar a transportadora de verdade e mostrar a resposta na próxima etapa, é com essa resposta em mãos que você faz o mapeamento.

Com tudo preenchido, o botão muda para **Testar e avançar**. Clique nele: a consulta é feita na hora, de verdade, e o resultado aparece na etapa seguinte.

### Etapa 2: Mapear

Aqui a Troque & Devolva mostra **a resposta real da sua transportadora**, obtida com o código de rastreamento que você informou na etapa anterior.

Você não precisa escrever nenhum código nem caminho: os valores da resposta aparecem destacados e clicáveis. Você vai marcar dois deles, o que indica a entrega e o que traz a data.

<figure><img src="/files/Dyoo7iPVLDJV4W9OXNsB" alt=""><figcaption><p>Etapa Mapear: a resposta da transportadora com os valores clicáveis</p></figcaption></figure>

#### Marcando o status de entrega

Clique no valor que indica que o pedido foi entregue, normalmente o status, a situação ou a descrição do evento de entrega. A Troque & Devolva mostra o campo selecionado e pergunta o que ele representa. Escolha **Status de entrega**.

<figure><img src="/files/EAU1nBShKW3ylRZgJAFZ" alt=""><figcaption><p>Ao clicar em um valor, você indica se ele é o status ou a data de entrega</p></figcaption></figure>

Em seguida, defina como esse valor deve ser comparado:

* **Valor exato**: a entrega só é reconhecida quando o campo for exatamente igual ao valor selecionado. Use quando a transportadora devolve um status padronizado, como `entregue` ou um código fixo
* **Contém o texto**: a entrega é reconhecida quando o campo tiver aquele trecho em qualquer parte. Use quando a transportadora devolve frases variáveis, como "Objeto entregue ao destinatário"

Clique em **Adicionar condição**.

<figure><img src="/files/mlb4oJ7LabwyhpMqoYR1" alt=""><figcaption><p>Escolha entre valor exato e contém o texto ao criar a condição de entrega</p></figcaption></figure>

{% hint style="info" %}
Você pode adicionar mais de uma condição, repetindo o processo em outros valores. Se **qualquer uma** delas for verdadeira, o pedido é considerado entregue.
{% endhint %}

#### Marcando a data de entrega

Agora clique no valor que contém a data em que o pedido foi entregue e escolha **Adicionar como data de entrega**. Não é preciso informar o formato: a Troque & Devolva reconhece os formatos mais comuns automaticamente.

<figure><img src="/files/WTTYvXGbOQVK8UYumQFE" alt=""><figcaption><p>Marcando o campo que contém a data de entrega</p></figcaption></figure>

#### Conferindo e criando

No rodapé, **Considera entregue quando** e **Data de entrega vem de** mostram o que foi mapeado. Enquanto estiverem como "Nada mapeado ainda", o plugin não está pronto. Se marcar algo errado, use o **x** ao lado para remover.

<figure><img src="/files/UaC9i0f3b0GIhL0A0XzK" alt=""><figcaption><p>Os dois campos mapeados, prontos para criar o plugin</p></figcaption></figure>

Com os dois preenchidos, clique em **Criar**.

O plugin passa a aparecer na listagem, com os campos que você mapeou e a indicação de que está ativo. Use **Editar** para ajustar a configuração e **Excluir** para removê-lo.

<figure><img src="/files/mX02NC3z1EXZd6HDG0gy" alt=""><figcaption><p>Plugin de rastreamento criado e ativo na listagem</p></figcaption></figure>

{% hint style="warning" %}
Marque os dois campos com atenção. Um plugin mapeado no valor errado não gera erro visível: ele simplesmente nunca encontra a entrega, e as solicitações continuam esperando análise manual.
{% endhint %}

### Como o plugin funciona no dia a dia

Assim que uma nova solicitação é criada, a Troque & Devolva consulta seus plugins ativos **antes** de tentar as transportadoras integradas, o ERP e a plataforma de e-commerce.

Se o plugin encontrar a entrega, a data é gravada na solicitação, as automações são acionadas na sequência e um comentário é registrado no histórico identificando o plugin que trouxe a informação.

Se nenhuma fonte encontrar a data, a Troque & Devolva tenta novamente a cada 30 minutos, por até 24 horas. Isso cobre o caso comum do cliente abrir a solicitação antes de o rastreio ser atualizado pela transportadora.

### Pontos de atenção

* Você pode cadastrar até **20 plugins de rastreamento por loja**
* Os plugins são consultados **na ordem em que foram cadastrados**. Se você tem mais de um, deixe primeiro o que resolve a maior parte dos casos
* Um plugin **desativado** é ignorado, sem ser excluído, útil para testes
* O plugin só é consultado em solicitações que tenham **código de rastreamento** no pedido
* Se a transportadora não responder ou retornar erro, a Troque & Devolva segue para a próxima fonte, sem interromper o atendimento

{% hint style="info" %}
Precisa de ajuda para configurar? Fale com nosso suporte com a documentação da API da sua transportadora em mãos que orientamos o preenchimento.
{% endhint %}