noopstudios / laravel-commerce
Orders, payments and allocations for Laravel, tying EuPago payments to Moloni invoices, with an optional Filament plugin.
Requires
- php: ^8.3
- illuminate/console: ^13.0
- illuminate/contracts: ^13.0
- illuminate/database: ^13.0
- illuminate/support: ^13.0
- noopstudios/laravel-moloni: ^0.1.2
Requires (Dev)
- filament/filament: ^5.0
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- noopstudios/laravel-eupago: ^0.1
- orchestra/testbench: ^11.0
- pestphp/pest: ^4.0 || ^5.0
- pestphp/pest-plugin-laravel: ^4.0 || ^5.0
Suggests
- filament/filament: Required for the orders and payments panel plugin (^5.0).
- noopstudios/laravel-eupago: Required for Multibanco and MB WAY payments.
Provides
None
Conflicts
None
Replaces
None
README
Encomendas, pagamentos e imputações para projetos Laravel 13 novos. Liga o noopstudios/laravel-eupago (opcional: Multibanco e MB WAY) ao noopstudios/laravel-moloni (obrigatório: documentos fiscais): uma encomenda paga ou faturada acaba com os documentos certos no Moloni, sem que o pagamento dependa deles.
Requisitos: PHP ^8.3, Laravel 13. Filament v5 é opcional (só para o painel). Licença: MIT.
O que faz
- Encomendas com linhas, totais calculados como o Moloni os calcula e um estado que só o pacote escreve.
- Pagamentos e imputações. Um pagamento é dinheiro recebido; as imputações dizem o que ele pagou. A dívida de uma encomenda é o total menos as imputações de pagamentos não anulados e menos o que notas de crédito vivas abatem às suas faturas.
- Dois circuitos de faturação (ver Os dois circuitos): pagar primeiro (fatura-recibo) ou faturar primeiro (fatura e um recibo por pagamento).
- Fila de revisão para o dinheiro que não se pode aplicar sozinho (tardio, duplicado, a mais, moeda errada): fica registado, sem imputação, à espera de uma decisão humana.
- Plugin Filament opcional para operar tudo isto.
As tabelas são orders, order_items, payments e payment_allocations.
Instalação
composer require noopstudios/laravel-commerce php artisan migrate # as migrações são carregadas pelo pacote php artisan vendor:publish --tag=commerce-config # opcional
O laravel-eupago só é preciso para Multibanco e MB WAY (composer require noopstudios/laravel-eupago); o Filament, só para o painel.
COMMERCE_ORDER_PREFIX=ORD # prefixo do número da encomenda: ORD-<id>
Opções só em config/commerce.php: models.order (ver Estender) e permissions (ver Plugin Filament).
O que a aplicação tem de ter
O que vem dos pacotes irmãos não se repete aqui; ver os respetivos README.
- laravel-moloni: as credenciais e as definições gravadas e validadas (
php artisan moloni:check), uma filadatabasecom worker, e cache com locks partilhada. Nas definições do Moloni, em métodos de pagamento, mapeia as quatro chaves que este pacote usa:multibanco,mbway,transferecash. Para o circuito B é preciso uma data de vencimento configurada para cadapayment_terms_daysque usares (o prazo0incluído). - laravel-eupago (se o instalares): a chave da API, o webhook configurado no EuPago e o scheduler a correr. O pacote liga-se sozinho: regista o seu
HandlesEupagoPayments(ver Limites se tiveres o teu). - Scheduler, fila e cache: o pacote agenda
commerce:recoverde cinco em cinco minutos, por isso oschedule:runtem de estar ativo e o worker da fila do Moloni a correr. Uma cachearrayoufilenão serve com mais de um processo.
Adaptar a encomenda: três níveis
| Nível | Quando | O que fazes |
|---|---|---|
| 1. Usar | A encomenda do pacote chega | Nada. Os extras vão para meta (JSON). |
| 2. Estender | Precisas de colunas ou métodos teus | Subclasse de Order, commerce.models.order e uma migração tua. |
| 3. Substituir | Já tens um modelo que se paga (reserva, inscrição) | Commerce::ignoreOrderMigrations() e implementar Payable e Invoiceable no teu modelo. |
1. Usar
use Noop\Commerce\Models\Order; $order = Order::create([ 'billing_name' => 'Ana Silva', 'billing_vat' => '509999999', 'is_business' => true, 'meta' => ['campaign' => 'black-friday'], ]);
meta (encomenda e linhas) é um array JSON livre.
2. Estender (subclasse de Order)
namespace App\Models; use Noop\Commerce\Models\Order as BaseOrder; class Order extends BaseOrder { public function __construct(array $attributes = []) { $this->mergeFillable(['channel']); parent::__construct($attributes); } }
// config/commerce.php (publicado): definido antes de o pacote arrancar 'models' => ['order' => \App\Models\Order::class],
Acrescenta as colunas numa migração tua (Schema::table('orders', ...); a tabela continua a ser orders). O alias morph continua a ser order: o getMorphClass() do pacote é fixo, por isso os documentos do Moloni e as imputações não dependem do nome da tua classe.
- Campos congelados.
billing_flow,currencyepayment_terms_dayssó mudam enquanto a encomenda édraft; depois lançaCommerceException. As linhas também só mudam emdraft.status,paid_at,number,public_tokene os totais não sãofillable: só o pacote os escreve. customerKey(). É o id estável do cliente no Moloni (o número do cliente é construído a partir dele). Por omissão, uma encomenda com comprador (buyer) usa a inicial do tipo do comprador mais o seu id (U15) e uma encomenda sem comprador usa0mais o id da encomenda. Se dois tipos de comprador partilharem a inicial (CustomereCompany), sobrepõe o método:
public function customerKey(): string { return $this->buyer_type === null ? parent::customerKey() : strtoupper(substr(class_basename($this->buyer_type), 0, 2)).$this->buyer_id; // duas letras em vez de uma }
3. Substituir
Quando as tabelas e o modelo já são teus, diz ao pacote para não criar orders nem order_items, num register() ou boot() de um service provider teu:
use Noop\Commerce\Facades\Commerce; Commerce::ignoreOrderMigrations();
As tabelas payments e payment_allocations carregam sempre. O teu modelo implementa Noop\Commerce\Contracts\Payable e Noop\Moloni\Contracts\Invoiceable (ver o README do laravel-moloni: toInvoiceData(), invoiceReference(), customerKey()) e tem chave primária inteira.
use Illuminate\Database\Eloquent\Model; use Noop\Commerce\Contracts\Payable; use Noop\Commerce\Enums\BillingFlow; use Noop\Moloni\Contracts\Invoiceable; class Booking extends Model implements Invoiceable, Payable { public function totalCents(): int { return $this->total_cents; } public function currency(): string { return 'EUR'; } public function billingFlow(): BillingFlow { return BillingFlow::PayFirst; } public function canReceivePayment(): bool { return $this->status === 'awaiting_payment'; } public function onDueChanged(int $dueCents): void { $this->forceFill(['status' => $dueCents === 0 ? 'paid' : 'awaiting_payment'])->save(); } public function onExpired(): void { $this->forceFill(['status' => 'expired'])->save(); } public function paymentLabel(): string { return "Reserva {$this->id}"; } // toInvoiceData(), invoiceReference() e customerKey(): ver o README do laravel-moloni. }
Cada método de Payable e quando o pacote o chama:
| Método | Quando |
|---|---|
totalCents() |
Sempre que calcula a dívida. Um total 0 não gera documentos. |
currency() |
Ao criar um pagamento manual (fica no pagamento), ao pedir Multibanco/MB WAY, que só cobram EUR, e quando o EuPago confirma um pagamento: um payable que não seja em EUR manda o pagamento para revisão (currency_mismatch). |
billingFlow() |
Decide o circuito: PayFirst (A) ou InvoiceFirst (B). |
canReceivePayment() |
Antes de um pagamento manual, antes de pedir Multibanco/MB WAY, e quando o EuPago confirma um pagamento: false manda o pagamento para revisão (not_accepting_payments). |
onDueChanged(int $dueCents) |
Dentro da transação, com a linha do payable bloqueada, depois de cada imputação e de cada anulação de pagamento. É aqui que o teu modelo atualiza o estado. Quando a dívida chega a zero o pacote dispara PayableSettled. |
onExpired() |
Dentro da transação do EuPago, quando uma referência Multibanco expirada era a última tentativa em aberto (ver Validade). Decide se fecha o modelo; se fechar, dispara o PayableExpired tu. |
paymentLabel() |
Só nas mensagens de erro e no painel. |
Para o morph do teu modelo vale o que o README do laravel-moloni diz sobre o morph map: define-o antes do primeiro documento e não o mudes.
O pacote não pede a fatura do circuito B de um payable que não seja a sua Order: o teu modelo pede-a quando quiser, com Moloni::invoice($model, $payment_terms_days), e o pacote trata dos recibos. No circuito A o pacote emite a fatura-recibo sozinho quando o payable fica pago. O plugin Filament foi pensado para o Order do pacote (níveis 1 e 2). No nível 3 o alias de morph order e o recurso Encomendas do plugin continuam a existir, mas só o recurso Pagamentos tem utilidade.
Criar uma encomenda
use Noop\Commerce\Enums\BillingFlow; use Noop\Commerce\Models\Order; $order = Order::create([ 'billing_name' => 'Ana Silva', 'billing_vat' => '509999999', // sem NIF: consumidor final 'billing_email' => 'ana@example.com', 'billing_country' => 'PT', 'is_business' => true, 'billing_flow' => BillingFlow::PayFirst, // por omissão 'payment_terms_days' => 0, // circuito B: dias até ao vencimento da fatura 'buyer_type' => User::class, // opcional: o comprador 'buyer_id' => $user->id, ]); $order->addItem([ 'name' => 'Consultoria', 'reference' => 'CONS-1', 'unit_net_price' => '10.00', // sem IVA, até 5 casas decimais 'tax_rate' => 23, 'quantity' => 2, // opcional; 1 por omissão ]); $order->confirm();
- Linhas.
addItem()aceita um array com os atributos da linha (name,unit_net_price,tax_rate,quantity,reference,description,exemption_reason,moloni_product_id,meta) ou umPurchasable. A quantidade é o argumento, senão a chavequantitydo item, senão 1. Só se acrescentam linhas a uma encomendadraft.
use Illuminate\Database\Eloquent\Model; use Noop\Commerce\Contracts\Purchasable; class Workshop extends Model implements Purchasable { public function toOrderItem(): array { return [ 'name' => $this->title, 'reference' => "WS-{$this->id}", 'unit_net_price' => number_format($this->price_cents / 100, 5, '.', ''), 'tax_rate' => 23, ]; } } $order->addItem($workshop, 2); // a linha fica ligada ao workshop (relação `purchasable`)
- Totais. São calculados a partir das linhas de fatura, linha a linha, como o Moloni os calcula (arredondamento half-up a duas casas; ver "Valores e totais" no README do
laravel-moloni), por isso o valor cobrado é o valor faturado.subtotal_cents,tax_centsetotal_centsatualizam-se a cada linha. Uma linha sem IVA precisa deexemption_reason. confirm()fecha o rascunho: passa apending_payment, ou apaidlogo (comPayableSettled, e sem documentos) quando o total é zero. Falha se não houver linhas. No circuito B pede ainda a fatura ao Moloni, depois do commit e sem nunca falhar por causa disso.cancel()só se a encomenda fordraft,pending_paymentouexpirede não tiver pagamentos imputados. Não toca nos documentos do Moloni nem nas referências já pedidas: um pagamento que chegue depois vai para a fila de revisão.- Número.
PREFIX-<id>(COMMERCE_ORDER_PREFIX). Há também umpublic_token(ULID) para URLs públicos.
Estados
Só o pacote escreve o estado (status não é fillable).
| Estado | Quando |
|---|---|
draft |
Ao criar; as linhas ainda mudam. |
pending_payment |
confirm() com total > 0; também quando a anulação de um pagamento devolve a dívida toda. |
partially_paid |
Depois de uma imputação, ou de uma anulação, que deixa a dívida entre zero e o total. |
paid |
A dívida chegou a zero (ou confirm() de um total zero). Guarda paid_at. |
expired |
Circuito A: a última referência Multibanco em aberto expirou sem pagamento. |
cancelled |
cancel(). |
Uma imputação a uma encomenda expired ou cancelled (decisão de um operador, ver allocate) reabre-a.
Os dois circuitos
| A. Pagar primeiro | B. Faturar primeiro | |
|---|---|---|
billing_flow |
PayFirst (por omissão) |
InvoiceFirst |
| Documento | Fatura-recibo, quando está paga | Fatura no confirm(), e um recibo por pagamento |
| Valor de cada pagamento | A dívida exata, num só pagamento | Qualquer valor até à dívida |
| Vários pagamentos | Não | Sim, e um pagamento pode pagar várias encomendas |
| Expira | Sim, com a última referência Multibanco | Não: a dívida mantém-se |
A. Pagar primeiro. confirm() → pedes a referência (ou registas o pagamento) pelo valor exato da dívida → o pagamento é imputado e a encomenda fica paid → o pacote pede ao Moloni a fatura-recibo, com o método e a data do pagamento. Um valor diferente da dívida é recusado ao pedir, e um pagamento do EuPago de outro valor vai para revisão (amount_mismatch).
use Noop\Commerce\Facades\Commerce; use Noop\Commerce\Models\Order; $order = Order::create(['billing_vat' => '509999999', 'is_business' => true]); $order->addItem(['name' => 'Consultoria', 'unit_net_price' => '10', 'tax_rate' => 23]); $order->confirm(); // 12,30 € a pagar $attempt = Commerce::multibanco($order); // entidade e referência para o cliente // o EuPago confirma → encomenda paga → fatura-recibo pedida ao Moloni
B. Faturar primeiro. confirm() pede a fatura, com o vencimento de payment_terms_days → cada pagamento (parcial ou total) é imputado → o pacote pede um recibo por pagamento, assim que a fatura estiver emitida (um pagamento recebido antes disso só recebe o recibo quando o Moloni emitir a fatura). Um pagamento que pague várias faturas tem um só recibo.
use Noop\Commerce\Enums\BillingFlow; use Noop\Commerce\Enums\PaymentMethod; use Noop\Commerce\Facades\Commerce; use Noop\Commerce\Models\Order; $order = Order::create([ 'billing_flow' => BillingFlow::InvoiceFirst, 'payment_terms_days' => 30, 'billing_vat' => '509999999', 'is_business' => true, ]); $order->addItem(['name' => 'Projeto', 'unit_net_price' => '1000', 'tax_rate' => 23]); $order->confirm(); // fatura a 30 dias pedida ao Moloni Commerce::multibanco($order, 50000); // 500,00 € agora; o resto mais tarde Commerce::recordPayment([[$order, 73000]], PaymentMethod::Transfer, now());
O pagamento não depende da faturação
Nada do que pede documentos corre dentro da transação de um pagamento, e nenhuma exceção da faturação chega a quem pagou. Se o Moloni falhar:
- a encomenda continua
paide oPayableSettledjá foi disparado; - o documento fica
failed(ouunknown, ver o README dolaravel-moloni) e os caminhos automáticos nunca o repetem; - no painel aparece "Documento em falta" e a ação Emitir documentos (
Billing::sync($order, retryFailed: true)) volta a pedir tudo o que falta, falhados incluídos: uma fatura ou fatura-recibo nova com os dados atuais da encomenda, um recibo falhado reenviado, e um recibo anulado no Moloni substituído por um novo.
commerce:recover corre de cinco em cinco minutos e, para as encomendas pending_payment, partially_paid ou paid mexidas nas últimas 24 horas (exceto no nível 3, em que as tabelas das encomendas são tuas) e para os payables com imputações das últimas 24 horas, pede o que falta e nunca existiu: a fatura do circuito B, a fatura-recibo do circuito A, os recibos. Apanha o processo que morreu entre o commit e o pedido, e tenta outra vez o pedido que o Moloni recusou antes de existir documento. Não repete documentos falhados. Também se corre à mão: php artisan commerce:recover.
Pagamentos
Multibanco e MB WAY
use Noop\Commerce\Facades\Commerce; $attempt = Commerce::multibanco($order); // a dívida toda $attempt = Commerce::multibanco($order, 50000); // circuito B: uma parte $attempt = Commerce::mbway($order, '912345678');
Devolvem a tentativa do laravel-eupago (PaymentAttempt, com entity, reference, amount_cents, expires_at). Regras:
- Exigem o
laravel-eupagoinstalado, a encomenda emEURe a aceitar pagamentos (pending_paymentoupartially_paid). - Sem valor, pede-se a dívida. No circuito A só se aceita a dívida exata; no B, mais de zero e até à dívida.
- Nunca dentro de uma transação de base de dados (o
laravel-eupagorecusa). - Os erros são
Noop\Eupago\Exceptions\EupagoExceptioncom->type:Rejected(podes tentar outra vez),Unknown(resultado incerto: não repitas, a encomenda fica bloqueada até o webhook, a expiração ou um operador a resolverem) eBlocked(pedido em curso, tentativa por resolver ou limite atingido). O detalhe está no README dolaravel-eupago. - Quando o EuPago confirma, o pacote regista o pagamento e imputa-o (ver Fila de revisão para o que não se pode imputar).
Pagamento manual
use Noop\Commerce\Enums\PaymentMethod; use Noop\Commerce\Facades\Commerce; $payment = Commerce::recordPayment( allocations: [[$order, 73000]], // [payable, cêntimos] method: PaymentMethod::Transfer, // Multibanco, Mbway, Transfer ou Cash paidAt: now(), recordedBy: $user, // opcional; só se guarda o id notes: 'Transferência de 12/11', idempotencyKey: 'transfer-2026-11-12-001', );
O pagamento é imputado de imediato, na mesma transação, e a encomenda atualiza-se. Cada valor tem de ser maior que zero e caber na dívida; no circuito A é a dívida exata. A encomenda tem de aceitar pagamentos.
Chave de idempotência. Sem chave, cada chamada é um pagamento novo (gera-se um ULID). Com chave, repetir a chamada devolve o pagamento já registado, desde que seja manual, não esteja anulado e tenha o mesmo total; qualquer outro caso lança CommerceException. Duas chamadas simultâneas com a mesma chave registam um só pagamento.
Um recibo para várias encomendas
Um pagamento pode pagar várias encomendas do circuito B, com um só recibo no Moloni. As regras, verificadas antes de gravar nada:
- todas em circuito B (o circuito A não partilha pagamentos);
- cada uma com a fatura já emitida;
- todas faturadas ao mesmo cliente do Moloni;
- nenhuma faturada a consumidor final (sem NIF);
- no máximo 25 payables por pagamento.
Commerce::recordPayment( allocations: [ [$orderA, 123_00], // liquida a encomenda [$orderB, 50_00], // parcial ], method: PaymentMethod::Transfer, paidAt: now(), idempotencyKey: 'transfer-2026-11-12-002', );
Se alguma regra falhar, nada é gravado e a exceção diz qual. O recibo é pedido quando todas as faturas estão emitidas.
Dívida
Commerce::dueCents($order); // int, cêntimos
É o total menos as imputações de pagamentos não anulados, menos o que as notas de crédito vivas (pendentes, a emitir, emitidas ou por confirmar) abatem às faturas vivas do payable, nunca abaixo de zero. É uma leitura simples, para mostrar.
Fila de revisão
Quando o EuPago confirma um pagamento que não se pode imputar à encomenda inteira, o pacote regista o pagamento sem imputação, com needs_review = true e um review_reason, dispara PaymentNeedsReview e deixa a encomenda como estava. O webhook fica processado: não há reenvios.
review_reason |
Quando |
|---|---|
not_accepting_payments |
A encomenda já não aceita pagamentos: tardio (expired, cancelled, ainda draft) ou duplicado (já paid). |
exceeds_due |
Circuito B: valor acima da dívida de agora (excesso). |
amount_mismatch |
Circuito A: valor diferente da dívida. |
currency_mismatch |
Encomenda noutra moeda que não EUR. |
duplicate_transaction |
O identificador de transação do EuPago já estava registado noutro pagamento. |
Quem decide:
// Aplicar a uma encomenda, uma só vez; reabre uma encomenda expirada ou cancelada $allocation = Commerce::allocate($payment, $order); // até ao que o pagamento tem e a encomenda deve $allocation = Commerce::allocate($payment, $order, 5000); // ou um valor // Tirar da fila sem aplicar (reembolsado, tratado fora) Commerce::resolveReview($payment, 'Reembolsado por transferência a 14/11');
allocate()aplica o pagamento a uma encomenda, uma só vez: recusa se o pagamento já não está em revisão, está anulado, já foi imputado, ou a encomenda édraft; no circuito A tem de ser pela dívida toda. Se o valor imputado for menos que o pagamento, o resto continua em revisão atéresolveReview().resolveReview()acrescenta a nota ao pagamento e tira-o da fila.
Anular um pagamento
Commerce::voidPayment($payment, 'Enganei-me no valor', $user);
Só pagamentos manuais. As encomendas que ele pagou voltam a dever esse valor (e o estado atualiza-se: pending_payment ou partially_paid). É recusado enquanto existir um recibo vivo desse pagamento ou, no circuito A, uma fatura-recibo viva da encomenda: cancela primeiro o documento no Moloni. Os documentos nunca se tocam por ele. O pagamento seguinte recebe o seu documento automaticamente: no circuito A, a fatura-recibo cancelada ou falhada do pagamento anulado já não impede que o pacote peça uma nova, com o método e a data do novo pagamento; no circuito B cada pagamento tem o seu recibo.
Validade das referências
Só uma referência Multibanco expirada que fosse a última tentativa em aberto fecha uma encomenda do circuito A que ainda esteja pending_payment (passa a expired e dispara PayableExpired). Um pedido MB WAY que expira ou é recusado nunca fecha nada: o cliente pode pedir outro pagamento. No circuito B nada expira. Uma encomenda expired já não aceita novos pedidos; um pagamento tardio vai para revisão e pode ser aplicado com allocate().
Eventos
Todos despachados depois do commit (ShouldDispatchAfterCommit), com a propriedade pública indicada:
| Evento | Propriedade | Quando |
|---|---|---|
Noop\Commerce\Events\PayableSettled |
payable |
A dívida chegou a zero (também uma encomenda de total zero ao confirmar). Pode voltar a disparar se um pagamento for anulado e a encomenda for paga outra vez: o listener deve ser idempotente. |
Noop\Commerce\Events\PayableExpired |
payable |
Uma encomenda do circuito A expirou. |
Noop\Commerce\Events\PaymentNeedsReview |
payment |
Um pagamento foi para a fila de revisão. |
Exemplo, entregar o produto quando a encomenda está paga:
namespace App\Listeners; use Noop\Commerce\Events\PayableSettled; use Noop\Commerce\Models\Order; class DeliverPurchase { public function handle(PayableSettled $event): void { if (! $event->payable instanceof Order) { return; } foreach ($event->payable->items()->with('purchasable')->get() as $item) { $item->purchasable?->deliverTo($event->payable); // o teu código; idempotente } } }
O Laravel descobre o listener pelo tipo do argumento de handle(). O evento é independente do Moloni: dispara mesmo que a fatura-recibo ainda não exista.
Plugin Filament
use Noop\Commerce\Filament\CommercePlugin; use Noop\Moloni\Filament\MoloniPlugin; $panel->plugins([CommercePlugin::make(), MoloniPlugin::make()]);
O MoloniPlugin é obrigatório no mesmo painel: sem ele, o CommercePlugin lança uma exceção ao arrancar.
Acrescenta o recurso Encomendas e o recurso Pagamentos (só de leitura: nada se cria, edita ou apaga diretamente). As traduções para pt vêm com o pacote. O acesso segue duas habilitações, verificadas com $user->can():
// config/commerce.php 'permissions' => [ 'view' => 'view orders', // vê as encomendas e os pagamentos 'manage' => 'manage orders', // corre as ações (e também vê) ],
Define-as no teu Gate ou no teu pacote de permissões. Uma permissão null (ou vazia) nunca concede nada. O pacote regista as suas policies, exceto para um modelo em que já tenhas registado uma; um host que registe a sua própria policy para o modelo da encomenda ou para Payment tem de definir nela a habilitação manage, senão todas as ações ficam escondidas.
- Encomendas. Lista com número, nome, total, dívida, estado e circuito, e filtro por estado. A página da encomenda mostra os dados, as linhas, os pagamentos (aplicados, em revisão, anulados), as tentativas do EuPago e os documentos do Moloni, e um aviso "Documento em falta" quando falta um. Ações: Registar pagamento (inclui pagar outras encomendas em aberto do mesmo cliente, com um só recibo), Gerar referência Multibanco, Pedir MB WAY, Emitir documentos, Pró-forma e Cancelar encomenda.
- Pagamentos. Lista com filtro "em revisão" ligado por omissão. Ações: Imputar a uma encomenda (
allocate), Dar como tratado (resolveReview) e Anular (voidPayment, só manuais sem recibo vivo). - Documentos. As ações das linhas (PDF, reemitir, nota de crédito, cancelar) são as do
laravel-molonie seguem as permissões do Moloni, não estas. - Ações do EuPago. As ações Multibanco e MB WAY e a tabela de tentativas só aparecem com o
laravel-eupagoinstalado. - Nenhuma ação abre uma transação de base de dados, mesmo num painel com
databaseTransactions(); o que o pacote recusa aparece como notificação de erro.
Testar na aplicação
Com Moloni::fake() e Eupago::fake() não há rede nem credenciais, e as regras e os eventos funcionam como em produção:
use Noop\Commerce\Enums\OrderStatus; use Noop\Commerce\Facades\Commerce; use Noop\Commerce\Models\Order; use Noop\Eupago\Facades\Eupago; use Noop\Moloni\Enums\DocumentType; use Noop\Moloni\Facades\Moloni; it('settles the order and issues the invoice-receipt', function () { $moloni = Moloni::fake(); $eupago = Eupago::fake(); $order = Order::create(['billing_vat' => '509999999', 'is_business' => true]); $order->addItem(['name' => 'Consultoria', 'unit_net_price' => '10', 'tax_rate' => 23]); $order->confirm(); $attempt = Commerce::multibanco($order); $eupago->pay($attempt); expect($order->refresh()->status)->toBe(OrderStatus::Paid); $moloni->assertIssued(DocumentType::InvoiceReceipt, fn ($document) => $document->invoiceable->is($order)); });
$eupago->expire($attempt) simula a expiração, e Moloni::fake()->failNext(...) o falhanço de um documento. A tabela settings do spatie tem de existir na base de dados de testes (ver o README do laravel-moloni).
Limites e notas de operação
- Dinheiro que só aparece nas tabelas do EuPago. Uma segunda transação numa tentativa já paga, um payable apagado e eventos
rejecteddo webhook não passam pela fila de revisão deste pacote. EscutaNoop\Eupago\Events\PaymentNeedsReviewe vigia o painel do EuPago. - Um
HandlesEupagoPaymentsteu substitui o do pacote (que só se regista se nada estiver ligado). Para o manteres, delega nele:
use Noop\Commerce\Eupago\EupagoPayments; use Noop\Eupago\Contracts\HandlesEupagoPayments; use Noop\Eupago\Data\ConfirmedPayment; use Noop\Eupago\Models\PaymentAttempt; class HostPayments implements HandlesEupagoPayments { public function __construct(private readonly EupagoPayments $commerce) {} public function canReceive(PaymentAttempt $attempt): bool { return $this->commerce->canReceive($attempt); } public function received(PaymentAttempt $attempt, ConfirmedPayment $payment): void { $this->commerce->received($attempt, $payment); } public function expired(PaymentAttempt $attempt): void { $this->commerce->expired($attempt); } }
- Não uses o "reenviar" da página de documentos do próprio Moloni para recibos ou faturas-recibo de encomendas: reenvia os dados congelados, mesmo que o pagamento tenha sido anulado entretanto. Usa Emitir documentos.
- Uma nota de crédito reduz a dívida mas não muda o estado da encomenda. Cancela-a à mão se for o caso.
- Uma nota de crédito emitida entre um pagamento e o seu recibo pode fazer o Moloni recusar o recibo.
- Ids.
recorded_by_id,voided_by_ide os ids dos morphs (payable_*,buyer_*,purchasable_*) são colunas inteiras: o utilizador e os modelos têm de ter chave primária inteira. - Só
EUR. O Moloni e o EuPago só trabalham com euros. - MySQL/MariaDB (InnoDB). Os bloqueios de linha (
SELECT … FOR UPDATE) dependem dele, como nolaravel-moloni; PostgreSQL não é suportado. Dentro de uma transação tua, um deadlock chega-te já com a transação anulada: repete a unidade de trabalho. - Sem integração com pacotes de auditoria. Quem registou ou anulou um pagamento fica só no id do utilizador.
Testes do pacote
vendor/bin/pest
Usam SQLite em memória. O teste dos bloqueios de linha só corre com MySQL, numa base dedicada e vazia (apaga e recria todas as tabelas):
COMMERCE_TEST_MYSQL_DATABASE=laravel_commerce_test COMMERCE_TEST_MYSQL_HOST=127.0.0.1 \ COMMERCE_TEST_MYSQL_PORT=3306 COMMERCE_TEST_MYSQL_USERNAME=root COMMERCE_TEST_MYSQL_PASSWORD= \ vendor/bin/pest tests/Feature/LedgerMysqlTest.php
Desenvolvimento
O composer.json publicado pede os pacotes irmãos ao Packagist, por isso o CI e os outros programadores não precisam de mais nada.
Para testar contra alterações locais ainda não publicadas nos irmãos, clona os três repositórios lado a lado (laravel-commerce, laravel-moloni, laravel-eupago) e corre bin/link-siblings depois de composer install (repete depois de um composer update que os reinstale). bin/link-siblings --undo volta às versões publicadas.
Para uma alteração que abrange dois pacotes: altera e testa localmente com as ligações, publica primeiro o pacote base (tag), depois sobe aqui a versão exigida e publica este.
Licença
MIT.