Integración · php

Integra la consulta de RUC en Laravel

Crea un servicio PHP para consultar RUC con el cliente HTTP de Laravel, credenciales en configuración y validación de respuestas.

Antes de empezar

Una aplicación Laravel con el cliente HTTP disponible. El ejemplo usa APIs del cliente HTTP documentadas para Laravel 12. Configura una API key activa y revisa el precio vigente.

Obtener API key

Puedes explorar primero el playground con datos ficticios. El código de este tutorial consulta datos reales cuando lo ejecutas; revisa su precio y usa únicamente un identificador autorizado.

Configura tu entorno

config/services.phpphp

// Add this entry to config/services.php:
'ecuadorapi' => ['key' => env('ECUADORAPI_KEY')],

La clave vive en tu servidor. No la incluyas en código del navegador, repositorios ni capturas.

Implementa la consulta

app/Services/EcuadorApi.phpphp

<?php
namespace App\Services;

use Illuminate\Support\Facades\Http;
use InvalidArgumentException;
use RuntimeException;

class EcuadorApi
{
    public function lookupRuc(string $ruc): array
    {
        if (!preg_match('/^\d{13}$/', $ruc)) {
            throw new InvalidArgumentException('Invalid RUC format');
        }
        $key = config('services.ecuadorapi.key');
        if (!$key) {
            throw new RuntimeException('Missing ECUADORAPI_KEY');
        }
        $response = Http::withToken($key)->acceptJson()
            ->connectTimeout(10)->timeout(60)
            ->get('https://api.ecuadorapi.com/api/v1/rucs/' . $ruc);
        if ($response->status() === 429) {
            throw new RuntimeException('Rate limited; Retry-After=' .
                ($response->header('Retry-After') ?? 'unknown'));
        }
        $body = $response->json();
        if (!$response->successful() || !is_array($body) ||
            ($body['error'] ?? false) || !is_array($body['data'] ?? null)) {
            throw new RuntimeException('EcuadorAPI request failed');
        }
        return $body['data'];
    }
}

Conéctala con tu flujo

Añade ECUADORAPI_KEY a las variables de entorno del servidor y la entrada mostrada a config/services.php.
Crea app/Services/EcuadorApi.php con la clase del ejemplo e inyéctala en tu controlador.
Valida y autoriza la petición en tu aplicación antes de consultar. Captura las excepciones de conexión y muestra un error seguro sin incluir claves ni registros personales.

Uso dentro de tu aplicaciónphp

<?php
// Inside an authenticated controller action with EcuadorApi injected:
$validated = $request->validate(['ruc' => ['required', 'regex:/^\d{13}$/']]);
$taxpayer = $ecuadorApi->lookupRuc($validated['ruc']);
// Map only the fields your authorized application flow needs.

Verifica éxito y errores antes de lanzar

Prueba una respuesta exitosa, campos null, un identificador sin resultados, una clave inválida, saldo insuficiente, 429 y un timeout. Los ejemplos no reintentan automáticamente: ante 429 respeta Retry-After y decide cómo reprogramar la tarea. Una consulta exitosa repetida puede volver a cobrarse.