Skip to Content
Getting StartedQuickstart

Quickstart

Issue your first invoice on the sandbox in about ten minutes, with an API key and curl.

Before you start

  1. Sign in to the Yona app at app.useyona.com  and open API keys.
  2. Create a sandbox key with the invoicing preset. It starts with sk_test_ and is shown once; copy it now.
  3. Every request below goes to https://gp.useyona.com with the key as a Bearer token. The key decides the environment: sk_test_ keys use the sandbox, sk_live_ keys the live service. The URL never changes.
No tax connection needed on the sandbox

Sandbox submissions go to the authority’s test system under Yona’s own test taxpayer, so you can submit before you connect your business. Live submissions need your own connection and crypto key; see Tax connection.

Step 1: Add a buyer

bash
curl -X POST https://gp.useyona.com/i/v1/buyers \
-H "Authorization: Bearer sk_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{
  "name": "Kano Grains Co.",
  "partyType": "company",
  "taxId": "12345678-0001",
  "email": "accounts@kanograins.example",
  "address": { "line1": "5 Marina Road", "city": "Lagos", "state": "Lagos", "country": "NG" }
}'

The response is 201 with the buyer in data. Keep data.id. For an individual, leave out taxId and send "partyType": "individual".

Step 2: Create an invoice

bash
curl -X POST https://gp.useyona.com/i/v1/invoices \
-H "Authorization: Bearer sk_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{
  "invoiceKind": "B2B",
  "invoiceDate": "2026-10-01",
  "currency": "NGN",
  "buyerId": "BUYER_ID",
  "lineItems": [{
    "description": "Widget",
    "quantity": "2",
    "unitCode": "EA",
    "unitPrice": "1500.50",
    "hsnCode": "8471.30",
    "productCategory": "Machinery",
    "taxCategory": "standard"
  }]
}'

The response is 201 with a draft invoice. Keep data.id. Notes on the fields:

  • invoiceKind is required: B2B, B2C, B2G or G2B.
  • Amounts are in major units, as decimal strings or numbers. Totals and tax are computed for you.
  • taxCategory takes standard, zero or exempt, or a tax-category code from Reference data.
  • Goods carry an hsnCode; services carry an isicCode instead.
  • invoiceNumber is allocated when you leave it out.

Step 3: Submit it

bash
curl -X POST "https://gp.useyona.com/i/v1/invoices/INVOICE_ID/submit?finalise=true" \
-H "Authorization: Bearer sk_test_your_key_here"

finalise=true finalises the draft and submits it in one step. The response is 202 Accepted: the submission is queued, signed and handed to the authority. Reporting an invoice uses credits; if the balance is short the answer is 402 with BIZ001, and nothing is sent.

Step 4: Watch it get registered

bash
curl https://gp.useyona.com/i/v1/invoices/INVOICE_ID/status \
-H "Authorization: Bearer sk_test_your_key_here"

Poll every few seconds. On the sandbox the authority’s test system usually answers within seconds. The fields to watch, abbreviated:

{
  "data": {
    "id": "INVOICE_ID",
    "status": "finalised",
    "simpleStatus": "reported",
    "reportedToNrs": true,
    "irn": "INV00042-94ND90NR-20261001"
  }
}

simpleStatus moves from issued to reported when the authority registers the invoice, and to delivered when the buyer’s access point confirms receipt. The full response shape is in Invoices.

To download the signed PDF: GET /i/v1/invoices/INVOICE_ID/download.

Next steps

  • Webhooks: be told when an invoice is registered, delivered or rejected, instead of polling.
  • Tax connection: connect your business to the authority before going live.
  • Going live: what changes with a live key.
  • API Reference: every endpoint, generated from the API itself.
Getting StartedAuthentication