openapi: 3.0.3
info:
  title: Allianz Trade Claims API
  description: Access and manage all insurance claims declared to Allianz Trade from within your ERP system. Retrieve claim status, submit new claims, and track claim progression for trade credit insurance policies.
  version: 1.0.0
  contact:
    name: Allianz Trade API Support
    email: api@allianz-trade.com
    url: https://developers.allianz-trade.com/
  x-generated-from: documentation
servers:
- url: https://api.allianz-trade.com/v1
  description: Allianz Trade API production server
security:
- OAuth2: []
tags:
- name: Claims
  description: Insurance claim management operations
paths:
  /claims:
    get:
      operationId: listClaims
      summary: Allianz Trade List Claims
      description: Retrieve a paginated list of insurance claims for your trade credit insurance policies.
      tags:
      - Claims
      parameters:
      - name: pageSize
        in: query
        required: false
        description: Number of items per page (Allianz Trade pagination standard)
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        example: 20
      - name: page
        in: query
        required: false
        description: Page number starting from 1
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: totalRequired
        in: query
        required: false
        description: Whether to include total count in response headers
        schema:
          type: boolean
          default: false
        example: false
      - name: policyId
        in: query
        required: false
        description: Filter claims by policy identifier
        schema:
          type: string
        example: POL-500123
      - name: claimStatus
        in: query
        required: false
        description: Filter by claim status
        schema:
          type: string
          enum:
          - submitted
          - under_review
          - approved
          - rejected
          - paid
        example: submitted
      responses:
        '200':
          description: Claims retrieved successfully
          headers:
            Total-Items:
              description: Total number of claims (when totalRequired=true)
              schema:
                type: integer
            Total-Pages:
              description: Total number of pages (when totalRequired=true)
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimList'
              examples:
                ListClaims200Example:
                  summary: Default listClaims 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - claimId: CLM-500123
                      policyId: POL-500123
                      debtorName: Acme Corp
                      claimAmount: 45000.0
                      currency: EUR
                      claimStatus: submitted
                      submittedAt: '2026-04-01T09:00:00Z'
        '401':
          description: Unauthorized - invalid or missing OAuth2 token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: submitClaim
      summary: Allianz Trade Submit Claim
      description: Submit a new insurance claim to Allianz Trade for a trade credit insurance policy when a debtor has defaulted on payment.
      tags:
      - Claims
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitClaimRequest'
            examples:
              SubmitClaimRequestExample:
                summary: Default submitClaim request
                x-microcks-default: true
                value:
                  policyId: POL-500123
                  debtorName: Acme Corp
                  debtorId: DEB-500456
                  claimAmount: 45000.0
                  currency: EUR
                  lossDate: '2026-03-01'
                  invoiceReference: INV-2026-001
                  overdueId: OVD-500123
      responses:
        '202':
          description: Claim submitted and accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              examples:
                SubmitClaim202Example:
                  summary: Default submitClaim 202 response
                  x-microcks-default: true
                  value:
                    jobId: JOB-500789
                    status: pending
                    createdAt: '2026-04-19T10:30:00Z'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /claims/{claimId}:
    get:
      operationId: getClaim
      summary: Allianz Trade Get Claim
      description: Retrieve details and current status for a specific insurance claim by its identifier.
      tags:
      - Claims
      parameters:
      - name: claimId
        in: path
        required: true
        description: Unique identifier of the claim
        schema:
          type: string
        example: CLM-500123
      responses:
        '200':
          description: Claim retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Claim'
              examples:
                GetClaim200Example:
                  summary: Default getClaim 200 response
                  x-microcks-default: true
                  value:
                    claimId: CLM-500123
                    policyId: POL-500123
                    debtorName: Acme Corp
                    debtorId: DEB-500456
                    claimAmount: 45000.0
                    approvedAmount: 40000.0
                    currency: EUR
                    claimStatus: approved
                    lossDate: '2026-03-01'
                    invoiceReference: INV-2026-001
                    overdueId: OVD-500123
                    submittedAt: '2026-04-01T09:00:00Z'
                    resolvedAt: '2026-04-10T14:00:00Z'
        '404':
          description: Claim not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /jobs/{jobId}:
    get:
      operationId: getJobStatus
      summary: Allianz Trade Get Job Status
      description: Poll for the status of an asynchronous claim submission operation.
      tags:
      - Claims
      parameters:
      - name: jobId
        in: path
        required: true
        description: Unique identifier of the async job
        schema:
          type: string
        example: JOB-500789
      responses:
        '200':
          description: Job status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              examples:
                GetJobStatus200Example:
                  summary: Default getJobStatus 200 response
                  x-microcks-default: true
                  value:
                    jobId: JOB-500789
                    status: processed
                    result:
                      claimId: CLM-500123
                    createdAt: '2026-04-19T10:30:00Z'
                    completedAt: '2026-04-19T10:31:00Z'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SubmitClaimRequest:
      title: SubmitClaimRequest
      type: object
      description: Request body for submitting an insurance claim
      required:
      - policyId
      - debtorName
      - claimAmount
      - currency
      - lossDate
      properties:
        policyId:
          type: string
          description: Trade credit insurance policy identifier
          example: POL-500123
        debtorName:
          type: string
          description: Name of the defaulting debtor
          example: Acme Corp
        debtorId:
          type: string
          description: Allianz Trade debtor identifier
          example: DEB-500456
        claimAmount:
          type: number
          format: double
          description: Total amount to claim
          example: 45000.0
        currency:
          type: string
          description: ISO 4217 currency code
          example: EUR
        lossDate:
          type: string
          format: date
          description: Date when the financial loss occurred
          example: '2026-03-01'
        invoiceReference:
          type: string
          description: Customer invoice reference
          example: INV-2026-001
        overdueId:
          type: string
          description: Related payment overdue identifier
          example: OVD-500123
    ClaimList:
      title: ClaimList
      type: object
      description: Paginated list of insurance claims
      properties:
        data:
          type: array
          description: List of insurance claim records
          items:
            $ref: '#/components/schemas/Claim'
    JobResponse:
      title: JobResponse
      type: object
      description: Async job status response
      properties:
        jobId:
          type: string
          description: Unique identifier for the async job
          example: JOB-500789
        status:
          type: string
          description: Current status of the job
          enum:
          - pending
          - processed
          - failed
          example: processed
        result:
          type: object
          description: Result data after successful job completion
          example:
            claimId: CLM-500123
        createdAt:
          type: string
          format: date-time
          description: When the job was created
          example: '2026-04-19T10:30:00Z'
        completedAt:
          type: string
          format: date-time
          description: When the job completed (null if still pending)
          example: '2026-04-19T10:31:00Z'
    Claim:
      title: Claim
      type: object
      description: An insurance claim filed with Allianz Trade
      properties:
        claimId:
          type: string
          description: Unique identifier for the insurance claim
          example: CLM-500123
        policyId:
          type: string
          description: Trade credit insurance policy identifier
          example: POL-500123
        debtorName:
          type: string
          description: Name of the debtor who defaulted on payment
          example: Acme Corp
        debtorId:
          type: string
          description: Allianz Trade debtor identifier
          example: DEB-500456
        claimAmount:
          type: number
          format: double
          description: Total amount claimed
          example: 45000.0
        approvedAmount:
          type: number
          format: double
          description: Amount approved by Allianz Trade (after processing)
          example: 40000.0
        currency:
          type: string
          description: ISO 4217 currency code
          example: EUR
        claimStatus:
          type: string
          description: Current status of the claim
          enum:
          - submitted
          - under_review
          - approved
          - rejected
          - paid
          example: submitted
        lossDate:
          type: string
          format: date
          description: Date when the financial loss occurred
          example: '2026-03-01'
        invoiceReference:
          type: string
          description: Customer invoice reference number
          example: INV-2026-001
        overdueId:
          type: string
          description: Related payment overdue identifier
          example: OVD-500123
        submittedAt:
          type: string
          format: date-time
          description: Timestamp when the claim was submitted
          example: '2026-04-01T09:00:00Z'
        resolvedAt:
          type: string
          format: date-time
          description: Timestamp when the claim was resolved
          example: '2026-04-10T14:00:00Z'
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Error code
          example: INVALID_REQUEST
        message:
          type: string
          description: Human-readable error description
          example: The claimAmount must be a positive number
        requestId:
          type: string
          description: Request identifier for support reference
          example: req-500999
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 client credentials for Allianz Trade API access
      flows:
        clientCredentials:
          tokenUrl: https://api.allianz-trade.com/oauth2/token
          scopes:
            claims:read: Read insurance claims
            claims:write: Submit and manage insurance claims