Criar uma correspondência

Identificador único da correspondência. Sempre começa com ltr_.

Tipo do objeto. Sempre letter.

Em que etapa a correspondência está. Ela só avança, nunca volta: scheduled (só quando agendada), received, in_production, printed, posted. De scheduled ou received ela pode ir para canceled; de received, in_production ou printed, para failed. Uma reimpressão na produção não muda o status.

Valores possíveis

• scheduled: A correspondência foi validada e espera a data de send_date. Ainda não foi cobrada. Na data, às 06:00 de Brasília, a CartaFlow debita o saldo e a correspondência passa para received. Se o saldo não cobrir o preço, ela vai para canceled. Pode ser cancelada sem custo.
• received: A CartaFlow validou o documento e o endereço, cobrou o envio do seu saldo e colocou a correspondência na fila de produção. Ainda pode ser cancelada, e o valor volta para o saldo.
• in_production: A correspondência entrou em um lote de impressão. A partir daqui ela não pode mais ser cancelada.
• printed: A correspondência foi impressa, dobrada e colocada no envelope. O próximo passo é a postagem.
• posted: A correspondência foi entregue aos Correios. A partir daqui a entrega segue o serviço postal, e a CartaFlow não recebe novas informações sobre ela. Uma correspondência registrada traz o código de rastreio dos Correios em tracking_code.
• canceled: O envio foi cancelado antes da produção e nada foi impresso. cancellation_reason diz o motivo: você cancelou, ou o saldo não cobria uma correspondência agendada na data do envio. Se havia cobrança, o valor voltou para o saldo.
• failed: Algo deu errado na produção e a correspondência não será postada. failure_reason diz o motivo. O valor voltou para o saldo automaticamente.

Destinatário.

Remetente impresso acima do destinatário: o que você enviou ou o remetente padrão da conta.

De onde veio o conteúdo da correspondência. O PDF final está em preview_url.

true quando a impressão é colorida.

true quando a impressão é frente e verso.

Onde o endereço é impresso.

Valores possíveis

• first_page: Na área do endereço da primeira página do documento.
• extra_page: Num lado só dele, o primeiro, sem custo.

Os serviços adicionais dos Correios escolhidos na criação. Sempre uma lista: [] numa carta simples.

Valores possíveis

• registered: Carta registrada: a correspondência é postada com registro nos Correios e recebe um código de rastreio, que aparece em tracking_code quando ela é postada.
• return_receipt: Aviso de recebimento (AR): os Correios devolvem um comprovante assinado por quem recebeu a correspondência ao remetente impresso no envelope. Exige registered.
• restricted_delivery: Mão própria (MP): os Correios entregam só para a pessoa cujo nome está no envelope. Exige registered.

Número de páginas do seu documento, sem contar o lado do endereço com extra_page.

Folhas de papel no envelope. Só frente, é pages. Em frente e verso, é metade de pages arredondada para cima com first_page, e metade de pages arredondada para baixo, mais 1, com extra_page. Máximo de 6, contando a folha que o endereço acrescenta, que não é cobrada.

O preço da correspondência. É cobrado do saldo na criação ou, se ela foi agendada, na data do envio (com o plano da conta nesse dia). Volta para o saldo se a correspondência for cancelada depois da cobrança ou falhar na produção.

A data agendada para o envio, AAAA-MM-DD. null quando a correspondência foi enviada na hora.

Por que a correspondência foi cancelada. null quando ela não está cancelada.

Valores possíveis

• requested: Você cancelou, pela API ou pelo painel.
• insufficient_balance: Era uma correspondência agendada e, na data do envio, o saldo não cobria o preço. Nada foi cobrado.

Por que a correspondência falhou na produção. null quando ela não está em failed. Quando ela falha, o valor volta para o saldo automaticamente.

Valores possíveis

• unprintable_document: O arquivo passou pela validação, mas não pôde ser impresso como está.
• damaged_in_production: A correspondência foi danificada na impressão, na dobra ou no envelopamento e não pôde ser refeita.
• refused_by_carrier: Os Correios recusaram a correspondência na postagem.
• other: Outro motivo. Fale com o suporte da CartaFlow pelo painel para saber os detalhes.

O código de rastreio dos Correios de uma correspondência registrada (postal_services com registered), como RA123456785BR. Preenchido quando ela é postada. null numa carta simples, que não tem rastreio, e antes da postagem.

Link para o PDF final, exatamente como será impresso, já com o endereço. O link vale por 60 minutos: consulte a correspondência de novo para receber um link novo. O arquivo fica disponível por pelo menos 90 dias depois da criação (ou depois da data do envio, numa correspondência agendada); null só depois desse prazo, se o arquivo deixar de estar disponível. Numa correspondência em preto e branco, o PDF mantém as cores do original: a conversão para tons de cinza acontece na impressão.

Seu identificador para esta correspondência, como o número da fatura ou o id do cliente no seu sistema. Aparece no painel e pode ser usado como filtro nas listagens. Não precisa ser único. Até 100 caracteres. null quando você não enviou.

Pares chave-valor para guardar dados seus junto do objeto, como o id do cliente ou do contrato. Voltam em todas as respostas e webhooks e nunca são impressos. Até 20 chaves; chaves com até 40 caracteres e valores em texto com até 500 caracteres. Não guarde dados sensíveis, como senhas ou números de cartão. Objeto vazio {} quando você não enviou.

Quando a correspondência chegou a cada status. null para os status pelos quais ela ainda não passou. Uma correspondência agendada nasce em scheduled, no momento de created_at.

Quando a correspondência foi criada e recebida, em UTC.