Metadados e referência

Correspondências e verificações têm dois campos para você guardar dados seus: reference e metadata. Nenhum dos dois é impresso. Os dois voltam em todas as respostas e em todos os webhooks.

A diferençaCopiar link da seção

Use reference para o identificador principal, aquele que alguém da sua equipe procuraria no painel, como o número da fatura. Use metadata para o resto do contexto que o seu sistema precisa ao receber um webhook.

ExemploCopiar link da seção

{
  "reference": "fatura-2026-10-0042",
  "metadata": {
    "customer_id": "1842",
    "contract": "C-2026-118",
    "billing_cycle": "2026-10"
  }
}

Quando o evento letter.posted chegar, o seu sistema encontra a fatura por reference e o cliente por metadata.customer_id, sem guardar o id da correspondência.

Para encontrar a correspondência de uma fatura:

curl "https://api.cartaflow.com.br/v1/letters?reference=fatura-2026-10-0042" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

Como reference não precisa ser único, a resposta é uma lista. Se você enviou a mesma fatura duas vezes de propósito, as duas aparecem.

Regras de metadataCopiar link da seção

• Valores são sempre texto. Para números, envie como texto: "1842", não 1842.
• Chaves demais, ou chaves e valores longos demais, recebem 422 com too_long e o campo em param, como metadata.customer_id. Um valor que não é texto recebe invalid_type.
• metadata não aceita objetos dentro de objetos.

Referência e Idempotency-KeyCopiar link da seção

Idempotency-Key é outra coisa: é um cabeçalho que evita criar a mesma correspondência duas vezes quando você repete uma requisição. Ele não fica guardado na correspondência. Muitas vezes o mesmo identificador serve para os dois, como o id da fatura. Veja Idempotência.