openapi: 3.1.0
info:
  title: Logynfra API
  version: "v1"
  description: >
    One API, One Integration. Unified infrastructure for logistics across Africa and the Middle East.
    Institutional Grade API for Shipments, Compliance, and Documentation.
    an EM300.co company.
servers:
  - url: https://api.logynfra.com/v1
    description: Production Environment
  - url: https://sandbox.logynfra.com/v1
    description: Open Sandbox for Developers

security:
  - ApiKeyAuth: []

paths:
  /shipments:
    post:
      summary: Create a new shipment
      description: Abstracts proprietary carrier data to create a universal shipment order.
      operationId: createShipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UniversalShipmentRequest'
      responses:
        '201':
          description: Shipment successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UniversalShipmentResponse'
  /docs/generate:
    post:
      summary: Generate customs documentation
      description: A single, seamless API to generate and store digital Bills of Lading, Commercial Invoices, and Packing Lists compliant with regional standards.
      operationId: generateDocs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentGenerationRequest'
      responses:
        '200':
          description: Document generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentGenerationResponse'
  /compliance/verify:
    post:
      summary: Verify entities for compliance
      description: Automated carrier vetting, shipper verification, and restricted party screening.
      operationId: verifyCompliance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComplianceRequest'
      responses:
        '200':
          description: Verification complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceResponse'
  /settle:
    post:
      summary: Multi-currency freight settlement
      description: Settle freight costs across fragmented payment rails with automated FX.
      operationId: settleFreight
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementRequest'
      responses:
        '200':
          description: Settlement processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementResponse'
  /exceptions:
    post:
      summary: Report a shipment exception
      description: Standardized endpoint for carriers and sensors to report physical delays or damage.
      operationId: reportException
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExceptionReport'
      responses:
        '202':
          description: Exception accepted and recovery triggered
  /spot-bid:
    post:
      summary: Initiate a spot-bid auction
      description: Manually trigger a rescue shipment auction for a failed leg of a journey.
      operationId: triggerSpotBid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpotBidTrigger'
      responses:
        '200':
          description: Auction initiated

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Logynfra-Key
      description: >
        Institutional Grade API key. Use sk_live_ prefix for production,
        sk_test_ prefix for sandbox. Keys are generated via /dashboard/keys.
  schemas:
    ExceptionReport:
      type: object
      required:
        - shipmentId
        - type
        - severity
        - location
      properties:
        shipmentId:
          type: string
          description: Logynfra shipment ID (LOG-XXXX format)
        type:
          type: string
          enum: [DELAY_BORDER, CARGO_DAMAGE, MECHANICAL_FAILURE, NETWORK_OUTAGE]
        severity:
          type: string
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
        location:
          type: object
          required: [lat, lng, description]
          properties:
            lat:
              type: number
            lng:
              type: number
            description:
              type: string
    SpotBidTrigger:
      type: object
      required:
        - shipmentId
        - failedCarrierId
        - location
        - cargoValue
      properties:
        shipmentId:
          type: string
          description: Logynfra shipment ID requiring rescue
        failedCarrierId:
          type: string
          description: ID of the carrier that failed, for trust score penalization
        location:
          type: string
          description: Current location string (e.g. "KE/UG Border")
        cargoValue:
          type: number
          description: Declared cargo value in USD for bid weighting
    SettlementRequest:
      type: object
      required:
        - shipmentId
        - amount
        - currency
        - idempotencyKey
      properties:
        shipmentId:
          type: string
        amount:
          type: number
        currency:
          type: string
          description: ISO 4217 currency code (e.g. USD, NGN, AED)
        idempotencyKey:
          type: string
          description: >
            Caller-supplied unique key (UUID recommended). The system derives a
            deterministic settlement_id from this key — retrying with the same key
            is always safe and will never create a duplicate settlement.
    SettlementResponse:
      type: object
      properties:
        settlement_id:
          type: string
          description: Deterministic settlement identifier derived from idempotencyKey
        status:
          type: string
          enum: [SETTLED, PENDING, FAILED]
        fee:
          type: number
          description: Transaction fee charged (1% of amount)
        idempotency_key:
          type: string
    UniversalShipmentRequest:
      type: object
      properties:
        originId:
          type: string
          description: ID of the origin location
        destinationId:
          type: string
          description: ID of the destination location
        packageDetails:
          type: array
          items:
            type: object
            properties:
              weight:
                type: number
              dimensions:
                type: string
      required:
        - originId
        - destinationId
        - packageDetails
    UniversalShipmentResponse:
      type: object
      properties:
        shipmentId:
          type: string
        status:
          type: string
        carrierId:
          type: string
    DocumentGenerationRequest:
      type: object
      properties:
        shipmentId:
          type: string
        documentType:
          type: string
          enum: [BILL_OF_LADING, COMMERCIAL_INVOICE, PACKING_LIST]
        isoCountryCode:
          type: string
          description: Target country ISO code (e.g., NG, KE, AE)
      required:
        - shipmentId
        - documentType
        - isoCountryCode
    DocumentGenerationResponse:
      type: object
      properties:
        documentId:
          type: string
        url:
          type: string
          format: uri
        hash:
          type: string
          description: Immutable ledger hash for verification
    ComplianceRequest:
      type: object
      properties:
        entityId:
          type: string
        entityType:
          type: string
          enum: [CARRIER, SHIPPER]
      required:
        - entityId
        - entityType
    ComplianceResponse:
      type: object
      properties:
        status:
          type: string
          enum: [VERIFIED, REJECTED, PENDING_MANUAL_REVIEW]
        reason:
          type: string
