OAuth API
Changed
The buyer's legal registration follows the PINT AE rules
- The buyer's registration id (buyer.legal_registration_id, IBT-047) is required only on an Out of scope of VAT invoice (type 480) and on a credit note related to goods or services (type 81).
- That includes an invoice whose every line is exempt or out of scope, because it becomes type 480 or 81.
- On every other invoice the buyer's registration is optional.
- When you send the id, send its type too (buyer.legal_registration_type: TL, EID, PAS or CD).
- TL also needs authority_name. PAS also needs passport_country_code, a two-letter ISO 3166-1 code.
- A request that leaves one out is refused with a 422 that names the field. POST /oauth/invoices/validate reports the same errors.
- For EID and CD no authority is sent, even if you supply one. The second value is written only for TL (the authority) and PAS (the country).
- The buyer's TIN is no longer copied into this field. The TIN, the TRN and the participant id are never used as a legal registration number.
Why we changed this
- The specification asks for the buyer's registration only on those two document types, and asks for its type whenever an id is sent. Our API did neither: it copied the buyer's TIN into the field with no type.
- A TIN is a tax identifier, not a legal registration number, and a registration with no type breaks IBR-180-AE. A document could go out that the rules reject, with no error to the sender.
- In the specification, EID and CD carry no second value, so sending an authority for them was not allowed.
- The Peppol rule IBR-149-AE says the buyer registration is required for every UAE buyer, but its own test checks the VAT number, not the registration. We do not enforce a buyer registration on the strength of that rule.
Reference
From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.
IBR-136-AE ↗The buyer legal registration identifier must be present on an Out of scope of VAT invoice and on a credit note related to goods or services.IBR-180-AE ↗When the buyer id is given on the 0235 scheme, its registration type must be present.IBR-183-AE ↗The type must be Commercial/Trade license, Emirates ID, Passport or Cabinet decision.IBR-101-AE ↗A trade licence (TL) must carry its authority name.IBR-010-AE ↗A passport must carry its issuing country.IBR-011-AE ↗The passport country must be coded with ISO 3166-1.IBR-CL-11 ↗A registration identifier scheme must come from the ISO 6523 list, so the type is never written in schemeID.IBR-103 ↗The buyer legal registration identifier may occur at most once.IBR-149-AE ↗Known issue: its message and its test disagree, so it is not enforced.
What to do: Send the buyer's registration on Out of scope of VAT invoices and on credit notes related to goods or services. Wherever you already send an id, add its type.
Legal registration rules →Push invoice →
Changed
An invoice to a UAE buyer with no registration no longer fails with Company ID is required
- An invoice to a UAE buyer that sends no buyer.legal_registration_id passed validation but then failed while the XML was built, with the error Company ID is required.
- That was a fault in how the buyer was carried from validation to the XML. It is fixed: such an invoice is built and sent, and the buyer's registration is left out of the XML.
- The buyer's registration is still required on an Out of scope of VAT invoice and on a credit note related to goods or services, and its type is still required whenever you send the id.
- An invoice that failed this way can be sent again: PATCH /oauth/invoices/{invoice_id} with the same invoice body.
- Anything that stops the document being built is now reported when you send or validate, as an error in section document, and never later as a failed conversion.
- POST /oauth/invoices/validate shows it too, so a preview now predicts the send.
Why we changed this
- The specification makes the buyer's registration optional except on those two document types, and our validation already accepted an invoice without it. The XML step then rejected the same invoice, so the two disagreed.
- The fault only appeared in the step that builds the XML, which is why validation and the preview did not show it.
- A client should be told what is missing when they send, not find a failed status afterwards, so validation now also builds the document as a dry run.
Reference
From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.
IBR-136-AE ↗The buyer legal registration identifier is required only on an Out of scope of VAT invoice and on a credit note related to goods or services.IBR-180-AE ↗When the buyer id is given on the 0235 scheme, its registration type must be present.
What to do: If an invoice to a UAE buyer failed with Company ID is required, send it again with PATCH /oauth/invoices/{invoice_id} and the same invoice body. Nothing else changes.
Legal registration rules →
Breaking change
The seller's legal registration comes from the entity, and is required
- State the seller's registration once, on the entity: legal_registration_id, legal_registration_type, and issuing_authority (TL) or passport_country (PAS).
- Every invoice for that entity then carries it exactly as given.
- One invoice can differ by sending the seller block on that invoice.
- An invoice for an entity with no registration is refused with a 422 that names what is missing.
- So is a trade licence without its issuing authority, and a passport without its country or with a code that is not ISO 3166-1.
- For EID and CD no authority is sent.
- Before, the invoice carried the entity's registry code labelled as a passport issued by AE, whatever you had set. That value is removed.
- Entities created through FTA onboarding have no registration until you set one.
Why we changed this
- The specification requires the seller's legal registration id and its type on every UAE document, with the authority for TL and the country for PAS.
- We were sending the entity's registry code, which is a TIN, labelled as a passport issued by AE. A TIN is not a legal registration number, and the label was not true.
- That value was there because we believed the gateway needed it to find the sender. We tested it on the Peppol development gateway: the sender is found from the endpoint, not from this element.
- The registration belongs to the seller, so the seller states it once on the entity. We no longer decide it for you.
Reference
From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.
IBR-006 ↗An invoice must contain the seller name.IBR-150-AE ↗The seller legal registration identifier must be provided when the endpoint scheme is 0235.IBR-181-AE ↗When the seller id is given on the 0235 scheme, its registration type must be present.IBR-173-AE ↗The type must be Commercial/Trade license, Emirates ID, Passport or Cabinet decision.IBR-172-AE ↗A trade licence (TL) must carry its authority name.IBR-012-AE ↗A passport must carry its issuing country.IBR-013-AE ↗The passport country must be coded with ISO 3166-1.IBR-100 ↗The seller legal registration identifier may occur at most once.
What to do: Set the registration on each entity you send invoices for, before you send the next invoice.
Update an entity →Legal registration rules →
New
PUT is accepted on the entity update, and the registration fields are checked together
- PATCH and PUT on /oauth/entities/{entity_id} are the same partial update: send only the fields you want to change.
- A change to the registration fields is checked against what the entity will then hold.
- An id needs its type, and a type needs its id.
- TL needs issuing_authority. PAS needs passport_country, an ISO 3166-1 code.
- Otherwise the update is a 400 and nothing is stored.
- An update that touches none of these fields is not checked.
Why we changed this
- A registration set on the entity is used on every invoice, so a half-filled one (an id with no type, a TL with no authority) would make every invoice fail.
- The update now refuses it when it is entered, instead of each invoice failing later.
- PUT is accepted because many clients update with PUT. It does the same partial update as PATCH.
Reference
From the PINT AE Billing 1.0.4 specification. Each ID opens the rule on the Peppol documentation.
IBR-181-AE ↗A seller id on the 0235 scheme needs its registration type.IBR-172-AE ↗A trade licence (TL) must carry its authority name.IBR-012-AE ↗A passport must carry its issuing country.IBR-013-AE ↗The passport country must be coded with ISO 3166-1.
Update an entity →