@core / invoices

1.0.1 ▾

1.0.1

認証済みMIT

GitHub

注文からスペインの請求書：法定採番、簡易/完全、訂正請求書、VeriFactu 形式のハッシュチェーン

コード8 ファイルコンテキスト約 852 トークンスキャン合格

約 852 トークン→ src/lib/invoices/AGENTS.md→ .cursor/rules/genpm-core-invoices.mdc

これは AI が src/lib/invoices で作業するときに読む内容そのものです。それ以外はコンテキストに追加されません。

@core/invoices — rules for AI agents

Purpose

Spanish invoices for paid orders (@core/orders): correlative numbering per series and year without gaps, simplified invoice up to the legal limit and full invoice above it, credit notes (rectificativas por diferencias) for refunds in their own series, full invoices that replace simplified ones when the customer gives their tax details, printable HTML with the mandatory content, and VeriFactu-style registration records: each record carries the SHA-256 hash of the previous one (format verified against the AEAT example) and the AEAT verification QR URL. Invoices are never edited or deleted. Tables: invoices, invoice_counters, invoice_records.

Scope of 1.0 (tell the person): this package prepares the data required by RD 1007/2023 and Order HAC/1177/2024, but it does not yet sign records (non-VeriFactu mode) nor send them to the AEAT (VeriFactu mode), and it is not a certified billing system. Deadlines changed several times (RD-ley 15/2025 set 2027; in October 2026 the Ministry announced a move to October 2028): check the current official calendar with the AEAT or a tax advisor.

Map

index.ts — invoiceOrder, rectifyRefund, rectifyInFull, remainingToRectify, replaceSimplified, verifyChain, invoiceHtml, invoiceQrUrl, invoicesAdminResource.
invoices.ts — issuing and order events. verifactu.ts — hash input, hash, Madrid dates, amounts, QR URL. html.ts — printable invoice.

Integration

Env: INVOICE_ISSUER_NIF, INVOICE_ISSUER_NAME, INVOICE_ISSUER_ADDRESS; optional INVOICE_SERIES (default A; credit notes use <series>R), INVOICE_VAT_RATE (default 21, prices include VAT), INVOICE_RETAIL=1 (simplified limit 3,000 € instead of 400 €), INVOICE_QR_ENV=test while testing.
Migrations as in src/lib/db/AGENTS.md. Import @/lib/invoices once at startup (e.g. src/genpm/commerce.ts): it issues invoices when orders are paid and credit notes when they are refunded (background jobs, retried).
Admin: add invoicesAdminResource({ printPath: (i) => \/invoices/${i.number}` })tosrc/genpm/admin.ts`.
Printable page for the owner (protected by invoices:read) or the customer (signed order link): return new Response(invoiceHtml(inv, { qrImageSrc }), { headers: { 'content-type': 'text/html' } }). Generate the QR image from invoiceQrUrl(inv) with a QR library in the app.
Verify: pay a test order → invoice A<year>-000001; refund part → credit note AR<year>-000001 with a negative total; verifyChain(nif) returns ok: true.

Conventions

Lines add up to the total: products at their pre-discount amount, one "Discount" line, "Shipping (<method>)" and "Tax" if added on top.
"Rectify in full" (admin, rectifyInFull) credits only what earlier credit notes left; it refuses when nothing remains.
All lines use one VAT rate in 1.0; mixed rates (reduced, exempt) need per-line taxes before using this package.
Issue invoices in EUR only; convert other currencies before.
Keep invoices and records at least as long as tax law requires (typically 4–6 years); never prune these tables.

Don't

Don't edit, renumber or delete invoices or records; correct with credit notes.
Don't print "VERI*FACTU" on invoices until records are actually sent to the AEAT.
Don't present this package as certified or as legal/tax advice.

# @core/invoices — rules for AI agents

## Purpose
Spanish invoices for paid orders (@core/orders): correlative numbering per series and year without gaps, simplified
invoice up to the legal limit and full invoice above it, credit notes (rectificativas por diferencias) for refunds in
their own series, full invoices that replace simplified ones when the customer gives their tax details, printable HTML
with the mandatory content, and VeriFactu-style registration records: each record carries the SHA-256 hash of the
previous one (format verified against the AEAT example) and the AEAT verification QR URL. Invoices are never edited
or deleted. Tables: `invoices`, `invoice_counters`, `invoice_records`.

**Scope of 1.0 (tell the person):** this package prepares the data required by RD 1007/2023 and Order HAC/1177/2024,
but it does not yet sign records (non-VeriFactu mode) nor send them to the AEAT (VeriFactu mode), and it is not a
certified billing system. Deadlines changed several times (RD-ley 15/2025 set 2027; in October 2026 the Ministry
announced a move to October 2028): check the current official calendar with the AEAT or a tax advisor.

## Map
- `index.ts` — `invoiceOrder`, `rectifyRefund`, `rectifyInFull`, `remainingToRectify`, `replaceSimplified`, `verifyChain`, `invoiceHtml`, `invoiceQrUrl`, `invoicesAdminResource`.
- `invoices.ts` — issuing and order events. `verifactu.ts` — hash input, hash, Madrid dates, amounts, QR URL. `html.ts` — printable invoice.

## Integration
1. Env: `INVOICE_ISSUER_NIF`, `INVOICE_ISSUER_NAME`, `INVOICE_ISSUER_ADDRESS`; optional `INVOICE_SERIES` (default `A`;
   credit notes use `<series>R`), `INVOICE_VAT_RATE` (default 21, prices include VAT), `INVOICE_RETAIL=1` (simplified
   limit 3,000 € instead of 400 €), `INVOICE_QR_ENV=test` while testing.
2. Migrations as in `src/lib/db/AGENTS.md`. Import `@/lib/invoices` once at startup (e.g. `src/genpm/commerce.ts`):
   it issues invoices when orders are paid and credit notes when they are refunded (background jobs, retried).
3. Admin: add `invoicesAdminResource({ printPath: (i) => \`/invoices/${i.number}\` })` to `src/genpm/admin.ts`.
4. Printable page for the owner (protected by `invoices:read`) or the customer (signed order link):
   return `new Response(invoiceHtml(inv, { qrImageSrc }), { headers: { 'content-type': 'text/html' } })`. Generate the QR
   image from `invoiceQrUrl(inv)` with a QR library in the app.
5. Verify: pay a test order → invoice `A<year>-000001`; refund part → credit note `AR<year>-000001` with a negative total;
   `verifyChain(nif)` returns `ok: true`.

## Conventions
- Lines add up to the total: products at their pre-discount amount, one "Discount" line, "Shipping (<method>)" and "Tax" if added on top.
- "Rectify in full" (admin, `rectifyInFull`) credits only what earlier credit notes left; it refuses when nothing remains.
- All lines use one VAT rate in 1.0; mixed rates (reduced, exempt) need per-line taxes before using this package.
- Issue invoices in EUR only; convert other currencies before.
- Keep invoices and records at least as long as tax law requires (typically 4–6 years); never prune these tables.

## Don't
- Don't edit, renumber or delete invoices or records; correct with credit notes.
- Don't print "VERI*FACTU" on invoices until records are actually sent to the AEAT.
- Don't present this package as certified or as legal/tax advice.

.genpmignore 適用後に組み込まれる正確なツリーです。固定先:

src/lib/invoices/index.ts読み取り専用 · 6912dca

// @core/invoices — API pública. Al importarlo emite facturas al pagarse los pedidos y rectificativas en los reembolsos.
export { invoicesAdminResource } from './admin.ts';
export { INVOICE_TITLES, invoiceHtml } from './html.ts';
export {
  InvoiceError,
  invoiceOrder,
  invoiceQrUrl,
  issuer,
  linesOf,
  rectifyInFull,
  rectifyRefund,
  registerInvoicing,
  remainingToRectify,
  replaceSimplified,
  simplifiedLimit,
  split,
  verifyChain,
} from './invoices.ts';
export { type Invoice, type InvoiceLine, type InvoiceRecord, invoiceCounters, invoiceRecords, invoices, type Party } from './schema.ts';
export { type AltaFields, type AnulacionFields, amountText, huella, huellaInput, madridTimestamp, qrUrl, spanishDate } from './verifactu.ts';

バージョン	コミット	公開日	スキャン
1.0.1	6912dca	4 時間前	スキャン合格

$genpm add @core/invoices

組み込み先: src/lib/invoices
コミット
タグ: v1.0.1
必要: @core/contracts ^1.0.0 @core/db ^1.0.0 @core/orders ^1.0.0
npm: zod ^4.0.0
Env: INVOICE_ISSUER_NIF INVOICE_ISSUER_NAME INVOICE_ISSUER_ADDRESS INVOICE_SERIES INVOICE_VAT_RATE INVOICE_RETAIL INVOICE_QR_ENV
品質: 100/100
インストール数: 0 / 30日
公開日: 4 時間前 · genpm-system

README バッジ

[![genpm](https://api.genpm.net/v1/badge/@core/invoices.svg)](https://genpm.net/p/@core/invoices)