Pular para o conteúdo

Integrar com Laravel

  • 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 try genérico que engole tudo
  • Acompanhar a entrega, por consulta ou por webhook
  • 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

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]>"

Em config/services.php:

'iporto' => [
'url' => env('IPORTO_API_URL'),
'key' => env('IPORTO_API_KEY'),
'from' => env('IPORTO_MAIL_FROM'),
],

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}");
}
}

$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'),
]);
}

$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.


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:undelivered

Recebendo 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]);
}

Mesmo endpoint, com channel:

app(IportoMessages::class)->send([
'channel' => 'sms',
'to' => preg_replace('/\D/', '', $pedido->cliente_telefone),
'text' => "Seu pedido {$pedido->numero} foi confirmado.",
]);

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-Key não cria uma segunda mensagem
  • Um from que 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.