openapi: 3.1.0
info:
  title: SAP Ariba Procurement Invoices Receipts 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: Receipts
  description: Record goods receipts and service confirmations against purchase orders to support three-way matching.
paths:
  /orders/{orderId}/receipts:
    get:
      operationId: listReceipts
      summary: List Receipts for a Purchase Order
      description: Retrieves goods receipts and service confirmations recorded against a specific purchase order to support three-way matching.
      tags:
      - Receipts
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/OrderIdParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successfully retrieved receipts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiptListResponse'
        '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
    post:
      operationId: createReceipt
      summary: Create a Receipt
      description: Records a goods receipt or service confirmation against a purchase order. Receipts are used in the three-way matching process with purchase orders and invoices.
      tags:
      - Receipts
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/OrderIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiptCreate'
      responses:
        '201':
          description: Receipt created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
          headers:
            Location:
              description: URI of the newly created receipt
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Unprocessable entity - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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
    OrderIdParam:
      name: orderId
      in: path
      description: Unique purchase order identifier (UniqueName). This is the purchase order number with its version, or the ERP PO number (ERPPONumber).
      required: true
      schema:
        type: string
    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:
    ReceiptListResponse:
      type: object
      description: Paginated list of receipts
      properties:
        totalCount:
          type: integer
          example: 10
        skip:
          type: integer
          example: 10
        limit:
          type: integer
          example: 10
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/Receipt'
          example: []
    ReceiptCreate:
      type: object
      description: Request body for creating a receipt
      required:
      - receiptDate
      - lineItems
      properties:
        receiptDate:
          type: string
          format: date
          example: '2026-01-15'
        receiptType:
          type: string
          enum:
          - GoodsReceipt
          - ServiceConfirmation
          - ReturnDelivery
          default: GoodsReceipt
          example: GoodsReceipt
        lineItems:
          type: array
          items:
            type: object
            required:
            - poLineNumber
            - quantityReceived
            properties:
              poLineNumber:
                type: string
              quantityReceived:
                type: number
                format: double
              comments:
                type: string
          minItems: 1
          example: []
    UnitOfMeasure:
      type: object
      description: Unit of measure specification following UN/ECE Recommendation 20 standard codes
      required:
      - code
      properties:
        code:
          type: string
          description: Unit of measure code (UN/ECE Rec 20 or SAP Ariba internal code)
          examples:
          - EA
          - KG
          - PC
          - HR
        description:
          type: string
          description: Human-readable description of the unit
          examples:
          - Each
          - Kilogram
          - Piece
          - Hour
    Receipt:
      type: object
      description: A goods receipt or service confirmation recorded against a purchase order
      required:
      - receiptId
      - purchaseOrderId
      - receiptDate
      - lineItems
      properties:
        receiptId:
          type: string
          description: Unique receipt identifier
          example: '500123'
        purchaseOrderId:
          type: string
          description: Reference to the purchase order
          example: '500123'
        receiptDate:
          type: string
          format: date
          description: Date goods were received or services confirmed
          example: '2026-01-15'
        receiptType:
          type: string
          description: Type of receipt
          enum:
          - GoodsReceipt
          - ServiceConfirmation
          - ReturnDelivery
          example: GoodsReceipt
        status:
          type: string
          enum:
          - Draft
          - Posted
          - Reversed
          example: Draft
        lineItems:
          type: array
          items:
            type: object
            required:
            - poLineNumber
            - quantityReceived
            properties:
              poLineNumber:
                type: string
                description: Purchase order line item number
              description:
                type: string
                description: Item description
              quantityReceived:
                type: number
                format: double
                description: Quantity received
              unitOfMeasure:
                $ref: '#/components/schemas/UnitOfMeasure'
              deliveryNote:
                type: string
                description: Delivery note or packing slip reference
              comments:
                type: string
                description: Receipt comments
          minItems: 1
          example: []
        createdDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        createdBy:
          type: string
          description: User who created the receipt
          example: example_value
    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
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions for the requested operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      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: {}