FatooraFi API Documentation

REST API for ZATCA-verified invoice scoring and credit assessment.

Quick Start

The FatooraFi API provides invoice scoring and portfolio analytics. All endpoints return JSON.

# Base URL
https://api.fatoorafi.com/api

# Example: Get portfolio summary
curl https://api.fatoorafi.com/api/portfolio/summary

# Example: Score an invoice
curl -X POST https://api.fatoorafi.com/api/invoices/INV-00001/score

Risk Bands

Band	Score Range	Suggested Action
A	0-15	Fast-Track
B	16-35	Fast-Track
C	36-55	Review
D	56-75	Decline
E	76-100	Decline

Scoring Factors

Factor	Weight	Description
ZATCA Clearance	High	Invoice cleared by ZATCA Phase 2
Buyer Payment History	High	Historical payment behavior of the buyer
Hash Verification	High	Cryptographic hash matches ZATCA records
Invoice Concentration	Medium	Single buyer exposure relative to portfolio
Invoice Size	Medium	Amount relative to seller monthly revenue
Days to Due	Low	Time remaining until payment due date
Duplicate Detection	Critical	Invoice not submitted elsewhere
Dispute Status	Critical	No active disputes on the invoice

API Endpoints

GET/api/health

Health check and scenario info

Response:

{
  "status": "ok",
  "timestamp": "2025-01-07T12:00:00Z",
  "mode": "demo",
  "scenario": "standard",
  "scenarioDescription": "Mixed invoice portfolio",
  "availableScenarios": ["standard", "high_risk", "low_risk"],
  "data": { "companies": 47, "counterparties": 312, "invoices": 1000 }
}

GET/api/invoices

List invoices with pagination

Parameters:

limit(number)- Results per page (default: 50)

offset(number)- Pagination offset (default: 0)

Response:

{
  "data": [
    {
      "id": "INV-00001",
      "companyId": "company-001",
      "counterpartyId": "buyer-001",
      "issueDate": "2025-01-01",
      "dueDate": "2025-02-15",
      "amountNet": 125000,
      "vatAmount": 18750,
      "currency": "SAR",
      "zatcaClearanceStatus": "cleared",
      "qrOk": true,
      "hashMismatch": false,
      "duplicateFlag": false,
      "disputeFlag": false,
      "score": { "band": "A", "score": 92, ... }
    }
  ],
  "pagination": { "total": 1000, "limit": 50, "offset": 0, "hasMore": true }
}

GET/api/invoices/:id

Get single invoice with full details

Response:

{
  "data": {
    "id": "INV-00001",
    "seller": {
      "id": "company-001",
      "name": "Al-Faisal Trading Co.",
      "crNumber": "CR-001",
      "sector": "Retail",
      "typicalMonthlyRevenue": 2500000
    },
    "buyer": {
      "id": "buyer-001",
      "name": "SABIC",
      "payBehaviourBand": "A"
    },
    "score": {
      "invoiceId": "INV-00001",
      "score": 92,
      "band": "A",
      "reasons": [
        { "code": "BUYER_HISTORY", "description": "Buyer payment history", "points": -10 },
        { "code": "ZATCA_VERIFIED", "description": "ZATCA verification status", "points": -15 }
      ],
      "buyerConcentrationIdx": 0.18,
      "modelVersion": "1.0.0",
      "scoredAt": "2025-01-07T12:00:00Z"
    },
    ...
  }
}

POST/api/invoices/:id/score

Score a single invoice

Response:

{
  "data": {
    "invoiceId": "INV-00001",
    "score": 92,
    "band": "A",
    "reasons": [...],
    "buyerConcentrationIdx": 0.18,
    "modelVersion": "1.0.0",
    "scoredAt": "2025-01-07T12:00:00Z"
  }
}

POST/api/invoices/score-all

Score all unscored invoices

Response:

{
  "data": {
    "scored": 150,
    "total": 1000
  }
}

GET/api/portfolio/summary

Portfolio analytics and band distribution

Response:

{
  "data": {
    "totalInvoices": 1000,
    "totalValue": 45750000,
    "totalValueFormatted": "SAR 45,750,000",
    "companies": 47,
    "counterparties": 312,
    "bandDistribution": { "A": 245, "B": 412, "C": 187, "D": 98, "E": 58 },
    "bandValues": { "A": 12500000, "B": 18200000, ... },
    "bySector": {
      "Construction": { "count": 287, "value": 15400000 },
      ...
    },
    "outcomes": {
      "paid_on_time": 672,
      "paid_late": 198,
      "disputed": 45,
      "pending": 67,
      "default": 18
    }
  }
}

GET/api/invoices/:id/credit-packet

Download PDF credit memo for an invoice

Response:

Binary PDF file

Integration Notes

Authentication

Production API uses API key authentication via the Authorization header. Demo mode does not require authentication.

Rate Limiting

API requests are limited to 1000 requests per minute per API key. Demo mode has a lower limit of 100 requests per minute.

Webhook Integration

Subscribe to real-time updates for invoice scoring events, integrity alerts, and portfolio changes. Contact us for webhook setup.

Questions? Contact us at hello@fatoorafi.com