Alya Books

    Developer docs

    REST API, webhooks, MCP server and CLI for UAE e-invoicing

    GuidesAPI reference

    Projects

    Group invoices, quotes and incoming invoices by project and read totals per project.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    A project is a first-class resource with a code, a customer, a status, dates and a budget. Its code doubles as the PINT AE project reference (BT-11, cac:ProjectReference/cbc:ID) on invoices.

    Routes

    curl "$BASE/projects?status=active&includeTotals=true" -H "X-API-KEY: $KEY"
curl -X POST "$BASE/projects" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Tower A fit-out", "customerId": "…", "startDate": "2027-01-01", "budget": 250000 }'
curl "$BASE/projects/{id}/documents" -H "X-API-KEY: $KEY"
curl "$BASE/projects/{id}/invoices?paymentStatus=unpaid" -H "X-API-KEY: $KEY"
    FieldNotes
    codeUnique per organization. Allocated from the project number series when omitted (P-{n} by default).
    name, nameAr, description, colorDisplay
    customerIdOptional contact
    statusactive (default), on_hold, completed, archived
    startDate, endDate, budget, currencyPlanning data
    metadataFree JSON
    totals (response)invoiceCount, invoicedTotal (issued invoices minus credit notes), paidTotal, outstandingTotal, incomingCount, incomingTotal (accepted supplier invoices), quoteCount. Test and archived documents are excluded.

    DELETE /projects/{id} deletes a project without documents; a project with linked documents is archived instead (archived: true).

    Linking documents

    • POST /invoices: set projectId on the input. projectReference (BT-11) defaults to the project code and can be overridden. PATCH /invoices/{id} accepts projectId on issued invoices as well (it is housekeeping data, not part of the reported XML).
    • GET /invoices?projectId= filters the list; projectId=none returns invoices without a project.
    • Creating a project whose code matches existing projectReference values links those invoices automatically.
    • Recurring invoices carry projectId and pass it to every generated invoice.

    Webhooks and MCP

    project.created fires on creation. MCP tools: list_projects, get_project, create_project, update_project, delete_project, list_project_documents.