The Management API enables you to self-service and automate the creation and management of companies and connectors. This API provides the capability to add new companies to your partner account with complete business details and to change existing company information. You can also create new messaging API or Hypertext transfer protocol secure (HTTPS) connectors for your companies, update existing connectors, and set up connectors using scenarios.

sequenceDiagram
  participant P as Partner/Client
  participant E as ecosio
  
  %% 1. Create Company Workflow
  P->>E: POST /api/v1/management/companies (Create Company)
  activate P
  activate E
  E-->>E: Invoke approval process
  E-->>P: {{managedCompanyUuid}}<br>{{approvalUuid}}
  deactivate P
  
  loop Poll company approval
      P->>E: GET /api/v1/management/approvals/{{approvalUuid}} (Get status)
      activate P
      E-->>P: {{status}}<br>{{reason}}
      deactivate P
      Note over P: Loop continues if status is PENDING
  end
  deactivate E
  
  opt Status is APPLIED
      Note over P: Company creation approved
      
      %% 2. Create Connector Workflow
      P->>E: POST /api/v1/management/connectors (Create a connector)
      activate P
      activate E
      E-->>E: Invoke approval process
      E-->>P: {{managedConnectorUuid}}<br>{{connectorUuid}}
      deactivate P
      
      loop Poll connector approval
          P->>E: GET /api/v1/management/approvals/{{approvalUuid}} (Get status)
      activate P
          E-->>P: {{status}}<br>{{reason}}
          deactivate P
          Note over P: Loop continues if status is PENDING
      end
      deactivate E

      %% 3. Apply Scenario Workflow
      P->>E: POST /api/v1/management/scenarios (Apply a scenario)
      activate P
      activate E
      E-->>E: Invoke approval process
      E-->>P: {{approvalStatus}}<br>{{rejectionReason}}
      deactivate P
      
      loop Poll scenario approval
          P->>E: GET /api/v1/management/approvals/{{approvalUuid}} (Get status)
          activate P
          E-->>P: {{status}}<br>{{reason}}
          deactivate P
          Note over P: Loop continues if status is PENDING
      end
      deactivate E
  end
  
  opt Status was REJECTED
      Note over P: Workflow terminates due to rejection
  end

Prerequisites

To use the Management API, you must:

• Have a valid ecosio partner account.
• Be able to authenticate with the ecosio API.

Companies

You can create a company by calling Create a company. When creating a company, you can add up to three levels of sub-companies to your account. Companies are automatically created directly under your partner account. To create a sub-company for another company under your partner account, provide the company ID for the companyUuid parameter. You can call Find Companies to get your sub-company IDs. You can also add company aliases, such as GLNs and Peppol participant IDs. To update an existing company, call Update a company.

Connectors

Use the Management API to create, configure, and manage connectors for your companies. You can choose from messaging API or HTTPS connectors. HTTPS connectors enable your ERP or business software to receive messages from ecosio. When you create a connector using the API, you define its configuration, including the type and direction. You can also modify an existing connector to update its functionality or change its associated companies.

Scenarios

Scenarios automatically apply country-specific mappings, required permissions, and connector configurations, enabling the quick creation of pre-configured connector setups.

You can also call List all scenarios to display a list of the names of available scenarios. Scenarios are currently available for the following countries, which creates the relevant e-invoicing connector.

Approval status

When you create or update a company or connector, a request is sent to ecosio for review. The API response includes the request’s ID. You can then call Get the status of the approval by its approval-UUID to retrieve the status of the request. If a request is rejected, the response will contain feedback explaining the reason.