> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maestro.robbu.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Uso de SFTP

> Importação automática de templates e campanhas via SFTP no Maestro.

Esta página orienta como usar os serviços automáticos de importação via SFTP para Templates e Campanhas no Maestro.

<Note>
  Os nomes de coluna abaixo são o padrão do Maestro. Se o arquivo do cliente usa nomes diferentes, um [Mapeamento de Layout de Importação](/integracoes/mapeamento-de-layouts) pode traduzi-los automaticamente, sem precisar alterar o arquivo de origem.
</Note>

## Configuração

A configuração de SFTP é feita em **Configurações > Empresa > Transferência de Arquivos**. A Gerente do Ambiente decide se as assessorias podem usar um SFTP próprio ou apenas o gerenciado pela Robbu.

### SFTP Robbu

A Robbu disponibiliza um servidor SFTP gerenciado, pronto para uso imediato. Ao habilitar, o sistema fornece servidor, porta, nome de usuário e senha.

### SFTP Próprio

A própria empresa gerencia seu SFTP.

<Warning>
  Essa opção deve ser habilitada pela Gerente do Ambiente nas configurações de Ambiente. Se algum parâmetro estiver em branco ou inválido, a importação será ignorada.
</Warning>

### Segurança

* Mantenha as credenciais em segurança.
* Garanta o uso correto de porta e endereço do servidor.
* A proteção desses dados garante a integridade dos arquivos durante as transferências.

## Diretórios

| Uso                          | Caminho SFTP         |
| ---------------------------- | -------------------- |
| Templates a serem importados | `/maestro/templates` |
| Campanhas a serem importadas | `/maestro/campaigns` |

Dentro de cada diretório acima, duas pastas são criadas automaticamente:

* `/processed` — arquivos importados com sucesso
* `/error` — importações que falharam, com sinalização do erro encontrado

<Note>
  Esses diretórios são criados automaticamente após a conexão do servidor SFTP na tela de configuração, mas pode levar até 10 minutos para aparecerem.
</Note>

## Importar campanhas

### Nome do arquivo

Não há nomenclatura obrigatória — o nome do arquivo será o nome do Público importado, então recomenda-se um nome descritivo.

<Warning>
  Verifique se a extensão não está duplicada, como em `arquivo.csv.csv`.
</Warning>

### Colunas do arquivo

O layout é o mesmo usado na importação manual de público pela tela — colunas, obrigatoriedade e o mecanismo de variáveis dinâmicas estão documentados em [Público](/guia-do-usuario/publico).

Exemplo:

```csv theme={null}
destination_value,channel,template_code,template_external_code,segment,document_number,contract_code,sender,dispatch_at,customer_name,attachment_file_name,notes_1,notes_2,notes_3,notes_4,broker_account_reference,broker,sms_flash,Var1,Var2
+5511988887777,whatsapp,W0003,,Varejo,12345678900,CT-98765,+5511999998888,2025-09-01 14:56:00,João Silva,,,,,,,,NÃO,Promoção de Inverno,10%
cliente@dominio.com,email,E0001,BR001,Financeiro,98765432100,CT-12345,,2025-09-01 15:10:00,Maria Souza,Fatura_Maria_Souza_07_2025.pdf,,,,,,NÃO,Fatura 07/2025,R$350
+5511977776666,sms,S0002,BR002,Atacado,11223344556,CT-45678,,2025-09-01 15:30:00,Carlos Lima,,,,,,Pontal,SIM,Código 123456,Validade 5min
```

### Fluxo de processamento

1. Faça upload do arquivo `.csv` em `/maestro/campaigns`.
2. Um serviço rotineiro roda a cada 10 minutos: cria `/processed` e `/error` se não existirem, e busca arquivos `.csv` ainda não importados.
3. Durante a importação, são validados: se cada linha cumpre as regras do ambiente (segmento existe e assessoria tem acesso; templates aprovados; horários de saída válidos; se a coluna `broker` for informada, se o provedor existe e é compatível com o segmento — nome inválido ou provedor sem perfil rejeita **o arquivo inteiro**).
4. Na importação: linhas que quebram regras geram `{nome original}_EXCEPTIONS.csv` em `/processed`, com a coluna adicional `Motivo Falha`.
5. Se não houver provedor para o canal configurado, é criado `{nome original}_created.csv` em `/processed` com os contatos processados (sem envio). Se houver provedor, os envios são criados e o arquivo gerado é `{nome original}_VALIDATED.csv`.
6. Arquivos de anexo (se houver) são destruídos após o envio.
7. Se houver falha no arquivo inteiro, é gerado `{nome do arquivo original}_errorDetail.txt` em `/error`.

## Importar templates

### Nome do arquivo

```
{nome do segmento}_{canal}_[{nome da WABA}]_{data}.csv
```

* **nome do segmento**: nome exato do segmento configurado (Segmentos).
* **canal**: `email` | `sms` | `whatsapp` | `rcs` (case-insensitive).
* **nome da WABA** (opcional, apenas WhatsApp): descrição da WABA.
* **data**: formato `yyyyMMdd` (ex.: `20250531`).

Exemplos: `retail_email_20250510.csv`, `finance_sms_20250101.csv`, `store_whatsapp_MinhaWaba_20250320.csv`

### Colunas do arquivo, por canal

<Note>
  Não é necessário manter a ordem sugerida das colunas, mas os nomes devem ser exatamente como documentado.
</Note>

**Templates WhatsApp:**

```
template_name,language,category,header_text,body_text,footer_text,reply_button_1,reply_button_2,reply_button_3,
url_button,url_button_text,template_status,reasons,template_code,external_code
```

| Campo                      | Obrigatório                                     | Descrição                                                                                |
| -------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `template_name`            | ✅ (criação)                                     | Nome único do template (sem espaços; usar `_` se necessário).                            |
| `language`                 | ✅ (criação)                                     | Idioma, formato `pt_BR`, `en_US` etc.                                                    |
| `category`                 | ✅ (criação)                                     | `MARKETING`, `UTILITY` ou `AUTHENTICATION`.                                              |
| `header_text`              | ✅ (coluna deve existir; valor pode ficar vazio) | Texto do cabeçalho.                                                                      |
| `body_text`                | ✅ (criação)                                     | Texto do corpo da mensagem.                                                              |
| `footer_text`              | ✅ (coluna deve existir; valor pode ficar vazio) | Texto do rodapé.                                                                         |
| `reply_button_1`/`_2`/`_3` | ✅ (coluna deve existir; valor pode ficar vazio) | Texto dos botões de resposta rápida.                                                     |
| `url_button`               | ✅ (coluna deve existir; valor pode ficar vazio) | URL do botão de ação (se existir).                                                       |
| `url_button_text`          | ✅ (coluna deve existir; valor pode ficar vazio) | Texto do botão de URL.                                                                   |
| `template_status`          | ❌                                               | `APROVADO` ou `REJEITADO` (status da revisão).                                           |
| `reasons`                  | ❌                                               | Motivos de reprovação, separados por `\|`. Cada motivo deve estar cadastrado no Maestro. |
| `template_code`            | ❌                                               | Código do template no Maestro (identifica o template na revisão).                        |
| `external_code`            | ❌                                               | Identificador externo do template. Deve ser único.                                       |

<Note>
  Para `header_text`, `footer_text`, `reply_button_1`/`_2`/`_3`, `url_button` e `url_button_text`, a coluna precisa existir no cabeçalho do arquivo mesmo quando não usada — só o valor da linha pode ficar em branco.
</Note>

**Templates de E-mail:**

```
template_name,subject,body_html,template_status,reasons,template_code,external_code
```

| Campo             | Obrigatório | Descrição                                  |
| ----------------- | ----------- | ------------------------------------------ |
| `template_name`   | ✅ (criação) | Nome único do template.                    |
| `subject`         | ✅ (criação) | Assunto do e-mail.                         |
| `body_html`       | ✅ (criação) | Corpo em HTML (inline).                    |
| `template_status` | ❌           | `APROVADO` ou `REJEITADO`.                 |
| `reasons`         | ❌           | Motivos de reprovação, separados por `\|`. |
| `template_code`   | ❌           | Código do template no Maestro.             |
| `external_code`   | ❌           | Identificador externo, único.              |

**Templates de SMS:**

```
template_name,text_body,template_status,reasons,template_code,external_code
```

| Campo             | Obrigatório | Descrição                                             |
| ----------------- | ----------- | ----------------------------------------------------- |
| `template_name`   | ✅ (criação) | Nome único do template.                               |
| `text_body`       | ✅ (criação) | Texto do corpo, pode conter variáveis (ex.: `{{1}}`). |
| `template_status` | ❌           | `APROVADO` ou `REJEITADO`.                            |
| `reasons`         | ❌           | Motivos de reprovação, separados por `\|`.            |
| `template_code`   | ❌           | Código do template no Maestro.                        |
| `external_code`   | ❌           | Identificador externo, único.                         |

**Templates de RCS:**

```
template_name;message_type;message;title;fallback;suggestion_1_title;suggestion_1_type;suggestion_1_value;
suggestion_2_title;suggestion_2_type;suggestion_2_value;suggestion_3_title;suggestion_3_type;suggestion_3_value;
suggestion_4_title;suggestion_4_type;suggestion_4_value;template_status;reasons;template_code;external_code
```

| Campo                | Obrigatório | Descrição                                                                                                 |
| -------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `template_name`      | ✅ (criação) | Nome único do template.                                                                                   |
| `message_type`       | ✅           | `Texto simples`, `Sugestão` ou `RichCard`.                                                                |
| `message`            | ✅           | Texto do corpo, pode conter variáveis (ex.: `{{1}}`).                                                     |
| `title`              | ❌           | Título do cartão (usado em `RichCard`).                                                                   |
| `fallback`           | ❌           | Texto alternativo quando o dispositivo/operadora não suporta RCS.                                         |
| `suggestion_x_title` | ❌           | Texto do botão de sugestão x (1 a 4).                                                                     |
| `suggestion_x_type`  | ❌           | `Resposta rápida`, `Abrir URL`, `Ligar`, `Criar evento`, `Compartilhar localização` ou `Ver localização`. |
| `suggestion_x_value` | ❌           | Valor correspondente ao tipo (URL, telefone etc.). Vazio quando o tipo for `Resposta rápida`.             |
| `template_status`    | ❌           | `APROVADO` ou `REJEITADO`.                                                                                |
| `reasons`            | ❌           | Motivos de reprovação, separados por `\|`.                                                                |
| `template_code`      | ❌           | Código do template no Maestro.                                                                            |
| `external_code`      | ❌           | Identificador externo, único.                                                                             |

<Warning>
  Regra específica do RCS: templates dos tipos `Texto simples` e `Sugestão` podem ser criados e revisados via importação. O tipo `RichCard` é **apenas revisado** — o template já deve existir no Maestro.
</Warning>

### Fluxo de processamento

1. Faça upload do `.csv` em `/maestro/templates`.
2. Um serviço rotineiro roda a cada 10 minutos: cria `/processed` e `/error` se não existirem, e busca arquivos ainda não importados.
3. Validações: nome do arquivo segue o padrão, segmento existe e assessoria tem acesso, campos obrigatórios do cenário estão presentes.
4. O comportamento da importação varia conforme os campos informados — veja [Fluxos](#fluxos).
5. O arquivo é movido para `/processed` (sucesso) ou `/error` (falha), gerando `{nome do arquivo original}_errorDetail.txt` em caso de erro.

### Fluxos

| Situação                                          | Ação do Maestro |
| ------------------------------------------------- | --------------- |
| Template não existe + `template_status` ausente   | Cria o template |
| Template não existe + `template_status` informado | Cria e revisa   |
| Template existe + `template_status` informado     | Apenas revisa   |
| Template existe + `template_status` ausente       | Erro            |

<Warning>
  RCS: templates com `message_type` igual a `Texto simples` ou `Sugestão` seguem a tabela acima. O tipo `RichCard` é apenas revisado — não é criado pela importação.
</Warning>

**Identificação do template existente** — o Maestro busca nesta ordem: `template_code` (código interno) → `external_code` (identificador externo) → se nenhum for informado, um novo template é criado.

### Regras

* `template_status` aceita apenas `APROVADO` ou `REJEITADO`.
* `reasons` é obrigatório quando `template_status=REJEITADO`; motivos múltiplos separados por `|`, cada um previamente cadastrado no Maestro.
* O template existente deve estar com status **Em Revisão** para ser revisado.
* `external_code` deve ser único por empresa.
* Se qualquer linha do arquivo contiver erro, **nenhuma linha é processada**.

## FAQ

<AccordionGroup>
  <Accordion title="Posso enviar arquivos sem seguir o padrão de nomenclatura?">
    Depende do tipo de importação. Na importação de **templates**, não — o arquivo será rejeitado e movido para a pasta `error`, com um `_errorDetail.txt`. Na importação de **campanhas**, não há validação de nome de arquivo.
  </Accordion>

  <Accordion title="Preciso recriar os diretórios processed e error manualmente?">
    Não. O sistema os cria automaticamente quando não existirem.
  </Accordion>

  <Accordion title="Posso reaproveitar um arquivo já processado?">
    Não. Arquivos em `processed` não são reprocessados. Para enviar novamente, gere um novo `.csv`.
  </Accordion>

  <Accordion title="Com que frequência os arquivos são processados?">
    A cada 10 minutos, via rotina automática.
  </Accordion>
</AccordionGroup>

SFTP não conecta ou arquivo não sai da pasta de origem? Veja [Troubleshooting](/central-de-suporte/troubleshooting).