Register on Peppol
Publish a taxpayer's receiving capabilities to the Peppol directory.
Publishes the taxpayer's address and receiving capabilities to the Peppol directory, so other Access Points can find and invoice them.
/v1/api/taxpayers/{taxpayer_id}/peppol-registration| Field | Type | Description | |
|---|---|---|---|
| capabilities | string[] | required | Which document types the taxpayer will accept. At least one — see the values below |
Capability values
| Value | Lets the taxpayer receive |
|---|---|
billing_invoice | Invoices from suppliers |
billing_credit_note | Credit and debit notes from suppliers |
selfbilling_invoice | Self-billed invoices raised by their customers |
selfbilling_credit_note | Self-billed credit notes |
Four values, and mls isn't one of them — naming it is rejected. MLS (delivery receipts between
Access Points, not a business document) is published automatically on every registration regardless of
what you ask for, which is why the example response above shows three published entries for a
two-capability request. It can't be requested and — once published — can't be withdrawn on its own either; it's removed only
when the taxpayer leaves the network entirely, not through the
capability-removal call below.
document_type_id in the response is scheme-qualified — peppol-doctype-wildcard:: or
busdox-docid-qns:: (MLS's own scheme) prefixed onto the identifier, joined with ::. Paste it back
exactly as returned if you ever need to name a capability by its raw identifier instead of its key.
Capabilities publish one at a time internally, but the call is not partial-success-tolerant: the first one that fails aborts the request, and you get a single error response for the whole call, not a 200 with a per-capability success/failure breakdown. Whatever published before the failing one is still recorded on SUMU's side (visible via subsequent calls), but this response won't show you that mix — only the error that stopped it. Re-calling with the same capability list is safe (each publish is idempotent, so redoing an already-published one is a harmless no-op), and it will get further if whatever blocked the failing one is now fixed.
Registration requires an authority association
Before a taxpayer can be published, it must be connected to your Service Provider account in the
Oman Tax Authority's Fawtara portal. Until that's in place this endpoint returns a
400 VALIDATION_ERROR whose message names the rejected publish — there's no dedicated
code for this specific cause, so match on the message, not just the status. This is a manual step
outside the API — start it early, it gates go-live for each taxpayer.
Remove a capability
/v1/api/taxpayers/{taxpayer_id}/peppol-registrationSame path, a capabilities body array instead of a query — withdraws specific document types while
leaving the taxpayer registered for the rest. mls is rejected here the same way it is on registration;
it only goes when the taxpayer does, via Offboard from Peppol below.
DELETE /v1/api/taxpayers/{taxpayer_id}/peppol-registration
{ "capabilities": ["selfbilling_credit_note"] }{
"message": "Removed 1 capabilities from 0248:OM1100449001",
"data": {
"participant_id": "0248:OM1100449001",
"removed": [
{
"key": "selfbilling_credit_note",
"document_type_id": "peppol-doctype-wildcard::urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:peppol:pint:selfbilling-1@om-1::2.1"
}
]
}
}If that was the taxpayer's last live capability, peppol_status on the taxpayer record drops back to
not_registered — check List and retrieve taxpayers rather than
assuming one withdrawal leaves them reachable for anything.
Offboard from Peppol
/v1/api/taxpayers/{taxpayer_id}/peppol-participantThe taxpayer's own exit, not a bigger version of removing a capability — this takes them out of the SMP,
the SML, and the Peppol Directory entirely, in one call, no body. Every capability goes with them,
including mls, which nothing else can remove.
DELETE /v1/api/taxpayers/{taxpayer_id}/peppol-participant{
"message": "Removed 0248:OM1100449001 from the SMP, SML and Directory",
"data": {
"participant_id": "0248:OM1100449001",
"removed": 4
}
}removed counts how many capabilities were live at the moment of removal — not a fixed number, and not
meaningful beyond a confirmation that something was actually there to remove. Afterward, the taxpayer's
peppol_status reads removed — a distinct, terminal value, not the same as not_registered for a
taxpayer that was simply never published. There's no way back from this call: re-registering starts
over as a new participant, not a resumed one.