Skip to content
Dashboard

Getting started · Quick start

Make your first invoice request

Enable the POS integration, exchange its credentials for an access token, create an NGN invoice, and read it back. Every request below goes to the live API.

Goal: a 200 response whose data contains the new invoice ID

Before you begin

  • An e-Invoicing organization you can configure in the dashboard
  • A secure server-side secret store
  • curl and jq, or Node.js 18+, or Python with requests
Hosthttps://api.uat.einvoicing.avetiumtechnologies.com/api/v1

All paths start with /api/v1/. The samples read the host from EINV_BASE_URL. There is a single host; no separate sandbox or production host exists.

1. Enable the POS integration

  1. 1. Open Integrations

    In the dashboard, go to Integrations and choose "Configure POS Integration".

  2. 2. Enable the integration

    Enable it. The page then shows your Client ID and Client Secret (the public key). Programmatically, POST /api/v1/organizations/pos/enable does the same.

  3. 3. Copy the credentials

    Store both values in your secret store. You will send them to the authenticate endpoint.

Treat the Client Secret like a password

Keep it out of source control, client-side code and logs. If it may have leaked, rotate it with POST /api/v1/organizations/{orgReference}/pos/rotate-key; the old key stops working.

2. Exchange credentials for a token

POST/api/v1/organizations/pos/authenticateReturns a token

Send { clientId, publicKey }; both are required. The token is at data.token.access_token. Send it as a bearer token on the calls below.

3. Create your first invoice

POST/api/v1/organizations/{organizationReference}/invoices/posCreates an invoice

Send the bearer token and an X-Client-Id header, which is required on organization-scoped endpoints. The web app sends the organization's client ID (its reference) for this header, and the sample uses that same value for the path. The API reference does not define a different value for POS calls, so if you get 401 or 403, check this header first.

A minimal body

The spec marks no invoice field as required, so the sample sends a short body in NGN. Submitting to NRS needs more detail (tax totals, supplier party, codes); see Create an invoice for the full field list.

4. Retrieve it

GET/api/v1/organizations/{organizationReference}/invoices/pos/{invoiceId}Reads one invoice

Confirm success

200 OK

Every response is wrapped as statusCode, message, timestamp, data and successful. Create also returns 200, not 201. Read the invoice ID from data.id.

Common errors

400The body is malformed or a field failed validation; read message.
401Missing, expired or invalid bearer token, or wrong clientId/publicKey on authenticate.
403The token is valid but not allowed for this organization, or X-Client-Id is missing or does not match.
404The organization reference or invoice ID does not exist.
409The request conflicts with the current state of the resource.
500Unexpected server failure. Retry later and contact support if it persists.

See Errors for the envelope and what to do for each status.

Coming soon Soon

Separate Sandbox and Production environments, scoped API keys and idempotency keys are planned. None of them are needed or available in this flow today.

Test checklist

  • Token is requested only from your backend
  • Authorization header uses Bearer <access_token>
  • X-Client-Id is sent on both invoice calls
  • Create returns 200 and data.id is present
  • The invoice can be retrieved by that ID
  • Secrets and personal data are absent from logs
IntroductionAPI keys