Documentação API Escrybe

A integração com a API da Escrybe é bem simples. Veja abaixo os parâmetros e exemplo de códigos para integrar seu sistema.

A partir de 09/11/2021 alguns novos parâmetros serão exigidos para uso da versão 2 da API. Verifique abaixo se algum campo usado pelo seu sistema precisa de adequação.

VERSÃO ATUAL DA API: v2 de 10 de janeiro de 2023

Você precisa de uma API Token Key para ser autenticado. Pegue seu token clicando no nome de usuário no canto direito da barra superior, depois em Configurações.

Token

Na página Configurações, você pode solicitar para que seja gerada uma nova key, se necessário.

Em toda solicitação feita através da API, será necessário informar seu token e devem ser feitas através de HTTPS. Todas as requisições HTTP serão recusadas.

Escrybe usa códigos de resposta HTTP padrão para indicar o sucesso ou falha da requisição. Resumidamente, códigos 2xx indicam sucesso; códigos 4xx indicam falha gerada por dados informados a nós (por exemplo: falta de informações, link de arquivo inválido, etc). Códigos 5xx indicam um erro interno nos servidores Escrybe (acontecem raramente).

Código	Cód. interno	Motivo
200	200.0	Sucesso - pedido seria aceito se não fosse um teste
200	200.1	Sucesso - pedido aceito
401	401	Token inválido
400	400	Requisição incompleta
400	400.0	Não foi enviada requisição via POST
400	400.1	Modalidade de envio inválida
400	400.2.1	Dados do destinatário insuficientes ou incompletos
400	400.2.2	Dados do remetente não informados e não preenchidos no cadastro do usuário
400	400.3.1	Arquivo inválido ou caminho para arquivo inacessível
400	400.3.2	Quantidade de páginas inválida, menor que 1 ou maior 100
400	400.4.1	CEP do destinatário inválido
400	400.4.2	CEP do remetente inválido
400	400.5	Erro ao registrar pedido
400	400.6	Método de pagamento inválido
400	400.7.1	Dados para envio de telegrama incompletos
400	400.7.2	Data para telegrama pré-datado inválida. Deve ser no dia seguinte ou maior no formato YYYY-MM-DD
400	400.7.3	Data para telegrama pré-datado não definida. Deve ser no dia seguinte ou maior no formato YYYY-MM-DD
400	400.8	Erro ao registrar dados do telegrama
500	500	Erro interno do servidor
500	500	Falha ao validar contrato do usuário - por favor contatar suporte em escrybe.com.br/suporte
500	503	Servidor em manutenção, tente novamente mais tarde

A API sempre retornará em formato JSON da seguinte forma:

{"status":XXX,"status_message":"abcdef","data":ZZ}

No caso de sucesso em um novo pedido, o campo "data" informará o número do pedido, caso queira armazenar em seu sistema. Posteriormente será possível consultar o status do pedido com esse número.

Se sua requisição for para consultar informações de um pedido existente, o campo "data" retornará um Array() com os dados conforme abaixo:
{"status":XXX,"status_message":"abcdef", { 'numPages':'', 'name':'', 'addr1':'', 'addr2':'', 'zip':'', 'city':'', 'state':'', 'country':'', 'name_sender':'', 'addr1_sender':'', 'addr2_sender':'', 'zip_sender':'', 'city_sender':'', 'state_sender':'', 'country_sender':'', 'shipType':'', 'tracking':'', 'status':'', 'dateSubmit':'', 'dateLastChange':'', 'value':'', 'tag':'' }}

Também é possível consultar o status do pedido através do painel na página Meus pedidos.

Toda conexão deve ser via HTTPS

Dados devem ser enviados via POST para requisição de novos pedidos ou via GET para obter informações de um pedido existente.

Você pode enviar requisições através de um formulário HTML ou comando cURL (PHP, terminal Linux/Unix/Mac ou outros sistemas).

Não oferecemos suporte ao comando cURL no Windows (Prompt ou PowerShell).

Veja ao lado alguns exemplos.

Endereço para envio de requisições

Exemplo de código usando formulário HTML

<form action="https://escrybe.com.br/api/v2/post/" method="POST" enctype="multipart/form-data">
<input type="text" name="userSecurityToken" value="XXXXXXX">
<!--Se deseja enviar o arquivo utilizando um link, utilize um input tipo texto como abaixo-->
<input type="text" name="pdfFile" value="https://link.para/arquivo.pdf">
<!--Se deseja enviar o arquivo diretamente pelo POST, utilize um input tipo arquivo com o mesmo nome, como abaixo (remova o campo de texto acima, se for esta sua opção)-->
<input type="file" name="pdfFile" value="/caminho/para/o/arquivo.pdf">
<!--Insira aqui os demais campos necessários-->
<button type="submit" value="Enviar">
<form>

Exemplo de comando usando cURL no terminal (Linux/Unix/Mac)

Atenção para o campo pdfFile. Se utilizar para envio como arquivo (ao invés de um link), utilize o caminho completo dentro da máquina e acrescente um @ antes do caminho. Abaixo os dois exemplos.

Como link:
curl -F "pdfFile=https://" -F "userSecurityToken=XXXX" -F "name=João Paulo dos Santos" -F "addr1=Av. Paulista" -F "street_number=1200" -F "addr2=Conjunto 45" -F "zip=00000000" -F "city=São Paulo" -F "state=SP" -F "country=Brasil" -F "name_sender=Maria Luz" -F "addr1_sender=Rua Ipanema" -F "street_number_sender=350" -F "addr2_sender=Casa" -F "zip_sender=00000000" -F "city_sender=Rio de Janeiro" -F "state_sender=RJ" -F "country_sender=Brasil" -F "shipType=01" https://escrybe.com.br/api/v2/post/

Como arquivo:
curl -F "pdfFile=@/caminho/para/o/arquivo.pdf" -F "userSecurityToken=XXXX" -F "name=João Paulo dos Santos" -F "addr1=Av. Paulista" -F "street_number=1200" -F "addr2=Conjunto 45" -F "zip=00000000" -F "city=São Paulo" -F "state=SP" -F "country=Brasil" -F "name_sender=Maria Luz" -F "addr1_sender=Rua Ipanema" -F "street_number_sender=350" -F "addr2_sender=Casa" -F "zip_sender=00000000" -F "city_sender=Rio de Janeiro" -F "state_sender=RJ" -F "country_sender=Brasil" -F "shipType=01" https://escrybe.com.br/api/v2/post/

Exemplo de código usando cURL no PHP

Obs: se desejar enviar o PDF em arquivo (ao invés de link), utilizar o comando realpath("/caminho/para/o/arquivo.pdf") ao inserir o caminho.
<?php //Array com todas as informações a serem enviadas
$dados = ["userSecurityToken" => "XXXXXXXXXXXXXXXX", "pdfFile" => "https://link.para/arquivo.pdf", "name" => "João Paulo dos Santos", "addr1" => "Av. Paulista", "street_number" => "1200", "addr2" => "Conjunto 45", "zip" => "00000000", "city" => "São Paulo", "state" => "SP", "addr1_sender" => "Rua Ipanema", "street_number_sender" => "350", "addr2_sender" => "Casa", "zip_sender" => "00000000", "city_sender" => "Rio de Janeiro", "state_sender" => "RJ", "shipType" => "01", "tag" => "campanhaVerao", "test" => "1"];

//Configurar cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://escrybe.com.br/api/v2/post/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $dados);
$resposta = curl_exec($ch);
var_export($resposta);
?>

Endereço para consultar informações de um pedido existente

Exemplo de comando usando cURL no terminal (Linux/Unix/Mac)

Substitua 'XXX' pelo seu Token e 'YYY' pelo ID do job que deseja consultar
curl -X GET 'https://escrybe.com.br/api/v2/get/XXX/YYY'


Exemplo de código usando cURL no PHP

<?php //Configurar cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://escrybe.com.br/api/v2/get/XXX/YYY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
var_export($resposta);
?>

Verifique os campos obrigatórios para uma requisição bem sucedida.

Nome do campo e exemplo	Descrição
userSecurityToken "userSecurityToken" => "XXXXXXXXXXXXXXXX"	Sua API Token Key - fornecida na página Configurações Tipo: texto Obrigatório: sim
pdfFile "pdfFile" => "https://link.para/arquivo.pdf" ou "pdfFile" => "/caminho/para/o/arquivo.pdf"	Este campo pode conter dois tipos de informação com destino ao arquivo PDF a ser impresso: 1. Um link que esteja disponível publicamente ou 2. Caminho local da sua máquina Tipo: texto indicando um arquivo PDF Obrigatório: sim se shipType for 1, 2 ou 3 (carta)
name "name" => "João Paulo dos Santos"	Nome do destinatário para quem esta correspondência será enviada Tipo: texto Obrigatório: sim
addr1 "addr1" => "Av. Paulista"	Primeira linha de endereço (logradouro). Nome da Rua, Avenida, Alameda, Praça. Identificação principal da localização do destinatário Tipo: texto Obrigatório: sim
street_number "street_number" => "1200"	Número do prédio, podendo ser acompanhado de identificação de bloco ou "s/n", se aplicável, do destinatário. Exemplos: '1200', '123A', '123-A', 'S/N' Tipo: texto Obrigatório: não
addr2 "addr2" => "Conjunto 45"	Identificação específica de complemento como: casa, conjunto, apartamento, sala, bloco ou andar do destinatário. Tipo: texto Obrigatório: não
zip "zip" => "00000000"	CEP do destinatário Tipo: texto, somente números, 8 dígitos Obrigatório: sim
city "city" => "São Paulo"	Cidade do destinatário Tipo: texto Obrigatório: sim
state "state" => "SP"	Estado do destinatário Tipo: texto, 2 caracteres Obrigatório: sim
country "country" => "Brasil"	País do destinatário Tipo: texto Padrão: Brasil Obrigatório: não Obs: Atualmente o país de destino só pode ser o Brasil, por isso mesmo que seja definido, será ignorado
name_sender "name_sender" => "Maria Luz"	Nome do remetente da correspondência. Tipo: texto Obrigatório: não Obs: os dados de remetente (name_sender, addr1_sender, addr2_sender, zip_sender, city_sender, state_sender) não são obrigatórios caso esses dados tenham sido preenchidos no sistema na página Minhas informações. Se seu cadastro não possuir essas informações e não forem informados no momento da requisição, o pedido será negado.
addr1_sender "addr1_sender" => "Rua Ipanema"	Primeira linha de endereço (logradouro). Nome da Rua, Avenida, Alameda, Praça acompanhado do número do prédio. Identificação principal da localização do remetente Tipo: texto Obrigatório: não
street_number_sender "street_number_sender" => "350"	Número do prédio, podendo ser acompanhado de identificação de bloco ou "s/n", se aplicável, do remetente. Exemplos: '1200', '123A', '123-A', 'S/N' Tipo: texto Obrigatório: não
addr2_sender "addr2_sender" => "Casa"	Identificação específica de complemento como: casa, conjunto, apartamento, sala, bloco ou andar do remetente Tipo: texto Obrigatório: não
zip_sender "zip_sender" => "00000000"	CEP do remetente Tipo: texto, somente números, 8 dígitos Obrigatório: não
city_sender "city_sender" => "Rio de Janeiro"	Cidade do remetente Tipo: texto Obrigatório: não
state_sender "state_sender" => "RJ"	Estado do remetente Tipo: texto, 2 caracteres Obrigatório: não
country_sender "country_sender" => "Brasil"	País do remetente Tipo: texto Padrão: Brasil Obrigatório: não Atualmente o país de origem só pode ser o Brasil, por isso mesmo que seja definido, será ignorado.
virtualbox "virtualbox" => false	Uso do VirtualBox ou nãoremetente Tipo: boolean, true; false Padrão: false Obrigatório: não Ao utilizar VirtualBox, é necessário utilizar o nome do remetente junto do ID de usuário e o endereço Escrybe: 'name_sender' => 'Nome do cliente [UID: ID_DO_CLIENTE]' 'addr1_sender' => Rua Lourenço Prado 'addr2_sender' => Sala 24 'street_number_sender' => 218 'zip_sender' => 17201000 'city_sender' => Jaú 'country_sender' => Brasil
telegram_msg "telegram_msg" => "Lorem ipsum dolor sit amet, consectetuer adipiscing elit..."	Conteúdo da mensagem do telegrama Tipo: texto Obrigatório: sim se modalidade 4 (Telegrama) Texto sem emojis e os seguintes caracteres especiais: # & < > Somente disponível a partir da API v2.
telegram_post_dated "telegram_post_dated" => 0	Se o telegrama deve ser pós-datado Tipo: boolean, 1 = true; 0 = false Padrão: 0 = false Obrigatório: não Somente disponível a partir da API v2.
telegram_post_dated_date "telegram_post_dated_date" => "2022-12-25"	Data em que o telegrama deve ser enviado (pós-datado) Tipo: texto, formato data YYYY-MM-DD Obrigatório: sim se telegram_post_dated for true Deve ser no futuro (dia seguinte a postagem ou após). Somente disponível a partir da API v2.
telegram_sender_copy "telegram_sender_copy" => 0	Se o remetente do telegrama deve receber uma cópia Tipo: boolean, 1 = true; 0 = false Obrigatório: não Somente disponível a partir da API v2.
telegram_delivery_confirmation "telegram_delivery_confirmation" => 0	Se o remetente do telegrama deve receber uma confirmação de que o destinatário recebeu o telegrama enviado. Similar ao Aviso de recebimento da carta registrada. Tipo: boolean, 1 = true; 0 = false Obrigatório: não Somente disponível a partir da API v2.
test "test" => "1"	Tipo: boolean, 1 = true; 0 = false Padrão: 0 = false Obrigatório: não Se definido como 1, a API irá analisar todos os campos e retornará código 200 (em caso de sucesso) porém não registrará no sistema. Se não for bem sucedida, informará qual o erro como qualquer requisição.
shipType "shipType" => 1	Modalidades de envio da correspondência Padrão: 1 (Simples) Tipo: int, somente número de acordo com os códigos abaixo Obrigatório: não Modalidades disponíveis: 1 - Simples 2 - Registrada 3 - Registrada + AR 4 - Telegrama 5 - Mala Direta 6 - Sedex 7 - Sedex + AR Obs: a modalidade Telegrama ainda está em fase de testes e somente suportada a partir da API v2
tag "tag" => "primeiro contato"	Tag para uso interno do cliente, de forma a facilitar o agrupamento e filtro de envios de correspondências (ex: campanha publicitária) Tipo: texto Obrigatório: não Não pode conter espaços ou caracteres especiais. Caracteres especiais serão removidos espaços serão convertidos em traços.
Exemplo com todos os campos	{ "userSecurityToken" => "XXXXXXXXXXXXXXXX", "pdfFile" => "https://link.para/arquivo.pdf", "name" => "João Paulo dos Santos", "addr1" => "Av. Paulista", "street_number" => "1200", "addr2" => "Conjunto 45", "zip" => "00000000", "city" => "São Paulo", "state" => "SP", "addr1_sender" => "Rua Ipanema", "street_number_sender" => "350", "addr2_sender" => "Casa", "zip_sender" => "00000000", "city_sender" => "Rio de Janeiro", "state_sender" => "RJ", "shipType" => "01", "tag" => "campanhaVerao", "test" => "1" }

Campos obrigatórios para receber informações de um pedido existente.

Nome do campo e exemplo	Descrição
userSecurityToken "userSecurityToken" => "XXXXXXXXXXXXXXXX"	Sua API Token Key - fornecida na página Configurações Obrigatório: sim
job_id "job_id" => "ZZZZZZZ"	O ID do pedido que deseja receber informações Tipo: texto, somente números Obrigatório: sim
Exemplo	{ "userSecurityToken" => "XXXXXXXXXXXXXXXX", "job_id" => "ZZZZZZZ" }

Consulte a página de suporte se houver dúvidas: escrybe.com.br/suporte

Se ainda assim houver problemas ou sugestões, entre contato através do e-mail [email protected]