{
  "openapi": "3.1.0",
  "info": {
    "title": "Famitek Partners Registry API",
    "version": "1.0.0",
    "description": "Public endpoints of the Famitek Partners Registry: service health, referral click attribution, and End Customer checkout for a Charter's published offer. Authenticated Charter, Control Center, and application endpoints are not part of this public contract."
  },
  "servers": [
    {
      "url": "https://registry.famitek.com"
    }
  ],
  "security": [],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service and database readiness",
        "responses": {
          "200": {
            "description": "The service and its database are up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "database": {
                      "const": "up"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The service is running but its database is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "database": {
                      "const": "down"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/affiliates/click": {
      "post": {
        "operationId": "recordReferralClick",
        "summary": "Record a referral click from a ?ref= landing",
        "description": "Idempotent per clickKey: repeating a click updates its landing path instead of recording a second one.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code",
                  "clickKey"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{2,31}$"
                  },
                  "clickKey": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "landingPath": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Click recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "referralId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The referral code is not active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The code or click key is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Referrals are temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/customer/offers/{token}": {
      "get": {
        "operationId": "getOffer",
        "summary": "Read a Charter's published offer",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Offer token from the checkout link a Charter shares.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The offer as the End Customer sees it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "amountCents": {
                      "type": "integer"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "billingKind": {
                      "type": "string"
                    },
                    "charterName": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The offer does not exist or is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The service is not accepting new customers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many checkout requests from this address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Customer checkout is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/customer/offers/{token}/setup": {
      "post": {
        "operationId": "beginCheckout",
        "summary": "Start checkout and receive a Stripe SetupIntent client secret",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Offer token from the checkout link a Charter shares.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "requestKey",
                  "continuityAccepted",
                  "name",
                  "email"
                ],
                "properties": {
                  "requestKey": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Client-generated key; retrying with the same key resumes the same checkout."
                  },
                  "continuityAccepted": {
                    "const": true,
                    "description": "Agreement to the customer continuity consent."
                  },
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "clientSecret": {
                      "type": "string"
                    },
                    "requestKey": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The offer does not exist or is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The service is not accepting new customers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Missing consent or an invalid request key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many checkout requests from this address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Customer checkout is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/customer/offers/{token}/complete": {
      "post": {
        "operationId": "completeCheckout",
        "summary": "Complete checkout after the payment form succeeds",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Offer token from the checkout link a Charter shares.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "requestKey"
                ],
                "properties": {
                  "requestKey": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order and its state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "serviceOwner": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No checkout exists for this request key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The payment form has not been completed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid request key or unsupported payment method.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many checkout requests from this address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Customer checkout is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}