Facturación electrónica en PHP para Ecuador (SRI, con ejemplos)

FACTUPLAN_API_KEY=ak_test_xxxxxxxxxxxxxxxxxx
FACTUPLAN_RUC=0950194407001

<?php
require_once 'factuplan-client.php';

$client = new FactuplanClient(
    apiKey: getenv('FACTUPLAN_API_KEY'),
    taxpayerRuc: getenv('FACTUPLAN_RUC'),
);

$payload = [
    'customer' => [
        'identificationType' => 'RUC',
        'identification' => '0993378150001',
        'legalName' => 'Cliente Demo S.A.',
        'email' => 'facturas@cliente-demo.ec',
        'saveToContacts' => true,
    ],
    'items' => [
        [
            'code' => 'SERV-001',
            'description' => 'Desarrollo web mensual',
            'quantity' => 1,
            'unitPrice' => 500.00,
            'discount' => 0,
            'taxType' => 'IVA_RATE',
            'tax' => 15,
        ],
    ],
    'payments' => [
        [
            'method' => '20',     // Transferencia bancaria (catálogo SRI)
            'amount' => 575.00,    // 500 + IVA 15%
        ],
    ],
    'sendEmail' => true,
];

try {
    $response = $client->request('POST', '/v1/developer/invoices', $payload);
    $factura = $response['data'];

    echo "✅ Factura emitida\n";
    echo "Clave de acceso: {$factura['accessKey']}\n";
    echo "RIDE PDF: {$factura['pdfUrl']}\n";
    echo "Estado: {$factura['status']}\n";
} catch (FactuplanApiException $e) {
    echo "❌ Error: {$e->getMessage()} (HTTP {$e->statusCode})\n";
    if ($e->apiCode) {
        echo "Código API: {$e->apiCode}\n";
    }
    if ($e->details) {
        echo "Detalles: " . json_encode($e->details, JSON_UNESCAPED_UNICODE) . "\n";
    }
}

<?php
require 'vendor/autoload.php';
require 'FactuplanGuzzleClient.php';

$client = new FactuplanGuzzleClient(
    apiKey: getenv('FACTUPLAN_API_KEY'),
    taxpayerRuc: getenv('FACTUPLAN_RUC'),
);

$factura = $client->emitirFactura([
    'customer' => [
        'identificationType' => 'RUC',
        'identification' => '0993378150001',
        'legalName' => 'Cliente Demo S.A.',
        'email' => 'facturas@cliente-demo.ec',
    ],
    'items' => [
        [
            'description' => 'Servicio mensual',
            'quantity' => 1,
            'unitPrice' => 500.00,
            'taxType' => 'IVA_RATE',
            'tax' => 15,
        ],
    ],
    'sendEmail' => true,
]);

echo "Clave: {$factura['accessKey']}\n";
echo "PDF: {$factura['pdfUrl']}\n";

{
  "data": { /* recurso o lista */ },
  "meta": {
    "requestId": "req_1a2b3c",
    "timestamp": "2026-05-27T12:34:56.789Z"
  }
}

{
  "statusCode": 422,
  "message": "Customer identification is invalid",
  "code": "INVOICE_4002",
  "details": [
    "identification must be a 13-digit RUC"
  ]
}

function withBackoff(callable $fn, int $maxAttempts = 5): mixed {
    $attempt = 0;
    while ($attempt < $maxAttempts) {
        try {
            return $fn();
        } catch (FactuplanApiException $e) {
            if (!in_array($e->statusCode, [429, 500, 502, 503, 504], true)) {
                throw $e;
            }
            $delay = min(1000000 * (2 ** $attempt), 30000000); // microsegundos
            usleep($delay);
            $attempt++;
        }
    }
    throw new RuntimeException("Max reintentos excedidos");
}

// Uso
$factura = withBackoff(fn () => $client->request('POST', '/v1/developer/invoices', $payload));

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use GuzzleHttp\Psr7\Response;
use Psr\Http\Message\RequestInterface;

$stack = HandlerStack::create();
$stack->push(Middleware::retry(
    function ($retries, RequestInterface $req, ?Response $res, ?Throwable $err) {
        if ($retries >= 5) return false;
        if ($err instanceof \GuzzleHttp\Exception\ConnectException) return true;
        if ($res && in_array($res->getStatusCode(), [429, 500, 502, 503, 504], true)) return true;
        return false;
    },
    fn ($retries) => 1000 * (2 ** $retries) // ms
));

$client = new Client([
    'base_uri' => 'https://api.factuplan.com.ec',
    'handler' => $stack,
    // ...
]);

add_action('woocommerce_order_status_completed', function ($order_id) {
    $order = wc_get_order($order_id);
    $cliente = [
        'identificationType' => 'CEDULA',  // ajustar según campos de WC
        'identification' => $order->get_meta('_cedula'),
        'legalName' => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
        'email' => $order->get_billing_email(),
    ];

    $items = [];
    foreach ($order->get_items() as $item) {
        $items[] = [
            'code' => $item->get_product()->get_sku() ?: (string) $item->get_product_id(),
            'description' => $item->get_name(),
            'quantity' => $item->get_quantity(),
            'unitPrice' => (float) $item->get_subtotal() / $item->get_quantity(),
            'taxType' => 'IVA_RATE',
            'tax' => 15,
        ];
    }

    $client = new FactuplanGuzzleClient(
        apiKey: get_option('factuplan_api_key'),
        taxpayerRuc: get_option('factuplan_ruc'),
    );

    try {
        $factura = $client->emitirFactura([
            'customer' => $cliente,
            'items' => $items,
            'sendEmail' => true,
        ]);

        $order->update_meta_data('_factuplan_access_key', $factura['accessKey']);
        $order->update_meta_data('_factuplan_pdf_url', $factura['pdfUrl']);
        $order->save();
    } catch (Exception $e) {
        error_log("Factuplan error en pedido {$order_id}: " . $e->getMessage());
    }
});

function validarRuc(string $ruc): bool {
    if (!preg_match('/^\d{13}$/', $ruc)) return false;
    if (!str_ends_with($ruc, '001')) return false;

    $provincia = (int) substr($ruc, 0, 2);
    if ($provincia < 1 || $provincia > 24) return false;

    $tercerDigito = (int) $ruc[2];
    $cedula = substr($ruc, 0, 10);

    if ($tercerDigito >= 0 && $tercerDigito <= 5) {
        return validarCedula($cedula); // persona natural
    } elseif ($tercerDigito === 6) {
        return validarSociedadPublica($ruc); // sociedad pública
    } elseif ($tercerDigito === 9) {
        return validarSociedadPrivada($ruc); // sociedad privada
    }

    return false;
}

function validarCedula(string $cedula): bool {
    if (strlen($cedula) !== 10) return false;
    $coef = [2, 1, 2, 1, 2, 1, 2, 1, 2];
    $sum = 0;
    for ($i = 0; $i < 9; $i++) {
        $prod = (int) $cedula[$i] * $coef[$i];
        $sum += $prod >= 10 ? $prod - 9 : $prod;
    }
    $verificador = (10 - ($sum % 10)) % 10;
    return $verificador === (int) $cedula[9];
}

// Ejemplo
if (!validarRuc('0993378150001')) {
    throw new InvalidArgumentException('RUC inválido');
}

$client->request('POST', '/v1/developer/invoices', $payload, [
    'headers' => ['Idempotency-Key' => "order-{$pedidoId}"]
]);

error_log(json_encode([
    'event' => 'invoice.created',
    'accessKey' => $factura['accessKey'],
    'status' => $factura['status'],
    'requestId' => $factura['meta']['requestId'] ?? null,
]));

// En el handler del webhook
queue()->push(new ProcesarFacturaAutorizadaJob($event));
return response()->json(['received' => true]);