feat(skills): add domain skills for Openapi services with auth, company, documents, risk, trust, geo, messaging, esignature, invoicing, automotive and utilities

francescobianco · francescobianco · commit a6e7f3f9123a · 2026-06-10T10:01:04.000+02:00
diff --git a/README.md b/README.md
@@ -1 +1,30 @@
-# openapi-skiils
+ # openapi-skills
+
+Agent skills for using and integrating the services of the [Openapi](https://openapi.com) API marketplace — the largest certified API marketplace in Europe.
+
+## Repository layout
+
+| Folder | Purpose |
+|---|---|
+| [`knowledge/`](knowledge/) | Curated knowledge base: company profile, services catalog, platform guide (auth, billing, sandbox), FAQ, references, per-service endpoint docs and vendored OpenAPI specs |
+| [`skills/`](skills/) | The agent skills, one folder per domain, each with a `SKILL.md` |
+
+## Skills
+
+| Skill | Covers |
+|---|---|
+| [openapi-auth](skills/openapi-auth/SKILL.md) | OAuth v2 token lifecycle, scopes, wallet, usage stats (required by all others) |
+| [openapi-company](skills/openapi-company/SKILL.md) | Company data: Italy, EU, worldwide |
+| [openapi-documents](skills/openapi-documents/SKILL.md) | Official documents: visure camerali, balance sheets, DURC, protests (DocuEngine, Visure Camerali, Visengine) |
+| [openapi-risk](skills/openapi-risk/SKILL.md) | Credit scores, CRIF reports, KYC, negative events |
+| [openapi-trust](skills/openapi-trust/SKILL.md) | Validation of emails, phones, IPs, URLs, PEC, fiscal codes, plates |
+| [openapi-geo](skills/openapi-geo/SKILL.md) | Geocoding, zip codes, Italian cadastre, real estate valuations |
+| [openapi-messaging](skills/openapi-messaging/SKILL.md) | SMS v2, PEC, Massive REM, postal mail via Poste Italiane |
+| [openapi-esignature](skills/openapi-esignature/SKILL.md) | eIDAS e-signatures and qualified time stamping |
+| [openapi-invoicing](skills/openapi-invoicing/SKILL.md) | Electronic invoicing (Invoice, SDI) and bill payments |
+| [openapi-automotive](skills/openapi-automotive/SKILL.md) | Vehicle data by license plate |
+| [openapi-utilities](skills/openapi-utilities/SKILL.md) | Exchange rates, HTML-to-PDF, .it domains, managed RAG |
+
+## Credentials
+
+Skills expect `OPENAPI_EMAIL` and `OPENAPI_API_KEY` (account credentials for `oauth.openapi.com`) and/or a ready-made `OPENAPI_TOKEN` Bearer token in the environment. See [knowledge/platform-guide.md](knowledge/platform-guide.md).
diff --git a/skills/openapi-auth/SKILL.md b/skills/openapi-auth/SKILL.md
@@ -0,0 +1,47 @@
+---
+name: openapi-auth
+description: Authenticate with the Openapi marketplace (oauth.openapi.com). Use when you need to create, inspect, renew or delete Bearer tokens, list available scopes, check wallet credit, subscriptions, or API usage stats. Required by every other openapi-* skill.
+---
+
+# Openapi authentication (OAuth v2)
+
+All Openapi services require a Bearer token created through OAuth v2. This skill manages that token lifecycle.
+
+## Credentials
+
+Two layers — never confuse them:
+
+1. **Account credentials** (email + API key) → used only against `https://oauth.openapi.com`, as HTTP Basic auth (`username = email`, `password = API key`).
+2. **Bearer token** (created here, with scopes) → used against every service API as `Authorization: Bearer <token>`.
+
+Expect credentials in the environment as `OPENAPI_EMAIL`, `OPENAPI_API_KEY` (and optionally a ready-made `OPENAPI_TOKEN`). Never print or commit them.
+
+## Create a token
+
+```bash
+curl -s -u "$OPENAPI_EMAIL:$OPENAPI_API_KEY" https://oauth.openapi.com/tokens \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "scopes": ["GET:company.openapi.com/IT-start"],
+    "name": "agent token",
+    "ttl": 86400
+  }'
+```
+
+- Scope format: `METHOD:host/path-prefix` (e.g. `POST:sms.openapi.com/messages`). Request only the scopes the task needs, with a short `ttl`.
+- Discover valid scopes: `GET https://oauth.openapi.com/scopes` (Basic auth).
+- A refresh token can renew an expired token: `PATCH /tokens/{id}` with the refresh token as Bearer.
+
+## Useful management endpoints (Basic auth)
+
+- `GET /tokens`, `GET|PATCH|DELETE /tokens/{token}` — token lifecycle
+- `GET /wallet`, `GET /wallet/transactions` — credit balance (check before expensive paid calls)
+- `GET /subscriptions` — active plans and remaining requests
+- `GET /stats`, `GET /stats/apis/{domain}` — usage analytics
+- `GET /errors`, `GET /callbacks` — error log and callback monitoring
+
+## Notes
+
+- OAuth v1 (`oauth.openapi.it`) is deprecated — always use `oauth.openapi.com`.
+- Sandbox testing requires enabling "sandbox credit" in the console first; see [platform guide](../../knowledge/platform-guide.md).
+- Full spec: [knowledge/oas/oauthv2.openapi.json](../../knowledge/oas/oauthv2.openapi.json) · endpoint list: [knowledge/services/oauthv2.md](../../knowledge/services/oauthv2.md)
diff --git a/skills/openapi-automotive/SKILL.md b/skills/openapi-automotive/SKILL.md
@@ -0,0 +1,24 @@
+---
+name: openapi-automotive
+description: Vehicle data through Openapi Automotive - look up cars, motorcycles and insurance status by license plate (Italian and European). Use for "whose car is this plate", vehicle technical data, insurance validity checks.
+---
+
+# Openapi Automotive
+
+Base URL: `https://automotive.openapi.com` — vehicle information by license plate, sourced from the Ministry of Transport (European basis).
+
+Authentication: Bearer token — see the `openapi-auth` skill.
+
+## Endpoints (14 — see reference for the full list)
+
+- Cars: vehicle technical data by plate
+- Motorcycles: same for two-wheelers
+- Insurance: check insurance coverage status of a plate
+
+## Sandbox
+
+A dedicated sandbox simulates requests with test plates — use it to validate integrations before paying for real lookups.
+
+## References
+
+Full spec: [knowledge/oas/automotive.openapi.json](../../knowledge/oas/automotive.openapi.json) · endpoint list: [knowledge/services/automotive.md](../../knowledge/services/automotive.md)
diff --git a/skills/openapi-company/SKILL.md b/skills/openapi-company/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: openapi-company
+description: Look up company/business data through Openapi - Italian companies by VAT/tax code or name, European and worldwide company search, legal forms, company credit scores. Use for questions like "find data about company X", "who owns VAT number Y", "search companies in France/EU/worldwide".
+---
+
+# Openapi Company data
+
+Base URL: `https://company.openapi.com` — company master data from official registers (Chamber of Commerce, CRIF, INPS and more).
+
+Authentication: Bearer token with `company.openapi.com` scopes — see the `openapi-auth` skill.
+
+## Choosing the right endpoint
+
+| Need | Endpoint |
+|---|---|
+| Quick Italian company lookup (cheap) | `GET /IT-start/{vat_or_taxcode}` |
+| Full Italian company report | `GET /IT-full/{vat_or_taxcode}` |
+| Advanced Italian data (async) | `GET /IT-advanced/{id}` after starting a request |
+| Search Italian companies by name/filters | `GET /IT-search` |
+| Italian legal forms list | `GET /IT-legalforms` |
+| French companies | `GET /FR-search` |
+| Other EU countries (async start/advanced) | `EU-start` → `EU-advanced` |
+| Worldwide (async) | `WW-start` → `WW-advanced`; quick top-level: `WW-top` |
+| Credit score (top-level) | see `risk` service (`openapi-risk` skill) |
+
+The async pattern (start → poll advanced with the returned `id`, or pass a `callback` URL) is described in the [platform guide](../../knowledge/platform-guide.md#async-request-pattern).
+
+## Example
+
+```bash
+curl -s https://company.openapi.com/IT-start/12485671007 \
+  -H "Authorization: Bearer $OPENAPI_TOKEN"
+```
+
+## Notes
+
+- The legacy `imprese.openapi.it` API offers similar Italian lookups; prefer `company.openapi.com`. Sandbox test VAT numbers: https://docs.openapi.it/imprese-sandbox-examples.html
+- Full spec: [knowledge/oas/company.openapi.json](../../knowledge/oas/company.openapi.json) · endpoints: [knowledge/services/company.md](../../knowledge/services/company.md) · legacy: [knowledge/services/imprese.md](../../knowledge/services/imprese.md)
diff --git a/skills/openapi-documents/SKILL.md b/skills/openapi-documents/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: openapi-documents
+description: Obtain official Italian documents through Openapi - chamber of commerce reports (visure camerali), financial statements/balance sheets, company files (fascicoli), bylaws, DURC, protest reports, cadastral documents. Use when the user needs an official PDF document about an Italian company or person.
+---
+
+# Openapi official documents
+
+Three services deliver official documents; all are **asynchronous** (request → poll → download PDF).
+
+| Service | Base URL | Use for |
+|---|---|---|
+| DocuEngine (preferred) | `https://docuengine.openapi.com` | All documents: Business Register, Revenue Agency, Municipalities, INPS (DURC), protests, balance sheets |
+| Visure Camerali | `https://visurecamerali.openapi.it` | Chamber of commerce registrations and financial statements |
+| Visengine (legacy) | `https://visengine2.altravia.com` | Older engine for the same document families |
+
+Authentication: Bearer token — see the `openapi-auth` skill.
+
+## DocuEngine workflow
+
+1. `GET /services` — discover available document types and prices.
+2. `POST /documents` with the service code and subject (VAT/tax code) — returns a request `id`. Optionally pass a `callback` URL.
+3. `GET /documents/{id}` — poll status until the document is ready.
+4. Download the PDF from the returned URL/payload.
+
+Document families include: visura camerale (ordinaria/storica, by company type), fascicolo (company file, current/historical), bilancio (XBRL, ottico, riclassificato), statuto (bylaws), certificato di iscrizione, DURC online, protesti and pregiudizievoli (companies and persons), cariche/quote/soci (offices, shares, shareholders), eventi negativi.
+
+## Notes
+
+- These calls are **paid per document** — check wallet credit first (`openapi-auth`) and confirm with the user before bulk requests.
+- Sandbox responses are illustrative; enable sandbox credit first.
+- Specs: [docuengine](../../knowledge/oas/docuengine.openapi.json) · [visurecamerali](../../knowledge/oas/visurecamerali.openapi.json) · [visengine](../../knowledge/oas/visengine.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
diff --git a/skills/openapi-esignature/SKILL.md b/skills/openapi-esignature/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: openapi-esignature
+description: Digital signatures and time stamps through Openapi - eIDAS-compliant electronic signature workflows (eSignature) and qualified time stamping of documents (Marche Temporali). Use when the user needs a document signed electronically or time-stamped with legal validity.
+---
+
+# Openapi eSignature & time stamping
+
+Bearer token required (see the `openapi-auth` skill). Signing and stamping are paid, legally binding actions — confirm with the user before submitting documents.
+
+| Service | Base URL | Use for |
+|---|---|---|
+| eSignature | `https://esignature.openapi.com` | eIDAS-compliant signature processes (simple to qualified), signer invitations, signed-document retrieval |
+| Time Stamping | `https://ws.marchetemporali.com` | Purchase qualified timestamps and apply them to documents |
+
+## eSignature workflow (typical)
+
+1. Create a signature process/envelope with the document (PDF) and signer details.
+2. Signers receive an invitation and sign according to the configured signature level.
+3. Track process status (webhooks/polling) and download the signed document when complete.
+
+Legacy **Digital Signature** (`ws.firmadigitale.com` — Infocert/Aruba kits, digital identities) is **deprecated**; use eSignature for new integrations.
+
+## References
+
+Specs: [esignature](../../knowledge/oas/esignature.openapi.json) · [marchetemporali](../../knowledge/oas/marchetemporali.openapi.json) · legacy [firmadigitale](../../knowledge/oas/firmadigitale.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
diff --git a/skills/openapi-geo/SKILL.md b/skills/openapi-geo/SKILL.md
@@ -0,0 +1,26 @@
+---
+name: openapi-geo
+description: Italian geographic and property data through Openapi - geocoding/reverse geocoding, zip codes (CAP), municipalities/provinces/regions with ISTAT codes, Italian cadastre (catasto) property and owner lookups, real estate valuations and comparables.
+---
+
+# Openapi geo & real estate data
+
+Four services; all use a Bearer token (see the `openapi-auth` skill).
+
+| Service | Base URL | Use for |
+|---|---|---|
+| Geocoding | `https://geocoding.openapi.it` | Address → coordinates (`/geocode`) and coordinates → address (`/reverse`) |
+| Zip Codes (CAP) | `https://cap.openapi.it` | Italian municipalities, zip codes, provinces, regions, metropolitan cities, ISTAT codes, suppressed municipalities |
+| Catasto | `https://catasto.openapi.it` | Italian cadastre: cadastral data of buildings/land and their registered holders (by property or by subject) |
+| Real Estate | `https://realestate.openapi.com` | Property valuations and comparables by type, location, contract type |
+
+## Typical lookups
+
+- Zip → municipalities: `GET /comuni?cap=...` style search; municipality ↔ ISTAT code lookups; full lists of regions/provinces.
+- Cadastre queries are official paid lookups, several async — confirm before running many of them; subject searches return personal data (GDPR care).
+- Real estate valuation: query `/valuation` with property type, location and contract type.
+
+## Notes
+
+- CAP sandbox has a limited dataset; some parameters return fixed data.
+- Specs: [geocoding](../../knowledge/oas/geocoding.openapi.json) · [cap](../../knowledge/oas/cap.openapi.json) · [catasto](../../knowledge/oas/catasto.openapi.json) · [realestate](../../knowledge/oas/realestate.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
diff --git a/skills/openapi-invoicing/SKILL.md b/skills/openapi-invoicing/SKILL.md
@@ -0,0 +1,24 @@
+---
+name: openapi-invoicing
+description: Italian electronic invoicing and payments through Openapi - send/receive electronic invoices via SDI (Sistema di Interscambio), digital receipts, legal storage, and bill payments (MAV, RAV, PagoPA, car tax). Use for fatturazione elettronica and bill payment tasks.
+---
+
+# Openapi invoicing & payments
+
+Bearer token required (see the `openapi-auth` skill). Sending invoices to the Revenue Agency and paying bills are **irreversible fiscal/financial actions — always confirm with the user first**.
+
+| Service | Base URL | Use for |
+|---|---|---|
+| Invoice (preferred) | `https://invoice.openapi.com` | Active/passive electronic invoices, digital receipts, SDI transmission, digital signature, legal storage |
+| SDI | `https://sdi.openapi.it` | Lower-level interaction with the Sistema di Interscambio |
+| Paying Bills | `https://ws.pagasubito.it` | Pay bollettini, MAV, RAV, PagoPA, car tax (bollo auto) |
+
+## Key facts
+
+- **Receiving supplier invoices** requires registering Openapi's Recipient Code (Codice Destinatario) on the Revenue Agency website — the SDI spec description contains the step-by-step guide.
+- Invoices are FatturaPA XML; the Invoice API handles signing, transmission and status monitoring (delivery receipts, rejections) and can forward to legal storage (`api_configuration`).
+- Status updates can be pushed to a `callback` URL.
+
+## References
+
+Specs: [invoice](../../knowledge/oas/invoice.openapi.json) · [sdi](../../knowledge/oas/sdi.openapi.json) · [bollettini](../../knowledge/oas/bollettini.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
diff --git a/skills/openapi-messaging/SKILL.md b/skills/openapi-messaging/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: openapi-messaging
+description: Send communications through Openapi - SMS with custom sender (SMS v2), Italian certified e-mail (PEC/Legalmail), bulk certified mail (Massive REM), and physical mail via Poste Italiane (registered letters, telegrams, priority mail). Use when the user wants to send a message, letter or certified communication.
+---
+
+# Openapi messaging & communications
+
+All services use a Bearer token (see the `openapi-auth` skill). **Every send is an outward-facing, paid action: always confirm recipient, content and cost with the user before sending.**
+
+| Service | Base URL | Use for |
+|---|---|---|
+| SMS v2 | `https://sms.openapi.com` | SMS with custom sender, delivery reports; IT/ES dedicated endpoints + worldwide |
+| PEC | `https://pec.openapi.it` | Activate and manage Legalmail certified e-mail boxes |
+| Massive REM | `https://ws.pecmassiva.com` | Bulk certified e-mail with delivery/receipt verification |
+| Postal Service | `https://ws.ufficiopostale.com` | Raccomandate, telegrams, priority mail via Poste Italiane |
+
+## SMS v2
+
+```bash
+curl -s -X POST https://sms.openapi.com/messages \
+  -H "Authorization: Bearer $OPENAPI_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"sender": "MyBrand", "body": "Hello!", "recipients": ["+39333…"]}'
+```
+
+SMS v1 (`ws.messaggisms.com`) is **deprecated** — use SMS v2.
+
+## Postal Service workflow
+
+1. `POST` a new mail item (recipient, document).
+2. Check the returned prices and confirm with a `PATCH` (or pass `autoconfirm: true`).
+3. Receive status updates via the `callback` URL you provide.
+
+## References
+
+Specs: [smsv2](../../knowledge/oas/smsv2.openapi.json) · [pec](../../knowledge/oas/pec.openapi.json) · [pecmassiva](../../knowledge/oas/pecmassiva.openapi.json) · [ufficiopostale](../../knowledge/oas/ufficiopostale.openapi.json) — endpoint lists in [knowledge/services/](../../knowledge/services/).
diff --git a/skills/openapi-risk/SKILL.md b/skills/openapi-risk/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: openapi-risk
+description: Assess the reliability of Italian/worldwide companies and individuals through Openapi Risk - credit scores, CRIF reports, KYC checks, negative events, protests, personal/economic data. Use for due diligence, creditworthiness, AML/KYC questions.
+---
+
+# Openapi Risk
+
+Base URL: `https://risk.openapi.com` — reports and scores on natural and legal persons, sourced from CRIF, the Protest Register and other official registers.
+
+Authentication: Bearer token — see the `openapi-auth` skill.
+
+## Main capabilities (56 endpoints — see reference for the full list)
+
+- **Credit score**: `GET /IT-creditscore-top/{vat_or_taxcode}` for a quick Italian company score; deeper CRIF-based reports via async endpoints.
+- **KYC**: `POST /WW-kyc-full` for worldwide know-your-customer checks.
+- **Negative events**: protests, prejudicial acts, bankruptcies on companies and individuals.
+- **Person data**: personal data, phones, economic indicators of natural/legal persons.
+
+Most heavy reports follow the async pattern (start → poll with `id` or `callback`) described in the [platform guide](../../knowledge/platform-guide.md#async-request-pattern).
+
+## Compliance
+
+- Several Risk services fall under the Italian **TULPS** regulation: the account must have completed identity-document verification in the console before activation ([FAQ](../../knowledge/faq.md)).
+- Reports are paid per request and can be expensive — check wallet credit and confirm with the user before launching them.
+- Personal data returned is subject to GDPR: use it only for the stated, legitimate purpose; do not store it in the repo.
+
+## References
+
+Full spec: [knowledge/oas/risk.openapi.json](../../knowledge/oas/risk.openapi.json) · endpoint list: [knowledge/services/risk.md](../../knowledge/services/risk.md)
diff --git a/skills/openapi-trust/SKILL.md b/skills/openapi-trust/SKILL.md
diff --git a/skills/openapi-utilities/SKILL.md b/skills/openapi-utilities/SKILL.md
