O projeto Muambator tem como objetivo gerenciar e monitorar os pacotes de encomendas junto as operadoras logísticas. Toda vez que detectarmos uma alteração no tracking desses pacotes, enviamos uma notificação para os usuários cadastrados.
API (Application Program Interface) é um conjunto de protocolos e interfaces que permitem que softwares "conversem entre si". Por exemplo, através de uma API é possível que um sistema diferente do Facebook possa fazer um post numa timeline, ou até mesmo alterar sua foto de perfil. Atualmente diversos sistemas expõem suas funcionalidades através de API, incluindo Instagram, Gmail, Spotify, Slack, Twitter, Google Drive, Dropbox… Enfim, hoje praticamente qualquer sistema consegue interagir com qualquer outro.
Sim! O Muambator suporta a integração com outros sistemas através de uma API. E SIMMMMMM! Você consegue integrar aquele seu super sistema de comércio eletrônico.
REST & JSON.
Mais uma foca acaba de morrer. E para cada vez que esse formato é apresentado, morre um tigre de bengala. É oficial, não vamos integrar nunca com essa entronha. Mas se você precisar muito, envie um e-mail. Mas se você quiser continuar contestando, Phillip Morris apresenta melhor como você anda defasado através deste post.
Não. Ainda não existe almoço grátis, e alguém tem que ajudar a pagar nosso Ela é oferecida apenas para clientes com um volume considerável de pacotes. Ah mas vocês querendo ficar ricos cobrando de todo mundo por um simples acesso! Se você ainda não está convencido, vem conosco nesse post.
Claro serhumaninho. É bem simples mesmo. Abaixo apresentamos um código de exemplo para adicionar um pacote através de um script escrito em Python. Uma série de scripts está disponível aqui..
# -*- encoding: utf-8 -*-
import requests
if __name__ == "__main__":
host = "www.muambator.com.br"
api_token = "insira-seu-token-aqui"
codigo_pacote = "PL970650197BR"
r = requests.post('https://%s/api/clientes/v1/pacotes/%s/?api-token=%s' % (host, codigo_pacote, api_token), headers={"Content-type": "application/json"})
print r.status_code
print r.textO código acima é apenas um exemplo. Sim, sabemos que está bem simples, mas é a maneira mais simples que podemos fazer. (E não vem dizer que em Java dá pra fazer com menos linhas que isso hein!)
O código acima basicamente irá apresentar a seguinte reposta:
201
{
"status": "OK",
"message": "",
"results": {
"PL970650197BR": {
"pais_origem": "Brasil",
"tributado": false,
"icone": "",
"nome": "",
"extraviado_ou_devolvido": false,
"tags": [],
"entregue": true,
"sigla_pais_origem": "br",
"tracking": [
{
"local": "CEE NORTE - Porto Alegre/RS",
"map": "Porto Alegre, RS, Brasil",
"datahora": "08/05/2017 16:18",
"situacao": "Entrega Efetuada",
"icone": "green"
},
{
"local": "CEE NORTE - Porto Alegre/RS",
"map": "Porto Alegre, RS, Brasil",
"datahora": "08/05/2017 10:03",
"situacao": "Objeto saiu para entrega ao destinatário",
"icone": "blue"
},
{
"local": "CTE PORTO ALEGRE - PORTO ALEGRE/RS Objeto encaminhado",
"map": "PORTO ALEGRE, RS, Brasil",
"datahora": "05/05/2017 04:13",
"situacao": "Em trânsito para CEE NORTE - Porto Alegre/RS",
"icone": "orange"
},
{
"local": "CTE CURITIBA - CURITIBA/PR Objeto encaminhado",
"map": "CURITIBA, PR, Brasil",
"datahora": "30/04/2017 12:26",
"situacao": "Em trânsito para CTE PORTO ALEGRE - PORTO ALEGRE/RS",
"icone": "orange"
},
{
"local": "AGF SAO CAMILO - Pinhais/PR Objeto encaminhado",
"map": "Pinhais, PR, Brasil",
"datahora": "27/04/2017 10:20",
"situacao": "Em trânsito para CTE CURITIBA - CURITIBA/PR",
"icone": "orange"
},
{
"local": "AGF SAO CAMILO - Pinhais/PR",
"map": "Pinhais, PR, Brasil",
"datahora": "26/04/2017 14:05",
"situacao": "Objeto postado após o horário limite da agência",
"icone": "yellow"
}
],
"arquivado": false,
"marcado_como_entregue": false,
"numero_dias": 12,
"carrier": "correios",
"numero_dias_uteis": 7,
"codigo": "PL970650197BR",
"ultimo_tracking": {
"local": "CEE NORTE - Porto Alegre/RS",
"map": "Porto Alegre, RS, Brasil",
"datahora": "08/05/2017 16:18",
"situacao": "Entrega Efetuada",
"icone": "green"
}
}
}
}
O 201 é o código HTTP para informar que um objeto foi criado. Clique aqui para maiores informações.
O restante do código é o resultado da execução serializado em JSON. Todas as requisições de API do Muambator são apresentados seguindo o seguinte schema:
{
"status": "",
"message": "",
"results": null
}
O padrão acima apresenta o resultado da chamada do nosso servidor. O atributo status sempre será OK ou ERROR. No campo message, apresentamos uma mensagem para informar o problema relatado na execução, e atualmente utilizamos apenas para informar o motivo do erro (quando o status for ERROR). No campo results, apresentamos o resultado. Quando tiver qualquer problema, o campo results sempre será apresentado como null.
Chablaw! Toma essa resposta!
// Execução 1
409
{"status":"ERROR","message":"Este pacote j\u00e1 foi adicionado nesta conta!","results":null}
// Execução 2
409
{"status":"ERROR","message":"Este pacote j\u00e1 foi adicionado nesta conta!","results":null}
// Execução 3
409
{"status":"ERROR","message":"Este pacote j\u00e1 foi adicionado nesta conta!","results":null}
// Execução N
409
{"status":"ERROR","message":"Este pacote j\u00e1 foi adicionado nesta conta!","results":null}
O nosso sistema não permite que mais um pacote com o mesmo código seja adicionado ao mesmo usuário.
Show me the code little grasshopper.
# -*- encoding: utf-8 -*-
import requests
if __name__ == "__main__":
host = "www.muambator.com.br"
api_token = "insira-seu-token-aqui"
codigo_pacote = "PL970650197BR"
r = requests.delete('https://%s/api/clientes/v1/pacotes/%s/?api-token=%s' % (host, codigo_pacote, api_token), headers={"Content-type": "application/json"})
print r.status_code
print r.textNeste caso, a execução acima apresentará o status code como 204 (No Content) e não trará nada no corpo. Simples né não?
Neste parágrafo é pra você apresentar naquela reunião que marcaram para falar 2 horas sobre a possível integração com o Muambator:
URL do endpoint: https://www.muambator.com.br/api/clientes/v1/
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/[codigo do pacote aqui]/
Método: POST
Content-Type: application/json
| Nome do Parâmetro | Tipo | Tamanho Máximo | Valor Padrão | Observação |
|---|---|---|---|---|
| nome | string | 250 bytes | null | |
| emails | list | (sem limites) | [] | Neste campo podem ser informados uma lista de e-mails que irão receber as notificações dos pacotes. |
| tags | list | 250 bytes | [] | |
| categoria | string | 30 | null | Qualquer id válido de categoria |
| cep_origem | string | 10 | null | Formato: 99.999-999 |
| cep_destino | string | 19 | null | Formato: 99.999-999 |
| data_previsao_entrega | date | 10 | null | Formato: yyyy-mm-dd |
| valor | float | 0 | ||
| (#categorias) |
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/[codigo do pacote aqui]/
Método: GET
Content-Type: application/json
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/[codigo do pacote aqui]/
Método: DELETE
Content-Type: application/json
URL: https://www.muambator.com.br/api/clientes/v1/categorias/
Método: GET
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/
Método: GET
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/pendentes/
Método: GET
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/entregues/
Método: GET
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/arquivados/
Método: GET
Todos os pacotes tributados (aqueles mesmo, que você pensou que chegariam suave na nave e você levou o talagaço) na conta
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/tributados/
Método: GET
Todos os pacotes atrasados na conta (aqueles que ainda não foram entregues e possuem o atributo data_previsao_chegada para uma data anterior ao dia/hora atual)
URL: https://www.muambator.com.br/api/clientes/v1/pacotes/atrasados/
Método: GET
Tão importante quanto construir essa bagaça, é reconhecer e mandar o salve pra aquela galera que nos ajudou a descobrir bugs, melhorar documentação no melhor momento #tamojunto. Aqui é uma maneira de agradecer e reconhecer essas pessoas:
- Thiago Barradas
- Pedro Santiago