Correspondências disparadas por eventos

Quando algo importante acontece com um cliente, seu sistema chama a API e nós imprimimos e postamos.

Contas novas ganham R$ 50 em créditos, o suficiente para 3 cartas simples.

O que é uma correspondência transacional

É uma correspondência enviada por causa de algo que aconteceu com um cliente específico: a conta foi aberta, o contrato mudou, o endereço foi atualizado, a conta foi encerrada. Cada envio tem um destinatário e um motivo, ao contrário de uma campanha enviada para muita gente ao mesmo tempo.

Algumas dessas comunicações precisam chegar por escrito, porque o contrato exige ou porque o cliente precisa guardar o documento. Como os eventos acontecem um de cada vez, ao longo do dia, juntar tudo para imprimir na mão não funciona. Com a API, cada evento gera o próprio envio.

Carta impressa dobrada entrando em um envelope branco com janela

Como funciona com a CartaFlow

Escolha os eventos
Por exemplo: conta aberta, contrato alterado e conta encerrada.
Monte o modelo do documento
O seu sistema preenche o modelo com os dados do cliente e gera o PDF.
Chame a API
No mesmo trecho de código que trata o evento, uma requisição cria o envio com o PDF e o endereço.
Acompanhe pela API
Consulte quando a correspondência foi impressa e postada e guarde isso no histórico do cliente.

Um exemplo na prática

Por exemplo: uma fintech precisa avisar por escrito quando muda as tarifas de uma conta. Quando a nova tarifa é cadastrada, o sistema gera um comunicado para cada cliente afetado e chama a API da CartaFlow uma vez por cliente.

Ninguém da equipe imprime ou posta nada. O id de cada envio fica salvo no cadastro do cliente, e o atendimento vê quando a correspondência foi postada se o cliente perguntar.

{
  "id": "ltr_8Kq2wX4m",
  "object": "letter",
  "status": "received",
  "pages": 2,
  "to": {
    "name": "Destinatário Exemplo",
    "cep": "01001-000",
    "city": "São Paulo",
    "state": "SP"
  },
  "created_at": "2026-10-13T14:20:00Z"
}

Exemplo ilustrativo da resposta da API ao criar um envio.

Eventos que costumam gerar uma correspondência

Alguns exemplos, com o documento enviado em cada caso.

Eventos do sistema e a correspondência enviada em cada um
Quando acontece	O que é enviado
Conta aberta ou cadastro aprovado	Carta de boas-vindas com os dados da conta
Mudança de contrato ou de tarifas	Comunicado com as novas condições e a data em que passam a valer
Mudança de endereço	Confirmação enviada para o endereço novo
Conta encerrada	Confirmação do encerramento e o que acontece a seguir
Aniversário do contrato	Informe anual ou aviso de renovação

curl https://api.cartaflow.com.br/v1/letters \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \
  -H "Idempotency-Key: fatura-2026-10-0042" \
  -F "to[name]=Destinatário Exemplo" \
  -F "to[address_line1]=Rua Exemplo, 128" \
  -F "to[address_line2]=Ap. 52" \
  -F "to[district]=Centro" \
  -F "to[city]=São Paulo" \
  -F "to[state]=SP" \
  -F "to[cep]=01001-000" \
  -F "color=true" \
  -F "file=@fatura-outubro.pdf"

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.append('to[name]', 'Destinatário Exemplo');
form.append('to[address_line1]', 'Rua Exemplo, 128');
form.append('to[address_line2]', 'Ap. 52');
form.append('to[district]', 'Centro');
form.append('to[city]', 'São Paulo');
form.append('to[state]', 'SP');
form.append('to[cep]', '01001-000');
form.append('color', 'true');
form.append('file', new Blob([await readFile('fatura-outubro.pdf')]), 'fatura-outubro.pdf');

const res = await fetch('https://api.cartaflow.com.br/v1/letters', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CARTAFLOW_API_KEY}`,
    'Idempotency-Key': 'fatura-2026-10-0042',
  },
  body: form,
});
const letter = await res.json();

import os
import requests

letter = requests.post(
    "https://api.cartaflow.com.br/v1/letters",
    headers={
        "Authorization": f"Bearer {os.environ['CARTAFLOW_API_KEY']}",
        "Idempotency-Key": "fatura-2026-10-0042",
    },
    data={
        "to[name]": "Destinatário Exemplo",
        "to[address_line1]": "Rua Exemplo, 128",
        "to[address_line2]": "Ap. 52",
        "to[district]": "Centro",
        "to[city]": "São Paulo",
        "to[state]": "SP",
        "to[cep]": "01001-000",
        "color": "true",
    },
    files={"file": open("fatura-outubro.pdf", "rb")},
).json()

Exemplo ilustrativo da API, sujeito a mudanças antes do lançamento. Envie uma chave de idempotência por evento: se a mesma requisição for repetida, a API não cria um segundo envio.

Por onde enviar e quanto custa

Envie pelo painel, sem programar, ou deixe o seu sistema enviar automaticamente pela API.

Painel

Pouco usado

Pelo site, sem programar

Para um caso fora do comum, que a equipe resolve manualmente.

API

Mais indicado

Pelo seu sistema, automático

Cada evento cria o próprio envio no momento em que acontece.

Quanto custa

Cada envio custa o valor por envio do seu plano, mais a mensalidade, se houver. O plano mais econômico depende de quantos envios você faz por mês: Avulso até 24 envios por mês, Essencial de 25 a 256 envios por mês, Profissional de 257 a 1.466 envios por mês e Escala a partir de 1.467 envios por mês.

Calcular meu plano

Perguntas frequentes

Veja todas as respostas em perguntas frequentes.

O que são correspondências transacionais?

São correspondências enviadas por causa de algo que aconteceu com um cliente específico, como abertura de conta, mudança de contrato ou encerramento. Cada envio tem um destinatário e um motivo.

Preciso de um volume mínimo para usar a API?

Não. Cada chamada pode criar um único envio, e você paga por envio. O plano Avulso não tem mensalidade.

Como evito enviar a mesma correspondência duas vezes?

Envie uma chave de idempotência em cada requisição, por exemplo o identificador do evento. Se a chamada for repetida com a mesma chave, a API não cria um segundo envio.

Consigo saber quando a correspondência foi postada?

Sim. A API informa as etapas que a CartaFlow controla, a impressão e a postagem. Depois da postagem, a entrega segue os prazos dos Correios.

Outros casos de uso

Envie sua primeira carta automática grátis.