Documentação

Criar uma verificação

Envia para o endereço uma correspondência com a sua marca e um código de 6 dígitos.

POST
/verifications

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.

Cabeçalhos

Idempotency-Key?string

Um valor único por operação, como o id da fatura no seu sistema ou um UUID. Se você repetir a requisição com a mesma chave em até 24 horas, a API devolve a resposta da primeira vez em vez de criar outro objeto. Recomendado em todo POST. Até 255 caracteres.

Tamanholength <= 255

Corpo da requisição

application/json
  1. body

A correspondência sai do modelo da CartaFlow, que você pode personalizar em letter, ou do seu próprio PDF, em document. Envie um ou outro, nunca os dois. Uma verificação vai sempre como carta simples: não há postal_services aqui.

to*

O endereço a verificar e o nome de quem mora ou trabalha nele.

method*string

Como a pessoa confirma o código. Define também o que vai impresso na correspondência.

Valores possíveis

  • hosted_page: A pessoa confirma em uma página com a sua marca, hospedada pela CartaFlow: pelo QR code, que abre a página já com o código, ou digitando o código no endereço impresso. Você não precisa construir tela nenhuma; o resultado chega por webhook e aparece no painel.
  • code: A correspondência traz só o código, sem QR code e sem o endereço da página. A pessoa digita o código no seu site ou aplicativo, e o seu servidor confere com POST /v1/verifications/{verification_id}/check.
Valores"hosted_page""code"
letter?

Personaliza a correspondência do modelo da CartaFlow, só nesta verificação. Cada campo que você não envia vem do modelo padrão da sua empresa, salvo no painel, e, quando a empresa não salvou um, do padrão da CartaFlow. Os textos ficam abaixo da janela do envelope. Os textos padrão e as partes fixas, como "Seu código" e a instrução do QR code, são em português. O logo, o nome da sua empresa, o endereço e o código são sempre impressos e não mudam por aqui. Não use junto com document: a API responde 422 com invalid_value.

document?||

O seu próprio PDF, no lugar do modelo da CartaFlow. Escolha a forma pelo campo type: url (até 10 MB), upload (um arquivo enviado antes com POST /v1/uploads, até 10 MB) ou base64 (até 3 MB). Este endpoint aceita só JSON: para mandar o arquivo, use o upload em duas etapas.

O PDF segue as regras de uma correspondência (A4 em retrato, até 6 folhas, área do endereço em branco com address_placement: first_page, texto selecionável) e tem marcações reservadas, que a CartaFlow preenche:

  • {{OTP_CODE}}: obrigatória. O lugar onde o código é impresso, no formato 123 456, com a fonte, o tamanho e a cor da marcação. Sem ela, a API responde 422 com otp_code_missing.
  • {{VERIFICATION_URL}}: opcional. O endereço da página de confirmação (hosted_page_url), sem o código.
  • {{QR_CODE}}: opcional. Um QR code de 25 x 25 mm que abre a página já com o código. O canto superior esquerdo fica onde começa a marcação: deixe esse espaço em branco, à direita e abaixo dela.

{{VERIFICATION_URL}} e {{QR_CODE}} só valem com method: hosted_page; com method: code, a API responde 422 com invalid_value. Escreva as marcações em maiúsculas, com as chaves. As outras marcações, como {{nome}}, funcionam como numa correspondência: envie os valores em variables, sem incluir as reservadas (variable_not_found).

color?boolean

true imprime em cores. false imprime em preto e branco: um PDF colorido sai em tons de cinza. A impressão colorida tem acréscimo por página impressa (cada lado impresso conta como uma página). Só vale com document, o seu próprio PDF. A correspondência do modelo da CartaFlow é sempre uma folha em preto e branco: sem document, enviar este campo com um valor diferente do padrão dá 422 com invalid_value.

Padrãofalse
double_sided?boolean

true imprime frente e verso: cada folha leva duas páginas do documento, então a correspondência usa menos folhas e custa menos. false imprime só a frente de cada folha. Só vale com document, o seu próprio PDF. A correspondência do modelo da CartaFlow é sempre uma folha em preto e branco: sem document, enviar este campo com um valor diferente do padrão dá 422 com invalid_value.

Padrãofalse
address_placement?string

Onde a CartaFlow imprime o endereço do destinatário no seu PDF. Só vale com document, o seu próprio PDF. A correspondência do modelo da CartaFlow é sempre uma folha em preto e branco: sem document, enviar este campo com um valor diferente do padrão dá 422 com invalid_value.

Valores possíveis

  • first_page: Na área do endereço da primeira página do seu documento (90 x 45 mm, a 20 mm da esquerda e 45 mm do topo). Essa área precisa estar em branco no seu PDF. Padrão.
  • extra_page: Num lado só dele, o primeiro, que aparece pela janela do envelope. Use quando o seu layout ocupa a área do endereço. Ele ocupa um lado que ficaria em branco, quando há um: o verso da primeira página, só frente, ou o lado que sobra, em frente e verso com número ímpar de páginas. Em frente e verso com número par de páginas, entra uma folha a mais no início. O endereço nunca é cobrado.
Padrão"first_page"
Valores"first_page""extra_page"
instructions?string

Texto impresso logo abaixo do código, no modelo da CartaFlow, dizendo onde digitar. Use com method: code, por exemplo "Abra o app, vá em Perfil > Endereço e digite o código". Também é impresso com method: hosted_page quando letter desliga o QR code e o endereço da página. Se você não enviar, imprimimos "Digite este código no site ou aplicativo de" seguido do nome da sua empresa. Não é impresso no seu próprio PDF: escreva a instrução no documento. Até 300 caracteres.

Tamanho1 <= length <= 300
return_url?string

Só para method: hosted_page. Depois de confirmar, a página mostra um botão que leva para esta URL, como a área logada do seu site.

Formatouri
Tamanholength <= 2048
reference?string

Seu identificador para esta verificação, 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.

Tamanholength <= 100
metadata?

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.

Camposproperties <= 20

Corpo da resposta

A verificação foi criada e cobrada. Status received.

application/json
  1. response

Uma verificação de endereço físico: a CartaFlow envia uma correspondência com um código, com a sua marca, e o endereço fica verificado quando a pessoa confirma o código. O código nunca aparece neste objeto, nem no painel.

id*string

Identificador único da verificação. Sempre começa com ver_.

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

Tipo do objeto. Sempre verification.

status*string

Em que etapa a verificação está. Ela só avança: received, in_production, awaiting_code, verified. De received ela pode ir para canceled; de in_production, para canceled (pela CartaFlow) ou revoked; de awaiting_code, para failed, expired ou revoked; de verified, para revoked. Só verified quer dizer endereço confirmado.

Valores possíveis

  • received: A CartaFlow recebeu o pedido, cobrou o preço do seu saldo e colocou a correspondência com o código na fila de produção. Se você cancelar agora, nada é impresso e o valor volta para o saldo.
  • in_production: A correspondência com o código está sendo impressa e envelopada. Cancelar agora revoga a verificação (revoked), sem devolução do valor.
  • awaiting_code: A correspondência foi postada. Agora esperamos a pessoa confirmar o código. Ela tem 60 dias a partir da postagem (veja expires_at). Cancelar agora revoga a verificação, sem devolução do valor.
  • verified: A pessoa confirmou o código certo. Ela recebe correspondência no endereço informado. confirmation diz como e quando. Você ainda pode revogar a verificação, e ela passa para revoked.
  • failed: Foram digitados 5 códigos errados. A verificação foi bloqueada para impedir tentativas aleatórias. Crie uma nova verificação se quiser tentar de novo.
  • expired: Passaram 60 dias desde a postagem sem que a pessoa confirmasse o código.
  • canceled: A verificação foi cancelada antes da postagem e o valor voltou para o seu saldo. Ou você cancelou enquanto ela estava em received, ou a CartaFlow cancelou porque a correspondência não pôde ser produzida.
  • revoked: Você cancelou a verificação depois que a produção começou: em produção, aguardando código ou já verificada. O valor não volta para o saldo, porque a produção já começou, e uma correspondência que estava em produção ainda é postada. O código deixa de funcionar, na página e na API, e a verificação nunca mais aparece como verified.
Valores"received""in_production""awaiting_code""verified""failed""expired""canceled""revoked"
method*string

Como a pessoa confirma o código.

Valores possíveis

  • hosted_page: Na página com a sua marca, pelo QR code ou digitando o código.
  • code: Digitando o código no seu site ou aplicativo.
Valores"hosted_page""code"
source*string

Por onde a verificação foi criada. Não depende de como ela é confirmada (veja confirmation).

Valores possíveis

  • api: Pela API, com POST /v1/verifications.
  • dashboard: No painel, por alguém da sua equipe.
Valores"api""dashboard"
to*

O endereço verificado.

document*|||

Como a correspondência foi feita: o modelo da CartaFlow ou o seu PDF. A cópia dela, com o código escondido (000 000), está em preview_url.

instructions*|

O texto que você enviou para imprimir abaixo do código, no modelo da CartaFlow. null quando você não enviou.

return_url*|

Para onde a página leva a pessoa depois da confirmação. null quando não se aplica.

Formatouri
hosted_page_url*|

O endereço da página de confirmação, com a sua marca (por enquanto no domínio verifica.cartaflow.com.br): https://verifica.cartaflow.com.br/{id da sua conta}/{token da página}. É o endereço impresso na correspondência e o que o QR code abre; o QR code leva o código junto, mas este link não, então quem abre o link precisa digitar o código. Você pode mandar este link por e-mail ou mostrar no seu app. Trate-o como um endereço opaco: guarde e use como veio. null quando method é code.

Formatouri
attempts_remaining*integer

Quantos códigos errados ainda podem ser digitados. Começa em 5 e diminui a cada erro, pela página ou pela API. Em 0 a verificação vai para failed.

Intervalo0 <= value <= 5
expires_at*|

Prazo para a pessoa confirmar: 60 dias depois da postagem. null antes da postagem.

Formatodate-time
confirmation*|

Como e quando a pessoa confirmou o código: por onde (method), quando, de qual IP e de onde, aproximadamente. null enquanto a verificação não foi confirmada. Uma verificação revogada depois de confirmada mantém este registro, mas o status é revoked: o endereço não conta mais como verificado.

preview_url*|

Link para uma cópia da correspondência como ela será impressa, com o endereço, mas sem o código: no lugar dele aparece 000 000, e no lugar do QR code, um quadro que mostra onde ele será impresso. O código só existe no arquivo que a CartaFlow imprime: nem a API nem o painel conseguem mostrá-lo. O link vale por 60 minutos: consulte a verificação de novo para receber um link novo. null nos eventos e webhooks, e quando o arquivo não está disponível.

Formatouri
price*

O preço cobrado do saldo na criação. Com o modelo da CartaFlow, um envio simples do seu plano: uma linha base. Com o seu PDF, o preço de uma correspondência com as mesmas opções: base, additional_sheets e color. Nunca há serviços dos Correios. Volta para o saldo quando a verificação é cancelada (canceled); não volta quando ela é revogada (revoked).

reference*|

Seu identificador para esta verificação, 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.

Tamanholength <= 100
metadata*

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.

Camposproperties <= 20
status_transitions*

Quando a verificação chegou a cada status. null para os status pelos quais ela não passou. O status received é o momento de created_at. Uma verificação revogada depois de confirmada mantém verified_at.

created_at*string

Quando a verificação foi criada.

Formatodate-time
curl -X POST "https://api.cartaflow.com.br/v1/verifications" \  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "to": {    "name": "Destinatário Exemplo",    "postal_code": "01001-000",    "number": "128",    "complement": "Ap. 52"  },  "method": "hosted_page",  "return_url": "https://www.exemplo.com.br/conta",  "reference": "cliente-1842"}'

{  "id": "ver_3Hd9Kp2qZ6tW",  "object": "verification",  "status": "received",  "method": "hosted_page",  "source": "api",  "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"  },  "document": {    "type": "template",    "title": "Confirme o seu endereço",    "body": "{{empresa}} pediu a confirmação de que você recebe correspondência neste endereço. Use o código abaixo para confirmar.",    "footer": "O código vale por 60 dias depois da postagem e só funciona para este endereço. Não compartilhe este código com ninguém.",    "include_qr_code": true,    "include_page_url": true  },  "instructions": null,  "return_url": "https://www.exemplo.com.br/conta",  "hosted_page_url": "https://verifica.cartaflow.com.br/acc_7Jw3Nf8Xq2Lp/9Qx2Lm7Tp4Rb8Kd3Wn6Yc1",  "attempts_remaining": 5,  "expires_at": null,  "confirmation": null,  "preview_url": "https://files.cartaflow.com.br/previews/ver_3Hd9Kp2qZ6tW.pdf?expires=1760369400&signature=5d2e81b3",  "price": {    "currency": "BRL",    "total": 990,    "items": [      {        "type": "base",        "quantity": 1,        "unit_amount": 990,        "amount": 990      }    ]  },  "reference": "cliente-1842",  "metadata": {},  "status_transitions": {    "in_production_at": null,    "awaiting_code_at": null,    "verified_at": null,    "failed_at": null,    "expired_at": null,    "canceled_at": null,    "revoked_at": null  },  "created_at": "2026-10-13T14:20:00Z"}