moegoapis

MoeGo APIs

This repository contains the original interface definitions of public MoeGo APIs that support REST protocols. Reading these definitions helps you better understand the MoeGo APIs and use them more efficiently. You can also use these definitions with open-source tools to generate client libraries, documentation, and other artifacts.

[TOC]

📚 Documentation

📘 View Full API Documentation - Comprehensive documentation hosted on GitHub Pages

The documentation includes detailed guides for all API modules, integration examples, and best practices for using MoeGo APIs.

Try it now

Run In Postman

Click the Run in Postman button to try out the MoeGo APIs using Postman — a popular API client that makes it easy to explore and test APIs without writing any code.

Note: Replace the collection Authorization ${Base_64_API_Key} with your own API Key encoded in Base64.

📌 Important Notes

🚀 Getting Started

To begin using the MoeGo APIs effectively, follow these steps:

  1. Request API Access

    • For all API key requests, we kindly ask you to work directly with your dedicated Customer Success Manager. They will guide you through our API key application process.

  2. Retrieve Required Information

    • Use the ListCompany and ListBusiness APIs to retrieve the necessary obfuscated IDs (CompanyID, BusinessID) and verify that your requests are targeting the correct entities.

  3. Validate with Postman

    • Use the Postman collection to test and validate API calls before integrating them into your application.
    • Replace the placeholder authorization token with your Base64-encoded API key.
    • Review example requests and responses to understand API behavior and expected data formats.

  4. Explore OpenAPI Specifications

    • Check the OpenAPI specifications to understand detailed API contracts, including request/response schemas, error codes, and endpoint parameters.
    • Use these specifications with tools like Swagger UI or OpenAPI Generator to create client SDKs in your preferred programming language.

  5. (Optional) Use Example Scripts

    • Use the provided example scripts like export_orders.py to quickly get started with common tasks such as exporting order data to CSV format.

  6. (Optional) Configure Webhooks

    • Set up Webhooks to subscribe to events you care about, such as APPOINTMENT_CREATED or APPOINTMENT_UPDATED. This enables real-time notifications for key business events.

API Changelog

After completing API changes, update docs/CHANGELOG.md to document them.

AI-Assisted Workflow

Use this prompt to auto-generate changelog entries:

Read the file docs/CHANGELOG.md to understand the format.
Then analyze this git diff and update the CHANGELOG.md [Unreleased] section:

[PASTE THE GIT DIFF OUTPUT HERE]

Requirements:
1. Only include API-visible changes (endpoints, fields, error codes)
2. Classify changes as MAJOR (breaking), MINOR (additions), or PATCH (fixes)
3. Use existing format with categories: Added/Changed/Deprecated/Removed/Fixed
4. Be concise and clear
5. Replace the [Unreleased] N/A entries with actual changes
6. Write the complete updated [Unreleased] section

Return only the updated [Unreleased] section content.

Copy the AI output and replace the [Unreleased] section in docs/CHANGELOG.md.

Version Types

For full details, see docs/CHANGELOG.md and docs/versioning/README.md.

🌐 Domain Structure

MoeGo APIs are organized under the following domain:

openapi.moego.pet

Each path corresponds to a specific version and resource:

Each module includes multiple APIs for handling different use cases such as authentication, data management, and event notifications.

📦 Core Modules Overview

🔐 Authentication & Authorization

👥 Customer & Pet Management

📅 Scheduling & Availability

💰 Orders & Payments

🛒 Retail & Inventory Management

👥 Membership & Packages

⚙️ Settings & Integrations

📋 Agreements & Feedback

📊 Reporting & Analytics

🧩 Common Data Models

🔄 Webhook Integration

Webhooks provide an efficient way to receive real-time updates when certain events occur within the MoeGo system. Key features include:

For more details:

📄 OpenAPI Specifications

To better support developers using MoeGo APIs, we have added corresponding openapi.json files under the docs/openapi directory. These files are generated based on the Protocol Buffer definitions and provide comprehensive interface descriptions for REST APIs, including request paths, parameters, and response formats.

With these OpenAPI specifications, developers can:

It is recommended to refer to the corresponding module documentation ( e.g., Customer, Appointment) alongside the OpenAPI files for a more complete understanding.

Each JSON file corresponds to a core module and follows the OpenAPI 3.0 specification, making it easy to integrate into various development toolchains.

📛 Common Error Responses

When using the MoeGo APIs, you may encounter the following common error responses:

Invalid Obfuscated ID

{
    "code": 13,
    "message": "invalid obfuscate",
    "details": []
}

This error occurs when you use an incorrectly formatted ID that does not conform to the expected obfuscation format.

No Permission to Access Resource

{
    "code": 7,
    "message": "no permission to access the resource",
    "details": []
}

This error occurs when you do not have permission to access the corresponding ID.

Unauthorized Access to Resources

{
  "code":  16,
  "message":  "Authentication failed. Cause: no authorization found in headers. please check your credentials and try again."
}

This error occurs when you use an incorrect API Key.