factulink/factulink-php

SDK oficial de FactuLink para PHP y Laravel. Facturación electrónica CFDI 4.0 conforme al Anexo 20 del SAT (México), con tipos nativos, auto-paginación, manejo de errores tipado e integración Laravel lista para usar.

Instalación

composer require factulink/factulink-php

Requiere PHP 8.1+ y la extensión ext-json. Compatible con Laravel 9, 10 y 11 (auto-discovery).

Quickstart (PHP plano)

use FactuLink\FactuLink;

$fc = new FactuLink([
    'apiKey' => 'sk_test_...',
]);

// Emitir un CFDI
$cfdi = $fc->cfdis->create([
    'tipo' => 'I',
    'receptor' => [
        'rfc' => 'XAXX010101000',
        'nombre' => 'Cliente de Prueba',
        'regimen_fiscal' => '601',
        'domicilio_fiscal' => '06600',
        'uso_cfdi' => 'G03',
    ],
    'conceptos' => [[
        'clave_prod_serv' => '43211503',
        'descripcion' => 'Laptop',
        'cantidad' => 1,
        'clave_unidad' => 'H87',
        'valor_unitario' => 15000,
    ]],
]);

echo $cfdi->uuid;

// Descargar PDF (bytes binarios)
$pdf = $fc->cfdis->downloadPdf($cfdi->uuid);
file_put_contents('factura.pdf', $pdf);

Quickstart (Laravel)

1. Publica la config (opcional):

php artisan vendor:publish --tag=factulink-config

2. Define en .env:

FACTULINK_API_KEY=sk_test_...
FACTULINK_BASE_URL=https://api.factulink.com.mx

3. Usa por inyección o Facade:

use FactuLink\FactuLink;
use FactuLink\Laravel\Facades\FactuLink as FactuLinkFacade;

// Inyección
public function emitir(FactuLink $fc) {
    return $fc->cfdis->create([...]);
}

// Facade
$cfdi = FactuLinkFacade::cfdis()->create([...]);

Recursos disponibles

Recurso	Métodos
$fc->cfdis	create, list, get, cancel, downloadXml, downloadPdf, satStatus, validate, listAutoPaginate
$fc->clients	create, list, get, update, delete
$fc->certificates	upload, list, get, update, delete
$fc->catalogs	products, units, taxRegimes, cfdiUsages, paymentForms, paymentMethods, currencies, countries
$fc->webhooks	create, list, update, delete, deliveries, test
$fc->ai	createFromText, confirmInvoice, copilot
$fc->apiKeys	create, list, revoke

Paginación automática

foreach ($fc->cfdis->listAutoPaginate(['estado' => 'timbrado']) as $cfdi) {
    echo $cfdi->uuid . PHP_EOL;
}

Manejo de errores

use FactuLink\Errors\ApiError;
use FactuLink\Errors\AuthError;
use FactuLink\Errors\RateLimitError;

try {
    $fc->cfdis->create($params);
} catch (RateLimitError $e) {
    echo "Retry after {$e->retryAfter}s";
} catch (AuthError $e) {
    echo "API key inválida";
} catch (ApiError $e) {
    echo "{$e->errorCode}: {$e->getMessage()}";
}

Jerarquía:

• FactuLink\Errors\FactuLinkError (base)
  • ApiError (status, errorCode, message, details; code() getter)
    • AuthError (401)
    • RateLimitError (429, retryAfter)

Nota: errorCode se llama así para no chocar con Exception::$code (int) que PHP reserva. Usa $err->errorCode o $err->code().

Idempotency

create() y métodos POST aceptan un parámetro opcional para enviar el header Idempotency-Key:

$fc->cfdis->create($params, idempotencyKey: 'my-unique-id');

Configuración

new FactuLink([
    'apiKey' => 'sk_live_...',                   // requerido
    'baseUrl' => 'https://api.factulink.com.mx', // default
    'timeout' => 30,                             // segundos
    'retries' => 2,                              // 429 + 5xx
]);

Reintentos: backoff exponencial 1s → 2s → 4s con cap 10s, sólo en 429/500/502/503/504.

Ambientes

• Sandbox — API keys con prefijo sk_test_.... MockPAC, no consume folios reales.
• Producción — API keys con prefijo sk_live_.... Timbrado real con Finkok.

El mismo baseUrl (https://api.factulink.com.mx) atiende ambos — el prefijo de la API key determina el ambiente.

Subir CSD

$cer = file_get_contents('mi.cer');
$key = file_get_contents('mi.key');
$cert = $fc->certificates->upload($cer, $key, 'password-de-la-llave');

Documentación

• Portal de developers: docs.factulink.com.mx
• OpenAPI spec: openapi.json
• SDK Node: @factulink/node

Reportar bugs

Abre un issue en github.com/IYair/fc-sdk-php/issues. Incluye:

• Versión del SDK (factulink/factulink-php)
• Versión de PHP (php -v)
• Versión de Laravel (si aplica)
• Snippet mínimo reproducible
• Mensaje de error completo (sin tu API Key)

Contribuir

composer install
composer qa          # cs-check + phpstan + phpunit
composer cs-fix      # auto-fix style

Sigue Conventional Commits.

Licencia

MIT © 2026 Yair Chan and FactuLink contributors