Documentação API escrybe

Introdução

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

Autenticação

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.

Erros

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
400 400.0 Não foi enviada requisição via POST
400 400.1 Dados insuficientes ou incompletos
400 400.2 Dados remetente não informados e não preenchidos no cadastro do usuário
401 401.0 Token inválido
400 400.3.1 Arquivo inválido ou link para arquivo inacessível
400 400.3.2 Quantidade máxima de páginas excedida (Máx. 60 páginas)
400 400.4 CEP inválido
400 400.5 Dados incompletos
500 500 Erro interno do servidor

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.

Conexão ao servidor

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). Veja ao lado alguns exemplos.

Endereço para envio de requisições

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

Exemplo de código usando formulário HTML

<form action="https://escrybe.com.br/api/v1/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/v1/post/

Como arquivo:
curl -F "[email protected]/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/v1/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/v1/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 código usando formulário HTML

<form action="https://escrybe.com.br/api/v1/get/" method="GET">
<input type="text" name="userSecurityToken" value="XXXXXXX">
<input type="text" name="job_id" value="ZZZZZZZ">
<button type="submit" value="Enviar">
<form>

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/v1/get/?userSecurityToken=XXX&job_id=YYY'

Exemplo de código usando cURL no PHP

<?php //Array com todas as informações a serem enviadas
$dados = ['userSecurityToken' => 'XXXXXXX', 'job_id' => 'ZZZZZZZ'];

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

Envio de novos pedidos

Requisição via POST

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
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: 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: 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.
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" => "01"
Forma de envio da correspondência
Padrão:
Tipo: somente número de acordo com os códigos abaixo
Obrigatório: não

Formas disponíveis:
1 - Comum
2 - Registrada
3 - Registrada + AR
tag
"tag" => "campanhaVerao"
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.
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" }

Consultar pedido existente

Obrigatórias

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: somente números
Obrigatório: sim
Exemplo { "userSecurityToken" => "XXXXXXXXXXXXXXXX", "job_id" => "ZZZZZZZ" }

Suporte e contato

Dúvidas, problemas e sugestões

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]