Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/fawtar-app:fawtar-app-invoices-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Fawtar Business Invoices API
x-capabilities: https://fawtar.app/.well-known/fawtar-capabilities.json
version: 1.0.0
description: 'Arabic-first invoicing, accounting, payroll and point of sale for Saudi businesses. Invoice QR fields do not establish full system compliance or Phase 2 integration. Filtering and sorting follow ransack conventions, and the API-KEY header is accepted alongside Authorization: Bearer, so a client written against Qoyod can be repointed here by changing the base URL and the key. Agent capabilities, sandbox onboarding and prepaid prices: https://fawtar.app/.well-known/fawtar-capabilities.json'
contact:
name: Fawtar
url: https://fawtar.app/docs/api
servers:
- url: https://fawtar.app
security:
- bearerAuth: []
tags:
- name: Invoices
description: إصدار الفواتير الضريبية وقراءتها.
paths:
/api/v1/invoices:
get:
operationId: listInvoices
tags:
- Invoices
summary: List invoices
description: الفاتورة الصادرة وثيقة نظامية ورمز QR محسوب من محتواها، فلا تُعدَّل — تُصحَّح بإشعار دائن عبر POST /credit_notes. الترقيم متسلسل بلا فجوات ويُخصَّص عند الإنشاء.
security:
- bearerAuth:
- invoices:read
- apiKeyHeader: []
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: q[s]
in: query
description: 'Sort, e.g. "number desc". Sortable: number, issued_at, due_date, total, created_at'
schema:
type: string
- name: q[field_predicate]
in: query
description: 'Ransack-style filter. Filterable fields: number, status, paid_status, type, tax_treatment, buyer_name, issued_at, due_date, total, created_at. Predicates: eq, not_eq, cont, start, end, gt, gteq, lt, lteq, in, null.'
schema:
type: string
responses:
'200':
description: A page of results
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
meta:
type: object
properties:
page:
type: integer
limit:
type: integer
total:
type: integer
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: خطأ غير متوقع من جانبنا.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: createInvoice
tags:
- Invoices
summary: Create a invoice
description: 'Use a stable Idempotency-Key (required for credit notes, recommended for legacy-compatible invoice/payment creation). First write: 201; exact replay: 200 with Idempotency-Replayed: true. Changed request: 409. Retry timeouts/503 with the SAME key and body. No email or customer delivery is performed.'
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
minLength: 1
maxLength: 128
pattern: ^[!-~]+$
security:
- bearerAuth:
- invoices:write
- apiKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
taxTreatment:
default: tax
type: string
enum:
- tax
- ordinary
type:
type: string
enum:
- simplified
- standard
pricesIncludeVat:
default: false
type: boolean
currency:
type: string
maxLength: 3
exchangeRate:
type: number
exclusiveMinimum: 0
maximum: 10000
buyer:
type: object
properties:
additionalNumber:
anyOf:
- type: string
pattern: ^\d{4}$
- type: string
const: ''
countrySubentity:
anyOf:
- type: string
maxLength: 120
- type: string
const: ''
name:
anyOf:
- type: string
maxLength: 120
- type: string
const: ''
vatNumber:
anyOf:
- type: string
pattern: ^3\d{13}3$
- type: string
const: ''
address:
anyOf:
- type: string
maxLength: 200
- type: string
const: ''
crNumber:
anyOf:
- type: string
maxLength: 30
- type: string
const: ''
street:
anyOf:
- type: string
maxLength: 120
- type: string
const: ''
building:
anyOf:
- type: string
maxLength: 20
- type: string
const: ''
district:
anyOf:
- type: string
maxLength: 120
- type: string
const: ''
city:
anyOf:
- type: string
maxLength: 120
- type: string
const: ''
postalCode:
anyOf:
- type: string
maxLength: 20
- type: string
const: ''
phone:
type: string
maxLength: 30
email:
type: string
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
lines:
minItems: 1
maxItems: 50
type: array
items:
type: object
properties:
accountingClass:
type: string
enum:
- own_fee
- third_party
thirdPartyKind:
type: string
enum:
- workshop
- parts
- towing
- other
payeeName:
type: string
maxLength: 160
taxCategory:
type: string
enum:
- S
- Z
- E
- O
taxExemptionReasonCode:
type: string
maxLength: 40
taxExemptionReason:
type: string
maxLength: 200
originalItemId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
productId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
inventoryId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description:
type: string
minLength: 1
maxLength: 200
quantity:
type: number
exclusiveMinimum: 0
maximum: 1000000
unitPrice:
type: number
minimum: 0
maximum: 100000000
vatRate:
type: number
unit:
anyOf:
- type: string
maxLength: 20
- type: string
const: ''
discountKind:
type: string
enum:
- percent
- amount
discountValue:
default: 0
type: number
minimum: 0
maximum: 100000000
required:
- description
- quantity
- unitPrice
- vatRate
documentDiscountKind:
type: string
enum:
- percent
- amount
documentDiscountValue:
default: 0
type: number
minimum: 0
maximum: 100000000
notes:
anyOf:
- type: string
maxLength: 500
- type: string
const: ''
paymentInstructions:
type: string
maxLength: 600
clientId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
bilingual:
type: boolean
dueDate:
type: string
format: date
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
supplyDate:
type: string
format: date
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
purchaseOrderNumber:
type: string
maxLength: 80
contractReference:
type: string
maxLength: 120
required:
- type
- lines
example:
taxTreatment: tax
type: simplified
buyer:
name: Example buyer
lines:
- description: Service
quantity: 1
unitPrice: 100
vatRate: 0.15
responses:
'200':
description: Exact idempotent replay
headers:
X-Fawtar-Credits-Remaining:
description: Remaining write credits for agent/sandbox keys; subscription keys are not metered.
schema:
type: integer
minimum: 0
'201':
description: Created
content:
application/json:
schema:
type: object
additionalProperties: true
headers:
X-Fawtar-Credits-Remaining:
description: Remaining write credits for agent/sandbox keys; subscription keys are not metered.
schema:
type: integer
minimum: 0
'400':
description: يتطلب إنشاء الإشعار الدائن Idempotency-Key ثابتًا؛ المفتاح المُرسل يجب أن يكون صالحًا في كل عمليات الإنشاء المالية.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Prepaid balance exhausted. Authenticate to POST top_up_url to receive a hosted checkout link.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- error
- code
- balance
- required_credits
- top_up_url
- top_up_method
- pack
properties:
error:
const: payment_required
code:
const: insufficient_credits
balance:
type: integer
minimum: 0
required_credits:
type: integer
minimum: 1
top_up_url:
type: string
format: uri
top_up_method:
const: POST
pack:
type: object
additionalProperties: false
required:
- currency
- price_minor
- credits
- minimum_top_up_minor
properties:
currency:
const: SAR
price_minor:
const: 9900
credits:
const: 1000
minimum_top_up_minor:
const: 9900
example:
error: payment_required
code: insufficient_credits
balance: 0
required_credits: 1
top_up_url: https://fawtar.app/api/v1/credits/top-up
top_up_method: POST
pack:
currency: SAR
price_minor: 9900
credits: 1000
minimum_top_up_minor: 9900
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: استُخدم المفتاح نفسه مع جسم طلب مختلف؛ لا تعِد تنفيذ الحدث بمفتاح جديد.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: فشل التحقق. التفاصيل في details لكل حقل.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: النتيجة غير مؤكدة. أعد الجسم نفسه بالمفتاح نفسه حتى تحصل على المعرّف.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/invoices/{id}:
get:
operationId: getInvoice
tags:
- Invoices
summary: Fetch one invoice
security:
- bearerAuth:
- invoices:read
- apiKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: The record
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/v1/invoices/{id}/pdf:
get:
operationId: downloadInvoicePdf
tags:
- Invoices
summary: Download an issued invoice or credit-note PDF
description: Explicit caller action; does not send the document. Standard Phase 2 documents require clearance first.
security:
- bearerAuth:
- invoices:read
- apiKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: 'PDF, Cache-Control: no-store'
content:
application/pdf:
schema:
type: string
format: binary
'401':
description: المفتاح مفقود أو ملغى أو منتهٍ أو لا يحمل الصلاحية المطلوبة.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: لا يوجد سجل بهذا المعرّف ضمن منشأتك.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: استُخدم المفتاح نفسه مع جسم طلب مختلف؛ لا تعِد تنفيذ الحدث بمفتاح جديد.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: تجاوزت الحد. أعد المحاولة بعد المدة في ترويسة Retry-After.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: النتيجة غير مؤكدة. أعد الجسم نفسه بالمفتاح نفسه حتى تحصل على المعرّف.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
error:
type: string
enum:
- idempotency_key_required
- idempotency_conflict
- document_not_ready
- write_outcome_unknown
- document_render_failed
- invalid_json
- unauthorized
- not_found
- method_not_allowed
- delete_refused
- validation_failed
- rate_limited
- query_failed
message:
type: string
details:
type: object
additionalProperties:
type: array
items:
type: string
required:
- error
securitySchemes:
supabaseSession:
type: http
scheme: bearer
description: Provider-verified Supabase access token, for onboarding claims only.
bearerAuth:
type: http
scheme: bearer
description: 'Authorization: Bearer fwt_live_… or fwt_test_…'
apiKeyHeader:
type: apiKey
in: header
name: API-KEY
description: Qoyod-compatible header carrying the same key.