Skip to main content
GET
Download AADL Avis

Overview

Streams the avis de paiement AADL publishes for a housing file — the same PDF the tenant would download from the biller — for a transaction you own. Like Download Receipt, it does not return the JSON envelope on success: the bytes are the body, so you can stream them straight to your own customer. It is not the receipt. The receipt is proof that your payment went through; the avis is AADL’s own statement of what the housing file owes. Only AADL publishes one.
The avis is addressed by transaction, never by housing file. There is no codeloc in this request and none is accepted. We load the transaction, confirm it is yours in this environment, refuse it if its partner is not AADL, and read the housing file from the bill already stored on it.That is deliberate. AADL’s own export page needs no session and answers with a PDF for any code, whether or not it exists — proxying a caller-supplied one would turn this endpoint into a way to enumerate other people’s housing files. Resolving it from your own transaction makes that impossible.

Path Parameters

string
required
The transaction identifier. A 24-character lowercase hexadecimal string, from Get Transaction by ID or from any list, belonging to an AADL transaction of yours.Unlike the receipt, the transaction does not have to be SUCCESS: any of your AADL transactions that has resolved a bill can produce an avis.

Response

On success the body is the PDF itself. Read the headers to know what you received.
header
required
application/pdf.
header
required
attachment; filename="avis_<transactionId>.pdf". The name is built from the transaction identifier alone, so it carries no tenant identity.
header
required
The size of the file in bytes.
header
required
private, no-store. AADL regenerates the avis on demand and replaces it every period, so there is nothing stable to cache — and it is one customer’s document, never a shared one.

Examples

Success Response

The body is binary. The headers look like this:

Error Responses

Errors are returned as JSON, in the same envelope as every other endpoint.
The key was absent or rejected.
What to do: verify the key against the Authentication guide.
The identifier is unknown, or the transaction is not yours in this environment.
A sandbox key never sees a production transaction, and neither sees another key’s. The answer is the same in every case, so the endpoint never confirms that somebody else’s transaction exists.What to do: check the identifier, and check you are using the key the transaction was created with.
The transaction is yours, but its partner does not publish an avis.
What to do: read partner on the transaction first and only offer the download when it is AADL. For every other biller, the receipt is the document you want.
No housing file has been resolved on this transaction, or AADL declined to produce the document.
A discovery that has not reached READY has no bill on it yet, so there is nothing to resolve a housing file from.What to do: wait for the transaction to carry a bill, then try again. A refusal from the biller is worth one retry, not a loop.

What the avis is for

Showing the customer what they owe

The avis carries AADL’s own breakdown of the housing file. It is the document a tenant recognises.

Not a substitute for the receipt

Only the receipt proves a payment went through. Store that one against your order.
Remember that an AADL housing file has exactly one open avis, with any arrears folded into its total — so this PDF is the whole of what the file owes, never one period out of several. See Partners and Accounts.

Best Practices

Check the partner first

Offer the download only for AADL transactions. Every other partner answers 404 NOT_FOUND.

Never expose the URL

This URL needs your API key. Serve the bytes from your own system, behind your own authentication.

Fetch it fresh

no-store is not decoration — AADL replaces the avis every period. Download it when you need it.

Never send a codeloc

There is no identifier parameter to guess. If your code builds one, it is calling the wrong thing.

Download Receipt

Proof of a successful payment

Get Transaction by ID

Where partner and the bills appear

Discover Bills

How an AADL housing file is looked up

Partners and Accounts

The AADL identifier rules