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 "ID: {$factura['id']}\n";
    echo "Estado: {$factura['status']}\n"; // DRAFT: la emisión sigue en segundo plano

    // El PDF se pide aparte, cuando el comprobante ya está en COMPLETED:
    // GET /v1/developer/receipts/{id}/status → { status, authorizationNumber, messages }
    // GET /v1/developer/receipts/{id}/pdf → { url, previewUrl } (url expira en 5 minutos)
} 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' => [
        [
            'code' => 'SERV-001',
            'description' => 'Servicio mensual',
            'quantity' => 1,
            'unitPrice' => 500.00,
            'taxType' => 'IVA_RATE',
            'tax' => 15,
        ],
    ],
    'sendEmail' => true,
]);

echo "Clave: {$factura['accessKey']}\n";
echo "Estado: {$factura['status']}\n"; // DRAFT; el PDF se pide después en /v1/developer/receipts/{id}/pdf

{
  "data": {
    "id": "0199c2d4-7b1e-7c3a-9f40-2d6a8e5b1c77",
    "accessKey": "1305202401099337815000110010010000056781234567811",
    "sequential": "000005678",
    "status": "DRAFT",
    "total": "575",
    "source": "API",
    "apiKeyId": "0199c2d4-6a10-7c11-8d2e-1f2a3b4c5d6e"
  },
  "meta": {
    "requestId": "0199c2d4-8f10-7a22-b3c1-5e9d7a4f6b20",
    "timestamp": "2026-05-27T12:34:56.789Z"
  }
}

{
  "data": null,
  "meta": {
    "requestId": "0199c2d4-8f10-7a22-b3c1-5e9d7a4f6b20",
    "timestamp": "2026-05-27T12:34:56.789Z"
  },
  "error": {
    "code": "GENERAL_0002",
    "message": "customer.El RUC debe tener 13 dígitos numéricos y terminar en 001",
    "statusCode": 400,
    "details": {
      "validation": [
        "customer.El RUC debe tener 13 dígitos numéricos y terminar en 001"
      ]
    }
  }
}

function withBackoff(callable $fn, int $maxAttempts = 5): mixed {
    for ($attempt = 1; ; $attempt++) {
        try {
            return $fn();
        } catch (FactuplanApiException $e) {
            // Solo fallos temporales: 408, 429 por límite de peticiones y 5xx.
            // Un 400, 401, 403, 409 o el 429 de API_10002 responden lo mismo aunque repitas.
            $temporal = in_array($e->statusCode, [408, 429, 500, 502, 503, 504], true)
                && $e->apiCode !== 'API_10002';
            if (!$temporal || $attempt >= $maxAttempts) {
                throw $e;
            }
        } catch (RuntimeException $e) {
            // Error de red o timeout de cURL: no llegó ninguna respuesta
            if ($attempt >= $maxAttempts) {
                throw $e;
            }
        }

        usleep(min(1000000 * (2 ** ($attempt - 1)), 30000000)); // microsegundos
    }
}

// Uso
$payload['devReference'] = "pedido-{$pedidoId}"; // la misma en cada intento
$factura = withBackoff(fn () => $client->request('POST', '/v1/developer/invoices', $payload))['data'];

if ($factura['duplicate']) {
    // Un intento anterior sí llegó: no se emitió nada nuevo. Revisa $factura['status'].
}

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-rest.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,
            // El hook puede dispararse más de una vez para el mismo pedido:
            // con la misma referencia, la segunda llamada devuelve la factura que ya existe.
            'devReference' => "wc-pedido-{$order_id}",
        ]);

        $order->update_meta_data('_factuplan_access_key', $factura['accessKey']);
        $order->update_meta_data('_factuplan_receipt_id', $factura['id']); // el PDF se pide después: GET /v1/developer/receipts/{id}/pdf
        $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: dígito verificador de la cédula
    }

    // Sociedad pública (6) o privada (9): este ejemplo solo comprueba el formato
    return $tercerDigito === 6 || $tercerDigito === 9;
}

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

$payload['devReference'] = "pedido-{$pedidoId}"; // la misma en cada reintento

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

if ($factura['duplicate']) {
    // Ya existía: no se emitió nada nuevo. Revisa $factura['status'].
}

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

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