OpenGov Invoice Sync API

openapi: 3.2.0
info:
  title: OpenGov Purchase Order Invoice Sync API
  version: 1.0.0
  description: API for managing purchase orders, line items, splits, and vendors.
servers:
- url: https://api-purchase-order.procurement.opengov.com
  description: Production
- url: https://api-purchase-order.procurement.ogstaging.us
  description: Staging
- url: https://api-purchase-order.procurement.ogintegration.us
  description: Integration
security:
- platformApiKey: []
- platformBearerToken: []
tags:
- name: invoiceSync
paths:
  /api/v1/po/entities/{entityId}/invoice-allocations:
    post:
      tags:
      - invoiceSync
      operationId: invoiceSync.sync
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
        description: The UUID of the Platform entity
      responses:
        '200':
          description: Idempotent replay — a request with this idempotencyKey was already accepted.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - status
                    properties:
                      status:
                        type: string
                        enum:
                        - accepted
                    additionalProperties: false
                additionalProperties: false
                description: Idempotent replay — a request with this idempotencyKey was already accepted.
        '202':
          description: New request accepted successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - status
                    properties:
                      status:
                        type: string
                        enum:
                        - accepted
                    additionalProperties: false
                additionalProperties: false
                description: New request accepted successfully.
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Machine-readable error code
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Per-field validation errors (present for 400 validation errors)
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Dot-path to the field
                          example: lineItems.0.lineItemSplits.1
                        detail:
                          type: string
                          description: Human-readable validation message
                          example: 'Account 101-5100 has insufficient budget: requested 500.00, available 200.00'
                        code:
                          type: string
                          description: Machine-readable rule identifier
                          example: BUDGET_INSUFFICIENT
                        data:
                          type: object
                          description: Structured context for the error (account codes, amounts, IDs, etc.)
                          additionalProperties: true
                          example:
                            accountNumber: 101-5100
                            accountPseudoKey: GF-101-5100
                            requestedAmount: 500
                            availableAmount: 200
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '401':
          description: AuthError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  code:
                    type: string
                    description: Machine-readable error code
                    example: AuthenticationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: Authentication is required to access this resource.
                required:
                - status
                - code
                - detail
        '403':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 403
                  code:
                    type: string
                    description: Machine-readable error code
                    example: AuthorizationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: You do not have permission to perform this action.
                required:
                - status
                - code
                - detail
        '404':
          description: EntityNotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  code:
                    type: string
                    description: Machine-readable error code
                    example: PurchaseOrderNotFound
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: Purchase order with id 123 was not found.
                required:
                - status
                - code
                - detail
        '409':
          description: IdempotencyConflictError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 409
                  code:
                    type: string
                    description: Machine-readable error code
                    example: IDEMPOTENCY_CONFLICT
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: A request with this idempotency key is currently being processed. Retry after the in-flight request completes.
                required:
                - status
                - code
                - detail
        '500':
          description: InfrastructureError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 500
                  code:
                    type: string
                    description: Machine-readable error code
                    example: InternalServerError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: An unexpected error occurred while processing your request. Please try again later.
                required:
                - status
                - code
                - detail
      description: 'Processes delta-based invoice allocation updates. Accepts invoice header, line items (with quantities), and splits (with amounts). Upserts by invoiceLineId (allocations) and invoiceLineDistributionId (splits). Applies deltas to running totals and triggers financial recompute. Idempotent: replayed requests (same idempotencyKey) return 200; new requests return 202.'
      summary: Sync invoice allocations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - idempotencyKey
              - invoices
              properties:
                idempotencyKey:
                  $ref: '#/components/schemas/UUID'
                invoices:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                    - invoiceId
                    - lineItems
                    properties:
                      invoiceId:
                        $ref: '#/components/schemas/UUID'
                      invoiceNumber:
                        type: string
                        description: a string at most 64 character(s) long
                        title: maxLength(64)
                        pattern: ^\S[\s\S]*\S$|^\S$|^$
                        minLength: 1
                        maxLength: 64
                      lineItems:
                        type: array
                        minItems: 1
                        items:
                          type: object
                          required:
                          - invoiceLineId
                          properties:
                            invoiceLineId:
                              $ref: '#/components/schemas/UUID'
                            poPurchaseOrderId:
                              type: number
                            poLineItemId:
                              type: number
                            deltaMatchedQuantity:
                              $ref: '#/components/schemas/SignedDecimal_18_5'
                            deltaInvoicedQuantity:
                              $ref: '#/components/schemas/SignedDecimal_18_5'
                            lineItemSplits:
                              type: array
                              items:
                                type: object
                                required:
                                - invoiceLineDistributionId
                                properties:
                                  invoiceLineDistributionId:
                                    type: number
                                  poLineItemSplitId:
                                    type: number
                                  deltaMatchedAmount:
                                    $ref: '#/components/schemas/SignedDecimal_18_2'
                                  deltaInvoicedAmount:
                                    $ref: '#/components/schemas/SignedDecimal_18_2'
                                  deltaPaidAmount:
                                    $ref: '#/components/schemas/SignedDecimal_18_2'
                                  deltaEncLiquidatedAccrualAmount:
                                    $ref: '#/components/schemas/SignedDecimal_18_2'
                                additionalProperties: false
                          additionalProperties: false
                    additionalProperties: false
                  description: an array of at most 1 item(s)
                  title: maxItems(1)
                  maxItems: 1
              additionalProperties: false
        required: true
components:
  schemas:
    UUID:
      type: string
      description: a Universally Unique Identifier
      format: uuid
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    SignedDecimal_18_2:
      type: string
      title: Signed Decimal (18,2)
    SignedDecimal_18_5:
      type: string
      title: Signed Decimal (18,5)
  securitySchemes:
    platformApiKey:
      description: OpenGov Platform API Key
      type: apiKey
      name: Authorization
      in: header
    platformBearerToken:
      type: http
      scheme: bearer