e-Invoice lifecycle/flow + APP API usage questions

Lex

Please coudl you help confirm that the expect lifecycle of an e-Invoice from a business (tax-payer) in a B2B flow is accurate as described below:

Tax payer's internal system generates IRN using the FIRS defined standard
Tax payer's internal system created invoice document and validates invoice schema by calling FIRS API
Tax payer's internal system calls MBS via APP to sign and submit e-Invoice
Tax payer's internal system calls MBS via APP to transmit e-Invoice
Tax payer's customer/buyer receives notification from MBS via APP
Tax payer's customer/buyer calls MBS via APP to validate e-Invoice
Tax payer's customer/buyer calls MBS via APP to confirm e-Invoice receipt
Tax payer's customer/buyer calls MBS via APP to pull (or download) e-Invoice
Tax payer's customer/buyer pays invoice
Tax payer's customer/buyer calls MBS via APP to update e-Invoice status as PAID
Tax payer's internal system calls MBS via APP to confirm e-Invoice status

If above is true, could you help answer the questions below:

Tax Payer Login
What is the use case for tax payer login?
Is the expectation that APP are expected to authenticate Tax Payer before allowing them to access the the Invoice APIs
Is there a test tax payer login email and password that can be used for test?

Get Entity by Business ID
Am I able to get the Entity details of any Tax Payer or only those where I am their APP?
What is an Entity, how is it different from Tax Payer and Businesses? It looks like an Entity can have multiple businesses.

Invoice Signing/Submission by Taxpayer
Is it fair to say the purpose of signing an invoice is to register the Invoice with FIRS?

Invoice Validation Use Cases
What is the use case for validating a full invoice document (POST /api/v1/invoice/validate) vs validating by IRN (POST /api/v1/invoice/irn/validate)?
Is the epxtectation that full document invoice validation is for Sender while valdiation by IRN is for Receiver?

Invoice Confirmation (GET /api/v1/invoice/confirm/{IRN}) ?
What is the exact purpose of this endpoint, is it equivalent to retrieving the invoice status, or does it serve a different purpose?

TIN Lookup (GET /api/v1/invoice/transmit/lookup/tin/{TIN})
What is the intended purpose of this endpoint?
Is it meant to validate a buyer/supplier TIN before transmission?
When is validation by IRN used vs TIN validation?

Updating Invoice status to PAID, REEJCTED etc
Who can/should update invoice status, it is the sender of the invoice or the receiver?
Does MBS have valdiation on this?

Testing the Full Lifecycle
What is the recommended way to test the full invoice lifecycle especially how to confirm receipt of transmitted Invoice as a receiver - I have not figured a way to be a sender and a receiver at the same time. The same for pulling of transmitted invoices. Currently, we are unable to fully test some steps such as confirm receipt, and pull because its not clear how to register as a receiver linked to me as an APP

Confirming Transmitted Invoices (PATCH /api/v1/invoice/transmit/{IRN})
Is there any compliance or regulatory requirement that this confirmation must come from the receiver (tax payer) or can the APP confirm on behalf of the tax payer? Will this be elft to the discretion of the APP?

Invoice Pulling vs Search vs Download
What is the functional difference between:
GET /api/v1/invoice/transmit/pull
GET /api/v1/invoice/download/{{IRN}}
Are there specific use cases for each that we should be aware of? Is the pull used by receive to fetch all invoices that are meant for taxpayers subscribed to the APP?
The documentation does not have sample response for all the transmit API calls, pls can we get sample response json for them?

Invoice Status Update
Is it correct to assume that only the invoice receiver should be able to:
Update invoice status (PATCH /api/v1/invoice/update/{IRN})
Confirm transmitted invoice (PATCH /api/v1/invoice/transmit/{IRN})?
Does the MBS system enforce this rule (e.g. by checking business identity), or is this the responsibility of the APP?
Can a sender update the invoice status, or is that strictly limited to the receiver?
Are there any compliance or regulatory requirement around who access an invoice e.g. only parties (sender/receiver) can access an Invoice and if so does MBS do any valdiation or APP are expected to do that?

Lex

SysAdmin

Dear Lex,

Thank you for reaching out. Please find our response below:

1. Taxpayer Login

What is the use case for tax payer login? Taxpayer login allows an APP to retrieve the entity ID linked to a taxpayer, which serves as a unique key for accessing the taxpayer’s e-Invoicing configuration and profile.
Is the expectation that APP are expected to authenticate Tax Payer before allowing them to access the Invoice APIs? The e-Invoice APIs are publicly accessible. However, to onboard a taxpayer and retrieve their e-Invoicing profile, the APP must either use the taxpayer's authentication (Taxpayer Auth) or invoke the GET /entity endpoint, and this is only possible if the taxpayer has already enabled its entity for e-Invoicing.
Is there a test taxpayer login email and password that can be used for test? No. Test sign-in credentials are not provided

2. Get Entity by Business ID

Am I able to get the Entity details of any taxpayer or only those where I am their APP? No. You can only retrieve entity details for taxpayers who have explicitly selected you as their APP.
What is an Entity, how is it different from taxpayer and Businesses? It looks like an Entity can have multiple businesses? An Entity represents the taxpayer’s identity in the e-Invoicing system. It is uniquely tied to the TIN. In this context, each taxpayer equals one entity; an entity cannot have multiple businesses.

3. Invoice Signing/Submission by Taxpayer

Is it fair to say the purpose of signing an invoice is to register the Invoice with FIRS? Yes. Digital signing serves as the taxpayer’s official submission of the invoice to FIRS, registering it for fiscalization and compliance.

4. Invoice Validation Use Cases

What is the use case for validating a full invoice document (POST /api/v1/invoice/validate) vs validating by IRN (POST /api/v1/invoice/irn/validate)? Both endpoints are used by the sender. While POST /invoice/validate validates the full invoice structure and content, POST /invoice/irn/validate is specifically used to verify the integrity of the IRN computation. It's advisable to validate the IRN during implementation to prevent mismatches during full invoice validation.
Is the expectation that full document invoice validation is for the sender, while validation by IRN is for Receiver? Both validation endpoints are intended for the sender to ensure accuracy prior to Signing.

5. Invoice Confirmation (GET /api/v1/invoice/confirm/{IRN})

What is the exact purpose of this endpoint, is it equivalent to retrieving the invoice status, or does it serve a different purpose? This endpoint returns the current processing status of a specific invoice, confirming whether it has been transmitted or acknowledged.

6. TIN Lookup (GET /api/v1/invoice/transmit/lookup/tin/{TIN})

What is the intended purpose of this endpoint? This endpoint retrieves the taxpayer’s invoice exchange details, including their accounting party profile and corresponding APP.
Is it meant to validate a buyer/supplier TIN before transmission? Primarily, it is used to determine the party’s metadata and APP affiliation for routing purposes, not to validate tax registration.
When is validation by IRN used vs TIN validation? IRN validation is used during invoice creation to verify the integrity of the computed IRN while TIN lookup is used before invoice transmission to resolve the buyer’s routing and APP details.

7. Updating Invoice status to PAID, REEJCTED etc

Who can/should update invoice status, it is the sender of the invoice or the receiver? The sender is responsible for updating the invoice status, as the sender holds legal liability for the transaction.
Does MBS have validation on this? Currently, validation is limited, but the system roadmap includes policy enhancements to tie every financial transaction to an IRN for validation and traceability.

8. Testing the Full Lifecycle

What is the recommended way to test the full invoice lifecycle, especially how to confirm receipt of transmitted Invoice as a receiver - I have not figured a way to be a sender and a receiver at the same time. The same for pulling of transmitted invoices. Currently, we are unable to fully test some steps such as confirm receipt, and pull because its not clear how to register as a receiver linked to me as an APP? To perform end-to-end (E2E) testing, configure your test business as both the Accounting Supplier and Customer. With a properly configured webhook, this allows you to simulate invoice issuance, receipt, confirmation, and pull in a closed test loop.

9. Confirming Transmitted Invoices (PATCH /api/v1/invoice/transmit/{IRN})

Is there any compliance or regulatory requirement that this confirmation must come from the receiver (taxpayer) or can the APP confirm on behalf of the taxpayer? Will this be left to the discretion of the APP? The receiving APP is responsible for confirming receipt on behalf of the taxpayer, as part of the invoice exchange protocol.

10. Invoice Pulling vs Search vs Download

What is the functional difference between: Pull is for transmission logs; Download is for receiving payload delivery.
GET /api/v1/invoice/transmit/pull - Used by the APP to retrieve all invoices transmitted by the APP to various recipients.
GET /api/v1/invoice/download/{{IRN}} - Used by the receiving APP to download a specific invoice transmitted to its subscribed taxpayer.
Are there specific use cases for each that we should be aware of? Is the pull used by receiver to fetch all invoices that are meant for taxpayers subscribed to the APP? It can be used by both the the Receiver and Sender APP
The documentation does not have sample response for all the transmit API calls, pls can we get sample response json for them? FIRS will update the official API documentation to include sample JSON responses for all Transmit API calls.

11. Invoice Status Update

Is it correct to assume that only the invoice receiver should be able to:
Update invoice status (PATCH /api/v1/invoice/update/{IRN})? Incorrect. Only the sender has permission to update invoice status (e.g., PAID, REJECTED).
Confirm transmitted invoice (PATCH /api/v1/invoice/transmit/{IRN})? The receiver’s APP confirms receipt of the invoice.
Does the MBS system enforce this rule (e.g. by checking business identity), or is this the responsibility of the APP? Yes. The MBS platform validates all the details to ensure conformity before validating a transaction.
Can a sender update the invoice status, or is that strictly limited to the receiver? Yes. Status updates are strictly the sender’s responsibility and must align with the invoice lifecycle logic.
Are there any compliance or regulatory requirement around who access an invoice e.g. only parties (sender/receiver) can access an Invoice and if so does MBS do any valdiation or APP are expected to do that? No. Only parties directly involved in the transaction (sender or receiver) are permitted to access, lookup, or download an invoice. MBS enforces this through identity validation and access control.

Lex

Many thanks for taking your time to clearly explain this. Just 2 more question from me.

Testing the Full Lifecycle

How do I confirm my test business as both the Accounting Supplier and Customer?
Is it something I can do by myself or do I need to request via a channel? If I do need to request via a channel, what channel do I use?

Transmit Lookup by IRN vs by TIN

What is the difference between GET /api/v1/invoice/transmit/lookup/{IRN} and GET /api/v1/invoice/transmit/lookup/tin/{TIN} in terms of use case?
Also will they both return same response?

SysAdmin

1. Testing the Full Lifecycle

How do I confirm my test business as both the Accounting Supplier and Customer? Enter the same details in the Account Supplier Party and Accounting Customer Party. You can retrieve your test business by calling the search entity endpoint using your APP Keys.
Is it something I can do by myself or do I need to request via a channel? If I do need to request via a channel, what channel do I use? You can do it yourself. Just update the invoice schema to reflect your test data for both parties.

2. Transmit Lookup by IRN vs by TIN

What is the difference between GET /api/v1/invoice/transmit/lookup/{IRN} and GET /api/v1/invoice/transmit/lookup/tin/{TIN} in terms of use case? Both serve the same purpose: retrieving taxpayer invoice exchange details, including accounting party profiles and corresponding APPs. The key difference lies in the scope of information returned:
-LookUp IRN: Returns exchange details for both parties involved in the invoice.
-LookUp TIN: Returns exchange details for the single party whose TIN is provided.
Also will they both return same response? No.

Lex

Thanks a lot for your response. A question around pulling invoice. Each time an APP calls the pull invoice APP, does it get the list of all invoices transmitted to the APP since beginning of time, or does it return only invoices that are transmitted but have not been PAID? I am trying to understand if the returned invoice list grows forever or it cuts off by time, or by something else.

Also, can I use the API GET /api/v1/entity (Search Entity) to search by business Id? i.e. /api/v1/entity?business_id=xxxxxx-xxxx-xxxxx. Also I assume any business where I am their APP, the search API will return it. Pls can you confirm this?

SysAdmin

Please find our response below:
Each time an APP calls the pull invoice APP:

Does it get the list of all invoices transmitted to the APP since the beginning of time? Yes
Does it return only invoices that are transmitted but have not been PAID? No, all invoices, whether paid or not
Does the returned invoices list grow forever, or does it cut off by time, or by something else? For now, the list will continue to grow.

GET Entity/ Search Entity

Can I use the API GET /api/v1/entity (Search Entity) to search by business ID? i.e. /api/v1/entity?business_id=xxxxxx-xxxx-xxxxx? Yes, but not with Business ID, instead with Entity ID
Business where I am their APP, the search API will return it. Pls can you confirm this? Yes, the search entity API will help retrieve the names of businesses that as selected you as their APP