{
 "openapi": "3.1.0",
 "info": {
  "title": "GlobalStart — API de création de société",
  "version": "1.0.0",
  "summary": "Catalogue, devis, ouverture et suivi de dossiers de création de société, pour humains et agents IA.",
  "description": "API publique de GlobalStart : 29 juridictions, prix publics, devis, ouverture de dossier et suivi. Lecture ouverte ; l'écriture (POST /dossiers) exige une clé API (en-tête X-API-Key ou Authorization: Bearer). Le même service est exposé en MCP (JSON-RPC) sur /api/mcp.php.",
  "contact": {
   "name": "GlobalStart",
   "email": "contact@globalstart.fr",
   "url": "https://globalstart.fr/developpeurs.html"
  },
  "license": {
   "name": "Usage commercial — conditions sur demande",
   "identifier": "proprietary"
  }
 },
 "servers": [
  {
   "url": "https://globalstart.fr/api",
   "description": "Production"
  }
 ],
 "tags": [
  {
   "name": "catalogue"
  },
  {
   "name": "devis"
  },
  {
   "name": "dossiers"
  }
 ],
 "paths": {
  "/v1": {
   "get": {
    "operationId": "index",
    "tags": [
     "catalogue"
    ],
    "summary": "Points d'entrée de l'API",
    "responses": {
     "200": {
      "description": "Index"
     }
    }
   }
  },
  "/v1/sante": {
   "get": {
    "operationId": "sante",
    "tags": [
     "catalogue"
    ],
    "summary": "État du service",
    "responses": {
     "200": {
      "description": "Service disponible"
     }
    }
   }
  },
  "/v1/juridictions": {
   "get": {
    "operationId": "listerJuridictions",
    "tags": [
     "catalogue"
    ],
    "summary": "Lister les juridictions et leurs prix publics",
    "parameters": [
     {
      "name": "region",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "example": "europe"
     },
     {
      "name": "devise",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "EUR",
        "DZD"
       ]
      }
     },
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Recherche sur le nom"
     }
    ],
    "responses": {
     "200": {
      "description": "Catalogue",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "total": {
           "type": "integer"
          },
          "juridictions": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "slug": {
              "type": "string"
             },
             "nom": {
              "type": "string"
             },
             "forme": {
              "type": "string"
             },
             "region": {
              "type": "string"
             },
             "drapeau": {
              "type": "string"
             },
             "devise": {
              "type": "string"
             },
             "prix_min": {
              "type": "number"
             },
             "page": {
              "type": "string"
             },
             "commande": {
              "type": "string"
             },
             "formules": {
              "type": "array",
              "items": {
               "type": "object"
              }
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/juridictions/{slug}": {
   "get": {
    "operationId": "detailJuridiction",
    "tags": [
     "catalogue"
    ],
    "summary": "Détail d'une juridiction (prix, délai, inclus)",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Juridiction"
     },
     "404": {
      "description": "Inconnue",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean",
           "enum": [
            false
           ]
          },
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/devis": {
   "post": {
    "operationId": "creerDevis",
    "tags": [
     "devis"
    ],
    "summary": "Obtenir un devis ferme pour une juridiction et une formule",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "juridiction"
        ],
        "properties": {
         "juridiction": {
          "type": "string",
          "example": "royaume-uni"
         },
         "formule": {
          "type": "string",
          "example": "essentiel"
         },
         "pays_residence": {
          "type": "string",
          "example": "FR"
         },
         "activite": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Devis"
     },
     "404": {
      "description": "Juridiction inconnue"
     },
     "429": {
      "description": "Trop de demandes"
     }
    }
   }
  },
  "/v1/dossiers": {
   "post": {
    "operationId": "ouvrirDossier",
    "tags": [
     "dossiers"
    ],
    "summary": "Ouvrir un dossier de création (clé API requise)",
    "security": [
     {
      "cleApi": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "juridiction",
         "nom",
         "email",
         "telephone",
         "pays_residence"
        ],
        "properties": {
         "juridiction": {
          "type": "string"
         },
         "formule": {
          "type": "string"
         },
         "nom": {
          "type": "string",
          "description": "Nom du contact (ou raison sociale du client)"
         },
         "email": {
          "type": "string",
          "format": "email"
         },
         "telephone": {
          "type": "string"
         },
         "pays_residence": {
          "type": "string"
         },
         "denomination_sociale": {
          "type": "string"
         },
         "activite": {
          "type": "string"
         },
         "agent": {
          "type": "object",
          "description": "{nom, type: 'ia'|'humain', reference}"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Dossier créé"
     },
     "401": {
      "description": "Clé absente ou invalide"
     },
     "422": {
      "description": "Champ invalide"
     },
     "429": {
      "description": "Trop de demandes"
     }
    }
   }
  },
  "/v1/dossiers/{reference}": {
   "get": {
    "operationId": "suiviDossier",
    "tags": [
     "dossiers"
    ],
    "summary": "Suivre un dossier par sa référence",
    "security": [
     {
      "cleApi": []
     },
     {
      "bearer": []
     },
     {}
    ],
    "parameters": [
     {
      "name": "reference",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "email",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "email"
      },
      "description": "Adresse du dossier — exigée si aucune clé API n'est fournie"
     }
    ],
    "responses": {
     "200": {
      "description": "Dossier"
     },
     "401": {
      "description": "Justificatif manquant"
     },
     "404": {
      "description": "Introuvable"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "cleApi": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  }
 }
}