This repository is the canonical source of truth for all business document payload formats exchanged over the FideX AS5 protocol. It defines, validates, and documents the JSON payload structure for each B2B document type in the Venezuelan pharmaceutical supply chain.
The FideX standard bridges enterprise B2B EDI (GS1/AS5) with Venezuelan fiscal requirements (SENIAT/SUDEBAN), enabling secure, traceable, and legally compliant document exchange between laboratories, distributors (droguerías), and pharmacies.
| Document | document_type enum |
doc_type / retention_type |
Venezuelan Name | Description |
|---|---|---|---|---|
| Customer Master | GS1_CUSTOMER_MASTER_JSON |
— | Ficha de Cliente | Pharmacy/distributor master data with SICM health permits |
| Product Catalog | GS1_CATALOG_JSON |
DELTA_UPDATE / FULL_SYNC |
Catálogo / Lista de Precios | SKUs, multi-tier pricing, real-time inventory |
| Purchase Order | GS1_ORDER_JSON |
PURCHASE_ORDER |
Orden de Compra | Buyer-initiated order request |
| Quote / Proposal | GS1_ORDER_JSON |
QUOTE |
Presupuesto | Vendor's priced response to a purchase order |
| Confirmed Order | GS1_ORDER_JSON |
ORDER_CONFIRMED |
Orden Confirmada | Buyer confirms the vendor's presupuesto |
| Despatch Advice | GS1_DESPATCH_ADVICE_JSON |
DESPATCH_ADVICE |
Nota de Entrega / ASN | Advance Ship Notice with SSCC lot tracking |
| Invoice | GS1_INVOICE_JSON |
INVOICE |
Factura | Fiscal document with SENIAT multi-currency compliance |
| Credit Note | GS1_INVOICE_JSON |
CREDIT_NOTE |
Nota de Crédito | Reduces a prior invoice (returns, price adjustments) |
| Debit Note | GS1_INVOICE_JSON |
DEBIT_NOTE |
Nota de Débito | Increases a prior invoice (missed charges, corrections) |
| IVA Retention | GS1_RETENTION_JSON |
RETENTION_IVA |
Comp. Retención IVA | 75% VAT withholding by Contribuyentes Especiales (Prov. 049/056) |
| ISLR Retention | GS1_RETENTION_JSON |
RETENTION_ISLR |
Comp. Retención ISLR | Income tax withholding per Decreto 1808 Tabla 26 |
fidex-document-specs/
├── README.md # This file
├── CHANGELOG.md # Version history
├── Makefile # Developer commands
├── package.json # ajv-cli + prettier
│
├── memory-bank/ # Project context (GOS standard)
│ ├── 01_PROJECT_CHARTER.md
│ ├── 02_ARCHITECTURE_PRINCIPLES.md
│ ├── 03_AGENTIC_WORKFLOW.md
│ ├── activeContext.md # Current version, focus, patterns (v1.4)
│ ├── progress.md # What works, what's left, known issues (v1.4)
│ └── techContext.md # Tech stack, constraints, CI/CD (v1.4)
│
├── docs/ # Narrative & conceptual documentation
│ ├── 01-overview.md # Architecture & design philosophy
│ ├── 02-routing-envelope.md # kontext_routing deep-dive
│ ├── 03-security-jose.md # JWS/JWE Sign-then-Encrypt
│ ├── 04-gs1-identifiers.md # GTIN, GLN, SSCC, SICM explained
│ ├── 05-venezuelan-fiscal.md # IVA, IGTF, SENIAT, BCV rates
│ ├── 06-document-lifecycle.md # Order→Quote→Confirm→Invoice flow
│ ├── 07-credit-debit-notes.md # v1.1 — CN/DN fiscal mechanics
│ ├── 08-tax-retention.md # v1.1 — IVA & ISLR retention
│ ├── 09-erp-mapping/ # v1.2 — ERP integration mapping
│ │ ├── 00-index.md # ERP comparison matrix & architecture
│ │ ├── 01-odoo-17-18.md # Odoo 17/18 JSON-RPC + REST mapping
│ │ ├── 02-profit.md # Profit Plus v12 SQL/COM SDK mapping
│ │ ├── 03-saint.md # Saint Enterprise v6+ REST mapping
│ │ ├── 04-galac.md # Galac Software v5+ fiscal mapping
│ │ └── 05-sap-business-one.md # SAP B1 Service Layer mapping
│ ├── 10-government-observer-node.md # v1.5 — Privacy-preserving SENIAT bridge
│ ├── 11-dlt-merkle-anchoring.md # v1.5 — Two-stage J-MDN + hourly Merkle rollup
│ ├── 12-jsonata-maps.md # v1.5 — JSONata transformation maps reference
│ └── es/ # 🇪🇸 Spanish documentation (v1.3/v1.4)
│ ├── 01-descripcion-general.md
│ ├── 02-sobre-de-enrutamiento.md
│ ├── 03-seguridad-jose.md
│ ├── 04-identificadores-gs1.md
│ ├── 05-fiscal-venezolano.md
│ ├── 06-ciclo-de-documentos.md
│ ├── 07-notas-credito-debito.md
│ ├── 08-retenciones-fiscales.md
│ └── 09-integracion-erp/ # All 5 ERPs translated
│
├── schemas/ # JSON Schema 2020-12 definitions
│ ├── _common/ # Reusable $ref components
│ │ ├── kontext-routing.schema.json
│ │ ├── party.schema.json
│ │ ├── address.schema.json
│ │ ├── product-identity.schema.json
│ │ ├── pharma-attributes.schema.json
│ │ ├── tax-line.schema.json
│ │ ├── fiscal-totals-ves.schema.json
│ │ ├── fiscal-control.schema.json
│ │ ├── related-documents.schema.json
│ │ └── retention-detail.schema.json # v1.1 — retention line item
│ ├── customer-master/
│ │ └── gs1-customer-master.schema.json
│ ├── catalog/
│ │ └── gs1-catalog.schema.json
│ ├── order/
│ │ └── gs1-order.schema.json
│ ├── despatch-advice/
│ │ └── gs1-despatch-advice.schema.json
│ ├── invoice/
│ │ └── gs1-invoice.schema.json # v1.1 — added CREDIT_NOTE/DEBIT_NOTE if/then
│ ├── retention/ # v1.1 NEW
│ │ └── gs1-retention.schema.json
│ └── jmdn/ # v1.6 NEW — J-MDN receipt schema
│ └── gs1-jmdn.schema.json
│
└── examples/ # Valid, runnable payload examples
├── customer-master/
│ └── 01-pharmacy-independent.json
├── catalog/
│ ├── 01-delta-update.json
│ └── 02-full-sync-baseline.json
├── order/
│ ├── 01-purchase-order.json
│ ├── 02-quote-presupuesto.json
│ └── 03-order-confirmed.json
├── despatch-advice/
│ └── 01-asn-standard.json
├── invoice/
│ ├── 01-invoice-standard.json
│ ├── 02-invoice-with-fiscal-control.json
│ ├── 03-credit-note.json # v1.1 NEW
│ └── 04-debit-note.json # v1.1 NEW
├── retention/ # v1.1 NEW
│ ├── 01-retention-iva.json
│ └── 02-retention-islr.json
├── jmdn/ # v1.6 NEW — J-MDN receipt examples
│ ├── 01-technical-receipt.json
│ └── 02-fiscal-receipt.json
└── _invalid/ # Negative test fixtures (must FAIL)
├── invoice/01-credit-note-no-related.json
├── invoice/02-empty-document-number.json # v1.6 NEW
├── order/01-order-confirmed-no-quote.json
├── retention/01-bad-period-format.json
├── despatch-advice/01-bad-sscc.json # v1.6 NEW
└── jmdn/01-fiscal-no-merkle.json # v1.6 NEW
# Install dependencies
npm install
# Validate everything (positive + negative tests)
make validate-all
# Validate only positive examples
make validate
# Validate a single example
make validate-one FILE=examples/invoice/01-invoice-standard.jsonRead docs/06-document-lifecycle.md to understand the full Venezuelan B2B order-to-cash flow and docs/07-credit-debit-notes.md / docs/08-tax-retention.md for the v1.1 fiscal correction documents:
Buyer Vendor (Laboratorio)
│ │
│── PURCHASE_ORDER ─────────────►│ "Orden de Compra"
│ │
│◄── QUOTE (Presupuesto) ────────│ Vendor prices the request
│ │
│── ORDER_CONFIRMED ────────────►│ Buyer accepts the quote
│ │
│◄── DESPATCH_ADVICE (ASN) ──────│ Goods are shipped
│ │
│◄── INVOICE (Factura) ──────────│ Fiscal document issued
│ │
│◄── CREDIT/DEBIT NOTE ──────────│ Post-invoice correction (v1.1)
│ │
│◄── RETENTION COMPROBANTE ──────│ Tax withholding receipt (v1.1)
│ │
-
Separation of Concerns — The
kontext_routingenvelope carries transport metadata;payloadcarries business logic. The AS5 Hub routes without parsing sensitive content. -
English Enums, Bilingual Docs — All machine-readable values are in English (
PENDING,SHIPPED,PURCHASE_ORDER). Documentation anddescriptionfields are bilingual (EN/ES). -
GS1 Compliance — Mandatory use of
gtin(Global Trade Item Number) andgln(Global Location Number) for pharmaceutical traceability and LATAM regulatory compliance. -
Venezuelan Fiscal Isolation — SENIAT-specific data (
fiscal_totals_ves,fiscal_control) is isolated in dedicated nested objects, keeping the core format internationally viable. -
Merkle Root State Sync — Catalog/inventory documents use
sync_statewithprevious_merkle_root/current_merkle_rootfor self-healing "Rsync-style" synchronization.
The docs/09-erp-mapping/ directory provides field-level mapping tables and API endpoint references for integrating all 6 FideX document types into each supported ERP:
| ERP | Vendor | Integration Layer | Guide |
|---|---|---|---|
| Odoo 17 / 18 | Odoo S.A. | JSON-RPC + REST (/web/dataset/call_kw, /api/) |
01-odoo-17-18.md |
| Profit Plus v12 | Softech C.A. (miprofit.com) | SQL Server direct + ProfitSDK.dll COM |
02-profit.md |
| Saint Enterprise v6+ | Business Technology (saintve.com) | REST API /api/v1/ |
03-saint.md |
| Galac Software v5+ | Galac Software C.A. | XML import + REST /api/v1/ (fiscal only) |
04-galac.md |
| SAP Business One 10.0 | SAP SE | Service Layer REST (https://{server}:50000/b1s/v1/) |
05-sap-business-one.md |
Start with the index guide for an ERP comparison matrix, integration architecture, and the Venezuelan fiscal field reference (RIF, SICM, BCV rate, IGTF, IVA/ISLR retention).
- FideX Protocol (AS5):
greicodex/fidex-protocol— Transport layer, JOSE security, J-MDN receipts - FideX Hub:
greicodex/fidex-hub— Kontext AS5 routing engine (Go) - FideX Odoo Plugin:
greicodex/fidex-odoo— AS5 mixin for Odoo ERP
MIT © Greicodex — Open standard for the Venezuelan pharmaceutical supply chain.