openapi: 3.1.0
info:
  title: CargoDocs Customer Data/Docs Common Issuance API
  description: The CargoDocs Customer Data/Docs API enables exporters to draft trade and shipping documents, including tanker, bulker, or barge bills of lading from data imported from an ERP system, CTRM, TMS, WMS, etc. It also enables any party using CargoDocs to download copy docs and data to automate various back-office steps.
  version: 3.0.0
  contact:
    name: ICE Digital Trade (essDOCS)
    url: https://www.essdocs.com
  license:
    name: Proprietary
    url: https://www.essdocs.com
servers:
- url: https://api-test.cargodocs.com/v3
  description: Sandbox / Test Environment
- url: https://api.uat.cargodocs.com/v3
  description: UAT Environment
- url: https://api.cargodocs.com/v3
  description: Production Environment
security:
- bearerAuth: []
tags:
- name: Issuance
  description: Endpoints for drafting, issuing, and re-issuing electronic bills of lading
paths:
  /issuer/draft:
    post:
      operationId: createDraft
      summary: CargoDocs Create Draft eBoL
      description: Shares a draft electronic Bill of Lading (eBoL) or Sea Waybill (SWB) for approval by the shipper before signing and issuing.
      tags:
      - Issuance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DraftRequest'
      responses:
        '200':
          description: Draft created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DraftResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /issuer/issue:
    post:
      operationId: issueDocument
      summary: CargoDocs Issue eBoL
      description: Signs and issues the original electronic Bill of Lading (eBoL) or Sea Waybill (SWB) after the draft has been approved.
      tags:
      - Issuance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueRequest'
      responses:
        '200':
          description: Document issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /issuer/re-issue:
    post:
      operationId: reIssue
      summary: CargoDocs Re-Issue eBoL
      description: Allows the issuer to re-issue an electronic Bill of Lading, for example after an amendment request or when managing splits of an eBoL.
      tags:
      - Issuance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReIssueRequest'
      responses:
        '200':
          description: Document re-issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReIssueResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    DraftRequest:
      type: object
      properties:
        transactionId:
          type: string
          description: The unique identifier for the transaction
        documentType:
          type: string
          description: Type of document (e.g., eBoL, SWB)
          enum:
          - eBoL
          - SWB
        shipperDetails:
          type: object
          description: Details of the shipper
        consigneeDetails:
          type: object
          description: Details of the consignee
        cargoDetails:
          type: object
          description: Details of the cargo
    IssueRequest:
      type: object
      properties:
        draftId:
          type: string
          description: The identifier of the approved draft to issue
        transactionId:
          type: string
          description: The unique identifier for the transaction
    ReIssueResponse:
      type: object
      properties:
        documentId:
          type: string
          description: The identifier of the re-issued document
        status:
          type: string
          description: Status of the re-issued document
    IssueResponse:
      type: object
      properties:
        documentId:
          type: string
          description: The unique identifier for the issued document
        status:
          type: string
          description: Status of the issued document
        issuedAt:
          type: string
          format: date-time
          description: Timestamp when the document was issued
    ReIssueRequest:
      type: object
      properties:
        documentId:
          type: string
          description: The identifier of the document to re-issue
        reason:
          type: string
          description: Reason for re-issuance
    DraftResponse:
      type: object
      properties:
        draftId:
          type: string
          description: The unique identifier for the draft
        status:
          type: string
          description: Status of the draft
        transactionId:
          type: string
          description: The associated transaction identifier
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT