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
​
addr1
string
required
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}$
​
city
string
required
Required string length: 1 - 40
​
state
string
required

For Brazilian addresses this must be the 2-letter UF (e.g. SP).

Required string length: 1 - 40
​
country
string
required
Required string length: 1 - 60
​
paymentMethod
enum<string>
default:escrybe_credits
Available options:
escrybe_credits,
invoice,
team
​
team_member_id
integer

Required when paymentMethod=team.

​
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
​
addr2
string
Maximum string length: 40
​
name_sender
string

Sender block. If ANY of the sender fields is missing, the WHOLE block is taken from your account profile — including the fields you did send, which are overwritten. Send all seven sender fields together, or none of them. When the profile is also incomplete the request 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
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

Free-form label for your own reference.

​
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.

​
pdfFile
string

Required for shipTypes 1,2,3,5,6,7. base64 string, URL (public Google Docs/Drive links supported), or multipart file. 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. Returns 503 if DOCX conversion is not available on the server.

​
variables
string

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
​
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