ApoloFX Business API reference

Overview

The API is organized around predictable, resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP verbs and status codes. Every request is scoped to a company and a branch, so the same credentials can operate multiple branches. All amounts are decimal numbers in the currency indicated by the resource; timestamps are ISO 8601 with timezone.

• ✓ JSON over HTTPS, resource-oriented REST.
• ✓ Scoped by company and branch — one integration, many branches.
• ✓ Idempotent writes via an Idempotency-Key header (recommended for POST).
• ✓ Every operation is traceable and reflected across inventory, cash and accounting.

Base URL

All endpoints are relative to the base URL below. Only HTTPS is supported.

https://api.apolofx.com/v1

Authentication

Requests are authenticated with an API key issued from your ApoloFX Business account (staff role with API access). Send it as a Bearer token in the Authorization header. Keep your key server-side; never expose it in a browser or mobile app. Keys are scoped to a company and can be restricted per branch and per permission.

Authorization: Bearer sk_live_<your_api_key>
Content-Type: application/json

Endpoints

A preview of the endpoints that power the app. Each shows a sample request and response; fields may still change during beta.

GET /v1/rates?branch=bogota&base=USD

200 OK
{
  "branch": "bogota",
  "base": "USD",
  "quote": "COP",
  "buy": 3985.00,
  "sell": 4010.00,
  "updated_at": "2026-09-22T14:30:00-05:00"
}

POST /v1/transactions
{
  "branch": "bogota",
  "type": "sell",
  "base": "USD",
  "quote": "COP",
  "amount": 500.00,
  "client_id": "cli_8Q2K"
}

201 Created
{
  "id": "txn_9F3A2C",
  "type": "sell",
  "base": "USD",
  "quote": "COP",
  "amount": 500.00,
  "rate": 4010.00,
  "total": 2005000.00,
  "status": "settled",
  "created_at": "2026-09-22T14:32:10-05:00"
}

GET /v1/inventory?branch=bogota

200 OK
{
  "branch": "bogota",
  "balances": [
    { "currency": "USD", "amount": 42000.00, "avg_cost": 3970.15 },
    { "currency": "EUR", "amount": 8500.00, "avg_cost": 4310.40 }
  ]
}

POST /v1/invoices
{
  "transaction_id": "txn_9F3A2C",
  "client_id": "cli_8Q2K"
}

201 Created
{
  "id": "inv_00184",
  "transaction_id": "txn_9F3A2C",
  "cufe": "a1b2c3...",
  "status": "accepted",
  "issued_at": "2026-09-22T14:33:02-05:00"
}

GET /v1/clients/cli_8Q2K

200 OK
{
  "id": "cli_8Q2K",
  "name": "Comercial Andina S.A.S.",
  "doc_type": "NIT",
  "doc_number": "900123456",
  "dian_address": "CL 100 15 20, Bogota"
}

POST /v1/webhooks
{
  "url": "https://your-app.com/hooks/apolofx",
  "events": ["inventory.low", "reservation.created", "invoice.issued"]
}

201 Created
{
  "id": "whk_5T1B",
  "url": "https://your-app.com/hooks/apolofx",
  "events": ["inventory.low", "reservation.created", "invoice.issued"],
  "secret": "whsec_<sign_your_payloads>"
}

Errors

The API uses conventional HTTP status codes. 2xx means success, 4xx means the request was rejected (with a machine-readable code and a human message), and 5xx means something failed on our side. Error bodies share the same shape:

{
  "error": {
    "code": "insufficient_inventory",
    "message": "Not enough USD in branch bogota to settle this sell."
  }
}

Webhooks

Subscribe a URL to receive events as they happen, instead of polling. Each delivery is a POST with a JSON body and a signature header you verify with the subscription secret. We retry failed deliveries with exponential backoff.

• inventory.low A currency balance in a branch dropped below its minimum.
• reservation.created A client reserved an amount at a quoted rate.
• invoice.issued An electronic invoice was accepted by the DIAN.
• transaction.settled A buy/sell operation was settled.

POST https://your-app.com/hooks/apolofx
X-ApoloFX-Signature: t=1758561182,v1=5c9f...

{
  "id": "evt_7K2M",
  "type": "inventory.low",
  "created_at": "2026-09-22T14:40:00-05:00",
  "data": { "branch": "bogota", "currency": "USD", "amount": 1200.00, "minimum": 5000.00 }
}