Documentação

Criar um upload

Primeira etapa para enviar um PDF grande, de até 10 MB, que não cabe numa requisição (o corpo tem até 4,5 MB, então o multipart aceita PDFs de até 4 MB).

POST
/uploads

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

Os dados do PDF que você vai enviar. A resposta traz um upload_url para onde você envia o arquivo com PUT; depois, use o id do upload numa correspondência com document.type: upload.

filename*string

O nome do arquivo PDF, como fatura-outubro.pdf. Aparece em document.filename da correspondência e no painel. De 1 a 255 caracteres.

Tamanho1 <= length <= 255
size*integer

O tamanho do arquivo em bytes, de 1 a 10485760 (10 MB). Acima disso, a API responde 422 com out_of_range.

Intervalo1 <= value <= 10485760

Corpo da resposta

O upload foi criado. Envie o arquivo para upload_url em até 2 horas.

application/json
  1. response

Um lugar para enviar um PDF grande antes de criar a correspondência. Envie o arquivo com PUT para upload_url em até 2 horas e use o id numa correspondência em até 24 horas. Cada upload pertence à sua conta e serve para uma correspondência só.

id*string

Identificador único do upload. Use em document.upload_id ao criar a correspondência. Sempre começa com upl_.

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

Tipo do objeto. Sempre upload.

filename*string

O nome do arquivo, como você enviou.

size*integer

O tamanho do arquivo em bytes, como você informou.

upload_url*string

URL HTTPS assinada para enviar o arquivo. Envie os bytes do PDF no corpo de um PUT, com o cabeçalho Content-Type: application/pdf e sem o cabeçalho Authorization: a assinatura já está na URL. Uma resposta 2xx confirma que o arquivo chegou. Vale por 2 horas (até upload_url_expires_at). Trate a URL como um segredo e não a guarde: ela não aparece em nenhum outro lugar.

Formatouri
upload_url_expires_at*string

Até quando upload_url aceita o arquivo: 2 horas depois da criação. Se passar do prazo sem enviar, crie outro upload.

Formatodate-time
expires_at*string

Até quando o upload pode ser usado numa correspondência: 24 horas depois da criação. Depois disso, document.upload_id recebe 422 com upload_expired.

Formatodate-time
created_at*string

Quando o upload foi criado.

Formatodate-time
curl -X POST "https://api.cartaflow.com.br/v1/uploads" \  -H "Authorization: Bearer $CARTAFLOW_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "filename": "fatura-outubro.pdf",  "size": 7340032}'
{  "id": "upl_6Np3Vx8Rk2Tq",  "object": "upload",  "filename": "fatura-outubro.pdf",  "size": 7340032,  "upload_url": "https://files.cartaflow.com.br/uploads/upl_6Np3Vx8Rk2Tq?token=4f8a2c91d7",  "upload_url_expires_at": "2026-10-13T16:20:00Z",  "expires_at": "2026-10-14T14:20:00Z",  "created_at": "2026-10-13T14:20:00Z"}