Integrar com Node.js
O que este guia cobre
Seção intitulada “O que este guia cobre”- Enviar e-mail e SMS com o
fetchnativo, 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
Pré-requisitos
Seção intitulada “Pré-requisitos”- 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
Passo 1: Credenciais (3 min)
Seção intitulada “Passo 1: Credenciais (3 min)”No .env:
IPORTO_API_URL=https://api.iporto.com.br/api/external/v1IPORTO_API_KEY=sua_chave_aquiPasso 2: O client (7 min)
Seção intitulada “Passo 2: O client (7 min)”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();}Passo 3: Enviar, e guardar o código (4 min)
Seção intitulada “Passo 3: Enviar, e guardar o código (4 min)”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, });}Passo 4: Tratar a recusa (4 min)
Seção intitulada “Passo 4: Tratar a recusa (4 min)”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.
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, 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 });});Passo 6: SMS (opcional — 2 min)
Seção intitulada “Passo 6: SMS (opcional — 2 min)”await sendMessage({ channel: 'sms', to: pedido.clienteTelefone.replace(/\D/g, ''), text: `Seu pedido ${pedido.numero} foi confirmado.`,});Passo 7: Testes (4 min)
Seção intitulada “Passo 7: Testes (4 min)”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.fromaparece no log - 429 reenfileira usando o
Retry-After - A rota de webhook responde 200 e atualiza o seu registro
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.
