Build on Aequo

Quickstart

From a new key to your first list of invoices in three steps.

1. 1. Create an API key

   In the Aequo app, open Settings → API Keys. Workspace owners and admins can create keys; API access is included from the Growth plan up. Pick the scopes the key needs (for example documents:read). The key starts with nxs_live_ and is shown once; Aequo stores only a hash. A key can never do more than the person who created it, and it stops working if they lose access to the workspace. Keys cannot be used to create or revoke other keys.

2. 2. Authenticate

   Send the key as a bearer token on every request. Each endpoint checks for its scope, such as documents:read or matches:write; a key with the broad read or write permission covers every read or write scope.

   Authorization: Bearer nxs_live_...

3. 3. List invoices

   Documents are invoices (INV), purchase orders (PO) and delivery notes (DN). Filter by type, status, needs_review and an ISO 8601 from/to range.

   curl "https://api.nexusap.com/v1/documents?type=INV&limit=25" \
     -H "Authorization: Bearer $AEQUO_API_KEY"
   
   # 200 OK
   # { "data": [ { "id": "...", "type": "INV", "status": "...", ... } ],
   #   "nextCursor": "..." }   <- pass back as ?cursor= for the next page

   curl -X POST "https://api.nexusap.com/v1/documents" \
     -H "Authorization: Bearer $AEQUO_API_KEY" \
     -F "file=@invoice-1042.pdf" \
     -F "supplierId=<supplier uuid from GET /v1/suppliers>" \
     -F "type=INV"
   
   # 202 Accepted
   # { "id": "...", "status": "..." }

Webhooks

Register an HTTPS endpoint and choose the events you want. Then, in Settings → Notifications, turn on the Webhook channel for those events (new workspaces notify by email only). Aequo then posts a JSON body to your endpoint when each event happens, signed with the secret you supplied.

curl -X POST "https://api.nexusap.com/v1/webhooks" \
  -H "Authorization: Bearer $AEQUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/aequo/webhooks",
    "secret": "a-long-random-string",
    "events": ["MATCH_CLEARED", "EXCEPTION_CREATED", "EXCEPTION_RESOLVED"]
  }'

POST https://example.com/aequo/webhooks
Content-Type: application/json
X-Nexus-Signature-256: sha256=<hex HMAC-SHA256 of the body>

{
  "event": "EXCEPTION_CREATED",
  "occurredAt": "...",
  "tenantId": "...",
  "entityRefs": { ... },
  "summary": "...",
  "data": { ... }
}

import crypto from 'node:crypto';

// rawBody: the request body bytes exactly as received
export function isFromAequo(rawBody: Buffer, header: string, secret: string) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return (
    header.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
  );
}

The header keeps its original X-Nexus-Signature-256 name from before the Aequo rename, so existing receivers keep working. Respond with a 2xx status quickly and do heavy work asynchronously.