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

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/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/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/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` (Carta Simples) Tipo: int, somente número de acordo com os códigos abaixo Obrigatório: não Modalidades disponíveis: 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 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/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/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/suporte

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