Documentação API Escrybe

Nova documentação da API

Essa página foi substituída por uma nova plataforma de documentação, a consulta a qualquer informação da API deve ser feita através do link abaixo.

Acesse: https://escrybe.readme.io/

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.

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

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.

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

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.

Enviando novo pedido POST

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);
?>

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" }

Recuperando informações de um pedido existente GET

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);
?>

Códigos de estado de pedido (retornado como campo 'status'):

  • 0 = Processando
  • 1 = Em produção
  • 2 = Créditos insuficientes
  • 3 = Impresso
  • 4 = Postado
  • 5 = Cancelado
  • 6 = Devolvido

Códigos de estado de entrega de pedido (retornado como campo 'status_delivery'):

  • NULL ou vazio = Não temos informação de entrega (pedido não possui código de rastreio ou sistema não conseguiu capturar as informações de rastreio)
  • delivered = Entregue
  • going_back_to_sender = Destinatário devolveu a carta e está a caminho do remetente
  • delivered_to_sender = Devolvido para remetente

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" }

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]