Integrar com n8n
O que este guia cobre
Seção intitulada “O que este guia cobre”- Enviar e-mail e SMS pelo nó HTTP Request, sem escrever código
- Guardar o código de rastreio no passo seguinte do fluxo
- Ramificar por código de recusa com o nó Switch
- Receber o evento de entrega pelo nó Webhook
Pré-requisitos
Seção intitulada “Pré-requisitos”- Uma instância do n8n, na nuvem ou própria
- Uma chave de API — ver Chaves de API
- Um domínio e ao menos uma conta de envio nele, no painel do SMTP
- Para o webhook: uma URL do n8n alcançável pela internet
Passo 1: Credenciais (5 min)
Seção intitulada “Passo 1: Credenciais (5 min)”Guarde a chave como credencial, para ela não ficar escrita em cada nó:
- Settings → Credentials → New Credential → Header Auth
- Name:
iPORTO API - Header Name:
Authorization - Header Value:
Bearer sua_chave_aqui
Passo 2: O nó que envia (10 min)
Seção intitulada “Passo 2: O nó que envia (10 min)”Acrescente um nó HTTP Request com esta configuração:
Method: POSTURL: https://api.iporto.com.br/api/external/v1/messagesAuthentication: Predefined Credential Type → Header Auth → "iPORTO API"Send Body: onBody Content Type: JSONSpecify Body: Using JSON
JSON:{ "from": "Loja <[email protected]>", "to": ["{{ $json.cliente_email }}"], "subject": "Seu pedido {{ $json.numero }}", "html": "<p>Seu pedido {{ $json.numero }} foi confirmado.</p>", "tags": ["transacional", "pedido-{{ $json.numero }}"]}
Options → Response → Include Response Headers and Status: onOptions → Response → Never Error: onPasso 3: Guardar o código de rastreio (5 min)
Seção intitulada “Passo 3: Guardar o código de rastreio (5 min)”A resposta de sucesso é 202, e o código vem em body.message.tracking_code.
Acrescente um nó Set (ou Edit Fields) depois do HTTP Request:
Mode: Manual MappingFields: tracking_code = {{ $json.body.message.tracking_code }} numero = {{ $('Quando chega o pedido').item.json.numero }}Em seguida, grave onde o seu fluxo guarda dados — Postgres, Google Sheets, Airtable, o que for.
Passo 4: Ramificar por código de recusa (5 min)
Seção intitulada “Passo 4: Ramificar por código de recusa (5 min)”Acrescente um nó Switch depois do HTTP Request:
Mode: RulesValue to Match: {{ $json.statusCode }}
Rule 1 → 202 → [gravar o tracking_code] Rule 2 → 402 → [avisar o financeiro: sem crédito] Rule 3 → 413 → [mandar o anexo por URL em vez de base64] Rule 4 → 422 → [registrar {{ $json.body.errors }} e corrigir o campo] Rule 5 → 429 → [nó Wait de {{ $json.headers['retry-after'] }}s e voltar ao HTTP Request] Fallback → [registrar e alertar]O que cada código significa está em Erros.
Passo 5: Não enviar duas vezes (3 min)
Seção intitulada “Passo 5: Não enviar duas vezes (3 min)”Se o seu fluxo pode reexecutar — e com Retry On Fail ligado ele pode —, acrescente o
cabeçalho de idempotência no HTTP Request:
Options → Headers → Add Header Name: Idempotency-Key Value: pedido-{{ $json.numero }}Repetir com a mesma chave e o mesmo corpo devolve a mensagem original e
Idempotent-Replayed: true, sem enviar de novo. Com corpo diferente e a mesma chave, a
resposta é 422.
Passo 6: Receber o evento de entrega (5 min)
Seção intitulada “Passo 6: Receber o evento de entrega (5 min)”Num fluxo novo, acrescente um nó Webhook como gatilho:
HTTP Method: POSTPath: iporto-eventosResponse Mode: ImmediatelyResponse Data: { "ok": true }Copie a Webhook URL e cadastre no painel da iPORTO. Depois, um Switch para separar os eventos:
Value to Match: {{ $json.body.event }}
email.queued → [marcar como enfileirada] email.delivered → [marcar como entregue] email.rejected → [tratar a recusa: {{ $json.body.param.details.delivery.bounce }}] sms.delivered → [marcar o SMS como entregue]O código de rastreio chega em body.param.message_tracking_code, e o objeto completo da
mensagem em body.param.details — o mesmo que a consulta devolve.
A conferência da assinatura está em Verificar a assinatura.
Passo 7: SMS (opcional — 2 min)
Seção intitulada “Passo 7: SMS (opcional — 2 min)”Mesmo nó, outro JSON:
{ "channel": "sms", "to": "{{ $json.telefone.replace(/\\D/g, '') }}", "text": "Seu pedido {{ $json.numero }} foi confirmado."}Passo 8: Testes (5 min)
Seção intitulada “Passo 8: Testes (5 min)”Use Execute Workflow com um item de teste e confira no log de execução do nó.
Checklist:
- O HTTP Request devolve
statusCode202 e otracking_codeaparece no nó Set - Com um
fromque não é seu, o Switch cai no ramo 422 ebody.errors.fromaparece - Reexecutar o fluxo com a mesma
Idempotency-Keynão cria uma segunda mensagem - O nó Webhook mostra o evento recebido no log
- O Switch do webhook roteia
email.deliveredpara o ramo certo
Catálogo completo de campos e códigos: Referência.
