openapi: 3.1.0
info:
  title: SAP Ariba Procurement Invoices Suppliers API
  description: Enables integration with SAP Ariba procurement processes including purchase orders, invoices, requisitions, receipts, and supplier management across the SAP Business Network. This API supports the complete procure-to-pay lifecycle from requisition creation through invoice reconciliation and payment processing.
  version: 1.0.0
  contact:
    name: SAP Ariba API Support
    url: https://developer.ariba.com
    email: support@ariba.com
  license:
    name: SAP Developer License
    url: https://www.sap.com/about/legal/developer-license.html
  termsOfService: https://www.ariba.com/legal/terms-of-use
  x-sap-api-type: REST
  x-sap-shortText: Procurement API for purchase orders, invoices, and suppliers
  x-sap-stateInfo:
    state: Active
  x-documentation:
  - url: https://help.sap.com/docs/ariba-apis
    description: SAP Help Portal - Ariba APIs
  - url: https://api.sap.com/package/SAPAribaOpenAPIs/rest
    description: SAP Business Accelerator Hub
  - url: https://help.sap.com/docs/ariba-apis/operational-reporting-api-for-procurement/operational-reporting-api-for-procurement
    description: Operational Reporting API for Procurement
servers:
- url: https://openapi.ariba.com/api/procurement/v1
  description: SAP Ariba Production API Server
- url: https://sandbox.ariba.com/api/procurement/v1
  description: SAP Ariba Sandbox API Server
security:
- oauth2: []
tags:
- name: Suppliers
  description: Access and manage supplier profiles, onboarding, qualifications, performance, and risk assessments on the SAP Ariba Network.
paths:
  /suppliers:
    get:
      operationId: listSuppliers
      summary: List Suppliers
      description: Retrieves a paginated list of supplier profiles from the SAP Ariba Network. Supports filtering by supplier name, AN-ID, qualification status, commodity codes, and location.
      tags:
      - Suppliers
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        description: OData-style filter expression
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: Search suppliers by name (partial match supported)
        required: false
        schema:
          type: string
      - name: qualificationStatus
        in: query
        description: Filter by supplier qualification status
        required: false
        schema:
          $ref: '#/components/schemas/SupplierQualificationStatus'
      - name: commodityCode
        in: query
        description: Filter by UNSPSC commodity code
        required: false
        schema:
          type: string
      - name: country
        in: query
        description: Filter by supplier country (ISO 3166-1 alpha-2)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved list of suppliers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /suppliers/{supplierId}:
    get:
      operationId: getSupplier
      summary: Get a Supplier Profile
      description: Retrieves the complete profile details of a specific supplier including company information, contact details, addresses, certifications, commodity classifications, and qualification status.
      tags:
      - Suppliers
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - name: supplierId
        in: path
        description: Supplier AN-ID (Ariba Network ID) or internal supplier identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved supplier profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Supplier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    RealmParam:
      name: realm
      in: query
      description: The SAP Ariba realm identifier for the buyer organization. This is the unique site name assigned during provisioning.
      required: true
      schema:
        type: string
    SkipParam:
      name: skip
      in: query
      description: Number of records to skip for pagination (default 0)
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    LimitParam:
      name: limit
      in: query
      description: Maximum number of records to return per page (default 10, max 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  schemas:
    SupplierQualificationStatus:
      type: string
      description: Supplier qualification status on the Ariba Network
      enum:
      - Qualified
      - Conditional
      - NotQualified
      - PendingReview
      - Expired
    ContactInfo:
      type: object
      description: Contact information for a person or department
      properties:
        name:
          type: string
          description: Contact person name
          example: Example Title
        email:
          type: string
          format: email
          description: Contact email address
          example: user@example.com
        phone:
          type: string
          description: Contact phone number
          example: example_value
        fax:
          type: string
          description: Contact fax number
          example: example_value
        department:
          type: string
          description: Department name
          example: example_value
    Money:
      type: object
      description: Monetary amount with currency code following ISO 4217
      required:
      - amount
      - currencyCode
      properties:
        amount:
          type: number
          format: double
          description: The monetary value
          examples:
          - 1250.0
        currencyCode:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
          examples:
          - USD
          - EUR
          - GBP
    Supplier:
      type: object
      description: Complete supplier profile on the SAP Ariba Network including company information, classifications, and qualification details
      required:
      - supplierId
      - name
      properties:
        supplierId:
          type: string
          description: Unique supplier identifier (AN-ID)
          examples:
          - AN01000000001
        name:
          type: string
          description: Legal company name
          example: Example Title
        doingBusinessAs:
          type: string
          description: Trade name or DBA name
          example: example_value
        dunsNumber:
          type: string
          description: Dun and Bradstreet DUNS number
          pattern: ^\d{9}$
          example: example_value
        taxId:
          type: string
          description: Tax identification number
          example: '500123'
        yearEstablished:
          type: integer
          description: Year the company was established
          example: 10
        numberOfEmployees:
          type: string
          description: Employee count range
          enum:
          - 1-50
          - 51-200
          - 201-500
          - 501-1000
          - 1001-5000
          - 5001-10000
          - 10000+
          example: 1-50
        annualRevenue:
          $ref: '#/components/schemas/Money'
        qualificationStatus:
          $ref: '#/components/schemas/SupplierQualificationStatus'
        registrationStatus:
          type: string
          description: Registration status on the Ariba Network
          enum:
          - Active
          - Pending
          - Suspended
          - Inactive
          example: Active
        address:
          $ref: '#/components/schemas/Address'
        primaryContact:
          $ref: '#/components/schemas/ContactInfo'
        commodityCodes:
          type: array
          description: UNSPSC commodity codes the supplier serves
          items:
            $ref: '#/components/schemas/CommodityCode'
          example: []
        certifications:
          type: array
          description: Supplier certifications and compliance credentials
          items:
            type: object
            properties:
              type:
                type: string
                description: Certification type
                examples:
                - ISO9001
                - ISO14001
                - MBE
                - WBE
                - SDVOSB
              name:
                type: string
                description: Full certification name
              issuingBody:
                type: string
                description: Organization that issued the certification
              expirationDate:
                type: string
                format: date
                description: Certification expiration date
              status:
                type: string
                enum:
                - Active
                - Expired
                - Pending
          example: []
        diversityClassifications:
          type: array
          description: Supplier diversity classifications
          items:
            type: string
          example: []
        website:
          type: string
          format: uri
          description: Company website URL
          example: https://www.example.com
        description:
          type: string
          description: Company description
          example: A sample description.
        createdDate:
          type: string
          format: date-time
          description: Date the supplier profile was created
          example: '2026-01-15T10:30:00Z'
        lastModifiedDate:
          type: string
          format: date-time
          description: Date of last profile update
          example: '2026-01-15T10:30:00Z'
    Address:
      type: object
      description: Postal address structure used for shipping, billing, and company addresses
      properties:
        name:
          type: string
          description: Addressee name or attention line
          example: Example Title
        lines:
          type: string
          description: Street address lines
          example: example_value
        city:
          type: string
          description: City name
          example: example_value
        state:
          type: string
          description: State or province
          example: example_value
        postalCode:
          type: string
          description: Postal or ZIP code
          example: example_value
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          pattern: ^[A-Z]{2}$
          example: example_value
        phone:
          type: string
          description: Phone number
          example: example_value
        email:
          type: string
          format: email
          description: Email address
          example: user@example.com
    ErrorResponse:
      type: object
      description: Standard error response structure
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              examples:
              - INVALID_REQUEST
              - RESOURCE_NOT_FOUND
              - UNAUTHORIZED
            message:
              type: string
              description: Human-readable error message
            details:
              type: array
              description: Additional error details
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Field name that caused the error (for validation errors)
                  message:
                    type: string
                    description: Detail message for this specific issue
                  errorNumber:
                    type: string
                    description: SAP error number
                  errorModule:
                    type: string
                    description: SAP module where the error originated
          example: example_value
    SupplierListResponse:
      type: object
      description: Paginated list of suppliers
      properties:
        totalCount:
          type: integer
          description: Total number of matching suppliers
          example: 10
        skip:
          type: integer
          description: Number of records skipped
          example: 10
        limit:
          type: integer
          description: Maximum records per page
          example: 10
        suppliers:
          type: array
          items:
            $ref: '#/components/schemas/Supplier'
          example: []
    CommodityCode:
      type: object
      description: UNSPSC commodity classification code
      required:
      - code
      properties:
        code:
          type: string
          description: UNSPSC commodity code
          examples:
          - '43211500'
        description:
          type: string
          description: Commodity description
          examples:
          - Computers
        domain:
          type: string
          description: Classification domain identifier
          default: UNSPSC
          example: example_value
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions for the requested operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid parameters or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded. Retry after the duration specified in the Retry-After header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for SAP Ariba API authentication. Obtain client credentials from the SAP Ariba Developer Portal.
      flows:
        clientCredentials:
          tokenUrl: https://api.ariba.com/v2/oauth/token
          scopes: {}