Documentação

Consultar um evento

Devolve um evento.

GET
/events/{event_id}

Autenticação

apiKey
headerAuthorizationBearer <chave de API>

Chave de API no cabeçalho Authorization: Bearer cf_live_.... Crie e revogue chaves no painel, em Desenvolvedores > Chaves de API.

Parâmetros de caminho

event_id*string

O id do evento, que começa com evt_.

Corpo da resposta

O evento.

application/json
  1. response

Um acontecimento na sua conta, como uma correspondência postada. A CartaFlow envia cada evento para os seus webhooks e guarda por 30 dias.

id*string

Identificador único do evento. É o mesmo valor do cabeçalho webhook-id: use para ignorar entregas repetidas. Sempre começa com evt_.

Formato^evt_[A-Za-z0-9]+$
object*string

Tipo do objeto. Sempre event.

type*string

O que aconteceu. Cada mudança de status gera um evento com o nome objeto.novo_status; uma correspondência alterada no painel antes da produção, sem mudar de status, gera letter.updated.

Valores possíveis

  • letter.scheduled: Uma correspondência foi agendada com send_date. Ainda não foi cobrada.
  • letter.received: Uma correspondência foi cobrada e entrou na fila de produção: logo depois de criada ou, se foi agendada, na data do envio. Vale para correspondências criadas pela API e pelo painel.
  • letter.in_production: A correspondência entrou em um lote de impressão e não pode mais ser cancelada.
  • letter.printed: A correspondência foi impressa e envelopada.
  • letter.posted: A correspondência foi entregue aos Correios. É o último evento de uma correspondência enviada.
  • letter.canceled: A correspondência foi cancelada. Veja cancellation_reason: requested quando você cancelou, insufficient_balance quando uma correspondência agendada não pôde ser cobrada na data.
  • letter.failed: A correspondência falhou na produção e não será postada. O valor voltou para o saldo automaticamente. Veja failure_reason.
  • letter.updated: A correspondência foi alterada no painel antes da produção, sem mudar de status: data de envio, endereço, arquivo, variáveis, impressão, serviços dos Correios ou referência. data traz a correspondência como ficou. Se a mudança alterou o preço de uma correspondência agendada, price traz o novo valor.
  • verification.received: Uma verificação foi criada, pela API ou pelo painel (veja source), e a correspondência com o código está na fila de produção.
  • verification.in_production: A correspondência com o código está sendo impressa. A partir daqui, cancelar revoga a verificação, sem devolução.
  • verification.awaiting_code: A correspondência com o código foi postada. A pessoa já pode confirmar quando receber.
  • verification.verified: A pessoa confirmou o código certo. O endereço está verificado.
  • verification.failed: Foram digitados 5 códigos errados e a verificação foi bloqueada.
  • verification.expired: A pessoa não confirmou o código em 60 dias desde a postagem.
  • verification.canceled: A verificação foi cancelada antes da postagem, por você ou pela CartaFlow, e o valor voltou para o saldo.
  • verification.revoked: Você cancelou a verificação depois que a produção começou. O código deixou de funcionar e o valor não volta para o saldo. Se ela estava verified, trate o endereço como não verificado.
Valores"letter.scheduled""letter.received""letter.in_production""letter.printed""letter.posted""letter.canceled""letter.failed""letter.updated""verification.received""verification.in_production""verification.awaiting_code""verification.verified""verification.failed""verification.expired""verification.canceled""verification.revoked"
data*|

O objeto inteiro, como estava logo depois do acontecimento: uma correspondência nos eventos letter.* e uma verificação nos eventos verification.*.

created_at*string

Quando o evento aconteceu.

Formatodate-time
curl "https://api.cartaflow.com.br/v1/events/string" \  -H "Authorization: Bearer $CARTAFLOW_API_KEY"
{  "id": "evt_6Tq1Yz8Wm3Rb",  "object": "event",  "type": "letter.posted",  "data": {    "id": "ltr_8Kq2wX4mN7pR",    "object": "letter",    "status": "posted",    "to": {      "name": "Destinatário Exemplo",      "street": "Praça da Sé",      "number": "128",      "complement": "Ap. 52",      "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://arquivos.exemplo.com.br/faturas/2026-10-0042.pdf",      "variables": null    },    "color": true,    "double_sided": false,    "address_placement": "first_page",    "postal_services": [],    "pages": 2,    "sheets": 2,    "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        }      ]    },    "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": "fatura-2026-10-0042",    "metadata": {      "customer_id": "1842"    },    "status_transitions": {      "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    },    "created_at": "2026-10-13T14:20:00Z"  },  "created_at": "2026-10-14T16:05:00Z"}