Asesia API v2

Authentication

• Create credentials in Settings → API v2 (firm administrators, or the company owner when the firm allows it). Secrets are shown once and stored hashed; rotate them with a 24-hour grace period, or invalidate them at once if you suspect a leak. Every token issued, every write and (grouped) every read is audited.
• OAuth 2.0 client credentials: exchange client_id + client_secret for a 1-hour access token. Ask for a subset of the client's scopes with scope.
• Personal API keys (asesia_pk_…) are sent directly as a Bearer token, with the scopes fixed at creation.
• A firm credential reaches the firm's companies (same market only) and only the sections each company shares with its firm. A company credential reaches its own company.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=invoices:read invoices:write" \
  https://<host>/api/v2/oauth/token

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://<host>/api/v2/companies

companies:read · documents:read · documents:write · captures:read · expenses:read · invoices:read · invoices:write · invoices:issue · contacts:read · contacts:write · taxes:read · bank:read · webhooks:manage

Conventions

• Every resource lives under /companies/{companyId}. Ids of companies or objects you cannot reach answer 404, exactly like ids that do not exist.
• Pagination: limit (1–200, default 50) and an opaque cursor. Lists return data, total, truncated and nextCursor.
• Idempotency: send Idempotency-Key on POST creations. A retry returns the same response for 24 h (Idempotent-Replayed: true); the same key with a different body is rejected with 422.
• Errors: { "error": { "code", "params"?, "detail"?, "requestId" } }. Program against code (a stable catalogue shared with the app); detail is a hint and may be localized. Every response carries X-Request-Id.
• Rate limits are per credential (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After on 429).
• Reads carry a weak ETag; send it back as If-None-Match to get 304 Not Modified.
• Amounts are in EUR; invoices also keep their original currency.

Endpoints

Webhooks

• Register https endpoints (POST /webhooks or Settings). The host must resolve to public IPv4 addresses; this is checked when you save it and again, pinned to the connected address, on every delivery (no private, loopback or link-local destinations, no redirects).
• Each delivery is signed: X-Asesia-Signature: v1=<hex HMAC-SHA256 of timestamp + "." + raw body> with your endpoint secret, plus X-Asesia-Timestamp (seconds). Reject anything older than 5 minutes.
• Deduplicate on X-Asesia-Event-Id (the id in the body): it is the same across retries and manual redeliveries.
• Failed deliveries are retried after 1, 5, 30, 120 and 360 minutes (408, 429 and 5xx; other 4xx are not retried). 15 consecutive failures pause the endpoint. The delivery log and manual redelivery are in the API and in Settings.
• Firm endpoints receive events only for what each company shares with its firm.

import crypto from 'node:crypto'

function verify(rawBody, secret, signature, timestamp) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const mac = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')
  const a = Buffer.from(`v1=${mac}`), b = Buffer.from(signature)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Events

document.received

A document entered the company (upload, email, WhatsApp, API).

document.processed

OCR finished: extracted data is available.

capture.approved

A human (or an approval rule) approved a captured document; it is now an accounting fact.

capture.rejected

A captured document was rejected.

expense.created

An expense was created.

invoice.created

A sales invoice (draft or issued) was created.

invoice.issued

A draft was issued: it has its series number (and, where enabled, its tax-authority record).

invoice.paid

An invoice was marked as paid.

invoice.verifactu_status

The VERI*FACTU record of an invoice changed state (accepted, accepted with errors, rejected).

model.ready

A tax return was prepared or filed for a period (status PREPARADO or PRESENTADO).

bank.reconciled

A bank movement was reconciled.

Migrating from v1

• /api/v1 keeps working unchanged. It is deprecated: new features land only in v2.
• v1 keys (asesia_sk_…) are not accepted by v2 and v2 credentials are not accepted by v1. Create a v2 credential with the equivalent scopes, switch the base URL to /api/v2, and move the company from the X-Workspace-Id header into the path (/companies/{companyId}/…).
• Field names change from the internal names to the v2 contract (e.g. nif → taxId, next_cursor → nextCursor), and errors move into the error object.
• v1 webhooks keep firing; re-register your endpoints as v2 webhooks to get the new events (invoice.issued, invoice.verifactu_status, model.ready…), pinned SSRF protection and the delivery log. Then delete the v1 endpoint to avoid duplicates.
• When every integration has moved, revoke the v1 keys.