Ghiduri practice
Factură, PDF și email după o comandă
Separă emiterea documentului de randare, email și e-Factura, fără numere fiscale duplicate.
1. Configurează emitentul
Pentru o cheie de platformă, selectează firma autorizată cu forMerchant(businessId). Fiscal cere momentan UUID-ul firmei în Monedo-Merchant-Id; Commerce folosește mer_..., care nu este interschimbabil. Verifică permisiunile fiscale, seriile documentelor și datele legale ale emitentului. Factura aparține comerciantului emitent, nu automat dezvoltatorului aplicației.
2. Emite o singură dată
Exemplul emite factura unei comenzi cu linii și opțiune email. Customer trebuie să aibă adresa de email corectă atunci când soliciți acest canal. Backendul Monedo calculează totalurile și rezervă numărul. Nu rezerva tu numărul dintr-un contor local și nu retrimite cu o cheie nouă dacă generarea PDF întârzie. unit_price este o valoare în unități monetare principale: 100 înseamnă 100 RON, spre deosebire de amount din Payments.
import { MonedoFiscal } from '@monedo/fiscal';
// Fiscal platform requests currently use the authorized business UUID,
// not Commerce's opaque mer_... identifier. Never accept this UUID unchecked.
export async function issueOrderInvoice({ apiKey, businessId, order, fetch }) {
const fiscal = new MonedoFiscal({ apiKey, fetch }).forMerchant(businessId);
return fiscal.invoices.create({
external_reference: order.id,
customer: order.customer,
lines: order.lines.map((line) => ({
description: line.description,
quantity: line.quantity,
unit_price: line.unitPriceMajor,
vat_percent: line.vatPercent,
unit_code: line.unitCode,
})),
delivery: { render: true, email: { enabled: true } },
}, { idempotencyKey: `order_${order.id}_invoice_v1` });
}
// Fiscal unit_price is in major currency units. Payments amount is in minor units.
// Use the merchant's validated VAT configuration, not a universal hardcoded rate.
// Invoice creation, PDF rendering, email delivery and e-Invoice acceptance are
// separate outcomes. Retry the failed delivery, not invoice creation with a new key.
3. Urmărește livrările separat
Folosește invoices.retrieve și deliveries.retrieve pentru investigații și starea efectivă. Reia doar canalul eșuat cu opțiunile și cheile adecvate. Un răspuns 202 arată că procesarea a fost programată, nu că toate etapele au terminat.
| Etapă | Ce confirmă | Ce nu confirmă |
|---|---|---|
| Emiterea facturii | Documentul și numărul au fost create. | PDF-ul nu este neapărat disponibil încă. |
| Randarea PDF | Reprezentarea documentului este generată. | Nu implică trimiterea emailului. |
| Livrarea emailului | Starea canalului email în sistemul de livrare. | Nu este o confirmare de citire a destinatarului. |
| Transmiterea e-Factura | Depunerea pe canalul fiscal solicitat. | Acceptarea finală are propria stare și trebuie urmărită. |
Chitanță sau confirmare digitală?
O chitanță fiscală înregistrează încasarea numerar a facturii. Plata cu cardul poate produce o confirmare digitală de plată, nu o chitanță de numerar. Nu emite automat ambele documente pentru aceeași încasare și nu confunda documentul billing al abonamentului cu factura fiscală. Taxele și regulile de emitere se validează în configurația emitentului; exemplul nu înlocuiește verificarea fiscală.