> ## 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.

# Canal Carta

> Envie uma carta física registrada via Correios (AR-Cartas) a partir de um modelo configurado no setup.

O canal Carta gera uma **carta física registrada**, enviada via Correios, a partir de um modelo previamente configurado e das variáveis que preenchem o documento. Para usá-lo, inclua o bloco `carta` na requisição de envio (`POST /gw/email`) — veja a [visão geral do envio](/enviando/visao-geral).

<Warning>
  Para utilização do canal AR-Cartas é obrigatório passar pelo processo de SETUP para criação do modelo personalizado — entre em contato com nossa equipe de suporte para configuração. Sobre o AR-Cartas, converse também com o nosso time Comercial.
</Warning>

## Campos do objeto `carta`

<ParamField path="carta.name" type="string" required>
  Nome da carta enviada (uso interno, para sua referência).
</ParamField>

<ParamField path="carta.modelo" type="string">
  Modelo da carta a ser utilizado (ex.: `modelo-teste-padrao.docx`). Use este campo **ou** `carta.template` conforme a configuração do seu setup.
</ParamField>

<ParamField path="carta.template" type="string">
  Modelo da carta. Alternativa a `carta.modelo`, conforme definido no setup.
</ParamField>

<ParamField path="carta.variables" type="object" required>
  Valores que preenchem a carta física. As chaves disponíveis são **definidas no SETUP do modelo** junto ao suporte.
</ParamField>

## Exemplo completo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.ar-online.com.br/gw/email" \
    -H "Authorization: SEU_TOKEN_AQUI" \
    -H "Content-Type: application/json" \
    -d '{
      "nameTo": "João da Silva",
      "subject": "Documento Importante",
      "content": "<p><strong>Você recebeu um documento importante.</strong></p>",
      "carta": {
        "name": "teste-carta-padrao",
        "modelo": "modelo-teste-padrao.docx",
        "variables": {
          "TEMPLATE_CARTAS": "modelo-teste-padrao.docx",
          "ASSUNTO_CARTA": "JOÃO DA SILVA - Teste de envio AR-Cartas",
          "NOME_DESTINATARIO_CARTA": "João da Silva",
          "LOGRADOURO_CARTA": "RUA SEM SAIDA",
          "COMPLEMENTO_CARTA": "Casa",
          "NUMERO_CARTA": 99,
          "BAIRRO_CARTA": "CENTRO",
          "CIDADE_CARTA": "SÃO PAULO",
          "ESTADO_CARTA": "SP",
          "CEP_CARTA": "99999000"
        }
      }
    }'
  ```

  ```json Body theme={null}
  {
    "nameTo": "João da Silva",
    "subject": "Documento Importante",
    "content": "<p><strong>Você recebeu um documento importante.</strong></p>",
    "carta": {
      "name": "teste-carta-padrao",
      "modelo": "modelo-teste-padrao.docx",
      "variables": {
        "TEMPLATE_CARTAS": "modelo-teste-padrao.docx",
        "ASSUNTO_CARTA": "JOÃO DA SILVA - Teste de envio AR-Cartas",
        "NOME_DESTINATARIO_CARTA": "João da Silva",
        "LOGRADOURO_CARTA": "RUA SEM SAIDA",
        "COMPLEMENTO_CARTA": "Casa",
        "NUMERO_CARTA": 99,
        "BAIRRO_CARTA": "CENTRO",
        "CIDADE_CARTA": "SÃO PAULO",
        "ESTADO_CARTA": "SP",
        "CEP_CARTA": "99999000"
      }
    }
  }
  ```
</CodeGroup>

A resposta traz o `idEmail` do envio:

```json theme={null}
{
  "idEmail": "8c4813f5-8430-4ad4-ab72-19d7eed39731"
}
```

## Exemplo de carta

<img src="https://mintcdn.com/aronline/xG8qjUhq0nMODZpv/images/exemplo-carta.png?fit=max&auto=format&n=xG8qjUhq0nMODZpv&q=85&s=2a972079d56624e96ccfe6fbe6fa78a9" alt="Exemplo de carta gerada pelo AR-Cartas" width="894" height="942" data-path="images/exemplo-carta.png" />

Os valores destacados em **amarelo** correspondem às chaves passadas em `carta.variables`.

## Acompanhando o status

Consulte o status da carta (incluindo o código de rastreio dos Correios) com o `idEmail` do envio. Veja [Consultar status](/acompanhando/consultar-status).

## Prazos operacionais

A carta física depende dos Correios, então o ciclo tem prazos próprios. Os valores abaixo são **estimativas máximas**:

| Etapa                                   | Prazo estimado (máximo)                     |
| --------------------------------------- | ------------------------------------------- |
| Entrega                                 | até 15 dias úteis                           |
| Imagem do AR digitalizado               | 15 dias úteis após a confirmação de entrega |
| Atualização na plataforma               | até 72 h                                    |
| Devolução                               | 30 dias úteis                               |
| Retorno de PI (Pendência de Informação) | 15 dias úteis                               |

<Note>
  Esses prazos têm **natureza operacional e estimativa** e podem sofrer alterações em função de fatores externos aos sistemas da AR Online. Veja também as [notas técnicas](/notas-tecnicas/visao-geral).
</Note>