Calculate the price

Recipient. CartaFlow prints these details in the address area, which shows through the envelope window.

Sender, printed on one line above the recipient. Correios returns the letter to this address when it cannot be delivered, and sends the return receipt (return_receipt) here. If you leave it out, we use the account’s default sender, set in the dashboard under Configurações > Empresa (Settings > Company).

The content to print, in JSON. Pick the way with the type field: url (up to 10 MB), upload (a file sent beforehand with POST /v1/uploads, up to 10 MB) or base64 (up to 3 MB). To upload the PDF file together with the request, use multipart/form-data instead of JSON (file field, up to 4 MB). The PDF must be A4 portrait and fit in 6 sheets. See the Document and address area guide.

true prints in color. false prints in black and white: a color PDF comes out in grayscale. Color printing costs extra per printed page (each printed side counts as a page).

true prints on both sides: each sheet carries two pages of the document, so the letter uses fewer sheets and costs less. false prints on the front of each sheet only.

Where CartaFlow prints the recipient’s address.

Possible values

• first_page: In the address area of your document’s first page (90 x 45 mm, 20 mm from the left and 45 mm from the top). That area must be blank in your PDF. Default.
• extra_page: On a side of its own, the first one, which shows through the envelope window. Use it when your layout fills the address area. It takes a side that would otherwise be blank, when there is one: the back of the first page when printing on one side, or the spare side of a double-sided document with an odd number of pages. A double-sided document with an even number of pages gets one more sheet at the front. The address is never charged.

Optional Correios services, each with its own surcharge (a line in price). Without this field, or with [], the letter goes as a simple letter ("carta simples"), with no tracking after posting. return_receipt and restricted_delivery only work together with registered; without it, the API answers 422 with requires_registered. In multipart/form-data, repeat the postal_services[] field once per service.

Possible values

• registered: Registered letter ("carta registrada"): the letter is posted with registration at Correios and gets a Correios tracking code, shown in tracking_code once it is posted.
• return_receipt: Return receipt ("aviso de recebimento", AR): Correios returns a card signed by whoever received the letter to the sender printed on the envelope. Requires registered.
• restricted_delivery: Restricted delivery ("mão própria", MP): Correios delivers only to the person named on the envelope. Requires registered.

Schedules the letter for a date, formatted YYYY-MM-DD, from tomorrow up to 180 days ahead (Brasília time). The letter is validated now but only charged on that date, at 06:00: at that moment the balance must cover the price, otherwise the letter is canceled with cancellation_reason: insufficient_balance. Until then it stays scheduled and can be canceled at no cost. To send right away, leave this field out.

Your identifier for this letter, such as the invoice number or the customer id in your system. Shown in the dashboard and usable as a filter when listing. It does not have to be unique. Up to 100 characters.

Key-value pairs to store your own data with the object, such as your customer or contract id. Returned in every response and webhook and never printed. Up to 20 keys; keys up to 40 characters and string values up to 500 characters. Do not store sensitive data such as passwords or card numbers.