Pular para o conteúdo

Integrar com Node.js

  • Enviar e-mail e SMS com o fetch nativo, sem dependência nenhuma
  • Guardar o código de rastreio junto do seu registro
  • Tratar cada recusa pelo que ela significa
  • Receber o evento de entrega num endpoint Express
  • Node.js 18 ou mais novo (o fetch é nativo a partir dele)
  • Uma chave de API — ver Chaves de API
  • Um domínio e ao menos uma conta de envio nele, no painel do SMTP

No .env:

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

iporto.js
const BASE = process.env.IPORTO_API_URL;
const KEY = process.env.IPORTO_API_KEY;
export async function sendMessage(payload, { idempotencyKey } = {}) {
const response = await fetch(`${BASE}/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
},
body: JSON.stringify(payload),
// 10s cobre o aceite com folga: o envio acontece depois, na fila.
signal: AbortSignal.timeout(10_000),
});
return { status: response.status, body: await response.json(), headers: response.headers };
}
export async function findMessage(trackingCode) {
const response = await fetch(`${BASE}/messages/${trackingCode}`, {
headers: { Authorization: `Bearer ${KEY}`, Accept: 'application/json' },
});
return response.json();
}

const { status, body } = await sendMessage({
from: process.env.IPORTO_MAIL_FROM,
to: [pedido.clienteEmail],
subject: `Seu pedido ${pedido.numero}`,
html: `<p>Seu pedido ${pedido.numero} foi confirmado.</p>`,
tags: ['transacional', `pedido-${pedido.numero}`],
}, { idempotencyKey: `pedido-${pedido.numero}` });
if (status === 202) {
await db.pedidos.update(pedido.id, {
iportoTrackingCode: body.message.tracking_code,
});
}

switch (status) {
case 202:
await db.pedidos.update(pedido.id, { iportoTrackingCode: body.message.tracking_code });
break;
// Sem crédito: avise quem compra, não repita.
case 402:
await alertarFinanceiro(body.error);
break;
// Corpo acima de 16 MB: mande o anexo por `url` em vez de base64.
case 413:
logger.warn('[iPORTO] mensagem grande demais', { pedido: pedido.id });
break;
// Campo inválido. `errors` diz qual — não adivinhe.
case 422:
logger.error('[iPORTO] recusa de validação', { errors: body.errors });
break;
// Acima de 8.000 por minuto. `Retry-After` diz quantos segundos esperar.
case 429:
await filaDeReenvio.add(pedido, { delay: Number(headers.get('retry-after') ?? 60) * 1000 });
break;
default:
logger.error('[iPORTO] falha inesperada', { status });
}

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, então registre o parser com raw antes do JSON:

import express from 'express';
const app = express();
app.post('/webhooks/iporto', express.raw({ type: 'application/json' }), (req, res) => {
// A verificação da assinatura está em /api/webhooks/verificar-assinatura/
const evento = JSON.parse(req.body.toString('utf8'));
const codigo = evento.param?.message_tracking_code;
const status = evento.param?.details?.delivery?.status;
db.pedidos.updateByTrackingCode(codigo, { emailStatus: status });
res.json({ ok: true });
});

await sendMessage({
channel: 'sms',
to: pedido.clienteTelefone.replace(/\D/g, ''),
text: `Seu pedido ${pedido.numero} foi confirmado.`,
});

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
Janela do terminal
curl -X POST https://api.iporto.com.br/api/external/v1/messages \
-H "Authorization: Bearer $IPORTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"Loja <[email protected]>","to":["[email protected]"],"subject":"Teste","html":"<p>Teste</p>"}'

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