Dallol ERP API Reference

Versioned REST API for invoices, customers, products, Debo Pay checkout links, partner portal embeds, and MoR EIMS registration. Each API key is isolated to one company.

Get API keys OpenAPI YAML

Quick start

1. Register your company on the public site. After approval you receive App ID, Secret, webhook secret, and portal identifiers by email — not MoR certificate bundles.
2. Sign in and open your company mini-site at /site/{slug} or branded login at /auth?site={slug}.
3. Create or rotate keys under Settings → API keys. Configure webhook URL and portal embed there.
4. Call GET /ping, then enable only the scopes you need.
5. Enable EIMS / MoR credentials later under company EIMS settings when you are ready to register fiscal invoices.

Authentication

Send the key and secret on every request. HTTPS is required in production.

Authorization: Bearer <key>:<secret>

# Alternative header format
X-API-Key: <key>
X-API-Secret: <secret>

Webhooks

Payment and status events are delivered to your company webhook URL with an HMAC signature (same pattern as Debo Pay). Verify the signature before trusting the payload.

X-DeboPay-Signature: t=<unix>,v1=<hmac_sha256>

# Verify: HMAC-SHA256 of "{t}.{raw_body}" using your webhook secret

Default ERP callback path: {{SITE_BASE}}/debopay/webhook. Store the per-company webhook secret shown when keys are provisioned.

Scopes

Scopes are checked for every protected operation. Prefer separate keys for separate integrations.

Endpoints

EIMS consumer (MoR portal)

Dallol EIMS is a separate MoR-facing service. It does not own the product catalog — it reads products and invoices from Dallol ERP via this API, then registers fiscal documents with the Ministry of Revenue.

List products from ERP

curl "https://dallolerp.com/api/v1/products?limit=50" \
 -H "Authorization: Bearer KEY:SECRET"

Fetch invoice then register with MoR

curl "https://dallolerp.com/api/v1/invoices/123" \
 -H "Authorization: Bearer KEY:SECRET"

curl -X POST "https://dallolerp.com/api/v1/invoices/123/register" \
 -H "Authorization: Bearer KEY:SECRET"

Configure ERP_API_BASE_URL on each EIMS environment to the matching ERP /api/v1 base (production EIMS → production ERP, etc.).

Portal embed (partner sites)

After company registration is approved you receive three identifiers for embedding a booking/order panel (same idea as Zemen Booking):

1. company_id — tenant id
2. app_id — API key (dak_…)
3. invoice_id — invoice parameter on create/pay calls

Public script (UI shell only; secrets stay server-side):

<script src="{{SITE_BASE}}/portal/embed.js"
  data-company-id="1"
  data-app-id="dak_…"
  data-invoice-id=""></script>

Server-side order create:

curl -X POST https://dallolerp.com/api/v1/portal/orders \
 -H "Authorization: Bearer KEY:SECRET" \
 -H "Content-Type: application/json" \
 -d '{"customer_id":1,"currency":"ETB","lines":[{"description":"Booking","quantity":1,"unit_price":1000,"tax_rate":15}]}'

Invoice examples

List recent invoices

curl "https://dallolerp.com/api/v1/invoices?status=draft&limit=25" \
 -H "Authorization: Bearer KEY:SECRET"

Create a draft invoice

curl -X POST https://dallolerp.com/api/v1/invoices \
 -H "Authorization: Bearer KEY:SECRET" \
 -H "Content-Type: application/json" \
 -d '{
   "customer_id": 1,
   "invoice_date": "2026-07-15",
   "due_date": "2026-07-30",
   "currency": "ETB",
   "lines": [
     {
       "description": "Sack of teff (50kg)",
       "quantity": 20,
       "unit_price": 4500,
       "tax_rate": 15
     }
   ]
 }'

Register with EIMS

curl -X POST https://dallolerp.com/api/v1/invoices/123/register \
 -H "Authorization: Bearer KEY:SECRET"

The company must have EIMS credentials configured. A successful response includes the fiscal IRN.

Create a payment link

curl -X POST https://dallolerp.com/api/v1/payments/link \
 -H "Authorization: Bearer KEY:SECRET" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": 108000,
   "email": "buyer@example.com",
   "phone": "+251900000000",
   "purpose": "invoice",
   "label": "Order #1042"
 }'

The response includes a unique reference, checkout_url, amount, and a base64 QR image suitable for rendering to the buyer.

Responses and errors

Successful responses contain success: true. Errors contain success: false and an explanatory error. Subscription denials can also include a machine-readable code.

Limits and security

• Invoice lists return at most 100 records per request.
• POST requests are throttled and may return 429 Too Many Requests.
• Failed login IP blocks and Fail2ban protect the admin surface.
• Do not automatically retry invoice creation unless your application has confirmed the previous request did not succeed.
• Log request references and HTTP status codes, but never log credentials or full sensitive payloads.

Production checklist

• Use HTTPS (api.dallolerp.com / erp.dallolerp.com) and validate the server certificate.
• Create a dedicated least-privilege key for each integration.
• Store credentials in a secret manager and establish a rotation process.
• Set connection/read timeouts and exponential retry only for safe operations.
• Test EIMS and payment flows in approved sandbox environments before enabling production.
• Monitor authentication failures, quota responses, fiscal rejections, and payment callbacks.