Primeiros passos

Crie uma chave de APICopiar link da seção

No painel da CartaFlow, abra Desenvolvedores > Chaves de API e crie uma chave. Ela começa com cf_live_ e aparece uma vez só: copie e guarde em um lugar seguro.

Coloque a chave em uma variável de ambiente do seu servidor. Os exemplos desta documentação leem a chave de CARTAFLOW_API_KEY.

export CARTAFLOW_API_KEY="cf_live_..."

Confira a chaveCopiar link da seção

Chame GET /v1/account. A resposta mostra a empresa dona da chave.

curl https://api.cartaflow.com.br/v1/account \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

{
  "id": "acc_7Jw3Nf8Xq2Lp",
  "object": "account",
  "legal_name": "Exemplo Serviços Ltda.",
  "trade_name": "Exemplo",
  "cnpj": "12.345.678/0001-90",
  "plan": "essential",
  "default_sender": {
    "name": "Exemplo Serviços Ltda.",
    "street": "Avenida Exemplo",
    "number": "1000",
    "complement": "Sala 301",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100"
  },
  "created_at": "2026-09-01T12:00:00Z"
}

Se a resposta for 401, a chave está errada ou foi revogada. Copie de novo no painel.

Simule a correspondência, sem custoCopiar link da seção

Chame POST /v1/letters/quote com o destinatário e o documento. A simulação valida tudo, completa o endereço pelo CEP, conta as páginas e devolve o preço, sem criar nem cobrar nada. Use o PDF de exemplo da documentação, que já deixa a área do endereço em branco: https://docs.cartaflow.com.br/samples/exemplo-a4.pdf.

No endereço, bastam o nome, o CEP e o número. O logradouro, o bairro, a cidade e a UF vêm do CEP.

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" },
    "document": { "type": "url", "url": "https://docs.cartaflow.com.br/samples/exemplo-a4.pdf" }
  }'

{
  "object": "quote",
  "plan": "essential",
  "to": {
    "name": "Destinatário Exemplo",
    "street": "Praça da Sé",
    "number": "128",
    "complement": null,
    "neighborhood": "Sé",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01001-000"
  },
  "pages": 1,
  "sheets": 1,
  "price": {
    "currency": "BRL",
    "total": 990,
    "items": [{ "type": "base", "quantity": 1, "unit_amount": 990, "amount": 990 }]
  }
}

Se algo estiver errado, a resposta 422 lista todos os problemas de uma vez, os mesmos que a criação apontaria. Os valores de preço dos exemplos são ilustrativos: o preço real depende do plano da sua conta.

Envie a correspondênciaCopiar link da seção

Chame POST /v1/letters com o mesmo corpo. Agora a correspondência é de verdade: ela é impressa, postada pelos Correios e cobrada do seu saldo. Para ver o resultado, envie para o endereço da sua empresa.

curl -X POST https://api.cartaflow.com.br/v1/letters \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primeira-0001" \
  -d '{
    "to": {
      "name": "Destinatário Exemplo",
      "postal_code": "01001-000",
      "number": "128"
    },
    "document": {
      "type": "url",
      "url": "https://docs.cartaflow.com.br/samples/exemplo-a4.pdf"
    }
  }'

Se o PDF está no seu computador ou foi gerado pelo seu sistema, envie o arquivo direto, como multipart/form-data, com até 4 MB. O PDF vai na parte file e os campos do endereço são escritos entre colchetes. Baixe o PDF de exemplo para experimentar:

curl -X POST https://api.cartaflow.com.br/v1/letters \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \
  -H "Idempotency-Key: primeira-0002" \
  -F "file=@exemplo-a4.pdf" \
  -F "to[name]=Destinatário Exemplo" \
  -F "to[postal_code]=01001-000" \
  -F "to[number]=128"

As regras do multipart estão em Convenções. Para PDFs maiores, de até 10 MB, envie por URL ou com o upload em duas etapas. Veja Documento e área do endereço.

A resposta é 201 com a correspondência criada, em received e já cobrada. Repare no endereço completo em to e no preview_url, que abre o PDF exatamente como será impresso.

{
  "id": "ltr_8Kq2wX4mN7pR",
  "object": "letter",
  "status": "received",
  "to": {
    "name": "Destinatário Exemplo",
    "street": "Praça da Sé",
    "number": "128",
    "complement": null,
    "neighborhood": "Sé",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01001-000"
  },
  "from": {
    "name": "Exemplo Serviços Ltda.",
    "street": "Avenida Exemplo",
    "number": "1000",
    "complement": "Sala 301",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100"
  },
  "document": { "type": "url", "url": "https://docs.cartaflow.com.br/samples/exemplo-a4.pdf" },
  "color": false,
  "double_sided": false,
  "address_placement": "first_page",
  "postal_services": [],
  "pages": 1,
  "sheets": 1,
  "price": {
    "currency": "BRL",
    "total": 990,
    "items": [{ "type": "base", "quantity": 1, "unit_amount": 990, "amount": 990 }]
  },
  "send_date": null,
  "cancellation_reason": null,
  "failure_reason": null,
  "tracking_code": null,
  "preview_url": "https://files.cartaflow.com.br/previews/ltr_8Kq2wX4mN7pR.pdf?expires=1760369400&signature=9c1f2a7d",
  "reference": null,
  "metadata": {},
  "status_transitions": {
    "received_at": "2026-10-13T14:20:00Z",
    "in_production_at": null,
    "printed_at": null,
    "posted_at": null,
    "canceled_at": null,
    "failed_at": null
  },
  "created_at": "2026-10-13T14:20:00Z"
}

Acompanhe o statusCopiar link da seção

Consulte a correspondência pelo id com GET /v1/letters/{letter_id}.

curl https://api.cartaflow.com.br/v1/letters/ltr_8Kq2wX4mN7pR \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

A correspondência passa por in_production, printed e posted. Cada etapa depende da fila de produção e da postagem, e leva horas. O ciclo completo está em Correspondências e status.

Receba os eventos por webhookCopiar link da seção

Em vez de consultar a API de tempos em tempos, deixe a CartaFlow avisar o seu servidor. No painel, abra Desenvolvedores > Webhooks, informe uma URL HTTPS do seu servidor e escolha os eventos, como letter.posted. A cada mudança de status, a CartaFlow faz um POST para essa URL com a correspondência inteira.

Para conferir o seu endpoint, use o botão Enviar evento de teste no painel: ele envia uma entrega do tipo webhook.test. Como conferir a assinatura e responder está em Webhooks.

Antes de enviar em volumeCopiar link da seção

Antes de ligar a integração para todos os seus envios, confira:

• A chave cf_live_ está em uma variável de ambiente do servidor, nunca no código.
• Toda chamada POST envia Idempotency-Key com um valor do seu sistema, como o id da fatura. Veja Idempotência.
• O seu webhook confere a assinatura de cada evento e ignora eventos repetidos.
• O saldo da conta cobre os envios. Consulte GET /v1/balance antes de envios grandes. Veja Preços e saldo.
• O remetente padrão da conta está certo no painel, em Configurações > Empresa. É o endereço para onde os Correios devolvem uma correspondência que não puderam entregar.
• O seu sistema trata os erros pelo error.code. Veja Erros.