Skip to main content
POST
Create an order

Body

​
userSecurityToken
string
required

Your account security token.

​
shipType
enum<integer>
required

1 Carta Simples · 2 Carta Registrada · 3 Carta Registrada + AR · 4 Telegrama · 5 Mala Direta · 6 Sedex · 7 Sedex + AR · 8 eCarta Simples · 9 eCarta Registrada · 10 eCarta Registrada + AR. Sedex (6, 7) is only accepted with virtualbox=1 or when the sender address is in Jaú/SP.

Available options:
1,
2,
3,
4,
5,
6,
7,
8,
9,
10
​
name
string
required

Recipient name. Required fields sent blank (or containing only spaces) are rejected.

Required string length: 1 - 60
​
street_number
string
required

Building number. For Telegrama and eCarta (shipTypes 4, 8, 9, 10) it must contain at least one letter or digit — Correios requires the number in its own field. Use S/N when the address has none; - and . are rejected.

Required string length: 1 - 15
​
zip
string
required

Recipient ZIP (CEP), 8 digits. Punctuation is stripped, so 78470-000 and 78470000 are equivalent; anything that is not 8 digits is rejected. Validated against Correios for Brazilian addresses and the state is cross-checked against the CEP. A CEP that Correios has REPLACED is NOT rejected: the order is created with the new CEP and the success status_message says so (e.g. "CEP do destinatario 78460-000 foi alterado pelos Correios e corrigido automaticamente para 78470-000.").

Pattern: ^\d{5}-?\d{3}$
​
paymentMethod
enum<string>
default:escrybe_credits
Available options:
escrybe_credits,
invoice,
team
​
team_member_id
integer

Required when paymentMethod=team. It is NOT the team id: it is the id of YOUR membership in that team (team_members.id), which differs for each member. Get it from GET /api/v2/teams or from the panel (Times → "ID para a API"). The team owner has one too. A value that is not one of your memberships answers 403.

​
ar_type
enum<string>
default:physical

electronic is only allowed for shipTypes 3, 7 and 10.

Available options:
physical,
electronic
​
virtualbox
enum<string>
default:0

Virtual Box service — when 1 (or "true"), the sender address is replaced by Escrybe's facility (Jaú/SP) and Virtual Box pricing applies. This is also how you send Sedex (shipType 6 and 7) from a sender address outside Jaú/SP, which is otherwise refused.

Available options:
0,
1
​
addr1
string

Street (logradouro). Optional: when omitted or blank, it is filled from the CEP and the success status_message says so (e.g. "Endereco do destinatario completado pelo CEP: Avenida Paulista, São Paulo, SP."). Required when the CEP has no street (a city-wide CEP, which carries only city and state) or when Correios cannot be reached at that moment — the 400 names the missing fields. A value you send always wins over the CEP's.

Maximum string length: 60
​
addr2
string
Maximum string length: 40
​
city
string

Optional: filled from the CEP when omitted or blank (same rules as addr1).

Maximum string length: 40
​
state
string

For Brazilian addresses this must be the 2-letter UF (e.g. SP). Optional: filled from the CEP when omitted or blank; when sent, it must match the CEP's state.

Maximum string length: 40
​
country
string
default:Brasil

Optional: omitted or blank defaults to Brasil and the success status_message says so. Note for every text field of the address: the strings null, undefined, None, nan and nil (any case) are treated as BLANK, not as a value — they are what a serializer writes for an empty variable. A required field sent that way is rejected with 400 like a blank one.

Maximum string length: 60
​
name_sender
string

Sender block. name_sender, street_number_sender, zip_sender and country_sender are required for a request sender; addr1_sender, city_sender and state_sender go all three together or none of them (none: filled from zip_sender, same rules as the recipient). If any of the four is missing, or only one or two of the three are sent, the WHOLE block is taken from your account profile — including the fields you did send, which are overwritten. A profile with no street, city or state has them filled from its CEP; a profile with no CEP fails with 400.

Maximum string length: 60
​
addr1_sender
string
Maximum string length: 60
​
street_number_sender
string
Maximum string length: 15
​
addr2_sender
string
Maximum string length: 40
​
zip_sender
string

Sender ZIP (CEP), 8 digits. Same rules as zip, including the replaced-CEP auto-correction.

Pattern: ^\d{5}-?\d{3}$
​
city_sender
string
Maximum string length: 40
​
state_sender
string
Maximum string length: 40
​
country_sender
string
default:Brasil

Must be present to use the request sender (see name_sender); blank defaults to Brasil with a notice in status_message.

Maximum string length: 60
​
toAddrOnly
enum<integer>
default:0

Only honored for shipTypes 2, 3, 6, 7 and 10; forced to 0 otherwise.

Available options:
0,
1
​
tag
string

Optional label to organize your orders. Stored normalized: lowercase, accents removed, anything other than a-z, 0-9 becomes a hyphen ("Cobrança Março" → "cobranca-marco"). Filter the order lists by this value.

​
test
string
default:0

Validation mode. Accepts 1/true/yes/on to validate without creating the order (the calculated price is returned) and 0/false/no/off to submit for real. ANY other value is rejected with 400 — it used to fall through to a real, billable order.

​
client_request_id
string

Optional idempotency key (a UUID, for example), unique per order you intend to create. If the response to a POST is lost (timeout, network) and you repeat it with the same key, the API answers 200 with the visual_id of the order already created instead of creating a second one. A repeat while the first request is still being processed gets 409. Keys are remembered for 30 days. Invalid format: 400.

Pattern: ^[A-Za-z0-9-]{8,64}$
​
pdfFile
string

Required for shipTypes 1,2,3,5,6,7. base64 string, URL (public Google Docs/Drive links supported), or multipart file. Max 20 MB as multipart or base64 and 4 MB by URL (400 above that) and max 150 pages; password-protected PDFs are rejected.

​
docxFile
string

Optional alternative to pdfFile for shipTypes 1,2,3,5,6,7: a Word (.docx) template as base64 or multipart file. Every {{variable}} in the document (body, headers, footers) is replaced with the value given in variables for this recipient, then the result is converted to the PDF that gets printed. When both are sent, docxFile wins. Max 20 MB (400 above that). Returns 503 if DOCX conversion is not available or all conversion slots are busy (retry shortly).

​
variables
string

Placeholders in telegram_msg and ecarta_msg are substituted ONLY when this field is sent (non-empty); without it the text is stored exactly as received, {{...}} included. A docxFile template is always rendered. A malformed value is rejected with 400 before any charge. Optional JSON object {"nome": "Ana", "valor": "R$ 120,00"} with this recipient's values for the {{variable}} placeholders in telegram_msg, ecarta_msg or docxFile. Names are case/accent-insensitive ({{ Número do Contrato }} = numero_do_contrato); a placeholder with no value is rendered empty. Max 50 variables, 2000 characters each. Page count and price are computed on the rendered text. The recipient fields of this request are ALWAYS available as placeholders, in English or Portuguese, without being sent here: {{name}}/{{nome}}, {{addr1}}/{{endereco}}, {{street_number}}/{{numero}}, {{addr2}}/{{complemento}}, {{zip}}/{{cep}} (formatted 00000-000, after the Correios correction), {{city}}/{{cidade}}, {{state}}/{{uf}}, {{country}}/{{pais}}. A value sent in variables under one of these names is ignored in favor of the field.

​
duplex_printing
enum<integer>
default:1

Also accepts "true"/"false". Forced to 1 for single-page PDFs and to 0 when envelope_type=autoenvelope.

Available options:
0,
1
​
envelope_type
enum<string>
default:regular

autoenvelope requires a single-page PDF.

Available options:
regular,
autoenvelope
​
telegram_msg
string

Required for shipType=4. Min 10 chars; rendered content limited to 10 pages.

​
telegram_post_dated
enum<integer>

Required (0 or 1) when shipType=4.

Available options:
0,
1
​
telegram_post_dated_date
string<date>

Required when telegram_post_dated=1; must be a future date (tomorrow or later).

​
telegram_sender_copy
enum<integer>

Required (0 or 1) when shipType=4.

Available options:
0,
1
​
telegram_delivery_confirmation
enum<integer>

Required (0 or 1) when shipType=4.

Available options:
0,
1
​
telegram_sender_copy_format
enum<string>
default:both

How the sender copy is delivered when telegram_sender_copy=1: physical (paper, by mail), electronic (e-mail from Correios to the account e-mail) or both.

Available options:
physical,
electronic,
both
​
telegram_delivery_confirmation_format
enum<string>
default:both

How the delivery confirmation is delivered when telegram_delivery_confirmation=1: physical (paper, by mail), electronic (e-mail from Correios to the account e-mail) or both.

Available options:
physical,
electronic,
both
​
telegram_additional_email
string<email>

Single e-mail address that Correios use for the electronic copy of the telegram additionals (sender copy and delivery confirmation). Defaults to the e-mail of the account placing the order. An Escrybe return mailbox for the order is always added alongside it, so the document can be attached to the order. A malformed address is rejected with 400.

Maximum string length: 254
​
ecarta_msg
string

Required for shipTypes 8,9,10. Min 10 chars; may contain HTML. Rendered content limited to 10 pages.

​
use_client_contract
enum<string>
default:0

Post through your own Correios contract. Only for shipTypes 2,3,4,6,7,8,9,10; requires a PJ account with Correios credentials (API user, token, contract number and card) registered and a plan that allows it. Pricing changes: Correios bills postage, freight, AR, Mão Própria and telegram extras to YOUR contract, and Escrybe charges only handling/printing per your plan (plus extra sheets, single-sided printing, AutoEnvelope and VirtualBox where they apply). The Correios freight is quoted on your contract when the order is placed and returned as shipping_cost by GET /order — reported, not charged. A failed authentication or quote on your contract refuses the order with HTTP 400.

Available options:
0,
1

Response

Order accepted (or test validated)

​
status
integer
Example:

200

​
status_message
string
​
data