Correspondências e status

Uma correspondência é um documento que a CartaFlow imprime, coloca no envelope e posta nos Correios para um endereço no Brasil. Você cria a correspondência com POST /v1/letters e ela passa por uma sequência fixa de status até ser postada.

O ciclo de uma correspondênciaCopiar link da seção

A correspondência só avança. Ela começa em scheduled quando você agenda com send_date, ou direto em received quando envia na hora. Depois segue para in_production, printed e posted. Enquanto estiver em scheduled ou received, ela ainda pode ser cancelada. Se algo der errado na produção, ela vai para failed e o valor volta para o saldo.

Um status nunca volta atrás. Se uma correspondência precisa ser impressa de novo na produção, por exemplo porque o papel enroscou na impressora, ela entra em outro lote de impressão e continua no mesmo status.

Quando cada etapa aconteceuCopiar link da seção

O campo status_transitions guarda o momento em que a correspondência chegou a cada status, em UTC. Os status pelos quais ela ainda não passou valem null.

{
  "received_at": "2026-10-13T14:20:00Z",
  "in_production_at": "2026-10-13T21:00:00Z",
  "printed_at": "2026-10-14T10:42:00Z",
  "posted_at": "2026-10-14T16:05:00Z",
  "canceled_at": null,
  "failed_at": null
}

• received_at é o momento da cobrança. Numa correspondência enviada na hora, é igual a created_at. Numa correspondência agendada, é a data do envio.
• posted_at é o momento em que a correspondência foi entregue aos Correios. É o último registro de uma correspondência enviada.
• canceled_at só é preenchido quando a correspondência foi cancelada, e failed_at quando ela falhou na produção.

Como acompanharCopiar link da seção

Use webhooks. A CartaFlow faz um POST para a sua URL a cada mudança de status, e quando a correspondência é alterada no painel antes da produção (letter.updated), com a correspondência inteira no corpo. Você não precisa consultar a API depois.

Se você não puder receber webhooks, consulte a correspondência com GET /v1/letters/{letter_id}. As etapas de produção e postagem levam horas, então consultar mais de uma vez por hora não traz informação nova. Para muitas correspondências, use GET /v1/letters com o filtro status em vez de consultar uma a uma.

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

CancelarCopiar link da seção

Você pode cancelar uma correspondência com POST /v1/letters/{letter_id}/cancel enquanto ela estiver em scheduled ou received. Nada é impresso.

• Em received, a correspondência já foi cobrada. O valor volta para o saldo na hora, como uma movimentação do tipo refund.
• Em scheduled, nada foi cobrado ainda, então não há valor a devolver.
• A partir de in_production, a correspondência já está em um lote de impressão. A API responde 409 com o código letter_not_cancelable, como também para uma correspondência em posted ou failed.
• Cancelar uma correspondência que já está cancelada devolve a mesma correspondência, sem erro. Você pode repetir a chamada com segurança.

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

Por que uma correspondência foi canceladaCopiar link da seção

Toda correspondência cancelada traz o motivo em cancellation_reason. Nas outras, o campo vale null.

Alterar antes da produçãoCopiar link da seção

Pela API, uma correspondência não muda depois de criada: para mudar algo, cancele e crie outra. No painel, em Envios, quem pode enviar correspondências altera uma correspondência antes da produção:

Cada alteração gera o evento letter.updated, com a correspondência como ficou e o mesmo status. Enviar na hora uma correspondência agendada gera letter.received.

Quando a produção falhaCopiar link da seção

Se uma correspondência não pode sair, porque o arquivo não imprime, porque ela foi danificada e não pode ser refeita ou porque os Correios recusaram a postagem, ela vai para failed, um status final, e o valor volta para o saldo automaticamente, como uma movimentação do tipo refund. Você recebe o evento letter.failed.

O motivo vem em failure_reason. Nas outras correspondências, o campo vale null.

Para enviar de novo, crie uma nova correspondência. Erros que aparecem antes da cobrança, como um PDF fora do padrão ou um CEP que não existe, nunca chegam a failed: a API responde 422 na criação e nada é cobrado.

Serviços dos CorreiosCopiar link da seção

Sem nenhuma escolha, a correspondência vai como carta simples. Com o campo postal_services, você escolhe serviços adicionais dos Correios. Cada um tem acréscimo no preço, com uma linha própria em price. Veja Preços e saldo.

{
  "to": { "name": "Destinatário Exemplo", "postal_code": "01001-000", "number": "128" },
  "document": { "type": "url", "url": "https://arquivos.exemplo.com.br/notificacoes/contrato-5531.pdf" },
  "postal_services": ["registered", "return_receipt"],
  "reference": "contrato-5531"
}

• return_receipt e restricted_delivery só funcionam junto com registered. Sem ele, a API responde 422 com requires_registered e nada é criado.
• O aviso de recebimento volta para o remetente: o endereço que você enviou em from ou, se não enviou, o remetente padrão da conta. Confira esse endereço antes de usar o AR. A CartaFlow não recebe nem digitaliza o aviso.
• Em multipart/form-data, repita o campo para cada serviço: postal_services[]=registered e postal_services[]=return_receipt.
• A correspondência devolve a escolha em postal_services, sempre como lista: [] numa carta simples.

Depois da postagemCopiar link da seção

Em posted, a correspondência está com os Correios, e a entrega segue o serviço postal. A CartaFlow não recebe novas informações sobre ela, então posted é o último status de uma correspondência enviada. O prazo de entrega depende da modalidade postal e da distância até o destino, e não é garantido pela CartaFlow.

• Carta registrada: tracking_code traz o código de rastreio dos Correios, como RA123456785BR, a partir da postagem. Use esse código para acompanhar a entrega nos Correios.
• Carta simples: não tem rastreio depois da postagem, e tracking_code vale null.

Quando os Correios não conseguem entregar, a correspondência volta para o endereço do remetente, impresso acima do destinatário. É o endereço que você enviou em from ou, se não enviou, o remetente padrão da conta. Veja Endereços no Brasil.

O objeto CorrespondênciaCopiar link da seção

Os campos principais de uma correspondência. A lista completa, com o tipo e a descrição de cada campo, está em Consultar uma correspondência.