Integrar com Laravel
O que este guia cobre
Seção intitulada “O que este guia cobre”- Enviar e-mail e SMS pela API, com o cliente HTTP que já vem no Laravel
- Guardar o código de rastreio junto do seu registro
- Tratar as recusas sem um
trygenérico que engole tudo - Acompanhar a entrega, por consulta ou por webhook
Pré-requisitos
Seção intitulada “Pré-requisitos”- Laravel 10 ou 11
- 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 (5 min)
Seção intitulada “Passo 1: Credenciais (5 min)”No .env:
IPORTO_API_URL=https://api.iporto.com.br/api/external/v1IPORTO_API_KEY=sua_chave_aquiEm config/services.php:
'iporto' => [ 'url' => env('IPORTO_API_URL'), 'key' => env('IPORTO_API_KEY'), 'from' => env('IPORTO_MAIL_FROM'),],Passo 2: O client (10 min)
Seção intitulada “Passo 2: O client (10 min)”Uma classe só, com o token e a base já resolvidos:
<?php
namespace App\Services;
use Illuminate\Http\Client\Response;use Illuminate\Support\Facades\Http;
class IportoMessages{ public function send(array $payload, ?string $idempotencyKey = null): Response { return Http::baseUrl(config('services.iporto.url')) ->withToken(config('services.iporto.key')) ->acceptJson() // 10s cobre o aceite com folga: o envio em si acontece depois, na fila. ->timeout(10) ->when($idempotencyKey, fn ($http) => $http->withHeader('Idempotency-Key', $idempotencyKey)) ->post('/messages', $payload); }
public function find(string $trackingCode): Response { return Http::baseUrl(config('services.iporto.url')) ->withToken(config('services.iporto.key')) ->acceptJson() ->get("/messages/{$trackingCode}"); }}Passo 3: Enviar, e guardar o código (5 min)
Seção intitulada “Passo 3: Enviar, e guardar o código (5 min)”$resposta = app(IportoMessages::class)->send([ 'from' => config('services.iporto.from'), 'to' => [$pedido->cliente_email], 'subject' => "Seu pedido {$pedido->numero}", 'html' => view('emails.pedido-confirmado', ['pedido' => $pedido])->render(), 'tags' => ['transacional', "pedido-{$pedido->numero}"],], idempotencyKey: "pedido-{$pedido->numero}");
if ($resposta->successful()) { $pedido->update([ 'iporto_tracking_code' => $resposta->json('message.tracking_code'), ]);}Passo 4: Tratar a recusa (5 min)
Seção intitulada “Passo 4: Tratar a recusa (5 min)”$resposta = app(IportoMessages::class)->send($payload, "pedido-{$pedido->numero}");
if ($resposta->successful()) { $pedido->update(['iporto_tracking_code' => $resposta->json('message.tracking_code')]);
return;}
match ($resposta->status()) { // Sem crédito: avise quem compra, não repita. 402 => Notification::route('mail', config('mail.admin'))->notify(new SemCreditoNaIporto),
// Corpo acima de 16 MB: mande o anexo por `url` em vez de base64. 413 => Log::warning('[iPORTO] Mensagem grande demais', ['pedido' => $pedido->id]),
// Campo inválido. `errors` diz qual — não adivinhe. 422 => Log::error('[iPORTO] Recusa de validação', ['errors' => $resposta->json('errors')]),
// Acima de 8.000 por minuto. `Retry-After` diz quantos segundos esperar. 429 => $this->release((int) $resposta->header('Retry-After') ?: 60),
default => Log::error('[iPORTO] Falha inesperada', ['status' => $resposta->status()]),};Os códigos, com as distinções que mudam o seu código, estão em Erros.
Passo 5: Acompanhar a entrega (5 min)
Seção intitulada “Passo 5: Acompanhar a entrega (5 min)”Duas formas, e a segunda é a que não gasta requisição.
Consultando, quando você precisa saber agora:
$status = app(IportoMessages::class) ->find($pedido->iporto_tracking_code) ->json('delivery.status');// msg:yes:queue · msg:yes:delivered · msg:yes:finished[:with:bounce|filter|trap] · msg:not:undeliveredRecebendo o evento, que é o caminho normal. Configure o endereço no painel e exponha uma rota:
// routes/api.php — sem o middleware `auth`, e com o segredo conferido no controller.Route::post('/webhooks/iporto', IportoWebhookController::class);public function __invoke(Request $request){ // A verificação da assinatura está em /api/webhooks/verificar-assinatura/ $evento = $request->input('event'); $codigo = $request->input('param.message_tracking_code');
Pedido::where('iporto_tracking_code', $codigo)->update([ 'email_status' => $request->input('param.details.delivery.status'), ]);
return response()->json(['ok' => true]);}Passo 6: SMS (opcional — 2 min)
Seção intitulada “Passo 6: SMS (opcional — 2 min)”Mesmo endpoint, com channel:
app(IportoMessages::class)->send([ 'channel' => 'sms', 'to' => preg_replace('/\D/', '', $pedido->cliente_telefone), 'text' => "Seu pedido {$pedido->numero} foi confirmado.",]);Passo 7: Testes (5 min)
Seção intitulada “Passo 7: Testes (5 min)”it('guarda o código de rastreio quando a iPORTO aceita', function () { Http::fake([ '*/messages' => Http::response([ 'message' => ['tracking_code' => '3f2a7c18-9d4e-4b6a-8c1f-5e2d7a0b3f49'], ], 202), ]);
$pedido = Pedido::factory()->create();
(new EnviarConfirmacao)->handle($pedido);
expect($pedido->fresh()->iporto_tracking_code)->not->toBeNull();});Checklist:
- O envio devolve 202 e o código de rastreio fica gravado
- Repetir com a mesma
Idempotency-Keynão cria uma segunda mensagem - Um
fromque não é seu devolve 422 e o erro aparece no log com o campo - 429 reenfileira em vez de descartar
- A rota de webhook responde 200 e atualiza o seu registro
Catálogo completo de campos e códigos: Referência.
