# SimpleFatoora MCP > SimpleFatoora connects your AI client to SimpleFatoora for full ZATCA-compliant e-invoicing. It gives your agent programmatic access to generate all six required invoice types (B2C, B2B, Purchase) and manage every detail: customers, products, tax rates, and credit notes. ## Overview - **Category:** erp-operations - **Price:** Free - **Tags:** e-invoicing, zatca-compliance, invoice-management, customer-crud, product-crud, tax-reporting ## Description Listen up. If you're dealing with billing in Saudi Arabia, you need this SimpleFatoora server hooked up to your agent. It handles all the complicated stuff—making sure every invoice is 100% ZATCA compliant. Your agent gets programmatic access to generate six different types of invoices and keeps track of every detail: who bought it, what was sold, and how much tax applies. **Before running anything**, your agent first checks things out. You'll use `validate_api_key` to confirm the API key is valid and active. It's also smart enough that you can run `check_simplefatoora_status` right away; that tells you if the whole SimpleFatoora connection is up and working before you try to send a single dollar. **Generating Compliant Invoices.** This server lets your agent create specific documents required by law. To handle retail sales, it'll use `create_simplified_invoice` for B2C simplified billing. For registered businesses doing VAT transactions, the agent uses `create_vat_invoice` to generate a compliant B2B VAT invoice. If you're dealing with purchases, it gives you two options: running `create_standard_purchase` for full-detail purchase invoices or using `create_simplified_purchase` if that’s what fits your needs. You don't just create invoices; you adjust them too. When a customer returns something, the agent runs `create_credit_note`, generating a compliant credit note linked right to the original invoice. If there's an overpayment or some other adjustment needed, it uses `create_debit_note` to generate that official debit note. **Managing Customer Profiles.** You can build and maintain your entire customer database using these tools. To start someone new, you run `create_customer`. Need the details on a specific client? Use `get_customer` with their ID; otherwise, you can pull up multiple clients by running `list_customers`, often filtering them by things like VAT number. If an address changes or they get a tax update, you just call `update_customer`. When a customer account is totally defunct and needs to be wiped from the system records, you use `delete_customer`. **Handling Product Catalogs.** The agent keeps your master data clean too. To add new services or items, it uses `create_product`; if you need details on an existing item, run `get_product` with the code or ID. Want to see everything you've sold? `list_products` pulls a complete list of all available products. If the price goes up or the VAT rate changes, you use `update_product`. And if a product line is dead and needs removing entirely from your catalog records, it uses `delete_product`. **Checking Records.** You don't have to guess what happened with an invoice number. `get_invoice` pulls up all the data and current status for any existing invoice you provide. If you need a full history of everything generated in the account, run `list_invoices` to get a paginated list of every invoice. You can also call `list_products` again just to verify what's sitting in your catalog. This setup gives your agent total control over the entire financial lifecycle. You manage the client data, you keep the product codes fresh, and you generate every single document—from the initial B2C invoice to the final debit note—all while staying compliant with ZATCA regulations. It’s a full-stack solution; it's built for real business use. ## Tools ### check_simplefatoora_status Verifies if the SimpleFatoora connection is active and working. ### create_credit_note Generates a compliant credit note for an invoice. ### create_customer Creates a new customer profile in the system. ### create_debit_note Generates a compliant debit note for an invoice. ### create_product Creates a new product entry in the catalog. ### create_simplified_purchase Creates a purchase invoice using the simplified method. ### create_simplified_invoice Generates a B2C simplified invoice, suitable for retail sales. ### create_standard_purchase Generates a standard, full-detail purchase invoice. ### create_vat_invoice Creates a compliant B2B VAT invoice for registered businesses. ### delete_customer Permanently removes a customer from the system records. ### delete_product Removes a product entry from the catalog. ### get_customer Retrieves all details for a specific customer by ID. ### get_invoice Fetches the full data and status of an existing invoice number. ### get_product Retrieves all details for a specific product code or ID. ### list_customers Returns a list of multiple customers, often filtered by criteria like VAT number. ### list_invoices Retrieves a paginated list of all invoices generated in the account. ### list_products Returns a complete list of all products available in the catalog. ### update_customer Modifies existing customer details, like changing an address or tax number. ### update_product Changes product attributes such as price, description, or VAT rate. ### validate_api_key Checks if the provided API key is valid and active for SimpleFatoora. ## Prompt Examples **Prompt:** ``` Create a simplified B2C invoice for 3 items totaling 450 SAR in SimpleFatoora. ``` **Response:** ``` I've successfully created the simplified B2C invoice. The total is 450 SAR, including VAT. The ZATCA-compliant invoice with its cryptographic QR code has been generated. Would you like me to send it to the customer? ``` **Prompt:** ``` List all customers in SimpleFatoora with their VAT registration numbers. ``` **Response:** ``` Retrieving your customer list... You currently have 42 registered customers. I have compiled their names and VAT registration numbers. Would you like to export this list as a CSV file? ``` **Prompt:** ``` Create a credit note for invoice #1234 in SimpleFatoora due to a partial return. ``` **Response:** ``` Credit note successfully created and linked to invoice #1234. The adjustment for the partial return has been recorded and stamped for ZATCA Phase 2 compliance. Do you need to apply this credit to the customer's balance? ``` ## Capabilities ### Generate Compliant Invoices The agent generates specific types of invoices (B2C, B2B, Purchase) and automatically stamps them to meet ZATCA regulatory requirements. ### Manage Customer Records You can create, read, update, list, or delete full customer profiles, ensuring tax registration numbers are always current for compliance. ### Handle Financial Adjustments The system creates compliant credit notes and debit notes, linking them directly to existing invoices to adjust balances after returns or partial payments. ### Maintain Product Catalogs You control the master data by creating new products, updating VAT rates, and deleting unused items from your product catalog. ### Verify Compliance & Status The agent checks the connectivity status (`check_simplefatoora_status`) and validates API keys before running any critical transaction. ## Use Cases ### The End-of-Month Reconciliation An accountant needs to reconcile all sales. They ask their agent to 'List all invoices from the last 30 days.' The agent runs `list_invoices`, compiles the data, and groups it by invoice type (VAT vs. Simplified), giving the controller a clean summary ready for tax filing. ### Customer Data Correction A sales rep learns a client changed their VAT registration number. Instead of calling finance to update an internal sheet, they tell their agent: 'Update customer XYZ with new VAT number.' The agent calls `update_customer`, ensuring the next invoice generated will be compliant. ### Processing Returns A warehouse manager processes a partial return for Invoice #4567. They tell their agent, 'Create a credit note for 10 units from Invoice #4567.' The agent runs `create_credit_note`, linking the adjustment and stamping it for ZATCA compliance. ### New Product Launch The product team launches a new service. Instead of updating multiple spreadsheets, they ask their agent to 'Add the new service as product code SVC-001.' The agent calls `create_product`, adding it with correct VAT rates and immediately making it available for invoicing. ## Benefits - Generate all six compliant invoice types in one step. Whether it's a simplified B2C sale or a complex B2B VAT invoice, the agent runs `create_vat_invoice` and handles the required cryptographic stamp automatically. - Never manually update customer data again. Use `list_customers` to audit your roster, then use `update_customer` when an address or tax number changes, keeping records accurate for audits. - Manage the whole product lifecycle. If a price changes or a VAT rate shifts, you don't touch spreadsheets; you simply call `update_product`, and the master catalog is correct immediately. - Handle returns without headaches. When a customer returns goods, your agent calls `create_credit_note` (or `create_debit_note`) against the original invoice number, maintaining full compliance history. - Run high-level audits effortlessly. You can ask to see all invoices for last quarter and get them via `list_invoices`, giving you a clean, structured data set ready for export. ## How It Works The bottom line is: You connect your API key once, and your AI client handles all the complex billing logic using simple instructions. 1. First, subscribe to this server on Vinkius. You'll need your SimpleFatoora API Key from their developer dashboard. 2. Second, enter the required API key into your agent configuration. The agent uses this credential to authenticate all subsequent requests against the SimpleFatoora platform. 3. Third, tell your AI client what you want—e.g., 'Create a B2B VAT invoice for customer X.' The agent then executes the necessary tool calls (`create_vat_invoice`) and returns the compliant invoice document. ## Frequently Asked Questions **How do I generate a B2B invoice using SimpleFatoora?** You use the `create_vat_invoice` tool. This function handles all required B2B VAT logic, ensuring compliance with ZATCA standards and generating the correct document type. **What is the difference between `create_credit_note` and `create_debit_note`?** `create_credit_note` reduces a customer's balance (used for returns or overpayment). `create_debit_note` increases it, usually when you charge back an amount. **Can I update product prices using the SimpleFatoora MCP Server?** Yes. Use the `update_product` tool. This function lets you change price points and VAT rates for specific products without affecting historical invoices or customer data. **How do I list all my customers in SimpleFatoora?** Call the `list_customers` tool. It returns a list of registered clients, which you can then filter by criteria like VAT number or date range. **How do I check if my SimpleFatoora API key is working using the `validate_api_key` tool?** Running this tool confirms your credentials are active and correctly formatted. It provides a simple pass/fail status, letting you know immediately whether to continue building or if you need to update your keys. **What specific details can I pull for one transaction using the `get_invoice` tool?** The `get_invoice` tool retrieves every piece of data tied to a single invoice ID. You get the total amount, customer information, VAT breakdown, and the full status necessary for auditing or display purposes. **How do I retrieve all my registered products using the `list_products` tool?** This command pulls a complete list of every item in your product catalog. You get names, unique IDs, current prices, and associated VAT rates across all entries. **What is the process for generating a simplified consumer invoice using `create_simplified_invoice`?** To create a B2C invoice, you use this tool to handle transactions that don't require full VAT complexity. You provide the items and total amount, and it generates the necessary ZATCA-compliant document. **How can my AI generate ZATCA-compliant invoices?** Simply use the `create_invoice` tool. Your agent can instantly generate six types of invoices (including B2C and B2B), all fully compliant with ZATCA Phase 2, complete with QR codes, UUIDs, and cryptographic stamps. **Is it possible to programmatically access my client list and VAT numbers?** Yes. By executing the `list_customers` action, your AI agent can retrieve your entire client registry, including tax identification numbers, addresses, and contact details for seamless CRM integration. **Can I automatically issue credit notes for partial returns?** Absolutely. Ask the agent to use the `create_credit_note` tool. It will safely generate a ZATCA-compliant credit note linked to the original invoice, adjusting the accounting records automatically.