Send a new invoice data from Books to local certified solution via API json due local compliance

Send a new invoice data from Books to local certified solution via API json due local compliance

Greetings,  
I hope you are doing well and staying safe.  

Due to local compliance regulations, I am required to issue invoices exclusively using locally certified software, which Zoho Books is not. However, we would like to continue using Zoho Books, so we need to send invoice data to an external certified solution each time a new invoice is issued. This external system should automatically generate a corresponding invoice, essentially mirroring the one created in Zoho Books.  

I have access to the API documentation for the external certified solution and have attempted to create a custom function to extract invoice data, format it in JSON, and send it to the external system. However, due to my limited knowledge, I have been unable to save the custom function successfully, as the Deluge editor consistently flags syntax errors.  

The API documentation for the external solution can be found here: https://api.factplus.co.ao/documentation/  

Below are some of the approaches I have attempted:  

===
void EnviarFctraParaFctpls( Map invoice, Map organization, Map user )
{
    // A função já recebe os detalhes da fatura e organização como 'invoice' e 'organization'
    // Não precisamos usar zoho.books.getRecordsByID para os dados básicos da fatura.
    // Usaremos 'invoice' diretamente.

    // 1. Extrair Detalhes da Fatura (diretamente do 'invoice' Map)
    invoiceData = invoice; // 'invoice' já é o mapa com os dados da fatura
    organizationId = organization.get("organization_id"); // ID da sua organização no Zoho Books

    invoiceNumber = invoiceData.get("invoice_number");
    invoiceDate = invoiceData.get("date"); // Formato 'YYYY-MM-DD'
    dueDate = invoiceData.get("due_date"); // Formato 'YYYY-MM-DD'
    reference = invoiceData.get("reference_number"); // Pode usar o número de referência do Zoho Books
    currency = invoiceData.get("currency_code");
    // observation = invoiceData.get("notes"); // Supondo que 'notes' seja para observações
    
    // ATENÇÃO: Verifique na documentação do Factplus como lidar com 'retention'.
    // Se o Zoho Books não tiver um campo direto para 'retention', você pode precisar de lógica extra
    // ou definir como "0" se não for aplicável no seu caso.
    retention_value = "0"; 
    
    // Dados do Cliente
    customerData = invoiceData.get("customer_details");
    clientName = customerData.get("customer_name");
    clientNIF = customerData.get("vat_reg_no"); // Assumindo que NIF seja o VAT Registration Number
    clientEmail = customerData.get("email");
    clientCity = customerData.get("city");
    clientAddress = customerData.get("billing_address").get("address"); // Endereço de fatura
    clientPostalCode = customerData.get("billing_address").get("zip"); // CEP de fatura
    clientCountry = customerData.get("billing_address").get("country"); // País de fatura

    // Itens da Fatura
    lineItems = invoiceData.get("line_items");
    factplusItems = collection(); // Coleção para armazenar os itens formatados para o Factplus

    for each item in lineItems
    {
        // Para itemcode, é ideal usar um ID que seja único e identificável no Factplus.
        // item.get("item_id") é o ID interno do Zoho Books, o que pode não ser ideal se o Factplus
        // espera um código de item de produto/serviço. Considere usar item.get("name") ou um campo personalizado.
        itemCode = item.get("item_id"); 
        description = item.get("description");
        price = item.get("rate");
        quantity = item.get("quantity");
        taxRate = item.get("tax_percentage"); // Taxa de imposto
        discount = item.get("discount"); // Desconto por linha de item
        
        // ATENÇÃO: exemption_code e retention por item precisam ser verificados na API do Factplus.
        exemptionCode = ""; // Valor padrão, ajuste se tiver campo correspondente
        itemRetention = "0"; // Valor padrão, ajuste se tiver campo correspondente

        factplusItem = Map();
        factplusItem.put("itemcode", itemCode);
        factplusItem.put("description", description);
        factplusItem.put("price", price);
        factplusItem.put("quantity", quantity);
        factplusItem.put("tax", taxRate);
        factplusItem.put("discount", discount);
        factplusItem.put("exemption_code", exemptionCode);
        factplusItem.put("retention", itemRetention);
        
        factplusItems.add(factplusItem);
    }
    
    // 2. Construir o Objeto JSON para a API do Factplus
    // ATENÇÃO: SUBSTITUA 'SUA_CHAVE_API_AQUI' PELA SUA CHAVE DE 32 DÍGITOS DO FACTPLUS
    factplusPayload = Map();
    factplusPayload.put("apicall", "CREATE");
    factplusPayload.put("apikey", "SUA_CHAVE_API_AQUI"); // <-- SUA CHAVE API DO FACTPLUS AQUI!

    documentMap = Map();
    documentMap.put("type", "factura"); // Tipo de documento, confirme se "factura" é o correto
    documentMap.put("date", invoiceDate);
    documentMap.put("duedate", dueDate);
    documentMap.put("vref", invoiceNumber); // Usando o número da fatura como referência. Verifique se o Factplus aceita este formato.
    // A "serie" é crucial. O exemplo do Factplus mostra "2020". Você precisa definir uma série apropriada.
    // Se o Zoho Books não tiver um campo para série, pode ser um valor fixo ou derivado.
    documentMap.put("serie", "2024"); // <-- ATENÇÃO: Defina a série correta para o Factplus (ex: "2024", "FS_A")
    documentMap.put("currency", currency);
    documentMap.put("exchange_rate", "0"); // Ajuste se houver taxa de câmbio
    // documentMap.put("observation", invoiceData.get("notes")); // Se usar campo de notas
    documentMap.put("retention", retention_value);

    clientMap = Map();
    clientMap.put("name", clientName);
    clientMap.put("nif", clientNIF);
    clientMap.put("email", clientEmail);
    clientMap.put("city", clientCity);
    clientMap.put("address", clientAddress);
    clientMap.put("postalcode", clientPostalCode);
    clientMap.put("country", clientCountry);
    
    factplusPayload.put("document", documentMap);
    factplusPayload.put("client", clientMap);
    factplusPayload.put("items", factplusItems);

    // Converter o mapa Deluge para string JSON
    jsonString = factplusPayload.toString();

    // 3. Fazer a Chamada HTTP POST para a API do Factplus
    // ATENÇÃO: Você PRECISA substituir "https://api.factplus.co.ao" pelo ENDPOINT COMPLETO
    // da API do Factplus para a criação de faturas.
    // Ex: "https://api.factplus.co.ao/v1/invoices" ou similar.
    factplusAPI_URL = "https://api.factplus.co.ao"; // <-- SUBSTITUIR PELO ENDPOINT ESPECÍFICO DE CRIAÇÃO DE FATURA

    // Cabeçalhos (Content-Type é essencial para JSON)
    headers = Map();
    headers.put("Content-Type", "application/json");

    // Executar a chamada API
    apiResponse = invokeurl
    [
        url : factplusAPI_URL
        type : POST
        headers: headers
        content : jsonString
    ];

    // 4. Tratar a Resposta da API
    info "Request sent to Factplus: " + jsonString; // Para depuração, mostre o que foi enviado
    info "Factplus API Response: " + apiResponse;

    // Adicione lógica para verificar a resposta aqui.
    // Ex: if (apiResponse.get("status") == "success") { ... }
    // ou if (apiResponse.get("code") == 200) { ... }
    // Logar erros se a resposta indicar falha e talvez enviar um email de alerta.
    if (apiResponse.get("status") == "success") // Supondo que a API retorne um campo 'status'
    {
        info "Fatura enviada com sucesso para o Factplus!";
        // Opcional: Atualizar a fatura no Zoho Books com um campo de status "Enviado para Factplus"
        // Ou armazenar o ID de retorno do Factplus.
    }
    else
    {
        error "Erro ao enviar fatura para o Factplus: " + apiResponse.get("message"); // Supondo campo 'message'
        // Opcional: Enviar email de erro para o cliente ou para o administrador
    }
}
===

And

===
// Função para enviar fatura do Zoho Books para o Factplus
// Parâmetro: invoice_id (ID da fatura criada)
invoice_id = input.invoice_id;

// Obter detalhes da fatura do Zoho Books
invoice = zoho.books.getRecordsByID("Invoices", organization_id, invoice_id);
invoice_data = invoice.get("invoice");

// Mapear dados do cliente
customer_id = invoice_data.get("customer_id");
customer = zoho.books.getRecordsByID("Contacts", organization_id, customer_id);
customer_data = customer.get("contact");
client_map = Map();
client_map.put("name", customer_data.get("contact_name"));
client_map.put("nif", customer_data.get("tax_reg_no", ""));
client_map.put("email", customer_data.get("email", ""));
client_map.put("city", customer_data.get("billing_address").get("city", ""));
client_map.put("address", customer_data.get("billing_address").get("address", ""));
client_map.put("postalcode", customer_data.get("billing_address").get("zip", ""));
client_map.put("country", customer_data.get("billing_address").get("country", "Angola"));

// Mapear itens da fatura
items_list = List();
for each item in invoice_data.get("line_items")
{
    item_map = Map();
    item_map.put("itemcode", item.get("item_id", "ITEM" + item.get("line_item_id")));
    item_map.put("description", item.get("name"));
    item_map.put("price", item.get("rate").toString());
    item_map.put("quantity", item.get("quantity").toString());
    item_map.put("tax", "14"); // Ajuste conforme a tributação aplicável
    item_map.put("discount", item.get("discount", "0").toString());
    item_map.put("exemption_code", "");
    item_map.put("retention", "");
    item_map.put("unit", "Unidade");
    items_list.add(item_map);
}

// Construir o corpo da requisição para o Factplus
payload = Map();
payload.put("apicall", "CREATE");
payload.put("apikey", "SUA_CHAVE_API_FACTPLUS"); // Substitua pela sua chave de API
document_map = Map();
document_map.put("type", "factura");
document_map.put("date", invoice_data.get("date"));
document_map.put("duedate", invoice_data.get("due_date"));
document_map.put("vref", invoice_data.get("invoice_number"));
document_map.put("serie", invoice_data.get("date").left(4)); // Ano da fatura
document_map.put("currency", "AOA");
document_map.put("exchange_rate", "0");
document_map.put("observation", "");
document_map.put("retention", "0");
payload.put("document", document_map);
payload.put("client", client_map);
payload.put("items", items_list);

// Enviar requisição para o Factplus
headers = Map();
headers.put("Content-Type", "application/json");
response = invokeurl
[
    type: POST,
    parameters: payload.toString(),
    headers: headers,
    connection: "FactplusAPI"
];

// Logar a resposta para depuração
info response;
===

Any help?
Thanks in advance.

    • Recent Topics

    • FSM integration with Books

      Hi, I have spent a few months working with FSM and have come across a critical gap in the functionality, which I find almost shocking....either that, or I am an idiot. The lack of bi-directional sync between Books and FSM on Sales Orders/ Work Orders

    • How to close an estimate ?

      Hello, I have created estimates, and converted them to invoices to get 50% payment. Now I have 2 cases where the estimate stills shows status partially invoiced, however: 1. for one of them, project stopped half way, so the remaining part will never be

    • Power up your Kiosk Studio with Real-Time Data Capture, Client Scripts & More!

      Hello Everyone, We’re thrilled to announce a powerful set of enhancements to Kiosk Studio in Zoho CRM. These new updates give you more flexibility, faster record handling, and real-time data capture, making your Kiosk flows smarter and more efficient

    • How do you print out the invoices comments

      I have some invoices where i need to print out the comments that show when reminders and etc were sent how do we print those out in Zoho Books.

    • Unable to load a specific image

      Hi I am trying to upload an svg file, which reports that there is "a problem with the file", but does not say what sort of problem. I can't find anything which says which files are supported, so it may be it does not support svg. (which would be a real shame) The file itself will open in either Firefox or Chrome without problem. For the moment I am using a png file, which does not zoom well of course. David

    • Why does the Address field show the wrong map location even with a correct Pincode?

      I am noticing an issue with the Address field map in Zoho Creator. When I enter a city name that exists in multiple locations within the same state, the map sometimes points to the wrong area even if I have entered the correct Pincode. Currently, it seems

    • Books <-> CRM synchronisation with custom Fields

      Hello, We are synchronising Books Customers with CRM Accounts. In CRM Accounts I set up last year a "segments" multiselect field shown below In Books, I set up a custom multi-select field with the same value as in the CRM And set up the synchronisation inside Books. Want to synchronise the Books Segments with the CRM Segments, but the later doesn't exist, and another non-existing is there ?! First, I don't understand where the field Segmentation is coming from. Second, I set CRM Segmentation to sync

    • CRM x WorkDrive: We're rolling out the WorkDrive-powered file storage experience for existing users

      Release plan: Gradual rollout to customers without file storage add-ons, in this order: 1. Standalone CRM 2. CRM Plus and Zoho One DCs: All | Editions: All Available now for: - Standalone CRM accounts in Free and Standard editions without file storage

    • Archive Option in Conversation View

      Hello, I have a suggestion\request to add an "Archive Thread" button in conversation view of Zoho Mail. The best suggestion I have is to put an "Archive Thread" button next to the "Label Entire Thread" button in conversation view. Most users don't just

    • Outlook/Hotmail Blocking Zoho SMTP IPs (S3150)

      We are currently facing a serious deliverability issue with Zoho SMTP while sending transactional OTP emails for our production application. Emails sent to Outlook / Hotmail addresses are being rejected with the following error: 550 - 5.7.1 Unfortunately,

    • Outlook is blocking incoming mail

      Outlook is blocking all emails sent from the Zoho server. ERROR CODE :550 - 5.7.1 Unfortunately, messages from [136.143.169.51] weren't sent. Please contact your Internet service provider since part of their network is on our block list (S3150). It looks

    • Track Marketing Automation Campaigns in Zoho CRM

      Hello, I've been searching but haven't found the exact answer to this question. I am looking to track Marketing Automation email campaigns and activities inside of Zoho CRM. Use Case: Action: Prospect Submits A Lead Form Outcomes: Prospect created in

    • Zoho Social API for generating draft posts from a third-party app ?

      Hello everyone, I hope you are all well. I have a question regarding Zoho Social. I am developing an application that generates social media posts, and I would like to be able to incorporate a feature that allows saving these posts as drafts in Zoho Social.

    • Temporarily rate limited due to IP reputation.

      We have suddenly started receiving the following Mail Delivery Status Notification: Diagnostic-Code: 4.7.650 The mail server [136.143.184.12] has been temporarily rate limited due to IP reputation. For e-mail delivery information, see https://aka.ms/postmaster

    • Incorrect Functioning of Time Logs API (Version 3)

      We need to fetch the list of time logs for each task for our company internal usage. We are trying to achieve it by using the next endpoint: https://projects.zoho.com/api-docs#bulk-time-logs#get-all-project-time-logs Firstly, in the documentation the

    • IMPORTANT: It doesn´t search for letters with portuguese characters.

      Some of my articles have for example the word "vídeo". But if I search for "vídeo" it doesn´t find them. If I search for "video" it does find them. Idealy, it should find the articles either way. But if I have to choose, it would be better to find the

    • IMPORTANT: It doens´t show full article name on search - Should add line break

      When we search for articles, it doesn´t show the full name. There should be a line break so the user can see the full article name, otherwise the user can´t know if that´s the article he/she is looking for. This is very important, otherwise the user has

    • Zoho Books - Payment Gateway - Revolut

      Hi Books Team, My feature request if to include the popular platform Revolut as a payment collection option on invoices in Zoho Books. Please upvote if you are also looking for this option.

    • Zoho Books | Product updates | January 2026

      Hello users, We’ve rolled out new features and enhancements in Zoho Books. From e-filing Form 1099 directly with the IRS to corporation tax support, explore the updates designed to enhance your bookkeeping experience. E-File Form 1099 Directly With the

    • Kaizen #233 - Generating AI-powered Follow-up Emails Using CRM Functions and Widgets

      Hey everyone! Welcome back to another interesting post in the Kaizen series! Sales teams regularly capture interaction notes in CRM after speaking with prospects. However, drafting a follow-up email that reflects the conversation context can be repetitive

    • Connect Bank in Zoho Books

      Can I connect UOB or Ariwallex in Zoho Books?

    • Using MPN across multiple SKUs and inventory tracking

      I have several different SKU's that share a common MPN and would like to track inventory by MPN. SKU1 has MPN1 assigned SKU2 has MPN1 assigned Here is an example If I start with 5 of MPN 1 in stock I want each SKU1 and SKU2 to show as 5 in stock, If I

    • Extend Zoho Canvas Customization to Zoho Creator Forms and Reports

      Currently, Zoho Canvas allows users to design and customize the UI of Zoho CRM modules with a much better visual experience. This helps organizations create cleaner layouts, improve usability, and design interfaces that match their workflows. However,

    • Marketing Tip #1: Optimize item titles for SEO

      Your item title is the first thing both Google and shoppers notice. Instead of a generic “Leather Bag,” go for something detailed like “Handcrafted Leather Laptop Bag – Durable & Stylish.” This helps your items rank better in search results and instantly

    • Feature Enhancement Request – Text Formatting Options in Item Description (Zoho Books/Quotes Module)

      Dear Zoho Development Team, Greetings from Radiant360 Integrated Technical Services LLC. We would like to bring to your attention a functional limitation we've encountered within the Item Table / Quote Description section of Zoho Books (and Zoho CRM Quotes).

    • ZOHO Books Query

      Good day, Can someone please advise. I recently migrated from ZOHO Invoice to ZOHO Books. No that I want to use the inventory on Books I cant as all my items have transaction history. The person I spoke to at ZOHO said I need to create a new Company profile

    • Best way to schedule bill payments to vendors

      I've integrated Forte so that I can convert POs to bills and make payments to my vendors all through Books. Is there a way to schedule the bill payments as some of my vendors are net 30, net 60 and even net 90 days. If I can't get this to work, I'll have

    • ZOHO.CRM.UI.Record.open not working properly

      I have a Zoho CRM Widget and in it I have a block where it will open the blocks Meeting like below block.addEventListener("click", () => { ZOHO.CRM.UI.Record.open({ Entity: "Events", RecordID: meeting.id }).catch(err => { console.error("Open record failed:",

    • inventory removal at packing list or shipment.

      currently our system is set to remove inventory at invoice. This is creating an inventory nightmare? Is it possible to change the settings to remove the item from inventory at either the packing slip stage or shipping the item.

    • How to add employee and not invite them to log in?

      I want to add 50 employees, but invite them only when everything will be configured and ready. Is it possible? Should we create employee profiles and then convert them later? Thank you,

    • How is Your eCommerce Experience w/Zoho Inventory?

      First off, I'm SUPER grateful for the advent of Zoho Inventory and now the Zoho Commerce Suite. Overall, Inventory is a great product, especially for customers without an eCommerce presence. For eCommerce companies (especially those shipping more than ~10 packages/day), however, there are certain drawbacks that keep my clients from moving over to Zoho Inventory: Cons: 1. Invoice + Package Creation from Shopify/Other eCommerce Integrations: Zoho Inventory makes the somewhat perplexing decision to

    • Ability to Use Both AND and OR When Creating Rules (Advanced Conditions)

      I'd like to be able to use more complicated logic when setting up rules. E.g. in Zoho Mail, I can choose "Advanced conditions (AND/OR) to create a rule that can be applied to multiple subject lines from the same sender. But in Zoho TeamInbox, I will have

    • Zoho Desktop App- Unable to Minimize/Freezes

      I'm having issues with my Zoho Mail desktop app (PC). When go on my desktop and open the app this is what happens: - Unable to minimize and close app (in the screenshot attached you can see at the top right there is no option to minimize/close) - Unable

    • Zoho Invoice Zapier Integration

      Is there still a way to use Zapier with Zoho Invoice? I've read online that that migrated to Zoho Books or Billing but since I am just using Invoice I can not find a Zapier Connection anymore.

    • Conect chat of salesiq with zoho cliq

      Is there any way to answer from zoho cliq the chat of salesiq initiated by customers?

    • Bug: OAuth 2.0 State Parameter fails with Pipe Delimiters (RFC 6749 Non-Compliance)

      I've discovered a bug in how Zoho's API Console handles the OAuth 2.0 authorization flow when the state parameter contains pipe characters (|), and I'm hoping the Zoho team can address this in a future update. The Issue Zoho's OAuth 2.0 implementation

    • Zobot with Plugs

      Hello, I am having a problem with Zobot using Plugs. Here is my current flow: When I run the flow, I should immediately see the messages from the initial cards (Send Message cards), then after running the plug, and finally, see the messages after the

    • Print a document from Zoho Writer via Zoho Creator

      If i use the code below i can get writer to create a new document or email it to me but i want to be able to print it directly from the browser and not have to send it via email and then print. Below is the code im using. Attached options form zoho writer

    • Training for How can i Operate the Software Features

      need to Help for Training of the ZOHO Billing Software

    • Automating Vendor Contract Management between Zoho Contracts and Zoho Books using Zoho Flow

      Managing vendor agreements across procurement and finance systems often requires manually downloading executed contracts and attaching them to vendor records. This can become time-consuming and difficult to manage when dealing with a large number of contracts.

    • Next Page