{
  "openapi": "3.0.3",
  "info": {
    "title": "Labels & Stamps API",
    "description": "This API allows you to create shipping labels and stamps for your shipments.\n\n## Authentication\nAll endpoints require a valid API key passed in the `X-API-Key` header.\n",
    "version": "3.0.0",
    "contact": {
      "name": "Cosmo Cargo API Support",
      "email": "api@sh.example.com",
      "url": "https://developers.sh.example.com"
    }
  },
  "tags": [
    {
      "name": "Labels",
      "description": "Endpoints for managing shipping labels. Labels are printable documents that contain:\n\n* Shipping address information\n* Tracking barcodes\n* Carrier-specific routing data\n* Package details"
    },
    {
      "name": "Stamps",
      "description": "Endpoints for managing postage stamps. Stamps provide:\n\n* Proof of postage payment\n* Digital verification\n* Support for multiple output formats (PDF, PNG, ZPL)\n* 24-hour validity period"
    }
  ],
  "servers": [
    {
      "url": "https://eedefc50718545d6b3a6cd7ea38faf06_oas.api.mockbin.io/",
      "description": "Mockbin"
    },
    {
      "url": "https://api.sh.example.com/v1",
      "description": "Production environment"
    },
    {
      "url": "https://api.staging.sh.example.com/v1",
      "description": "Staging environment"
    },
    {
      "url": "https://api.dev.sh.example.com/v1",
      "description": "Development environment"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    },
    {
      "OAuth2": ["read:labels", "write:labels"]
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.sh.example.com/oauth/authorize",
            "tokenUrl": "https://auth.sh.example.com/oauth/token",
            "scopes": {
              "read:labels": "Read access to shipping labels",
              "write:labels": "Write access to shipping labels",
              "read:stamps": "Read access to shipping stamps",
              "write:stamps": "Write access to shipping stamps"
            }
          }
        }
      }
    },
    "schemas": {
      "Stamp": { "$ref": "label-base.json#/components/schemas/Stamp" },
      "Label": { "$ref": "label-base.json#/components/schemas/Label" },
      "Error": { "$ref": "label-base.json#/components/schemas/Error" }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "description": "Check if the API is up and running",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "healthy"
                    },
                    "version": {
                      "type": "string",
                      "example": "3.0.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stamps": {
      "post": {
        "tags": ["Stamps"],
        "summary": "Create a shipping stamp",
        "description": "Creates a new shipping stamp for a shipment.\n\nThe generated stamp will be available for download through the returned URL for 24 hours.\n",
        "operationId": "createStamp",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Stamp"
              },
              "examples": {
                "PDF": {
                  "value": {
                    "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
                    "format": "PDF"
                  }
                },
                "PNG": {
                  "value": {
                    "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
                    "format": "PNG"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stamp created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stamp"
                },
                "example": {
                  "id": "987fcdeb-51a2-43f7-9876-543210abcdef",
                  "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
                  "format": "PDF",
                  "url": "https://assets.sh.example.com/stamps/stamp-123456.pdf",
                  "createdAt": "2025-01-09T12:00:00Z",
                  "expiresAt": "2025-01-10T12:00:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_INPUT",
                  "message": "Invalid shipment ID provided"
                }
              }
            }
          },
          "404": {
            "description": "Shipment not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Shipment with ID 123e4567-e89b-12d3-a456-426614174000 not found"
                }
              }
            }
          }
        }
      }
    },
    "/stamps/{id}/invalid": {
      "put": {
        "tags": ["Stamps"],
        "summary": "Invalidate a shipping stamp",
        "description": "Invalidates a shipping stamp, making it no longer available for download.",
        "operationId": "invalidateStamp",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ID of the stamp to invalidate",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "style": "form",
            "explode": false,
            "required": true,
            "description": "The ID of the stamp to invalidate",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Stamp invalidated successfully"
          },
          "404": {
            "description": "Stamp not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Stamp with ID 987fcdeb-51a2-43f7-9876-543210abcdef not found"
                }
              }
            }
          }
        }
      }
    },
    "/labels": {
      "post": {
        "tags": ["Labels"],
        "summary": "Create a shipping label",
        "description": "Creates a new shipping label for a shipment.\n\nThe generated label will be available for download through the returned URL for 24 hours.\n",
        "operationId": "createLabel",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Label"
              },
              "example": {
                "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
                "format": "PDF",
                "size": "4x6"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Label created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                },
                "example": {
                  "id": "987fcdeb-51a2-43f7-9876-543210abcdef",
                  "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
                  "format": "PDF",
                  "size": "4x6",
                  "url": "https://assets.sh.example.com/labels/label-123456.pdf",
                  "createdAt": "2025-01-09T12:00:00Z",
                  "expiresAt": "2025-01-10T12:00:00Z"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_INPUT",
                  "message": "Invalid shipment ID or label size provided"
                }
              }
            }
          },
          "404": {
            "description": "Shipment not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Shipment with ID 123e4567-e89b-12d3-a456-426614174000 not found"
                }
              }
            }
          }
        }
      }
    },
    "/labels/{id}/invalidate": {
      "put": {
        "tags": ["Labels"],
        "summary": "Invalidate a shipping label",
        "description": "Invalidates a shipping label, making it no longer available for download.",
        "operationId": "invalidateLabel",
        "parameters": [
          {
            "name": "id",
            "example": "987fcdeb",
            "in": "path",
            "required": true,
            "description": "The ID of the label to invalidate",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Label invalidated successfully"
          },
          "404": {
            "description": "Label not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Label with ID 987fcdeb-51a2-43f7-9876-543210abcdef not found"
                }
              }
            }
          }
        }
      }
    },
    "/labels/{id}/trackingnumber": {
      "get": {
        "tags": ["Labels"],
        "summary": "Get tracking number",
        "description": "Retrieves the tracking number associated with a shipping label.",
        "operationId": "getLabelTrackingNumber",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ID of the shipping label",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "987fcdeb-51a2-43f7-9876-543210abcdef"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "The format of the response",
            "schema": {
              "type": "string",
              "enum": ["basic", "detailed", "carrier-specific"],
              "default": "basic"
            },
            "examples": {
              "basic": {
                "summary": "Basic tracking format",
                "value": "basic"
              },
              "detailed": {
                "summary": "Detailed tracking format with events",
                "value": "detailed"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of tracking events to return",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          },
          {
            "name": "carrier",
            "in": "query",
            "required": false,
            "description": "Filter tracking information by specific carrier",
            "schema": {
              "type": "string",
              "enum": ["UPS", "USPS", "FedEx", "DHL"],
              "default": null
            }
          },
          {
            "name": "events_since",
            "in": "query",
            "required": false,
            "description": "Only return tracking events after this timestamp",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2025-01-09T00:00:00Z"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort order for tracking events",
            "schema": {
              "type": "string",
              "enum": ["newest_first", "oldest_first"],
              "default": "newest_first"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tracking number retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["trackingNumber", "carrier"],
                  "properties": {
                    "trackingNumber": {
                      "type": "string",
                      "example": "1Z999AA1234567890"
                    },
                    "carrier": {
                      "type": "string",
                      "example": "UPS"
                    },
                    "trackingUrl": {
                      "type": "string",
                      "format": "uri",
                      "example": "https://www.ups.com/track?tracknum=1Z999AA1234567890"
                    }
                  }
                },
                "examples": {
                  "basic": {
                    "summary": "Basic tracking response",
                    "value": {
                      "trackingNumber": "1Z999AA1234567890",
                      "carrier": "UPS",
                      "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA1234567890"
                    }
                  },
                  "detailed": {
                    "summary": "Detailed tracking response",
                    "value": {
                      "trackingNumber": "1Z999AA1234567890",
                      "carrier": "UPS",
                      "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA1234567890",
                      "status": "In Transit",
                      "estimatedDelivery": "2025-01-10T17:00:00Z",
                      "events": [
                        {
                          "timestamp": "2025-01-09T14:23:00Z",
                          "location": "San Francisco, CA",
                          "status": "Out for Delivery"
                        },
                        {
                          "timestamp": "2025-01-09T08:12:00Z",
                          "location": "Oakland, CA",
                          "status": "Arrived at Local Facility"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Label not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Label with ID 987fcdeb-51a2-43f7-9876-543210abcdef not found"
                }
              }
            }
          }
        }
      }
    },
    "/labels/{id}": {
      "get": {
        "tags": ["Labels"],
        "summary": "Get shipping label",
        "description": "Retrieves a shipping label by ID. The label can be requested in different formats.",
        "operationId": "getLabel",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ID of the shipping label",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "987fcdeb-51a2-43f7-9876-543210abcdef"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "The desired format of the label",
            "schema": {
              "type": "string",
              "enum": [
                "PDF",
                "PNG",
                "ZPL",
                "JPEG",
                "TIFF",
                "SVG",
                "EPS",
                "BMP",
                "GIF",
                "WEBP",
                "PCX",
                "EMF",
                "PS"
              ],
              "default": "PDF"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Label retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Label"
                },
                "example": {
                  "id": "987fcdeb-51a2-43f7-9876-543210abcdef",
                  "shipmentId": "123e4567-e89b-12d3-a456-426614174000",
                  "format": "PDF",
                  "size": "4x6",
                  "url": "https://assets.sh.example.com/labels/label-123456.pdf",
                  "createdAt": "2025-01-09T12:00:00Z",
                  "expiresAt": "2025-01-10T12:00:00Z"
                }
              }
            }
          },
          "404": {
            "description": "Label not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "NOT_FOUND",
                  "message": "Label with ID 987fcdeb-51a2-43f7-9876-543210abcdef not found"
                }
              }
            }
          }
        }
      }
    }
  }
}