openapi: 3.0.0
info:
  title: AVYONIA API
  description: |
    API de vérification d'identité professionnelle AVYONIA.
    Permet de vérifier l'authenticité des profils professionnels contre les deepfakes.
  version: 1.0.0
  contact:
    email: api@avyonia.com
    url: https://avyonia.com/verification
  x-logo:
    url: https://avyonia.com/images/og-image.png

servers:
  - url: https://avyonia.com/_ai
    description: Production API

paths:
  /card-json:
    get:
      operationId: getCardJson
      summary: Get a professional profile as JSON (public, no auth)
      description: |
        Returns complete profile data as structured JSON for AI agents.
        No authentication, cookies, or headers required. Fully public.
        Perfect for LLMs, crawlers, and AI systems.
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
          description: Profile identifier (e.g., antoine-cazals)
          example: antoine-cazals
      responses:
        '200':
          description: Complete profile in Schema.org format
          content:
            application/json:
              schema:
                type: object
                properties:
                  "@context":
                    type: string
                    example: "https://schema.org"
                  "@type":
                    type: string
                    example: "Person"
                  name:
                    type: string
                  jobTitle:
                    type: string
                  email:
                    type: string
                  telephone:
                    type: string
                  url:
                    type: string
                  worksFor:
                    type: object
                  hasOccupation:
                    type: array
                  hasCredential:
                    type: array
              examples:
                profile:
                  summary: Example profile
                  value:
                    "@context": "https://schema.org"
                    "@type": "Person"
                    name: "Antoine Cazals"
                    jobTitle: "Fondateur"
                    email: "antoine@avyonia.com"
                    url: "https://avyonia.com/carte/antoine-cazals"
        '404':
          description: Profile not found

  /verify-profile:
    post:
      operationId: verifyProfile
      summary: Vérifier l'authenticité d'un profil professionnel
      description: |
        Vérifie si un profil AVYONIA a été authentifié par notre équipe.
        Retourne le statut de vérification, la méthode utilisée et les informations du profil.
        Utilisez cette API pour lutter contre les deepfakes et l'usurpation d'identité.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                slug:
                  type: string
                  description: Identifiant unique du profil (ex: antoine-cazals)
                  example: antoine-cazals
                cardId:
                  type: string
                  format: uuid
                  description: ID de la carte (alternative au slug)
              oneOf:
                - required: [slug]
                - required: [cardId]
            examples:
              bySlug:
                summary: Vérification par slug
                value:
                  slug: antoine-cazals
              byCardId:
                summary: Vérification par ID
                value:
                  cardId: 17e4f17d-8a6e-443a-9857-c4b24cecc563
      responses:
        '200':
          description: Profil trouvé
          content:
            application/json:
              schema:
                type: object
                properties:
                  verified:
                    type: boolean
                    description: true si le profil a été vérifié par Avyonia
                  verified_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: Date de vérification
                  method:
                    type: string
                    nullable: true
                    enum: [video_call, document, linkedin_match]
                    description: Méthode de vérification utilisée
                  profile:
                    type: object
                    properties:
                      slug:
                        type: string
                      name:
                        type: string
                      title:
                        type: string
                      company:
                        type: string
                      photo_url:
                        type: string
                        nullable: true
                  verification_url:
                    type: string
                    format: uri
                    description: URL pour consulter le profil vérifié
              examples:
                verified:
                  summary: Profil vérifié
                  value:
                    verified: true
                    verified_at: "2024-06-15T10:30:00Z"
                    method: video_call
                    profile:
                      slug: antoine-cazals
                      name: Antoine Cazals
                      title: Fondateur
                      company: Avyonia
                      photo_url: https://avyonia.com/images/antoine-cazals.jpeg
                    verification_url: https://avyonia.com/carte/antoine-cazals
                not_verified:
                  summary: Profil non vérifié
                  value:
                    verified: false
                    verified_at: null
                    method: null
                    profile:
                      slug: exemple-user
                      name: Exemple User
                      title: Consultant
                      company: Example Corp
                    verification_url: https://avyonia.com/carte/exemple-user
        '404':
          description: Profil non trouvé
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  verified:
                    type: boolean
                    enum: [false]
        '400':
          description: Paramètres manquants
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  verified:
                    type: boolean
                    enum: [false]

components:
  schemas:
    VerificationMethod:
      type: string
      enum:
        - video_call
        - document
        - linkedin_match
      description: |
        Méthodes de vérification disponibles:
        - video_call: Appel vidéo en direct avec l'équipe Avyonia
        - document: Vérification documentaire (carte d'identité, Kbis)
        - linkedin_match: Correspondance avec le profil LinkedIn professionnel