Developer

API Integration Guide

Create API keys, sync payment profiles, and let your ERP issue invoices safely with idempotent requests.

Manage API keys Download Postman collection

Quickstart

Go from account signup to invoice creation in minutes.

Base URL

https://invoicegen.dawnsynch.co.ke/api/v1

Required headers

Authorization: Bearer <token>

Accept: application/json

Idempotency-Key: unique-key

Recommended key scopes

Read customers Manage customers Read payment profiles Create invoices Read invoices Create statements Read statements Send statements

This set gives an ERP enough access to list payment profiles, sync customers, create invoices, and fetch PDFs without over-provisioning.

01

Create an API key

Open Profile, create a named key like ERP Production, and copy the token once.

02

Fetch payment profiles

Use payment-information endpoints to choose the currency/remittance profile you want tied to the invoice.

03

Sync your customer

Create or update the customer your ERP is billing before invoice creation.

04

Create the invoice

Send the invoice payload with an Idempotency-Key so retries never create duplicates.

Reference

Production API surface

Every endpoint below is designed for account-scoped integrations. Use the narrowest possible scopes per environment and keep one key per integration surface.

Authentication

Method Path Required scope What it does
POST /register Public Create a new account and start onboarding.
POST /login Public Issue a login session or API token flow for first-party access.
GET /me Authenticated Inspect the current account context.
POST /logout Authenticated Revoke the current authenticated session or token.

Customers

Method Path Required scope What it does
GET /customers customers:read List customers owned by the authenticated account.
POST /customers customers:write Create a customer, with duplicate prevention per account.
GET /customers/{id} customers:read Fetch one customer for ERP sync or reconciliation.
PUT /customers/{id} customers:write Update a customer owned by the account.
DELETE /customers/{id} customers:write Delete a customer that is no longer needed.

Payment information

Method Path Required scope What it does
GET /payment-information payment-information:read List remittance profiles by currency.
POST /payment-information payment-information:write Create a remittance profile and optionally make it default.
GET /payment-information/{id} payment-information:read Get one payment profile for reference.
PUT /payment-information/{id} payment-information:write Update bank/remittance details.
DELETE /payment-information/{id} payment-information:write Delete an unused payment profile.

Statements

Method Path Required scope What it does
POST /customers/{id}/statements statements:create Generate a statement for a customer from selected eligible commercial invoices.
GET /statements/{id} statements:read Fetch one generated statement in structured JSON form.
GET /statements/{id}/pdf statements:read Download the rendered statement PDF for archiving or delivery workflows.
POST /statements/{id}/email statements:send Email a generated statement PDF together with each selected invoice PDF attachment.

Invoices

Method Path Required scope What it does
GET /invoices invoices:read List invoices with related customer, totals, and payment profile data.
POST /invoices invoices:create Create an invoice safely with idempotency support.
GET /invoices/{id} invoices:read Inspect one invoice in structured JSON form.
PUT /invoices/{id} invoices:create Update an existing invoice owned by the account.
DELETE /invoices/{id} invoices:create Delete an invoice that should not remain in the system.
GET /invoices/{id}/pdf invoices:read Download the rendered PDF version for archival or ERP attachment workflows.

Create payment profile

Set invoice currency through payment information

curl --request POST 'https://invoicegen.dawnsynch.co.ke/api/v1/payment-information' \
  --header 'Authorization: Bearer ig_live_replace_with_your_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "currency": "USD",
    "account_name": "Example Trading Co.",
    "bank_name": "Demo Bank",
    "account_number": "000123456789",
    "swift_code": "DEMOUS33",
    "instructions": "Use invoice number as payment reference.",
    "is_default": true
  }'

Create customer

Sync the billing party first

curl --request POST 'https://invoicegen.dawnsynch.co.ke/api/v1/customers' \
  --header 'Authorization: Bearer ig_live_replace_with_your_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Example Trading Co.",
    "company_name": "Example Trading Co.",
    "email": "ap@example.test",
    "phone": "+1555010100",
    "address": "123 Example Street\nTestville TS 10001"
  }'

Create invoice

Use idempotency for ERP-safe retries

curl --request POST 'https://invoicegen.dawnsynch.co.ke/api/v1/invoices' \
  --header 'Authorization: Bearer ig_live_replace_with_your_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: erp-sync-20260514-0001' \
  --data '{
    "customer_id": 12,
    "payment_information_id": 3,
    "invoice_number": "INV-TEST-1001",
    "invoice_type": "commercial",
    "awb": "AWB-TEST-0001",
    "issue_date": "2026-05-14",
    "due_date": "2026-05-28",
    "tax_enabled": false,
    "status": "pending",
    "items": [
      {
        "name": "Sample consulting package",
        "description": "Demonstration line item",
        "quantity": 1,
        "unit_price": 1500
      }
    ]
  }'

Leave invoice_number out if you want InvoiceGen to generate it automatically. Every item should always include both a name and a description.

Create proforma invoice

Proforma items must include weights

curl --request POST 'https://invoicegen.dawnsynch.co.ke/api/v1/invoices' \
  --header 'Authorization: Bearer ig_live_replace_with_your_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: erp-sync-20260514-0001-proforma' \
  --data '{
    "customer_id": 12,
    "payment_information_id": 3,
    "invoice_type": "proforma",
    "issue_date": "2026-05-14",
    "due_date": "2026-05-28",
    "tax_enabled": false,
    "status": "pending",
    "items": [
      {
        "name": "Sample export item",
        "description": "Demonstration cargo line",
        "quantity": 10,
        "net_weight": 1000,
        "gross_weight": 1100,
        "unit_price": 45
      }
    ]
  }'

Operational notes

How the API behaves in production

Idempotent invoice creation

Reusing the same Idempotency-Key with the same payload replays the original invoice response instead of creating duplicates.

Request tracing

Every successful API response includes an X-Request-Id header so your ops team can match ERP logs to InvoiceGen requests.

Currency derivation

Invoices inherit currency from the chosen payment profile. Your ERP should select the right payment_information_id instead of sending freeform currency strings.

Scope-aware keys

Create separate keys for staging and production. Use the smallest scope set each integration needs so revocation stays safe and low-risk.

Response shape

Structured JSON, ready for ERP parsers

{
  "data": {
    "id": 42,
    "invoice_number": "INV-010042",
    "invoice_type": "commercial",
    "currency": "USD",
    "status": "pending",
    "customer": { ... },
    "payment_information": { ... },
    "items": [ ... ],
    "totals": {
      "subtotal": "2340.00",
      "tax": "0.00",
      "total": "2340.00"
    }
  }
}

Error handling

Status codes you should wire into your integration logic

200 OK

Request succeeded and returned a normal response body.

201 Created

A resource such as a customer, payment profile, or invoice was created successfully.

401 Unauthorized

The bearer token is missing, revoked, or invalid.

403 Forbidden

The API key does not have the required scope for the action.

409 Conflict

The same Idempotency-Key was reused with a different request payload.

422 Unprocessable Entity

Validation failed and the response body contains field-level errors.

429 Too Many Requests

Rate limits for the key or route were exceeded.

Recommended rollout

Integration checklist for production launch

  1. Create separate API keys for staging and production, each with the minimum required scopes.
  2. Store the bearer token securely in your ERP or secret manager, never in client-side code.
  3. Use one new Idempotency-Key per invoice creation attempt, and reuse it only for safe retries of the exact same payload.
  4. Log the returned invoice ID and X-Request-Id in your ERP for support and reconciliation.
  5. Validate payment profile and customer ownership in staging before automating production invoice issuance.