Generate File Upload Link (Atlas)

Overview

The POST /banking/ibans/v2/documents/generate-upload-link endpoint generates a temporary, pre-signed S3 upload URL. Clients can upload supporting documents (such as invoices, bills of lading, contracts, or identity documentation) directly to cloud storage without routing binary streams through the API gateway.

Upload Constraints

• Expiration: The upload link is valid for 10 minutes.
• Supported Formats: jpeg, jpg, pdf, png, svg.
• Maximum File Size: 5 MB.
• Subsequent Binding: The returned key string should be provided in supportingDocS3Key when creating payments (/payments/create) or FX trades (/fx/payments).

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/documents/generate-upload-link
• Authentication: Bearer token required
• Permissions: Admin:Exchange Now:read, Client:At Desired Rate:read, Admin:Exchange Later:read, Client:At Ahrvo Rate:read

Query Parameters

Parameter	Type	Required	Description	Example
companyId	string	No	Admin only: specifies target company ID to map the file directory.	45248

Request Body

Request Fields

Field	Type	Required	Description
fileName	string	Yes	Name of the file including extension (5 to 100 chars, e.g. invoice-12345.pdf).
documentInfo	object	No	Metadata linking the document to an entity.
documentInfo.source	string	No	Source category (e.g. user).
documentInfo.reference	string	No	Associated order or payment reference (e.g. TO-29072023-114).
documentInfo.entity	string	No	Entity category (e.g. order).
documentInfo.userRecordId	integer	No	User ID submitting the document (e.g. 2669).

Request Example

{
  "fileName": "invoice-august-2023.pdf",
  "documentInfo": {
    "source": "user",
    "reference": "TO-29072023-114",
    "entity": "order",
    "userRecordId": 2669
  }
}

---

Response

Success Response (200 OK)

{
  "link": "https://s3.amazonaws.com/ahrvo-docs-bucket/uploads/TO-29072023-114-invoice.pdf?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D&Expires=1690646400",
  "key": "documents/2023/07/TO-29072023-114-invoice.pdf"
}

Response Fields

Field	Type	Description
link	string	Secure pre-signed HTTPS upload URL valid for 10 minutes. Send an HTTP PUT request with binary file data to this URL.
key	string	Storage identifier key. Pass this in supportingDocS3Key on subsequent payment requests.

---

Two-Step Document Upload Flow

sequenceDiagram
    autonumber
    Client->>Atlas API: POST /documents/generate-upload-link
    Atlas API-->>Client: 200 OK (link, key)
    Client->>S3 Storage: PUT {link} with binary file body
    S3 Storage-->>Client: 200 OK (Uploaded)
    Client->>Atlas API: POST /payments/create (supportingDocS3Key = key)
    Atlas API-->>Client: 201 Created (Payment Confirmed)

---

Code Examples

cURL

# Step 1: Request pre-signed URL
curl -X POST "https://api.ahrvo.network/banking/ibans/v2/documents/generate-upload-link" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "invoice.pdf",
    "documentInfo": {
      "source": "user",
      "reference": "TO-29072023-114",
      "entity": "order"
    }
  }'

# Step 2: Upload file directly to S3
curl -X PUT "PRESIGNED_LINK_FROM_STEP_1" \
  -H "Content-Type: application/pdf" \
  --data-binary "@./invoice.pdf"

JavaScript (Node.js)

import fs from 'fs';

// 1. Get pre-signed URL
const linkRes = await fetch('https://api.ahrvo.network/banking/ibans/v2/documents/generate-upload-link', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ fileName: 'invoice.pdf' })
});

const { link, key } = await linkRes.json();

// 2. Upload file directly to storage
const fileStream = fs.readFileSync('./invoice.pdf');
await fetch(link, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: fileStream
});

console.log('Upload complete. Use key in payment creation:', key);

---

Interactive API Console

Test the endpoint directly in your browser: