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-credit-notes-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 Credit Notes 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: credit_notes
description: تصحيح فاتورة صادرة بالخصم.
paths:
/api/v1/credit_notes:
get:
operationId: listCreditNotes
tags:
- credit_notes
summary: List credit_notes
description: يرث الإشعار بيانات المشتري والعملة والضريبة من الأصل. نسبة البند المرتبط تطابق الأصل؛ لا يُقبل للبند غير المرتبط معدل غير موجود في الأصل. إجمالي صافي الإشعارات وضريبتها لا يتجاوز أصل كل نسبة ضريبية، داخل معاملة الإصدار. يتطلب Idempotency-Key؛ لا ينفّذ تحويلًا ماليًا أو إرسال بريد.
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, total, created_at'
schema:
type: string
- name: q[field_predicate]
in: query
description: 'Ransack-style filter. Filterable fields: number, status, buyer_name, issued_at, 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: createCreditNote
tags:
- credit_notes
summary: Create a credit_note
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: true
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:
originalInvoiceId:
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)$
reason:
type: string
minLength: 3
maxLength: 500
lines:
minItems: 1
maxItems: 50
type: array
items:
type: object
properties:
description:
type: string
minLength: 1
maxLength: 500
quantity:
type: number
exclusiveMinimum: 0
maximum: 1000000
unitPrice:
type: number
minimum: 0
maximum: 100000000
vatRate:
type: number
minimum: 0
maximum: 1
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)$
returnStock:
default: false
type: boolean
required:
- description
- quantity
- unitPrice
- vatRate
required:
- originalInvoiceId
- reason
- lines
additionalProperties: false
example:
originalInvoiceId: 11111111-1111-4111-8111-111111111111
reason: Partial return
lines:
- description: Returned service
quantity: 1
unitPrice: 10
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/credit_notes/{id}:
get:
operationId: getCreditNote
tags:
- credit_notes
summary: Fetch one credit_note
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'
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.