Preços e saldo

A conta CartaFlow tem um saldo pré-pago. Cada correspondência e cada verificação de endereço são pagas com esse saldo. A mensalidade do plano é cobrada à parte e não sai do saldo.

Como o preço é formadoCopiar link da seção

O preço de uma correspondência vem em price, linha por linha. Cada linha tem uma quantidade, o preço de uma unidade no plano da conta e o valor da linha.

As linhas aparecem sempre nessa ordem, e linhas com valor zero não aparecem. total é a soma das linhas e é o valor debitado do saldo. Todos os valores são inteiros em centavos: 1135 são R$ 11,35.

"price": {
  "currency": "BRL",
  "total": 1135,
  "items": [
    { "type": "base", "quantity": 1, "unit_amount": 990, "amount": 990 },
    { "type": "additional_sheets", "quantity": 1, "unit_amount": 75, "amount": 75 },
    { "type": "color", "quantity": 2, "unit_amount": 35, "amount": 70 }
  ]
}

• O destino não muda o preço. O valor é o mesmo para qualquer CEP do Brasil.
• Uma verificação de endereço com o modelo da CartaFlow custa o mesmo que um envio simples do seu plano: uma linha base. Com o seu próprio PDF, ela é cobrada como uma correspondência com as mesmas opções (folhas adicionais e cor), sem serviços dos Correios. Veja Verificação de endereço físico.
• Frente e verso deixa mais barato quando o documento tem várias páginas, porque usa menos folhas. A cor continua cobrada por página. Veja Documento e área do endereço.

Serviços dos CorreiosCopiar link da seção

Uma correspondência vai como carta simples, a não ser que você escolha serviços adicionais dos Correios em postal_services. Cada serviço acrescenta uma linha ao preço:

"price": {
  "currency": "BRL",
  "total": 3340,
  "items": [
    { "type": "base", "quantity": 1, "unit_amount": 990, "amount": 990 },
    { "type": "registered", "quantity": 1, "unit_amount": 1175, "amount": 1175 },
    { "type": "return_receipt", "quantity": 1, "unit_amount": 1175, "amount": 1175 }
  ]
}

Uma verificação de endereço é sempre uma carta simples. Como cada serviço funciona está em Correspondências e status.

Calcular o preço antes de enviarCopiar link da seção

POST /v1/letters/quote recebe exatamente o mesmo corpo de POST /v1/letters, em JSON ou com o PDF enviado como arquivo. A API valida tudo, completa o endereço pelo CEP, conta as páginas do documento e devolve o preço no plano atual da conta, com os serviços dos Correios escolhidos. Nada é criado nem cobrado, e o saldo não precisa cobrir o valor.

curl -X POST "https://api.cartaflow.com.br/v1/letters/quote" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "name": "Destinatário Exemplo", "postal_code": "01001-000", "number": "128", "complement": "Ap. 52" },
    "document": { "type": "url", "url": "https://arquivos.exemplo.com.br/faturas/2026-10-0042.pdf" },
    "color": true
  }'

A resposta traz o plano usado (plan), as páginas (pages), as folhas (sheets), o endereço completo (to) e o preço (price). Se a simulação passar, a criação com o mesmo corpo também passa, desde que haja saldo.

Quando o saldo é cobradoCopiar link da seção

Quando você cancela uma correspondência ou uma verificação que já foi cobrada, o valor volta para o saldo na hora. Uma correspondência agendada cancelada antes da data não tinha sido cobrada, então não há devolução. Uma verificação cancelada depois que a produção começou é revogada (revoked), e o valor não volta. Veja Cancelar ou revogar.

Quando uma correspondência falha na produção (status failed), o valor volta para o saldo automaticamente. Erros encontrados antes da cobrança, como um PDF fora do padrão, nunca são cobrados: a API responde 422 e nada é criado.

Consultar o saldoCopiar link da seção

GET /v1/balance devolve quanto você pode gastar agora.

{
  "object": "balance",
  "currency": "BRL",
  "available": 48865,
  "pending": 0
}

• available é o valor disponível para novos envios, em centavos.
• pending fica reservado para recargas que dependem da confirmação de um pagamento. Hoje o saldo é adicionado na hora, então pending é sempre 0.

Consulte o saldo antes de envios grandes. Você adiciona saldo no painel, em Saldo e extrato > Adicionar saldo, e o valor entra na hora. A equipe da CartaFlow também pode adicionar saldo à sua conta.

Conciliar os gastosCopiar link da seção

GET /v1/balance/transactions lista cada entrada e saída do saldo, da mais recente para a mais antiga. Cada movimentação traz o valor (amount, negativo quando sai do saldo), o saldo logo depois dela (balance_after) e, quando existe, o id da correspondência ou da verificação ligada a ela (source_id).

Para fechar o mês, filtre por tipo e período: GET /v1/balance/transactions?type=letter&created_after=2026-10-01T00:00:00Z&created_before=2026-11-01T00:00:00Z. Use a reference e os metadata de cada correspondência para ligar o gasto ao seu cliente ou ao seu centro de custo. Veja Paginação e filtros.