Pular para o conteúdo principal
POST
Criar um pedido

Corpo

​
userSecurityToken
string
obrigatório

Seu token de segurança.

​
shipType
enum<integer>
obrigatório

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) só é aceito com virtualbox=1 ou quando o endereço do remetente é em Jaú/SP.

Opções disponíveis:
1,
2,
3,
4,
5,
6,
7,
8,
9,
10
​
name
string
obrigatório

Nome do destinatário. Campos obrigatórios enviados em branco (ou só com espaços) são recusados.

Required string length: 1 - 60
​
street_number
string
obrigatório

Número do imóvel. Para Telegrama e eCarta (shipTypes 4, 8, 9, 10) precisa ter ao menos uma letra ou dígito — os Correios exigem o número em seu próprio campo. Use S/N quando não houver; - e . são recusados.

Required string length: 1 - 15
​
zip
string
obrigatório

CEP do destinatário, 8 dígitos. A pontuação é removida, então 78470-000 e 78470000 são equivalentes; qualquer valor que não tenha 8 dígitos é recusado. Validado nos Correios para endereços brasileiros e a UF é conferida contra o CEP. Um CEP que os Correios ALTERARAM NÃO é recusado: o pedido é criado com o CEP novo e a status_message de sucesso informa a troca (ex.: "CEP do destinatario 78460-000 foi alterado pelos Correios e corrigido automaticamente para 78470-000.").

Pattern: ^\d{5}-?\d{3}$
​
paymentMethod
enum<string>
padrão:escrybe_credits
Opções disponíveis:
escrybe_credits,
invoice,
team
​
team_member_id
integer

Obrigatório quando paymentMethod=team. NÃO é o id do time: é o id da SUA participação naquele time (team_members.id), diferente para cada membro. Obtenha em GET /api/v2/teams ou no painel (Times → "ID para a API"). O dono do time também tem o seu. Um valor que não seja uma participação sua responde 403.

​
ar_type
enum<string>
padrão:physical

electronic só é permitido para shipTypes 3, 7 e 10.

Opções disponíveis:
physical,
electronic
​
virtualbox
enum<string>
padrão:0

Serviço Virtual Box — quando 1 (ou "true"), o endereço do remetente é substituído pela unidade da Escrybe (Jaú/SP) e a precificação do Virtual Box é aplicada. É também o caminho para enviar Sedex (shipType 6 e 7) com remetente fora de Jaú/SP, que de outro modo é recusado.

Opções disponíveis:
0,
1
​
addr1
string

Logradouro. Opcional: quando omitido ou em branco, é preenchido pelo CEP e a status_message de sucesso informa (ex.: "Endereco do destinatario completado pelo CEP: Avenida Paulista, São Paulo, SP."). Obrigatório quando o CEP não tem logradouro (CEP geral da cidade, que só traz cidade e UF) ou quando os Correios não respondem naquele momento — o 400 lista os campos que faltam. O valor que você envia sempre prevalece sobre o do CEP.

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

Opcional: preenchida pelo CEP quando omitida ou em branco (mesmas regras do addr1).

Maximum string length: 40
​
state
string

Para endereços brasileiros deve ser a UF de 2 letras (ex.: SP). Opcional: preenchida pelo CEP quando omitida ou em branco; quando enviada, precisa bater com a UF do CEP.

Maximum string length: 40
​
country
string
padrão:Brasil

Opcional: omitido ou em branco assume Brasil, e o status_message de sucesso avisa. Vale para todo campo de texto do endereço: as strings null, undefined, None, nan e nil (em qualquer caixa) são tratadas como EM BRANCO, não como valor — é o que um serializador escreve para uma variável vazia. Campo obrigatório enviado assim é recusado com 400 como um em branco.

Maximum string length: 60
​
name_sender
string

Bloco do remetente. name_sender, street_number_sender, zip_sender e country_sender são obrigatórios para usar o remetente da requisição; addr1_sender, city_sender e state_sender vão os três juntos ou nenhum (nenhum: preenchidos pelo zip_sender, mesmas regras do destinatário). Se faltar um dos quatro, ou se vier só um ou dois dos três, o bloco INTEIRO vem do cadastro da sua conta — inclusive os campos que você enviou, que são sobrescritos. Cadastro sem logradouro, cidade ou UF tem esses campos preenchidos pelo CEP dele; cadastro sem CEP falha com 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

CEP do remetente, 8 dígitos. Mesmas regras do zip, incluindo a correção automática de CEP alterado.

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

Precisa estar presente para usar o remetente da requisição (ver name_sender); em branco assume Brasil, com aviso no status_message.

Maximum string length: 60
​
toAddrOnly
enum<integer>
padrão:0

Considerado apenas para shipTypes 2, 3, 6, 7 e 10; forçado para 0 nos demais.

Opções disponíveis:
0,
1
​
tag
string

Etiqueta opcional para organizar seus pedidos. Gravada normalizada: minúsculas, sem acento, e tudo que não for a-z ou 0-9 vira hífen ("Cobrança Março" → "cobranca-marco"). Use o valor gravado para filtrar as listas de pedidos.

​
test
string
padrão:0

Modo de validação. Aceita 1/true/yes/on para validar sem criar o pedido (o preço calculado é devolvido) e 0/false/no/off para enviar de verdade. QUALQUER outro valor é recusado com 400 — antes ele caía num pedido real e cobrável.

​
client_request_id
string

Chave de idempotência opcional (um UUID, por exemplo), única por pedido que você pretende criar. Se a resposta de um POST se perder (timeout, rede) e você repetir com a mesma chave, a API responde 200 com o visual_id do pedido já criado em vez de criar um segundo. Repetição enquanto a primeira requisição ainda está sendo processada recebe 409. As chaves são lembradas por 30 dias. Formato inválido devolve 400.

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

Obrigatório para shipTypes 1,2,3,5,6,7. String base64, URL (links públicos de Google Docs/Drive suportados) ou arquivo multipart. Máx. 20 MB em multipart ou base64 e 4 MB por URL (400 acima disso) e máx. 150 páginas; PDFs com senha são rejeitados.

​
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

Os marcadores em telegram_msg e ecarta_msg só são substituídos quando este campo é enviado (não vazio); sem ele o texto é gravado exatamente como recebido, {{...}} incluso. Um modelo docxFile é sempre renderizado. Valor malformado é recusado com 400 antes de qualquer cobrança.

Objeto JSON opcional {"nome": "Ana", "valor": "R$ 120,00"} com os valores deste destinatário para os marcadores {{variavel}} em telegram_msg, ecarta_msg ou docxFile. Nomes ignoram maiúsculas e acentos ({{ Número do Contrato }} = numero_do_contrato); marcador sem valor sai em branco. Máximo de 50 variáveis, 2000 caracteres cada. Páginas e preço são calculados sobre o texto renderizado. Os campos do destinatário desta requisição estão SEMPRE disponíveis como marcadores, em inglês ou português, sem precisar enviá-los aqui: {{name}}/{{nome}}, {{addr1}}/{{endereco}}, {{street_number}}/{{numero}}, {{addr2}}/{{complemento}}, {{zip}}/{{cep}} (formatado 00000-000, após a correção dos Correios), {{city}}/{{cidade}}, {{state}}/{{uf}}, {{country}}/{{pais}}. Um valor enviado em variables com um desses nomes é ignorado em favor do campo.

​
duplex_printing
enum<integer>
padrão:1

Também aceita "true"/"false". Forçado para 1 em PDFs de página única e para 0 quando envelope_type=autoenvelope.

Opções disponíveis:
0,
1
​
envelope_type
enum<string>
padrão:regular

autoenvelope exige um PDF de página única.

Opções disponíveis:
regular,
autoenvelope
​
telegram_msg
string

Obrigatório para shipType=4. Mín. 10 caracteres; conteúdo renderizado limitado a 10 páginas.

​
telegram_post_dated
enum<integer>

Obrigatório (0 ou 1) quando shipType=4.

Opções disponíveis:
0,
1
​
telegram_post_dated_date
string<date>

Obrigatório quando telegram_post_dated=1; deve ser uma data futura (amanhã ou depois).

​
telegram_sender_copy
enum<integer>

Obrigatório (0 ou 1) quando shipType=4.

Opções disponíveis:
0,
1
​
telegram_delivery_confirmation
enum<integer>

Obrigatório (0 ou 1) quando shipType=4.

Opções disponíveis:
0,
1
​
telegram_sender_copy_format
enum<string>
padrão:both

Como a cópia ao remetente é entregue quando telegram_sender_copy=1: physical (papel, pelo correio), electronic (e-mail dos Correios para o e-mail da conta) ou both (ambos).

Opções disponíveis:
physical,
electronic,
both
​
telegram_delivery_confirmation_format
enum<string>
padrão:both

Como a confirmação de entrega é entregue quando telegram_delivery_confirmation=1: physical (papel, pelo correio), electronic (e-mail dos Correios para o e-mail da conta) ou both (ambos).

Opções disponíveis:
physical,
electronic,
both
​
telegram_additional_email
string<email>

Endereço de e-mail único que os Correios usam para a via eletrônica dos adicionais do telegrama (cópia ao remetente e confirmação de entrega). Padrão: o e-mail da conta que faz o pedido. Uma caixa de retorno da Escrybe para o pedido vai sempre junto, para o documento ser anexado ao pedido. Endereço mal formatado é recusado com 400.

Maximum string length: 254
​
ecarta_msg
string

Obrigatório para shipTypes 8,9,10. Mín. 10 caracteres; pode conter HTML. Conteúdo renderizado limitado a 10 páginas.

​
use_client_contract
enum<string>
padrão: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.

Opções disponíveis:
0,
1

Resposta

Pedido aceito (ou teste validado)

​
status
integer
Exemplo:

200

​
status_message
string
​
data