Integrar com Python
O que este guia cobre
Seção intitulada “O que este guia cobre”- 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
Pré-requisitos
Seção intitulada “Pré-requisitos”- 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
Passo 1: Credenciais (3 min)
Seção intitulada “Passo 1: Credenciais (3 min)”export IPORTO_API_URL="https://api.iporto.com.br/api/external/v1"export IPORTO_API_KEY="sua_chave_aqui"Passo 2: O client (7 min)
Seção intitulada “Passo 2: O client (7 min)”import osimport 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()Passo 3: Enviar, e guardar o código (4 min)
Seção intitulada “Passo 3: Enviar, e guardar o código (4 min)”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()Passo 4: Tratar a recusa (4 min)
Seção intitulada “Passo 4: Tratar a recusa (4 min)”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.
Passo 5: Receber o evento de entrega (5 min)
Seção intitulada “Passo 5: Receber o evento de entrega (5 min)”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)Passo 6: SMS (opcional — 2 min)
Seção intitulada “Passo 6: SMS (opcional — 2 min)”import re
send_message({ "channel": "sms", "to": re.sub(r"\D", "", pedido.cliente_telefone), "text": f"Seu pedido {pedido.numero} foi confirmado.",})Passo 7: Testes (4 min)
Seção intitulada “Passo 7: Testes (4 min)”import responses
@responses.activatedef 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-KeydevolveIdempotent-Replayed: true - Um
fromque não é seu devolve 422 eerrors["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.
