SDK de PHP

composer require timbrix/sdk-php

use Timbrix\TimbrixClient;

$timbrix = new TimbrixClient(getenv('TIMBRIX_API_KEY') ?: ''); // API key de sandbox

$customer = $timbrix->customers->create([
    'legalName' => 'Cliente de Prueba SA de CV',
    'taxId' => 'DUM901231AB3',
    'taxSystem' => '601',
    'email' => 'facturas@cliente-prueba.mx',
    'defaultInvoiceUse' => 'G01',
    'addressStreet' => 'Blvd. Atardecer',
    'addressExterior' => '142',
    'addressNeighborhood' => 'Centro',
    'addressCity' => 'Huatabampo',
    'addressMunicipality' => 'Huatabampo',
    'addressZip' => '86500',
    'addressState' => 'Sonora',
]);

$product = $timbrix->products->create([
    'description' => 'Servicio de prueba',
    'productKey' => 84111506,
    'unitKey' => 'E48',
    'price' => 100.0,
]);

// `date` va en hora de Ciudad de México, no en UTC.
// Ver /api-reference/invoices/create#date
$date = (new DateTimeImmutable('now', new DateTimeZone('America/Mexico_City')))
    ->format('Y-m-d\TH:i:s');

$invoice = $timbrix->invoices->create([
    'type' => 'I',
    'date' => $date,
    'paymentForm' => '01',
    'paymentMethod' => 'PUE',
    'use' => 'G03',
    'customerId' => $customer->id,
    'items' => [['productId' => $product->id, 'quantity' => 1]],
    'idempotencyKey' => 'pedido-1042',
]);

echo $invoice->uuid; // folio fiscal (UUID) que asigna el PAC al timbrar

file_put_contents('factura.pdf', $timbrix->invoices->getPdf($invoice->uuid));
file_put_contents('factura.xml', $timbrix->invoices->getXml($invoice->uuid));

$timbrix = new TimbrixClient(getenv('TIMBRIX_API_KEY') ?: '', [
    'baseUrl' => 'https://api.timbrix.mx', // opcional
    'timeout' => 30,                       // segundos; 120 al timbrar
    'maxRetries' => 2,                     // reintentos automáticos
]);

use Timbrix\Exceptions\ConflictException;
use Timbrix\Exceptions\TimbrixException;
use Timbrix\Exceptions\ValidationException;

try {
    $invoice = $timbrix->invoices->create($data);
} catch (ValidationException $e) {
    foreach ($e->getMessages() as $message) {
        error_log($message); // uno por campo inválido
    }
} catch (ConflictException $e) {
    if ($e->getErrorCode() === 'PAC_STAMP_UNCONFIRMED') {
        // Espera el webhook invoice.stamped o invoice.stamping_failed.
    }
} catch (TimbrixException $e) {
    error_log($e->getErrorCode() . ': ' . $e->getMessage());
}

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Timbrix\Exceptions\SignatureVerificationException;
use Timbrix\Webhook;

class TimbrixWebhookController
{
    public function handle(Request $request): Response
    {
        try {
            $event = Webhook::constructEvent(
                $request->getContent(), // body crudo, sin decodificar
                (string) $request->header('X-Webhook-Signature'),
                (string) config('services.timbrix.webhook_secret'),
            );
        } catch (SignatureVerificationException $e) {
            return response('Firma inválida', 400);
        }

        // $event es el payload del evento. El tipo (por ejemplo "invoice.stamped")
        // llega solo en el header X-Webhook-Event, no dentro del payload.
        $type = $request->header('X-Webhook-Event');

        return response('ok');
    }
}