openapi: 3.1.0
info:
  title: AlchemyCode API
  description: "\n**AlchemyCode API** expone servicios de cumplimiento fiscal y laboral\
    \ en México:\nconstancia de situación fiscal, opinión SAT 32-D, domicilio fiscal,\
    \ buzón y\nopinión IMSS, opinión Infonavit, consulta del artículo 69-B y resolución\
    \ de\nCAPTCHAs.\n\n- Autenticación con **API keys** (`Authorization: Bearer ck_live_...`).\n\
    - Acceso **solo por invitación**; cada cuenta administra sus propias empresas\
    \ y\n  credenciales del SAT (e.firma), IMSS e Infonavit.\n- Cada petición se mide\
    \ por cuenta, empresa y servicio; el consumo de IA se\n  registra por separado.\n\
    - Errores con formato **RFC 9457** (`application/problem+json`) y `code` estable.\n\
    \nDocumentación completa, SDKs y ejemplos en **https://api.434alchemycode.com/docs**.\n"
  version: 1.0.0
servers:
- url: https://api.434alchemycode.com
  description: Producción
- url: http://127.0.0.1:8090
  description: Local
paths:
  /v1/health:
    get:
      tags:
      - Plataforma
      summary: Estado del servicio
      operationId: health_v1_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Health V1 Health Get
  /v1/services:
    get:
      tags:
      - Plataforma
      summary: Catálogo de servicios
      operationId: list_services_v1_services_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/me:
    get:
      tags:
      - Plataforma
      summary: Cuenta autenticada, plan y cuota
      operationId: me_v1_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Me V1 Me Get
        '422':
          description: Datos inválidos o regla de negocio incumplida (problem+json).
          content:
            application/problem+json:
              schema:
                type: object
      security:
      - ApiKeyAuth: []
  /v1/usage:
    get:
      tags:
      - Plataforma
      summary: Consumo agregado de la cuenta
      operationId: usage_v1_usage_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Usage V1 Usage Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/usage/events:
    get:
      tags:
      - Plataforma
      summary: Bitácora de peticiones (paginada)
      operationId: usage_events_v1_usage_events_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Per Page
      - name: service
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Service
      - name: company_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
      - name: outcome
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(success|error|rejected)$
          - type: 'null'
          title: Outcome
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Usage Events V1 Usage Events Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/files/{file_id}:
    get:
      tags:
      - Plataforma
      summary: Descarga un artefacto con URL firmada
      operationId: download_file_v1_files__file_id__get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          title: File Id
      - name: p
        in: query
        required: true
        schema:
          type: string
          title: P
      - name: exp
        in: query
        required: true
        schema:
          type: integer
          title: Exp
      - name: sig
        in: query
        required: true
        schema:
          type: string
          title: Sig
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/status:
    get:
      tags:
      - Estado
      summary: Estado real del sistema, componentes e incidentes
      operationId: status_json_v1_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Datos inválidos o regla de negocio incumplida (problem+json).
          content:
            application/problem+json:
              schema:
                type: object
      security:
      - ApiKeyAuth: []
  /v1/companies:
    get:
      tags:
      - Empresas
      summary: Lista empresas
      operationId: list_companies_v1_companies_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Per Page
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(active|suspended|archived)$
          - type: 'null'
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response List Companies V1 Companies Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Empresas
      summary: Crea una empresa
      operationId: create_company_v1_companies_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Create Company V1 Companies Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/companies/{company_id}:
    get:
      tags:
      - Empresas
      summary: Detalle de empresa
      operationId: get_company_detail_v1_companies__company_id__get
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Get Company Detail V1 Companies  Company Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    patch:
      tags:
      - Empresas
      summary: Actualiza empresa
      operationId: update_company_v1_companies__company_id__patch
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Update Company V1 Companies  Company Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
    delete:
      tags:
      - Empresas
      summary: Archiva empresa (borrado lógico)
      operationId: archive_company_v1_companies__company_id__delete
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/companies/{company_id}/credentials:
    get:
      tags:
      - Empresas
      summary: Estado de credenciales de la empresa
      operationId: get_credentials_v1_companies__company_id__credentials_get
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Get Credentials V1 Companies  Company Id  Credentials
                  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/companies/{company_id}/credentials/sat:
    post:
      tags:
      - Empresas
      summary: Carga e.firma (.cer, .key y contraseña)
      operationId: upload_sat_credentials_v1_companies__company_id__credentials_sat_post
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_sat_credentials_v1_companies__company_id__credentials_sat_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SatCredentialOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/companies/{company_id}/credentials/{portal}:
    post:
      tags:
      - Empresas
      summary: Carga credenciales de IMSS o Infonavit
      operationId: upload_portal_credentials_v1_companies__company_id__credentials__portal__post
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      - name: portal
        in: path
        required: true
        schema:
          type: string
          title: Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalCredentialIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalCredentialOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/companies/{company_id}/credentials/{kind}:
    delete:
      tags:
      - Empresas
      summary: Elimina credenciales (fiel | imss | infonavit)
      operationId: delete_credentials_v1_companies__company_id__credentials__kind__delete
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Company Id
      - name: kind
        in: path
        required: true
        schema:
          type: string
          title: Kind
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/sat/constancias:
    post:
      tags:
      - Servicios
      summary: Constancia de Situación Fiscal
      description: Descarga la CSF con la e.firma de la empresa y devuelve PDF + JSON
        normalizado.
      operationId: constancia_v1_sat_constancias_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConstanciaRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/sat/opiniones:
    post:
      tags:
      - Servicios
      summary: Opinión de Cumplimiento SAT (32-D)
      operationId: opinion_sat_v1_sat_opiniones_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpinionRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/sat/domicilios:
    post:
      tags:
      - Servicios
      summary: Estatus de domicilio fiscal
      operationId: domicilio_v1_sat_domicilios_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomicilioRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/imss/buzones:
    post:
      tags:
      - Servicios
      summary: Sincroniza el Buzón IMSS
      operationId: buzon_imss_v1_imss_buzones_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuzonImssRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/imss/opiniones:
    post:
      tags:
      - Servicios
      summary: Opinión de Cumplimiento IMSS
      operationId: opinion_imss_v1_imss_opiniones_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpinionImssRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/infonavit/opiniones:
    post:
      tags:
      - Servicios
      summary: Opinión de Cumplimiento Infonavit
      operationId: opinion_infonavit_v1_infonavit_opiniones_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpinionInfonavitRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/sat/articulo-69b:
    post:
      tags:
      - Servicios
      summary: Consulta Artículo 69-B (síncrona)
      operationId: articulo_69b_v1_sat_articulo_69b_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Articulo69bRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/captcha/resoluciones:
    post:
      tags:
      - Servicios
      summary: Resuelve un CAPTCHA (síncrona)
      operationId: captcha_v1_captcha_resoluciones_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptchaRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/jobs:
    get:
      tags:
      - Servicios
      summary: Lista trabajos
      operationId: list_jobs_v1_jobs_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Per Page
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(queued|running|succeeded|failed|canceled|expired)$
          - type: 'null'
          title: Status
      - name: service
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Service
      - name: company_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response List Jobs V1 Jobs Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/jobs/{job_id}:
    get:
      tags:
      - Servicios
      summary: Consulta un trabajo
      operationId: get_job_v1_jobs__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Get Job V1 Jobs  Job Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/jobs/{job_id}/cancel:
    post:
      tags:
      - Servicios
      summary: Cancela un trabajo en cola
      operationId: cancel_job_v1_jobs__job_id__cancel_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Cancel Job V1 Jobs  Job Id  Cancel Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/keys:
    get:
      tags:
      - Llaves
      summary: Lista llaves de la cuenta
      operationId: list_keys_v1_keys_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response List Keys V1 Keys Get
        '422':
          description: Datos inválidos o regla de negocio incumplida (problem+json).
          content:
            application/problem+json:
              schema:
                type: object
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Llaves
      summary: Crea una llave (se muestra una sola vez)
      operationId: create_key_v1_keys_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyCreateRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Create Key V1 Keys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/keys/{key_id}:
    delete:
      tags:
      - Llaves
      summary: Revoca una llave
      operationId: revoke_key_v1_keys__key_id__delete
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Key Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/webhooks:
    get:
      tags:
      - Webhooks
      summary: Lista webhooks
      operationId: list_webhooks_v1_webhooks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response List Webhooks V1 Webhooks Get
        '422':
          description: Datos inválidos o regla de negocio incumplida (problem+json).
          content:
            application/problem+json:
              schema:
                type: object
      security:
      - ApiKeyAuth: []
    post:
      tags:
      - Webhooks
      summary: Crea un webhook (secreto visible una sola vez)
      operationId: create_webhook_v1_webhooks_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Create Webhook V1 Webhooks Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/webhooks/{webhook_id}:
    delete:
      tags:
      - Webhooks
      summary: Desactiva un webhook
      operationId: delete_webhook_v1_webhooks__webhook_id__delete
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/webhooks/{webhook_id}/test:
    post:
      tags:
      - Webhooks
      summary: Envía un evento de prueba
      operationId: test_webhook_v1_webhooks__webhook_id__test_post
      parameters:
      - name: webhook_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Webhook Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Test Webhook V1 Webhooks  Webhook Id  Test Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyAuth: []
  /v1/auth/login:
    post:
      tags:
      - Autenticación
      summary: Inicia sesión en el panel
      operationId: login_v1_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Login V1 Auth Login Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/logout:
    post:
      tags:
      - Autenticación
      summary: Cierra sesión
      operationId: logout_v1_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Logout V1 Auth Logout Post
  /v1/auth/me:
    get:
      tags:
      - Autenticación
      summary: Usuario de la sesión actual
      operationId: me_v1_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Me V1 Auth Me Get
  /v1/auth/password:
    post:
      tags:
      - Autenticación
      summary: Cambia la contraseña
      operationId: change_password_v1_auth_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Change Password V1 Auth Password Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/invitations/{token}:
    get:
      tags:
      - Autenticación
      summary: Valida una invitación antes de aceptarla
      operationId: preview_invitation_v1_auth_invitations__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Preview Invitation V1 Auth Invitations  Token  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/invitations/accept:
    post:
      tags:
      - Autenticación
      summary: Acepta invitación y crea la cuenta
      operationId: accept_invitation_v1_auth_invitations_accept_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteAcceptRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Accept Invitation V1 Auth Invitations Accept Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/admin/metrics:
    get:
      tags:
      - Administración
      summary: Tablero global
      operationId: metrics_v1_admin_metrics_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Metrics V1 Admin Metrics Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/accounts:
    get:
      tags:
      - Administración
      summary: Cuentas de clientes
      operationId: list_accounts_v1_admin_accounts_get
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Q
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(active|suspended|closed)$
          - type: 'null'
          title: Status
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Per Page
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response List Accounts V1 Admin Accounts Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/accounts/{account_id}:
    get:
      tags:
      - Administración
      summary: Detalle de cuenta
      operationId: get_account_v1_admin_accounts__account_id__get
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Get Account V1 Admin Accounts  Account Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
    patch:
      tags:
      - Administración
      summary: Ajusta plan, cuota o estado
      operationId: update_account_v1_admin_accounts__account_id__patch
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Account Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Update Account V1 Admin Accounts  Account Id  Patch
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/invitations:
    get:
      tags:
      - Administración
      summary: Invitaciones
      operationId: list_invitations_v1_admin_invitations_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response List Invitations V1 Admin Invitations Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
    post:
      tags:
      - Administración
      summary: Invita a un desarrollador
      operationId: invite_v1_admin_invitations_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Invite V1 Admin Invitations Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/invitations/{invitation_id}/revoke:
    post:
      tags:
      - Administración
      summary: Revoca invitación
      operationId: revoke_invitation_v1_admin_invitations__invitation_id__revoke_post
      parameters:
      - name: invitation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Invitation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Revoke Invitation V1 Admin Invitations  Invitation
                  Id  Revoke Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/usage:
    get:
      tags:
      - Administración
      summary: Consumo global por cuenta y servicio
      operationId: admin_usage_v1_admin_usage_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Admin Usage V1 Admin Usage Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/ai:
    get:
      tags:
      - Administración
      summary: Consumo de IA por cuenta, modelo y operación
      operationId: admin_ai_v1_admin_ai_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Admin Ai V1 Admin Ai Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/audit:
    get:
      tags:
      - Administración
      summary: Auditoría
      operationId: admin_audit_v1_admin_audit_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Per Page
      - name: action
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Action
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Admin Audit V1 Admin Audit Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SessionAuth: []
  /v1/admin/services:
    get:
      tags:
      - Administración
      summary: Catálogo con precio y unidades (editable a futuro)
      operationId: admin_services_v1_admin_services_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Admin Services V1 Admin Services Get
        '422':
          description: Datos inválidos o regla de negocio incumplida (problem+json).
          content:
            application/problem+json:
              schema:
                type: object
      security:
      - SessionAuth: []
components:
  schemas:
    Articulo69bRequest:
      properties:
        company_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
          description: Si se omite, se consultan los RFC del lote sin empresa asociada.
        rfc:
          anyOf:
          - type: string
          - type: 'null'
          title: Rfc
          description: Un solo RFC. Mutuamente excluyente con `rfcs`.
        rfcs:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Rfcs
          description: Lote de hasta 5,000 RFC.
      type: object
      title: Articulo69bRequest
    Body_upload_sat_credentials_v1_companies__company_id__credentials_sat_post:
      properties:
        cer:
          type: string
          format: binary
          title: Cer
          description: Certificado .cer del SAT
        key:
          type: string
          format: binary
          title: Key
          description: Llave .key del SAT
        password:
          type: string
          title: Password
          description: Contraseña de la llave
      type: object
      required:
      - cer
      - key
      - password
      title: Body_upload_sat_credentials_v1_companies__company_id__credentials_sat_post
    BuzonImssRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
        wait:
          type: boolean
          title: Wait
          default: false
      type: object
      required:
      - company_id
      title: BuzonImssRequest
    CaptchaRequest:
      properties:
        image_base64:
          type: string
          title: Image Base64
          description: Imagen PNG/JPEG en base64 (sin prefijo data:).
        portal:
          type: string
          enum:
          - sat
          - imss
          - infonavit
          - otro
          title: Portal
          default: otro
        company_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
      type: object
      required:
      - image_base64
      title: CaptchaRequest
    CompanyCreate:
      properties:
        rfc:
          type: string
          title: Rfc
          examples:
          - OMX2503255F9
        legal_name:
          type: string
          maxLength: 240
          minLength: 2
          title: Legal Name
          examples:
          - OMNICONMX, S.A. de C.V.
        person_type:
          anyOf:
          - type: string
            enum:
            - moral
            - fisica
          - type: 'null'
          title: Person Type
        tax_regime:
          anyOf:
          - type: string
            maxLength: 8
          - type: 'null'
          title: Tax Regime
          examples:
          - '601'
        address:
          anyOf:
          - type: object
          - type: 'null'
          title: Address
        external_ref:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: External Ref
          description: Identificador en tu sistema; en el proveedor `alchemy` guarda
            el cliente_id interno.
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      type: object
      required:
      - rfc
      - legal_name
      title: CompanyCreate
    CompanyUpdate:
      properties:
        legal_name:
          anyOf:
          - type: string
            maxLength: 240
            minLength: 2
          - type: 'null'
          title: Legal Name
        tax_regime:
          anyOf:
          - type: string
            maxLength: 8
          - type: 'null'
          title: Tax Regime
        address:
          anyOf:
          - type: object
          - type: 'null'
          title: Address
        status:
          anyOf:
          - type: string
            enum:
            - active
            - suspended
            - archived
          - type: 'null'
          title: Status
        external_ref:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: External Ref
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
      type: object
      title: CompanyUpdate
    ConstanciaRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
        include_pdf:
          type: boolean
          title: Include Pdf
          description: Incluye el PDF oficial en `files`.
          default: true
        wait:
          type: boolean
          title: Wait
          description: Si es `true`, espera hasta 25 s y devuelve el resultado; si
            no, responde 202 con un job.
          default: false
      type: object
      required:
      - company_id
      title: ConstanciaRequest
    DomicilioRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
        wait:
          type: boolean
          title: Wait
          default: false
      type: object
      required:
      - company_id
      title: DomicilioRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InviteAcceptRequest:
      properties:
        token:
          type: string
          minLength: 10
          title: Token
        name:
          type: string
          maxLength: 160
          minLength: 2
          title: Name
        password:
          type: string
          maxLength: 128
          minLength: 12
          title: Password
        account_name:
          anyOf:
          - type: string
            maxLength: 160
          - type: 'null'
          title: Account Name
      type: object
      required:
      - token
      - name
      - password
      title: InviteAcceptRequest
    InviteCreateRequest:
      properties:
        email:
          type: string
          title: Email
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
        company:
          anyOf:
          - type: string
          - type: 'null'
          title: Company
          description: Empresa prospecto, solo para el correo.
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
        expires_in_hours:
          type: integer
          maximum: 720.0
          minimum: 1.0
          title: Expires In Hours
          default: 168
      type: object
      required:
      - email
      title: InviteCreateRequest
    KeyCreateRequest:
      properties:
        name:
          type: string
          maxLength: 80
          minLength: 2
          title: Name
          examples:
          - Producción · backend
        environment:
          type: string
          enum:
          - live
          - test
          title: Environment
          default: live
        scopes:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Scopes
        expires_in_days:
          anyOf:
          - type: integer
            maximum: 730.0
            minimum: 1.0
          - type: 'null'
          title: Expires In Days
      type: object
      required:
      - name
      title: KeyCreateRequest
    LoginRequest:
      properties:
        email:
          type: string
          title: Email
          examples:
          - ana@estudiofiscal.mx
        password:
          type: string
          minLength: 1
          title: Password
          examples:
          - UnaClaveSegura2026!
      type: object
      required:
      - email
      - password
      title: LoginRequest
    OpinionImssRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
        wait:
          type: boolean
          title: Wait
          default: false
      type: object
      required:
      - company_id
      title: OpinionImssRequest
    OpinionInfonavitRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
        wait:
          type: boolean
          title: Wait
          default: false
      type: object
      required:
      - company_id
      title: OpinionInfonavitRequest
    OpinionRequest:
      properties:
        company_id:
          type: string
          format: uuid
          title: Company Id
        wait:
          type: boolean
          title: Wait
          default: false
      type: object
      required:
      - company_id
      title: OpinionRequest
    PasswordChangeRequest:
      properties:
        current_password:
          type: string
          title: Current Password
        new_password:
          type: string
          maxLength: 128
          minLength: 12
          title: New Password
      type: object
      required:
      - current_password
      - new_password
      title: PasswordChangeRequest
    PlanUpdateRequest:
      properties:
        quota_units_month:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Quota Units Month
        plan_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Key
        status:
          anyOf:
          - type: string
            enum:
            - active
            - suspended
            - closed
          - type: 'null'
          title: Status
        suspended_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Suspended Reason
      type: object
      title: PlanUpdateRequest
    PortalCredentialIn:
      properties:
        username:
          type: string
          maxLength: 160
          minLength: 3
          title: Username
          examples:
          - '1234567890'
        password:
          type: string
          maxLength: 200
          minLength: 1
          title: Password
        extra:
          anyOf:
          - type: object
          - type: 'null'
          title: Extra
      type: object
      required:
      - username
      - password
      title: PortalCredentialIn
      description: Credenciales de portales (IMSS / Infonavit).
    PortalCredentialOut:
      properties:
        object:
          type: string
          title: Object
          default: portal_credential
        company_id:
          type: string
          format: uuid
          title: Company Id
        portal:
          type: string
          title: Portal
        username:
          type: string
          title: Username
        status:
          type: string
          title: Status
        last_verified_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Verified At
        message:
          type: string
          title: Message
      type: object
      required:
      - company_id
      - portal
      - username
      - status
      - message
      title: PortalCredentialOut
    SatCredentialOut:
      properties:
        object:
          type: string
          title: Object
          default: sat_credential
        company_id:
          type: string
          format: uuid
          title: Company Id
        status:
          type: string
          title: Status
        rfc:
          anyOf:
          - type: string
          - type: 'null'
          title: Rfc
        serial:
          anyOf:
          - type: string
          - type: 'null'
          title: Serial
        subject:
          anyOf:
          - type: string
          - type: 'null'
          title: Subject
        valid_from:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Valid From
        valid_to:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Valid To
        cer_sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Cer Sha256
        message:
          type: string
          title: Message
      type: object
      required:
      - company_id
      - status
      - message
      title: SatCredentialOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WebhookCreateRequest:
      properties:
        url:
          type: string
          title: Url
          examples:
          - https://api.tuempresa.mx/webhooks/alchemy
        events:
          items:
            type: string
          type: array
          title: Events
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      type: object
      required:
      - url
      title: WebhookCreateRequest
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: ck_live_...
      description: 'API key de la cuenta. Se envía como `Authorization: Bearer ck_live_...`.
        Las llaves `ck_test_` operan en sandbox con datos simulados.'
    SessionAuth:
      type: apiKey
      in: cookie
      name: alchemy_session
      description: Sesión del panel (cookie HttpOnly). Solo para endpoints de /v1/admin
        y /v1/auth.
tags:
- name: Plataforma
  description: Salud, catálogo de servicios, cuenta, consumo y archivos.
- name: Empresas
  description: Alta de empresas y credenciales cifradas (e.firma, IMSS, Infonavit).
- name: Servicios
  description: Ejecución de consultas y seguimiento de trabajos asíncronos.
- name: Llaves
  description: Gestión de API keys y scopes.
- name: Webhooks
  description: Notificaciones firmadas de trabajos terminados.
- name: Autenticación
  description: Sesión del panel y aceptación de invitaciones.
- name: Administración
  description: 'Consola AlchemyCode: cuentas, invitaciones, consumo e IA.'
x-logo:
  url: /static/icons.svg
  altText: AlchemyCode API