Integration API

Introduction

The integration API is source-system agnostic — it doesn't assume Protheus, SAP, RM, or any specific ERP. What speaks the language of a specific system is a connector (agent) that you maintain, outside of aprovaAI, translating between your system and this contract.

aprovaAI never initiates a connection to your system. It only receives authenticated calls and responds — fetching data from the source and writing the result back is your connector's responsibility.

A request created through this API behaves like any other from that point on: it goes through the workflow engine configured for the tenant, appears in aprovaAI's listings, generates in-app/push/email notifications for approvers, and has comments and history.

https://aprovaai.cyberpolos.net

Authentication

Each integration connection receives an API key in the format <connectionId>.<secret>, shown once when the credential is created — aprovaAI doesn't store or redisplay the secret in plain text after that. Send it on every call as a Bearer token:

Authorization: Bearer cm3xh2j4k0001abcd.k7f9QpX2yT8vR1nZmW3sLd

The credential only sees its own tenant, and can only create requests for types enabled for integration (see requestTypeKey in Create request). During the pilot, credentials are issued by the aprovaAI team — talk to your contact to get yours.

Idempotency

Every created request is identified by the externalSystem + externalRef pair you send. If your connector resends the same creation — due to a retry after a timeout, or reprocessing — aprovaAI never duplicates it: it returns the existing request.

Errors

Every error response (4xx/5xx) follows the same format, with a stable code for programmatic handling and a readable message:

{
  "error": {
    "code": "requester_not_found",
    "message": "No user with this email in this tenant."
  }
}

Most common codes, across endpoints:

Endpoints

curl -X POST https://aprovaai.cyberpolos.net/api/integrations/requests \
  -H "Authorization: Bearer <connectionId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSystem": "protheus",
    "externalRef": { "branch": "01", "docType": "SC7", "key": "000123" },
    "requestTypeKey": "purchase_order",
    "title": "Purchase Order 000123 — Dell Brazil",
    "amountCents": 600000,
    "requesterEmail": "requester@company.com",
    "customFields": { "vendor": "Dell Brazil", "justification": "Laptops for the team" }
  }'

{
  "requestId": "cmr1a2b3c4d5",
  "status": "pending",
  "url": "https://aprovaai.cyberpolos.net/requests/cmr1a2b3c4d5"
}

curl "https://aprovaai.cyberpolos.net/api/integrations/decisions?since=$CURSOR" \
  -H "Authorization: Bearer <connectionId>.<secret>"

{
  "decisions": [
    {
      "requestId": "cmr1a2b3c4d5",
      "externalSystem": "protheus",
      "externalRef": { "branch": "01", "docType": "SC7", "key": "000123" },
      "status": "approved",
      "decidedAt": "2026-07-19T18:00:00Z",
      "decidedExternally": false,
      "history": [
        { "step": "Manager Approval", "decision": "approved",
          "approverEmail": "manager@company.com", "comment": null }
      ]
    }
  ],
  "nextCursor": "MjAyNi0wNy0xOVQxODowMDowMC4wMDBafGNtcjFhMmIzYzRkNQ"
}

{ "ok": true, "tenant": "demo-company", "connection": "Production ERP" }

curl -X POST https://aprovaai.cyberpolos.net/api/integrations/requests/cmr1a2b3c4d5/status \
  -H "Authorization: Bearer <connectionId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled",
    "reason": "Order cancelled by the buyer directly in Protheus"
  }'

{ "requestId": "cmr1a2b3c4d5", "status": "cancelled" }

Approval via API

Approving a request without going through aprovaAI's named approvers is a governance decision, not just a technical one — by default, this credential cannot do that. allowExternalApproval = false

When explicitly enabled for a credential, an approval sent via POST .../status still counts as approved in all flows and reports, but is flagged as decidedExternally: true and visually highlighted in aprovaAI's interface — distinct from an approval that went through the workflow's approvers.

Recommended integration flow

1. Store the API key you receive securely — it isn't shown again.
2. Translate each document from your system into the POST /requests payload (how fields map is specific to your source system).
3. Store locally the relationship between the document's key at the source and the returned requestId.
4. Poll GET /decisions periodically, persisting the nextCursor on every call.
5. Apply the decision back in your system, with your own retry logic — aprovaAI doesn't know whether that write succeeded.
6. If the source document is cancelled, denied, or approved outside aprovaAI after being synced, call POST .../status to reflect it — without this step, the request stays pending indefinitely.