Integrating with Adera

The whole API is five endpoints. If this page takes longer than a coffee to read, it is our bug.

1 · Your key

Every call carries one header:

Authorization: Bearer adera_test_…

A key belongs to one environment, and you can tell which without asking anybody:

Same fields, same responses, same code path. What you test is what runs.

2 · Send a document

POST https://adera.com.et/v1/documents

{
  "reference": "INV-2026-00024",
  "buyer": {
    "name": "Kezira Pharmacy",
    "tin": "0012345678",
    "phone": "0915000000"
  },
  "lines": [
    {
      "description": "Amoxicillin 500mg capsule",
      "quantity": 10,
      "unit_price": 420,
      "line_total": 4200,
      "vat_exempt": true
    }
  ],
  "subtotal": 4200,
  "delivery_fee": 0,
  "discount": 0,
  "vat_amount": 0,
  "total": 4200,
  "currency": "ETB"
}

Add "connector": "cnet" to choose the target system — it is the default — and "kind": "credit_note" for a credit note.

Sending the same reference twice is safe. Your own reference is the idempotency key. A retry after a timeout returns the document already created, with 200 instead of 201, rather than asking a revenue system for a second receipt for one sale. This is the single most important sentence on this page.

3 · Ask what happened

GET https://adera.com.et/v1/documents/INV-2026-00024   # your reference
GET https://adera.com.et/v1/documents/doc_9f2c…          # or our id

{
  "id": "doc_9f2c4b17a0e3",
  "reference": "INV-2026-00024",
  "connector": "cnet",
  "environment": "sandbox",
  "status": "cleared",
  "result_number": "FS-SBX-4C1A9E22",
  "fiscal_number": "FS-SBX-4C1A9E22",
  "result_label": "fiscal number",
  "error": null,
  "attempts": 1,
  "submitted_at": "2026-09-03T09:14:02",
  "cleared_at":   "2026-09-03T09:14:02"
}

status is one of queued, leased, cleared, rejected or failed. Only cleared means it is done; rejected means the far end looked at it and said no, and the reason is in error.

4 · The rest

5 · Being told, instead of asking

Polling works perfectly well and needs no public address. If you would rather be told, give us a URL and a secret, and we will POST to it when a document resolves — retried six times over about two hours.

X-Adera-Event:     document.cleared
X-Adera-Timestamp: 1756882442
X-Adera-Signature: hmac_sha256(secret, "<timestamp>.<raw body>")

Verify the signature before trusting the body, and reject a timestamp more than a few minutes old — that is what stops a captured call being replayed at you tomorrow. A webhook we could not deliver never changes your document: it is still cleared, and GET still says so.

6 · When something is wrong

Every error is JSON, and every message is a sentence you can act on.

7 · What we will never do

We do not issue fiscal documents. In Ethiopia's clearance model the accredited system is the issuer; Adera carries your document to it and carries the number back, and records exactly what came back. If a number never arrives, your document stays queued and somebody is told — it is never quietly marked done.

Connectors