This project provides a Flask-based REST API to interact with an Odoo instance for company management and ZATCA E-Invoicing onboarding.
Some endpoints require an API key for authentication. The API key must be provided in the X-API-KEY header of your request.
Header: API-KEY: YOUR_API_KEY
If the API key is missing or invalid, the API will return a 401 Unauthorized response.
Endpoint: POST /create_company
Description: Creates a new company in Odoo. Automatically sets the country to Saudi Arabia.
Request Body:
{
"Name": "Company Name",
"Phone": "050XXXXXXX",
"CR": "1234567890",
"VAT": "300000000000003",
"Street": "Main St",
"Street2": "Building 1",
"City": "Riyadh",
"Zip": "12345",
"Building_Number": "1234",
"Plot_Identification": "5678",
"Mobile": "0501234567",
"Email": "company@example.com"
}
Success Response:
{
"response": "success",
"Company_ID": 123
}
Endpoint: GET /get_company/<info>
Description: Retrieves company details using the Commercial Registration (CR) number.
URL Parameter: info (CR Number)
Success Response:
{
"response": "success",
"Company": [{ ... company details ... }]
}
Endpoint: POST /update_company/<cr>
Description: Updates an existing company and its associated partner record.
URL Parameter: cr (Current CR Number)
Request Body (Partial updates supported):
{
"Name": "New Name",
"Street": "Main St",
"City": "Riyadh",
"Building_Number": "1234",
"Plot_Identification": "5678",
"Identification_Scheme": "CRN",
"Identification_Number": "1234567890"
}
Endpoint: GET /get_company_name/<name>
Description: Retrieves company details by its exact name.
URL Parameter: name (Company Name)
Success Response:
{
"success": true,
"message": "Company fetched successfully",
"data": {
"id": 1,
"name": "My Company",
"currency": { "id": 1, "name": "SAR" },
"mobile": "0501234567",
"email": "info@mycompany.com",
"website": "http://www.mycompany.com",
"logo_url": "/get_company_logo/1"
}
}
Endpoint: GET /get_company_logo/<int:company_id>
Description: Retrieves the logo of a company. Returns an image file.
URL Parameter: company_id (Company ID)
Success Response: (Image file - e.g., PNG)
Endpoint: GET /get_saudi_states/
Description: Retrieves a list of all administrative states/regions in Saudi Arabia.
Success Response:
{
"success": true,
"message": "Saudi states fetched successfully",
"data": {
"country": {
"id": 1,
"name": "Saudi Arabia",
"code": "SA"
},
"states": [
{ "id": 10, "name": "Riyadh", "code": "01" },
{ "id": 11, "name": "Makkah", "code": "02" }
]
}
}
Endpoint: POST /onboard_journal
Description: Checks if the "Customer Invoices" journal for a specific company is ready for ZATCA onboarding.
Request Body:
{
"company_id": "1234567890" // Commercial Registration (CR) number of the company
}
Success Response:
{
"success": true,
"message": "Journal Ready for ZATCA OnBoarding",
"journal": "Customer Invoices",
"company": "Company Name"
}
Endpoint: POST /submit_otp
Description: Submits the ZATCA OTP to complete the onboarding process for a company's sales journal.
Request Body:
{
"company_id": "1234567890", // Commercial Registration (CR) number of the company
"otp": "123456"
}
Success Response:
{
"success": true,
"message": "ZATCA Onboarding completed successfully!"
}
Endpoint: POST /create_partner
Description: Creates a new partner (customer/vendor) in Odoo. The Number field determines if it's a CR (10 digits) or VAT (15 digits).
Request Body:
{
"Name": "Partner Name",
"Phone": "050XXXXXXX",
"Number": "1234567890",
"Email": "partner@example.com",
"Is_Company": true,
"Country": "SA"
}
Success Response:
{
"response": "success",
"Partner_ID": 456,
"Number_Type": "CR"
}
Endpoint: GET /get_partner/<number>
Description: Retrieves partner details using their CR (10 digits) or VAT (15 digits) number.
URL Parameter: number (CR or VAT Number)
Success Response:
{
"response": "success",
"Partner": { ... partner details ... }
}
Endpoint: POST /update_partner/<number>
Description: Updates an existing partner's information.
URL Parameter: number (Current CR or VAT Number)
Request Body (Partial updates supported):
{
"Name": "Updated Partner Name",
"Phone": "051XXXXXXX",
"Number": "1234567891"
}
Success Response:
{
"response": "success",
"message": "Partner updated successfully"
}
Endpoint: POST /create_product
Description: Creates a new product in Odoo.
Request Body:
{
"ProductName": "New Product",
"Reference": "PROD-001",
"SalesPrice": 150.0,
"Cost": 100.0,
"Number": "1234567890",
"Category": "All",
"SalesTaxes": ["15%"],
"PurchaseTaxes": ["15%"]
}
Success Response:
{
"response": "success",
"Product_ID": 789
}
Endpoint: GET /get_product/<int:product_id>
Description: Retrieves product details using its ID.
URL Parameter: product_id (Product ID)
Success Response:
{
"response": "success",
"Product": { ... product details ... }
}
Endpoint: POST /update_product/<int:product_id>
Description: Updates an existing product's information.
URL Parameter: product_id (Product ID)
Request Body (Partial updates supported):
{
"ProductName": "Updated Product Name",
"SalesPrice": 160.0
}
Success Response:
{
"response": "success",
"message": "Product updated successfully"
}
Endpoint: POST /create_invoice
Description: Creates a new customer invoice in Odoo.
Request Body:
{
"Customer": "Customer Name",
"Lines": [
{
"ProductID": 1,
"Quantity": 2,
"Account": "Product Sales - (Saudi Arabia)",
"Taxes": ["VAT 15%"]
}
],
"InvoiceDate": "2023-01-01",
"DueDate": "2023-01-31",
"DeliveryDate": "2023-01-05"
}
Success Response:
{
"response": "success",
"Invoice_ID": 123,
"Invoice_Number": "INV/2023/0001"
}
Endpoint: GET /get_invoice/<int:invoice_id>
Description: Retrieves details of a specific customer invoice by its Odoo ID.
URL Parameter: invoice_id (Invoice ID)
Success Response:
{
"response": "success",
"Invoice": {
"id": 123,
"name": "INV/2023/0001",
"partner_id": [456, "Customer Name"],
"invoice_date": "2023-01-01",
"state": "draft",
"amount_total": 115.0
// ... other invoice details
}
}
Endpoint: POST /reverse_invoice/<int:invoice_id>
Description: Reverses a posted customer invoice by creating a credit note.
URL Parameter: invoice_id (Invoice ID)
Request Body (Optional):
{
"Reason": "Customer returned goods"
}
Success Response:
{
"response": "success",
"message": "Invoice reversed successfully",
"result": {
// ... Odoo result of reversal operation ...
}
}