Getting Started#

This guide walks you through authenticating with the Moloni ON API and making your first requests. The API uses GraphQL for all data operations, and supports two authentication methods:

• OAuth 2.0 (via API Clients): for web applications that act on behalf of a user
• API Keys (via API Keys): for machine-to-machine integrations with no user interaction

What is GraphQL?#

GraphQL is a query language for APIs that lets you request exactly the data you need in a single request. Unlike REST, where each endpoint returns a fixed structure, GraphQL uses a single endpoint and you specify the fields you want in your query.

Key concepts:

• Queries read data (similar to GET in REST)
• Mutations create, update or delete data (similar to POST/PUT/DELETE)
• You choose which fields to return, avoiding over-fetching

If you're new to GraphQL, these resources are a good starting point:

• Introduction to GraphQL: Official GraphQL documentation
• GraphQL Queries and Mutations: How to read and write data

Prerequisites#

• A Moloni ON account (sign up here)
• The API Access module enabled on your company (only required for company-related endpoints)

Choosing an authentication method#

If you're building a web application where users log in and interact, use an API Client with the OAuth 2.0 flow.

If you need a server or script to access the API without user interaction (e.g. syncing data, automated reports), use an API Key.

Using the API#

Regardless of the authentication method, all requests go to a single endpoint:

POST https://api.molonion.pt/v1

With the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Where YOUR_TOKEN is either an OAuth access token or an API key.

Response Structure#

All queries and mutations return a consistent shape:

{
  "data": {
    "queryName": {
      "errors": [],
      "data": { ... }
    }
  }
}

• errors: an array of validation errors (empty on success). Each error has a field and msg.
• data: the result object (single item) or array (list endpoints).

List endpoints also include an options object with pagination info.

Example: Query Customers#

query {
  customers(companyId: 1) {
    errors { field msg }
    data {
      customerId
      name
      vat
    }
  }
}

Example: Create a Customer#

mutation {
  customerCreate(companyId: 1, data: {
    vat: "987654321"
    number: "C002"
    name: "Acme Lda"
    countryId: 1
    languageId: 1
  }) {
    errors { field msg }
    data {
      customerId
      name
      vat
      number
    }
  }
}

Example: Delete#

mutation {
  customerDelete(companyId: 1, customerId: [42]) {
    status
    deletedCount
    errors { field msg }
  }
}

See the Deletion guide for details on bulk deletion, deletability checks, and document deletion rules.

Next steps#

• API Clients: Set up OAuth 2.0 authentication for web applications
• API Keys: Set up API keys for machine-to-machine integrations
• Schema & Tooling: Point your IDE and code generators at the schema
• Creating an Invoice: Create your first document
• Paying an Invoice: Record a payment with a receipt
• Explorer: Try queries live in the GraphiQL interface
• API Reference: Browse the full API