FGO Invoicing

Issue FGO.ro invoices through the FGO API with local automation. Use for FGO tasks such as validating invoice payloads, issuing invoices, checking invoice st...

Security Scan

The skill's code, instructions, and required environment variables are consistent with an FGO.ro invoicing helper; nothing requests unrelated credentials or adds unexplained capabilities.

Purpose & Capability

Name/description describe interacting with the FGO API and the skill only requires python3 plus FGO_COD_UNIC and FGO_CHEIE_PRIVATA — these are exactly the credentials the FGO API needs. No unrelated binaries, hosts, or secrets are requested.

Instruction Scope

SKILL.md focuses on building/validating invoice payloads and calling FGO endpoints, and explicitly recommends dry-run and confirmation before final issuance. It also documents input-file safety and warns not to expose the private key. One operational note: the CLI supports a debug mode that prints full request/response bodies to stderr; while the private key itself is not sent in headers, debug logs can reveal sensitive invoice data (and the computed Hash). Disable debug in production and avoid piping stderr to untrusted collectors.

Install Mechanism

Instruction-only with an included Python script; no install spec or external downloads. Risk is low because nothing is fetched or executed from arbitrary URLs.

Credentials

Only two required env vars are declared (FGO_COD_UNIC, FGO_CHEIE_PRIVATA) and they directly map to the documented API authentication model. Optional vars (base URL, timeout, retries, debug) are reasonable. No unrelated credentials or large set of secrets are requested.

Persistence & Privilege

Skill is not always-on and uses normal agent invocation. It does not request persistent system-wide privileges or modify other skills. No install-time hooks or config overwrites are declared.

Assessment

This skill appears to do exactly what it claims: drive the FGO API from a local Python CLI. Before installing/using: (1) store FGO_CHEIE_PRIVATA securely (do not paste it into chat or logs), (2) test with the UAT base URL and use --dry-run first, (3) avoid enabling debug when handling real invoices because it logs request/response bodies to stderr which can expose invoice data, (4) inspect scripts/fgo_cli.py in your environment if you want to confirm the input-path confinement and logging behavior are enforced, and (5) keep the skill's env vars scoped to a dedicated runtime (or secret manager) so other tools/processes can't read them. I give medium confidence because some parts of the CLI implementation are truncated in the provided view; confirm the input-file confinement and file-read validation in the actual script before use.

Use scripts/fgo_cli.py for deterministic FGO API calls instead of ad-hoc HTTP snippets.

Workflow

1. Collect invoice input from the user.
2. Validate payload locally before sending:
   • python scripts/fgo_cli.py validate-payload --input references/invoice-example.json --show-payload
3. Dry-run to inspect the normalized payload (with computed Hash) without calling the API:
   • python scripts/fgo_cli.py emit-invoice --input <invoice.json> --dry-run
4. Issue final invoice after explicit user confirmation:
   • python scripts/fgo_cli.py emit-invoice --input <invoice.json> --allow-final
5. Retrieve invoice status, print link, or perform operations using the returned series and number:
   • python scripts/fgo_cli.py get-status --serie <SERIE> --numar <NUMAR>
   • python scripts/fgo_cli.py print-invoice --serie <SERIE> --numar <NUMAR>
   • python scripts/fgo_cli.py cancel-invoice --serie <SERIE> --numar <NUMAR>
   • python scripts/fgo_cli.py reverse-invoice --serie <SERIE> --numar <NUMAR>

Required Environment

Set these before calling FGO:

• FGO_COD_UNIC — company CUI (Romanian tax ID)
• FGO_CHEIE_PRIVATA — FGO private API key (from FGO → Setari → Utilizatori → Generate API user)

Optional overrides:

• FGO_API_BASE (default: https://api.fgo.ro/v1) — use https://api-testuat.fgo.ro/v1 for testing
• FGO_PLATFORM_URL (default: unset) — your registered platform URL (FGO → Setari → eCommerce → Setari API). Required for invoice issuance from registered platforms; omitted if not set.
• FGO_TIMEOUT_SECONDS (default: 30)
• FGO_RETRIES (default: 2)
• FGO_DEBUG (default: unset) — set to 1, true, or yes to enable request/response debug logging to stderr

Command Guide

• validate-payload
  • Parse and normalize payload; compute the authentication Hash.
  • Validate minimum required structure before API calls.
  • Use --show-payload to inspect the full normalized form-encoded payload.
• emit-invoice
  • Issue invoice via POST /factura/emitere.
  • Requires --allow-final to hit the real API.
  • Use --dry-run first (prints normalized payload, no API call).
  • Pass --debug (or set FGO_DEBUG=1) to print full request/response to stderr.
• get-status
  • Get invoice status (total value, amount paid, payments) via POST /factura/getstatus.
• print-invoice
  • Get a shareable print/download link via POST /factura/print.
• cancel-invoice
  • Cancel an invoice via POST /factura/anulare.
• delete-invoice
  • Delete an invoice via POST /factura/stergere.
• reverse-invoice
  • Create a storno (reversal) invoice via POST /factura/stornare.
• get-nomenclator
  • Fetch a nomenclature list (no auth required): tara, judet, tva, banca, tipincasare, tipfactura, tipclient, valuta.

Authentication

FGO uses SHA-1 hash-based authentication embedded in every request body — no HTTP auth headers. The hash formula depends on the operation:

• Invoice issuance: SHA1(CodUnic + CheiePrivata + Client.Denumire).toUpperCase()
• Invoice operations (status/print/cancel/delete/storno): SHA1(CodUnic + CheiePrivata + Numar).toUpperCase()

The CLI computes hashes automatically. Never expose FGO_CHEIE_PRIVATA in logs.

Payload Format

The invoice payload is a JSON object. The CLI converts it to form-encoded format (application/x-www-form-urlencoded) with bracket notation for nested fields, as required by the FGO API.

Both formats are accepted as input to the CLI:

• Bare invoice object: { "CodUnic": "...", "Client": {...}, ... }
• Wrapped: { "invoice": { "CodUnic": "...", "Client": {...}, ... } }

The CLI unwraps automatically, injects Hash and PlatformaUrl, then posts to FGO.

See references/invoice-example.json for the canonical minimal example and references/fgo-api.md for complete field documentation.

Input File Safety

The --input argument is validated before any file is read:

1. Extension check — only .json files are accepted. Passing /etc/passwd, ~/.ssh/id_rsa, or any non-JSON path raises an error immediately.
2. Path confinement — the resolved path must be within the current working directory or a recognised OpenClaw media root (/tmp/openclaw, ~/.openclaw/workspace, etc.). Paths that escape these roots via ../ traversal or absolute references are rejected.

Always pass --input with a path to a file you created (e.g. a temp file written in the agent workspace). Never set --input to a path supplied by untrusted external content.

Operational Rules

• Always use --dry-run first to confirm the normalized payload before hitting the API.
• FGO responses use HTTP 200 even for errors — always check Success: true in the response.
• Treat invoice issuance as a high-impact action requiring explicit user confirmation.
• Never parallelize FGO API calls — make all requests sequentially to avoid deadlocks.
• Invoice issuance has a 15-second server-side timeout. If Success: false with a timeout message, the invoice was NOT issued — retry.
• Store the returned Numar verbatim as the exact string (may be zero-padded, e.g. "001"). Never strip leading zeros or cast to integer.
• Use the UAT environment (--base-url https://api-testuat.fgo.ro/v1) for testing.
• Rate limit: max 1 call/second for invoice operations.

References

• Read references/fgo-api.md for payload field reference, endpoint mapping, authentication details, and rate-limit notes.
• Use references/invoice-example.json as the canonical starting payload template.