Laravel InvoiceXpress

composer require digitaldev-lx/laravel-invoice-express

php artisan vendor:publish --tag=invoiceexpress-config
php artisan migrate

php artisan vendor:publish --tag=invoiceexpress-translations

use DigitaldevLx\LaravelInvoiceExpress\Facades\InvoiceExpress;
use DigitaldevLx\LaravelInvoiceExpress\DataTransferObjects\Client;
use DigitaldevLx\LaravelInvoiceExpress\DataTransferObjects\DocumentItem;
use DigitaldevLx\LaravelInvoiceExpress\DataTransferObjects\Invoice;
use DigitaldevLx\LaravelInvoiceExpress\DataTransferObjects\Tax;
use DigitaldevLx\LaravelInvoiceExpress\Enums\Country;
use DigitaldevLx\LaravelInvoiceExpress\Enums\DocumentType;

// 1. Criar cliente
$client = InvoiceExpress::clients()->create(new Client(
    name: 'Acme Lda',
    code: 'ACM-001',
    email: 'finance@acme.pt',
    fiscalId: '500000000',
    address: 'Rua das Flores 1',
    city: 'Lisboa',
    postalCode: '1000-001',
    country: Country::PT,
));

// 2. Criar fatura em rascunho
$invoice = InvoiceExpress::invoices()->create(new Invoice(
    type: DocumentType::Invoice,
    date: '2026-05-01',
    dueDate: '2026-05-31',
    items: [
        new DocumentItem(
            name: 'Consultoria',
            quantity: 4,
            unitPrice: 100.00,
            tax: new Tax(name: 'IVA23', value: 23.0),
        ),
    ],
    client: ['name' => 'Acme Lda', 'fiscal_id' => '500000000'],
));

// 3. Finalizar, gerar PDF e enviar por email
$id = (int) $invoice['id'];
InvoiceExpress::invoices()->finalize($id);
$pdfBytes = InvoiceExpress::invoices()->pdf($id);
InvoiceExpress::invoices()->email($id, $emailMessage);

// 4. Marcar como paga
InvoiceExpress::invoices()->payment($id, $paymentDto);

// Tipo default e Invoice
InvoiceExpress::invoices()->create($invoiceDto);

// Emitir nota de credito alterando o type
InvoiceExpress::invoices()->create(
    new Invoice(
        type: DocumentType::CreditNote,
        date: '2026-05-15',
        items: [...],
        client: [...],
    ),
);

// Ou passar explicitamente
InvoiceExpress::invoices()->create($invoiceDto, DocumentType::SimplifiedInvoice);

$guide = InvoiceExpress::guides()->create(new Guide(
    type: GuideType::Transport,
    date: '2026-05-15',
    loadedAt: '2026-05-15 10:00',
    loadedFrom: 'Lisboa',
    loadedTo: 'Porto',
    vehicleRegistration: '00-AA-00',
    items: [new DocumentItem(name: 'Pallet', quantity: 2)],
    client: ['name' => 'Acme'],
));

// Apenas o envelope JSON (URL valido 24h)
$envelope = InvoiceExpress::invoices()->pdfUrl($id);
$url = $envelope['output']['pdfUrl'];

// Os dois passos numa so chamada (devolve binary)
$pdfBytes = InvoiceExpress::invoices()->pdf($id);
file_put_contents(storage_path('invoice.pdf'), $pdfBytes);

// Segunda via (com marca de agua "2.a via")
$pdfBytes = InvoiceExpress::invoices()->pdf($id, secondCopy: true);

use DigitaldevLx\LaravelInvoiceExpress\DataTransferObjects\EmailMessage;
use DigitaldevLx\LaravelInvoiceExpress\DataTransferObjects\EmailRecipient;

InvoiceExpress::invoices()->email($id, new EmailMessage(
    to: new EmailRecipient(email: 'finance@acme.pt'),
    subject: 'A sua fatura n.o FAC2026/123',
    body: 'Em anexo a fatura referente aos servicos de Maio.',
    cc: new EmailRecipient(email: 'contabilidade@acme.pt'),
    logo: true,
));

$qr = InvoiceExpress::invoices()->qrCode($id);
$qr = InvoiceExpress::guides()->qrCode($guideId);

$secondCompany = InvoiceExpress::useAccount('outra-empresa', 'api-key-da-outra');

$secondCompany->invoices()->all();
$secondCompany->saft()->generate(2026, 4);

// O singleton default fica intacto
InvoiceExpress::client()->accountName(); // 'your-default-account'

use DigitaldevLx\LaravelInvoiceExpress\Concerns\HasInvoiceExpressDocuments;

final class Order extends Model
{
    use HasInvoiceExpressDocuments;
}

$table->unsignedBigInteger('invoiceexpress_document_id')->nullable()->index();
$table->string('invoiceexpress_document_type')->nullable();
$table->string('invoiceexpress_state')->nullable();
$table->string('invoiceexpress_account_name')->nullable();

$order = Order::find(1);

$order->createInvoiceXpressInvoice($invoiceDto);
$order->finalizeInvoiceXpress();
$order->emailInvoiceXpress($emailMessage);
$order->settleInvoiceXpress(new Payment(
    paymentMechanism: PaymentMethod::BankTransfer,
    amount: $order->total,
    paymentDate: now()->toDateString(),
));
$order->cancelInvoiceXpress('Customer refunded');

$pdf = $order->downloadInvoiceXpressPdf();

// Predicates
$order->invoiceXpressDocumentId();   // ?int
$order->invoiceXpressIsFinalized();  // bool
$order->invoiceXpressIsPaid();
$order->invoiceXpressIsCanceled();

RuntimeException
+-- InvoiceExpressException                 (base - apanhar para "qualquer falha")
    +-- AuthenticationException             (HTTP 401, expoe accountName)
    +-- BadRequestException                 (HTTP 400)
    +-- ValidationException                 (HTTP 422 - field-level errors)
    +-- NotFoundException                   (HTTP 404 - expoe resource + id)
    +-- RateLimitException                  (HTTP 429 - expoe retryAfter)
    +-- ServerException                     (HTTP 5xx)
    +-- UnknownEndpointException            (developer error)
    +-- WebhookException                    (signature invalida / payload malformado)

use DigitaldevLx\LaravelInvoiceExpress\Exceptions\RateLimitException;
use DigitaldevLx\LaravelInvoiceExpress\Exceptions\ValidationException;

try {
    InvoiceExpress::invoices()->create($dto);
} catch (ValidationException $e) {
    foreach ($e->getFieldErrors() as $field => $message) {
        logger()->warning("InvoiceXpress validation: {$field} - {$message}");
    }
} catch (RateLimitException $e) {
    sleep($e->retryAfter); // ou release() do queued job com delay
}

# Smoke-test da API key
php artisan invoiceexpress:test-connection
php artisan invoiceexpress:test-connection --account=other --key=other-api-key

# Dump tabular de todas as sequencias
php artisan invoiceexpress:sync-sequences

# Gerar SAF-T XML para um periodo
php artisan invoiceexpress:saft --year=2026 --month=4 --out=storage/saft.xml