{
  "openapi": "3.0.3",
  "info": {
    "title": "Progus Store Locator - location sync",
    "version": "1.0.0",
    "description": "The two operations a CRM needs to keep store locations in step: write a location under your own identifier, and remove it. Trimmed for Salesforce External Services - JSON only, flat schemas, no combinators. The full API is at https://sl-app.proguscommerce.com/openapi/store-locator-v1.json and is documented at https://sl-app.proguscommerce.com/docs/api"
  },
  "servers": [
    {
      "url": "https://sl-app.proguscommerce.com/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/locations/by-external-id/{external_id}": {
      "put": {
        "summary": "Create or update a location by external id",
        "description": "Upsert. 201 when a location was created, 200 when an existing one was updated. Coordinates are looked up from the address when lat and lon are not sent.",
        "operationId": "upsertLocation",
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your record identifier for this location, 1 to 64 characters.",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LocationInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The location was updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationResponse"
                }
              }
            }
          },
          "201": {
            "description": "The location was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request body was refused.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing, malformed, unknown or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "The shop holds as many locations as its plan allows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The shop is below the Pro plan, or the key lacks the write scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry-After says how many seconds to wait.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The API is not serving this installation yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a location by external id",
        "description": "Idempotent - an external id the shop does not have is still a 204.",
        "operationId": "deleteLocation",
        "parameters": [
          {
            "name": "external_id",
            "in": "path",
            "required": true,
            "description": "Your record identifier for this location, 1 to 64 characters.",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The location is gone."
          },
          "400": {
            "description": "The external id was refused.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing, malformed, unknown or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The shop is below the Pro plan, or the key lacks the write scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Retry-After says how many seconds to wait.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "The API is not serving this installation yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer sl_live_..."
      }
    },
    "schemas": {
      "LocationInput": {
        "type": "object",
        "description": "The fields of a location. Only name is required. Opening hours, custom fields and tags are part of the full API and are left out here.",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "maxLength": 255 },
          "active": { "type": "boolean" },
          "priority": { "type": "integer" },
          "lat": { "type": "number", "format": "double" },
          "lon": { "type": "number", "format": "double" },
          "address": { "type": "string", "maxLength": 255 },
          "full_address": { "type": "string", "maxLength": 255 },
          "city": { "type": "string", "maxLength": 255 },
          "province": { "type": "string", "maxLength": 255 },
          "zip_code": { "type": "string", "maxLength": 255 },
          "country": { "type": "string", "maxLength": 255 },
          "phone": { "type": "string", "maxLength": 255 },
          "fax": { "type": "string", "maxLength": 255 },
          "email": { "type": "string", "maxLength": 255 },
          "website": { "type": "string", "maxLength": 255 },
          "image_url": { "type": "string", "maxLength": 255 },
          "info": { "type": "string" },
          "facebook": { "type": "string", "maxLength": 255 },
          "google": { "type": "string", "maxLength": 255 },
          "linkedin": { "type": "string", "maxLength": 255 },
          "instagram": { "type": "string", "maxLength": 255 },
          "twitter": { "type": "string", "maxLength": 255 },
          "youtube": { "type": "string", "maxLength": 255 },
          "whatsapp": { "type": "string", "maxLength": 255 }
        }
      },
      "Location": {
        "type": "object",
        "description": "The location as stored. The full API returns opening hours, custom fields and tags as well.",
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "external_id": { "type": "string" },
          "name": { "type": "string" },
          "active": { "type": "boolean" },
          "priority": { "type": "integer" },
          "lat": { "type": "number", "format": "double" },
          "lon": { "type": "number", "format": "double" },
          "address": { "type": "string" },
          "full_address": { "type": "string" },
          "city": { "type": "string" },
          "province": { "type": "string" },
          "zip_code": { "type": "string" },
          "country": { "type": "string" },
          "phone": { "type": "string" },
          "fax": { "type": "string" },
          "email": { "type": "string" },
          "website": { "type": "string" },
          "image_url": { "type": "string" },
          "info": { "type": "string" },
          "created_at": { "type": "string" },
          "updated_at": { "type": "string" }
        }
      },
      "LocationResponse": {
        "type": "object",
        "properties": {
          "data": { "$ref": "#/components/schemas/Location" },
          "geocoding": {
            "type": "string",
            "description": "pending - coordinates are being looked up. not_needed - the location already has them. skipped_quota - the shop is out of geocoding budget for today; the location is stored without coordinates."
          }
        }
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "description": "Stable machine-readable code, e.g. validation_failed or rate_limited." },
          "message": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "$ref": "#/components/schemas/ApiError" }
        }
      }
    }
  }
}