> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ar-online.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Gerencie templates reutilizáveis com variáveis para os seus envios.

Templates são modelos de conteúdo reutilizáveis, com **variáveis** que você substitui no momento do envio. Em vez de repetir o mesmo texto a cada notificação, você cadastra um template uma vez e referencia as variáveis dinâmicas.

As variáveis usam a sintaxe `{{variavel}}` dentro do conteúdo. Exemplo:

```text theme={null}
Olá {{nome}}, você possui débitos pendentes no valor de {{valor}}.
```

<Warning>
  Atualmente, apenas os templates de **WhatsApp** estão funcionais. Os demais canais (Email, SMS, Carta e Voz) estarão disponíveis em breve.
</Warning>

## Autenticação

Como em toda a API, envie em **todas** as requisições o token no cabeçalho `Authorization` (sem o prefixo `Bearer`) e o `Content-Type: application/json`. O token de produção é solicitado ao suporte: [suporte@ar-online.com.br](mailto:suporte@ar-online.com.br).

```bash theme={null}
curl https://api.ar-online.com.br/gw/templates \
  -H "Authorization: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json"
```

## Endpoints disponíveis

| Método   | Endpoint                    | Descrição                         |
| -------- | --------------------------- | --------------------------------- |
| `GET`    | `/gw/templates`             | Listar templates do usuário       |
| `GET`    | `/gw/templates/{id}`        | Buscar template específico (UUID) |
| `PUT`    | `/gw/templates/{id}`        | Editar nome e compartilhamento    |
| `PATCH`  | `/gw/templates/{id}/status` | Ativar/desativar template         |
| `DELETE` | `/gw/templates/{id}`        | Desativar template (soft delete)  |

## Campos do template

<ResponseField name="id" type="string">
  UUID público do template.
</ResponseField>

<ResponseField name="templateId" type="string">
  ID do template no provedor (quando aplicável).
</ResponseField>

<ResponseField name="nome" type="string">
  Nome do template.
</ResponseField>

<ResponseField name="tipo" type="string">
  Tipo do template (`whatsapp`, `email`, `sms`, `carta`, `voz`).
</ResponseField>

<ResponseField name="conteudo" type="string">
  Conteúdo do template com variáveis no formato `{{variavel}}`.
</ResponseField>

<ResponseField name="variaveis" type="object">
  Objeto com as variáveis disponíveis e seus tipos.
</ResponseField>

<ResponseField name="ativo" type="boolean">
  Indica se o template está ativo.
</ResponseField>

<ResponseField name="versao" type="number">
  Número da versão atual do template.
</ResponseField>

<ResponseField name="criadoEm" type="string">
  Data de criação do template (ISO 8601).
</ResponseField>

<ResponseField name="atualizadoEm" type="string">
  Data da última atualização do template (ISO 8601).
</ResponseField>

<ResponseField name="compartilhadoComEntidade" type="boolean">
  Indica se o template está compartilhado com todos os usuários da mesma entidade.
</ResponseField>

## Operações

<AccordionGroup>
  <Accordion title="GET /gw/templates — Listar templates">
    Lista os templates acessíveis ao usuário (próprios + compartilhados com a sua entidade).

    **Query parameters**

    <ParamField query="type" type="integer">
      Filtra por tipo de template: `1` (WhatsApp), `2` (Email), `3` (SMS), `4` (Carta).
    </ParamField>

    **Exemplo de request**

    ```bash theme={null}
    curl "https://api.ar-online.com.br/gw/templates?type=1" \
      -H "Authorization: SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json"
    ```

    **Exemplo de response**

    ```json theme={null}
    {
      "data": [
        {
          "id": "f6cb58f2-3e9b-4899-b703-3facd52e17ee",
          "templateId": "provider-id-123",
          "nome": "Template Boas-vindas",
          "tipo": "email",
          "conteudo": "Olá {{nome}}, bem-vindo à plataforma!",
          "variaveis": {
            "nome": "string"
          },
          "ativo": true,
          "versao": 1,
          "criadoEm": "2026-03-23T10:00:00Z"
        },
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "templateId": "provider-id-456",
          "nome": "Template Cobrança",
          "tipo": "whatsapp",
          "conteudo": "Olá {{nome}}, você possui débitos pendentes no valor de {{valor}}.",
          "variaveis": {
            "nome": "string",
            "valor": "string"
          },
          "ativo": true,
          "versao": 2,
          "criadoEm": "2026-03-20T14:30:00Z"
        }
      ],
      "statusCode": 200
    }
    ```
  </Accordion>

  <Accordion title="GET /gw/templates/{id} — Buscar template específico">
    Retorna um único template pelo seu UUID público.

    **Parâmetros**

    <ParamField path="id" type="string" required>
      UUID público do template.
    </ParamField>

    **Exemplo de request**

    ```bash theme={null}
    curl https://api.ar-online.com.br/gw/templates/f6cb58f2-3e9b-4899-b703-3facd52e17ee \
      -H "Authorization: SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json"
    ```

    **Exemplo de response**

    ```json theme={null}
    {
      "data": {
        "id": "f6cb58f2-3e9b-4899-b703-3facd52e17ee",
        "templateId": "provider-id-123",
        "nome": "Template Boas-vindas",
        "tipo": "email",
        "conteudo": "Olá {{nome}}, bem-vindo à plataforma!",
        "variaveis": {
          "nome": "string"
        },
        "ativo": true,
        "versao": 1,
        "criadoEm": "2026-03-23T10:00:00Z",
        "atualizadoEm": "2026-03-25T15:20:00Z",
        "compartilhadoComEntidade": false
      },
      "statusCode": 200
    }
    ```
  </Accordion>

  <Accordion title="PUT /gw/templates/{id} — Editar template">
    Edita o nome e o compartilhamento do template.

    **Parâmetros**

    <ParamField path="id" type="string" required>
      UUID público do template.
    </ParamField>

    **Body**

    <ParamField body="nome" type="string">
      Novo nome do template.
    </ParamField>

    <ParamField body="compartilhadoComEntidade" type="boolean">
      Define se o template será compartilhado com a entidade. `true` compartilha com todos os usuários da mesma entidade; `false` remove o compartilhamento (apenas o dono tem acesso).
    </ParamField>

    **Exemplo de request**

    ```bash theme={null}
    curl -X PUT https://api.ar-online.com.br/gw/templates/f6cb58f2-3e9b-4899-b703-3facd52e17ee \
      -H "Authorization: SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json" \
      -d '{
        "nome": "Template Boas-vindas Atualizado",
        "compartilhadoComEntidade": true
      }'
    ```

    **Exemplo de response**

    ```json theme={null}
    {
      "data": {
        "id": "f6cb58f2-3e9b-4899-b703-3facd52e17ee",
        "nome": "Template Boas-vindas Atualizado",
        "compartilhadoComEntidade": true,
        "atualizadoEm": "2026-03-30T10:15:00Z"
      },
      "statusCode": 200
    }
    ```

    <Warning>
      Apenas o dono do template pode editá-lo.
    </Warning>
  </Accordion>

  <Accordion title="PATCH /gw/templates/{id}/status — Ativar/desativar">
    Ativa ou desativa o template.

    **Parâmetros**

    <ParamField path="id" type="string" required>
      UUID público do template.
    </ParamField>

    **Body**

    <ParamField body="ativo" type="boolean" required>
      Define o status do template. `true` ativa; `false` desativa.
    </ParamField>

    **Exemplo de request**

    ```bash theme={null}
    curl -X PATCH https://api.ar-online.com.br/gw/templates/f6cb58f2-3e9b-4899-b703-3facd52e17ee/status \
      -H "Authorization: SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json" \
      -d '{ "ativo": false }'
    ```

    **Exemplo de response**

    ```json theme={null}
    {
      "data": {
        "id": "f6cb58f2-3e9b-4899-b703-3facd52e17ee",
        "ativo": false,
        "atualizadoEm": "2026-03-30T10:20:00Z"
      },
      "statusCode": 200
    }
    ```
  </Accordion>

  <Accordion title="DELETE /gw/templates/{id} — Desativar (soft delete)">
    Desativa o template. Trata-se de um **soft delete**: o template é apenas desativado, não removido permanentemente.

    **Parâmetros**

    <ParamField path="id" type="string" required>
      UUID público do template.
    </ParamField>

    **Exemplo de request**

    ```bash theme={null}
    curl -X DELETE https://api.ar-online.com.br/gw/templates/f6cb58f2-3e9b-4899-b703-3facd52e17ee \
      -H "Authorization: SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json"
    ```

    **Exemplo de response**

    ```json theme={null}
    {
      "data": {
        "id": "f6cb58f2-3e9b-4899-b703-3facd52e17ee",
        "ativo": false,
        "message": "Template desativado com sucesso"
      },
      "statusCode": 200
    }
    ```

    <Note>
      Esta operação realiza um soft delete, apenas desativando o template (`ativo = false`). O template não é removido permanentemente do banco de dados.
    </Note>
  </Accordion>
</AccordionGroup>

## Tipos de template

Cada template é adequado a um canal específico:

| Tipo     | Valor             | Descrição                         |
| -------- | ----------------- | --------------------------------- |
| WhatsApp | `1` ou `whatsapp` | Templates para envio via WhatsApp |
| Email    | `2` ou `email`    | Templates para envio via Email    |
| SMS      | `3` ou `sms`      | Templates para envio via SMS      |
| Carta    | `4` ou `carta`    | Templates para envio via Carta    |
| Voz      | `voz`             | Templates para envio via Voz      |

## Compartilhamento de templates

Templates podem ser compartilhados com todos os usuários da mesma entidade através do campo `compartilhadoComEntidade`:

* **Compartilhado (`compartilhadoComEntidade: true`)**: todos os usuários da mesma entidade podem visualizar e utilizar o template.
* **Privado (`compartilhadoComEntidade: false`)**: apenas o dono do template pode visualizar e utilizar.

<Note>
  Apenas o **dono** do template pode editar, ativar/desativar ou excluir o template — mesmo quando ele está compartilhado.
</Note>

<Warning>
  Atualmente, apenas os templates de **WhatsApp** podem ser compartilhados. O compartilhamento para os demais canais estará disponível em breve.
</Warning>