API para Desenvolvedores: Visão Geral

Esta seção reúne os recursos para integrar os serviços da iPORTO via API (HTTP). Aqui você encontra como gerar uma chave, exemplos, endpoints úteis e boas práticas.

Resumo rápido em vídeo

Gerar chave de API

1. Acesse o painel: app.iporto.com.br
2. Caminho: Página inicial → API → Nova API
3. Defina um nome e clique em Criar
4. Anote a chave (token JWT) — validade de 1 ano

Guarde o token em local seguro e use somente no backend.

Endpoints úteis (índice)

• Créditos (qualquer serviço): Consultar créditos por plan_type
• Envio SMTP via API (exemplo): Exemplos de uso (API e SMTP)

Padrões de autenticação

• Header Authorization: Bearer SEU_TOKEN_JWT_AQUI
• Accept: application/json

Fluxo visual (API)

┌──────────────────────┐     HTTP/JSON + Bearer     ┌──────────────────────┐
│  Seu Sistema/App     │ ─────────────────────────▶ │  API iPORTO (Gateway)│
│ (ERP, Loja, Backend) │   POST /...                └────────────┬─────────┘
└──────────────────────┘                                         │ enfileira
                                                                 │
                                                    ┌────────────▼────────────┐
                                                    │        Fila (Queue)     │
                                                    └────────────┬────────────┘
                                                                 │ consome
                                           ┌──────────────────────▼────────────────────────┐
                                           │  Workers/Processors                           │
                                           │  valida payload, aplica regras, tracking      │
                                           └──────────────┬──────────────┬───────────┬─────┘
                                                          │              │           │
                                   ┌──────────────────────▼───┐   ┌──────▼───────────────┐   ┌──────────────────────┐
                                   │ SMTP (smtp-avancado.com) │   │  SMS Provider        │   │ Validador de E‑mail  │
                                   └──────────────────────────┘   └──────────────────────┘   └───────────┬──────────┘
                                                          │              │                          │
                                                          ▼              ▼                          ▼
                                              Entrega ao destinatário (e‑mail/SMS)       Checagens locais + provedores

                              ┌─────────────────────────────┐
                              │ Webhook de status/entrega   │
                              └──────────┬──────────────────┘
                                         │ HTTP POST
                                         ▼
                              ┌─────────────────────────────┐
                              │ Seu Sistema/App (callback)  │
                              └─────────────────────────────┘

Notas

• Requisições aceitas retornam 202 (enfileiradas). Status/entregas chegam via Webhook.
• Configure a URL de Webhook no painel e implemente idempotência (dedupe por message_id).
• Use retries/exponencial no seu lado para lidar com 429/5xx.
• Logue o request_id/message_id retornados para conciliação.
• Validador de E‑mail: executa checagens locais (sintaxe, MX, etc.) e consultas nos provedores de destino; retorna um resultado de validação e, opcionalmente, pode acionar webhook.

Boas práticas

• ✓ Rotacione a chave antes de expirar (1 ano)
• ✓ Nunca exponha o token no front‑end
• ✓ Registre IDs de requisição/entrega para auditoria