Pular para o conteúdo

Integrar com Python

  • Enviar e-mail e SMS com requests
  • Guardar o código de rastreio junto do seu registro
  • Tratar cada recusa pelo que ela significa
  • Receber o evento de entrega num endpoint Flask
  • Python 3.9 ou mais novo
  • pip install requests
  • Uma chave de API — ver Chaves de API
  • Um domínio e ao menos uma conta de envio nele, no painel do SMTP

Janela do terminal
export IPORTO_API_URL="https://api.iporto.com.br/api/external/v1"
export IPORTO_API_KEY="sua_chave_aqui"
export IPORTO_MAIL_FROM="Loja <[email protected]>"

iporto.py
import os
import requests
BASE = os.environ["IPORTO_API_URL"]
KEY = os.environ["IPORTO_API_KEY"]
_session = requests.Session()
_session.headers.update({
"Authorization": f"Bearer {KEY}",
"Accept": "application/json",
})
def send_message(payload, idempotency_key=None):
headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
# 10s cobre o aceite com folga: o envio acontece depois, na fila.
return _session.post(f"{BASE}/messages", json=payload, headers=headers, timeout=10)
def find_message(tracking_code):
return _session.get(f"{BASE}/messages/{tracking_code}", timeout=10).json()

resposta = send_message(
{
"from": os.environ["IPORTO_MAIL_FROM"],
"to": [pedido.cliente_email],
"subject": f"Seu pedido {pedido.numero}",
"html": f"<p>Seu pedido {pedido.numero} foi confirmado.</p>",
"tags": ["transacional", f"pedido-{pedido.numero}"],
},
idempotency_key=f"pedido-{pedido.numero}",
)
if resposta.status_code == 202:
pedido.iporto_tracking_code = resposta.json()["message"]["tracking_code"]
pedido.save()

corpo = resposta.json()
if resposta.status_code == 202:
pedido.iporto_tracking_code = corpo["message"]["tracking_code"]
pedido.save()
# Sem crédito: avise quem compra, não repita.
elif resposta.status_code == 402:
alertar_financeiro(corpo["error"])
# Corpo acima de 16 MB: mande o anexo por `url` em vez de base64.
elif resposta.status_code == 413:
logger.warning("[iPORTO] mensagem grande demais", extra={"pedido": pedido.id})
# Campo inválido. `errors` diz qual — não adivinhe.
elif resposta.status_code == 422:
logger.error("[iPORTO] recusa de validação", extra={"errors": corpo.get("errors")})
# Acima de 8.000 por minuto. `Retry-After` diz quantos segundos esperar.
elif resposta.status_code == 429:
espera = int(resposta.headers.get("Retry-After", 60))
reenviar_em(pedido, espera)
else:
logger.error("[iPORTO] falha inesperada", extra={"status": resposta.status_code})

Os códigos, com as distinções que mudam o seu código, estão em Erros.


Configure o endereço no painel e exponha a rota. O corpo cru é necessário para conferir a assinatura:

from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/webhooks/iporto")
def iporto_webhook():
# A verificação da assinatura está em /api/webhooks/verificar-assinatura/
# e usa request.get_data(), que é o corpo CRU.
evento = request.get_json(silent=True) or {}
codigo = evento.get("param", {}).get("message_tracking_code")
status = evento.get("param", {}).get("details", {}).get("delivery", {}).get("status")
atualizar_pedido_por_codigo(codigo, email_status=status)
return jsonify(ok=True)

import re
send_message({
"channel": "sms",
"to": re.sub(r"\D", "", pedido.cliente_telefone),
"text": f"Seu pedido {pedido.numero} foi confirmado.",
})

import responses
@responses.activate
def test_guarda_o_codigo_de_rastreio():
responses.add(
responses.POST,
f"{BASE}/messages",
json={"message": {"tracking_code": "3f2a7c18-9d4e-4b6a-8c1f-5e2d7a0b3f49"}},
status=202,
)
resposta = send_message({"from": "x", "to": ["[email protected]"], "subject": "a", "html": "<p>a</p>"})
assert resposta.status_code == 202
assert resposta.json()["message"]["tracking_code"]

Checklist:

  • O envio devolve 202 e o código de rastreio fica gravado
  • Repetir com a mesma Idempotency-Key devolve Idempotent-Replayed: true
  • Um from que não é seu devolve 422 e errors["from"] aparece no log
  • 429 reenfileira usando o Retry-After
  • A rota de webhook responde 200 e atualiza o seu registro

Catálogo completo de campos e códigos: Referência.