openapi: 3.1.0
info:
  title: Moffin Solutions API
  description: API para la consulta de datos fiscales y financieros de contribuyentes.
  version: 1.0.0
  contact:
    name: Soporte Moffin Solutions
    email: hola@moffin.mx
servers:
  - url: https://solutions-api.moffin.mx/api
    description: Servidor de producción
paths:
  /oauth/token:
    post:
      summary: Crear y refrescar token
      operationId: createToken
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Authentication'
      responses:
        '200':
          description: The timeline was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Credenciales inválidas
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                    example:
                      - >-
                        El grantType debe ser uno de los siguientes:
                        client_credentials, refresh_token.
                      - '"clientId" is not allowed'
                      - '"clientSecret" is not allowed'
        '401':
          description: Credenciales inválidas
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Credenciales inválidas
  /query/company-shareholders:
    post:
      summary: Consulta de información de accionistas por RFC
      operationId: requestCompanyShareholders
      description: >
        Permite obtener información detallada sobre los accionistas de una
        empresa a partir de su RFC. 

        La información incluye datos como nombre, nacionalidad, porcentaje de
        participación y más.


        La respuesta inicial confirmará el procesamiento de la consulta, y los
        datos detallados se enviarán posteriormente mediante un webhook
        configurado.


        **Respuesta inicial:**

        ```json

        {
            "message": "Consulta de SHAREHOLDERS procesada exitosamente.",
            "queryId": "6791b216ddf6a1c971a08624"
        }

        ```
      tags:
        - Consultas Empresariales
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC de la empresa a consultar
                  example: MOCKRFC123456
              required:
                - rfc
      responses:
        '200':
          description: Consulta exitosa de información de accionistas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyShareholdersResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /query/rfc-calculator:
    post:
      summary: Calcula el RFC de una Persona Física
      operationId: calculateRFC
      description: >
        Este endpoint permite calcular el RFC (Registro Federal de
        Contribuyentes) de una persona física proporcionando su nombre,
        apellidos y fecha de nacimiento.
      tags:
        - Consultas Fiscales
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Nombres de la persona.
                  example: ALAN ISAAC
                firstLastName:
                  type: string
                  description: Primer apellido de la persona.
                  example: CARDOZO
                secondLastName:
                  type: string
                  description: Segundo apellido de la persona (opcional).
                  example: AGUILAR
                day:
                  type: integer
                  description: Día de nacimiento.
                  example: 15
                month:
                  type: integer
                  description: Mes de nacimiento.
                  example: 1
                year:
                  type: integer
                  description: Año de nacimiento.
                  example: 1998
              required:
                - name
                - firstLastName
                - day
                - month
                - year
      responses:
        '200':
          description: RFC calculado exitosamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                    description: ID único de la consulta.
                    example: 6799511306b78436bf222363
                  service:
                    type: string
                    description: Servicio utilizado.
                    example: RFC_CALCULATOR
                  status:
                    type: string
                    description: Estado de la consulta.
                    example: SUCCESS
                  authentication:
                    type: string
                    description: Mecanismo de autenticación utilizado.
                    example: MOFFIN
                  metadata:
                    type: object
                    properties:
                      clientType:
                        type: string
                        description: Tipo de cliente.
                        example: PF
                      query:
                        type: object
                        properties:
                          name:
                            type: string
                            example: ALAN ISAAC
                          firstLastName:
                            type: string
                            example: CARDOZO
                          secondLastName:
                            type: string
                            example: AGUILAR
                          year:
                            type: integer
                            example: 1998
                          month:
                            type: integer
                            example: 1
                          day:
                            type: integer
                            example: 15
                  query:
                    type: object
                    properties:
                      name:
                        type: string
                        example: ALAN ISAAC
                      firstLastName:
                        type: string
                        example: CARDOZO
                      secondLastName:
                        type: string
                        example: AGUILAR
                      year:
                        type: integer
                        example: 1998
                      month:
                        type: integer
                        example: 1
                      day:
                        type: integer
                        example: 15
                  response:
                    type: object
                    properties:
                      rfc:
                        type: string
                        description: RFC calculado.
                        example: CAAA980115QN3
                  state:
                    type: object
                    description: Estado de la consulta.
                  organizationId:
                    type: integer
                    example: 1
                  organizationSlug:
                    type: string
                    example: moffin
                  profileId:
                    type: string
                    example: 99999
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-01-28T21:50:09.350Z'
                  updatedAt:
                    type: string
                    format: date-time
                    example: '2025-01-28T21:50:11.493Z'
        '400':
          description: Error en la solicitud.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Detalle del error.
                    example: El día no puede ser menor a 1.
        '500':
          description: Error interno del servidor.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Detalle del error.
                    example: Error procesando la consulta.
  /query/crf:
    post:
      summary: Consulta de Constancia de Régimen Fiscal (CRF)
      operationId: requestCRF
      description: >
        Permite obtener la Constancia de Régimen Fiscal (CRF) de un
        contribuyente a partir de su RFC.

        La respuesta inicial confirmará el procesamiento de la consulta, y los
        datos detallados se enviarán posteriormente mediante un webhook
        configurado.


        **Respuesta inicial:**

        ```json

        {
            "message": "Consulta de Certificado de régimen fiscal procesada exitosamente.",
            "queryId": "6791b216ddf6a1c971a08624"
        }

        ```
      tags:
        - Consultas Fiscales
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC del contribuyente a consultar
                  example: MOCKRFC123456
              required:
                - rfc
      responses:
        '200':
          description: Consulta exitosa del CRF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CRFWebhookResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /query/rfc-data:
    post:
      summary: Consulta de Datos del RFC
      operationId: requestRFCData
      description: >
        Permite obtener la información detallada del RFC de un contribuyente.

        La respuesta inicial confirmará el procesamiento de la consulta, y los
        datos detallados se enviarán posteriormente mediante un webhook
        configurado.


        **Respuesta inicial:**

        ```json

        {
            "message": "Consulta de RFC procesada exitosamente.",
            "queryId": "6791b7b4ddf6a1c971a08625"
        }

        ```
      tags:
        - Consultas Fiscales
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC del contribuyente a consultar
                  example: MOCKRFC123456
              required:
                - rfc
      responses:
        '200':
          description: Consulta exitosa de RFC
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RFCWebhookResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /query/curp-data:
    post:
      summary: Consulta de datos de CURP
      operationId: requestCURPData
      description: >
        Permite obtener información de un CURP, incluyendo datos personales y el
        RFC asociado.
      tags:
        - Consultas Fiscales
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                curp:
                  type: string
                  description: CURP del individuo a consultar
                  example: MOCKCURP123456XX9
              required:
                - curp
      responses:
        '200':
          description: Consulta exitosa de CURP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CURPResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCURPResponse'
  /query/job-history:
    post:
      summary: Consulta de Historial Laboral
      operationId: requestJobHistory
      description: >
        Permite obtener el historial laboral de un contribuyente a partir de su
        CURP.

        La respuesta inicial confirmará el procesamiento de la consulta, y los
        datos detallados se enviarán posteriormente mediante un webhook
        configurado.


        **Respuesta inicial:**

        ```json

        {
            "message": "Consulta de historial laboral procesada exitosamente.",
            "queryId": "6791b7b4ddf6a1c971a08626"
        }

        ```
      tags:
        - Consultas de Historial Laboral
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                curp:
                  type: string
                  description: CURP del contribuyente a consultar
                  example: AICA888888HMNJRC08
              required:
                - curp
      responses:
        '200':
          description: Consulta exitosa de historial laboral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobHistoryResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /query/sat/profile:
    post:
      summary: Creación de perfil SAT
      operationId: createProfileSAT
      description: >
        Para realizar consultas al SAT, primero es necesario crear el perfil de
        la persona a consultar proporcionando su RFC y CIEC.
      tags:
        - Consultas al SAT
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC del contribuyente (12 a 13 caracteres)
                  example: MOCKRFC123456
                ciec:
                  type: string
                  description: Clave de Identificación Electrónica Confidencial (CIEC)
                  example: '12345678'
              required:
                - rfc
                - ciec
      responses:
        '200':
          description: Perfil SAT creado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Perfil creado satisfactoriamente
                  rfc:
                    type: string
                    example: MOCKRFC123456
                  profileId:
                    type: integer
                    example: 27287
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                    example:
                      - El RFC debe tener al menos 12 caracteres.
        '403':
          description: CIEC y/o RFC inválidos
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: CIEC y/o RFC invalidos
                  rfc:
                    type: string
                    example: null
                  profileId:
                    type: integer
                    example: null
  /query/sat/csf:
    post:
      summary: Consulta de Situación Fiscal (CSF)
      operationId: requestProfileCSF
      description: >
        Permite consultar la situación fiscal de un contribuyente mediante su
        RFC.


        **Nota:** Antes de realizar esta consulta, es necesario crear un perfil
        SAT con el RFC y la CIEC.


        **Body de la solicitud:**

        ```json

        {
            "rfc": "MOCKRFC123456"
        }

        ```
      tags:
        - Consultas al SAT
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC del contribuyente a consultar
                  example: MOCKRFC123456
              required:
                - rfc
      responses:
        '200':
          description: Consulta exitosa del CSF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CSFResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorProfileNotFound'
  /query/sat/compliance-opinion:
    post:
      summary: Consulta de Opinión de Cumplimiento (32D)
      operationId: requestProfile32D
      description: >
        Permite obtener la Opinión de Cumplimiento (32D) de un contribuyente a
        partir de su RFC.


        **Nota:** Antes de realizar esta consulta, es necesario crear un perfil
        SAT con el RFC y la CIEC.


        **Importante:** La respuesta inicial confirmará el procesamiento de la
        consulta y los datos detallados se enviarán posteriormente mediante un
        webhook configurado.


        **Respuesta inicial:**

        ```json

        {
            "message": "Solicitud de 32D procesada exitosamente",
            "queryId": "6791b7b4ddf6a1c971a08625"
        }

        ```
      tags:
        - Consultas al SAT
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC del contribuyente a consultar
                  example: MOCKRFC123456
              required:
                - rfc
      responses:
        '200':
          description: Solicitud de Opinión de Cumplimiento procesada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceOpinionResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorProfileNotFound'
  /query/sat/invoice:
    post:
      summary: Consulta de Facturas SAT
      operationId: requestProfileInvoice
      description: >
        Permite obtener las facturas de un contribuyente a partir de su RFC y un
        período de consulta.


        **Nota:** Antes de realizar esta consulta, es necesario crear un perfil
        SAT con el RFC y la CIEC.


        **Importante:** La respuesta inicial confirmará el procesamiento de la
        consulta y los datos detallados se enviarán posteriormente mediante un
        webhook configurado.


        **Respuesta inicial:**

        ```json

        {
            "message": "Solicitud de facturas procesada exitosamente",
            "results": [
                {
                    "queryId": "6791c6756a250515924f140f",
                    "period": "2025-1",
                    "status": "PENDING"
                },
                {
                    "queryId": "6791c6796a250515924f1411",
                    "period": "2024-12",
                    "status": "PENDING"
                }
            ]
        }

        ```
      tags:
        - Consultas al SAT
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rfc:
                  type: string
                  description: RFC del contribuyente a consultar
                  example: MOCKRFC123456
                period:
                  type: string
                  enum:
                    - 1M
                    - 3M
                    - 6M
                    - 1Y
                    - 2Y
                    - 3Y
                  description: Período de consulta de facturas
                  example: 1Y
              required:
                - rfc
                - period
      responses:
        '200':
          description: Solicitud de consulta de facturas procesada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
        '400':
          description: Error en la solicitud
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorProfileNotFound'
  /query:
    get:
      summary: Obtener todas las consultas realizadas
      operationId: getAllQueries
      description: Devuelve una lista de todas las consultas realizadas en el sistema.
      tags:
        - Query Retrieval
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Número máximo de resultados por página
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: Número de página a recuperar
          schema:
            type: integer
            default: 1
        - name: status
          in: query
          description: Estado de la consulta (ej. SUCCESS, PENDING, FAILED)
          schema:
            type: string
            enum:
              - SUCCESS
              - PENDING
              - FAIL
        - name: profileId
          in: query
          description: ID del perfil asociado a la consulta
          schema:
            type: integer
        - name: service
          in: query
          description: Tipo de servicio consultado
          schema:
            type: string
            enum:
              - CSF
              - CRF
              - RFC
              - JOB_HISTORY
              - 32D
              - invoices
        - name: queryId
          in: query
          description: ID único de la consulta
          schema:
            type: string
      responses:
        '200':
          description: Lista de consultas recuperada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQueriesResponse'
  /query/{queryId}:
    get:
      summary: Obtener una consulta específica por ID
      operationId: getQueryById
      description: Devuelve los detalles de una consulta específica a partir de su ID.
      tags:
        - Query Retrieval
      security:
        - bearerAuth: []
      parameters:
        - name: queryId
          in: path
          required: true
          description: ID único de la consulta a recuperar
          schema:
            type: string
      responses:
        '200':
          description: Consulta recuperada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQueryByIdResponse'
components:
  schemas:
    Authentication:
      type: object
      properties:
        grantType:
          type: string
          description: Tipo de autorización requerido para obtener un token de acceso
          example: client_credentials
          enum:
            - client_credentials
            - refresh_token
        clientId:
          type: string
          description: >-
            Identificador único proporcionado por Moffin para autenticar la
            solicitud
          example: MOFFIN_cccccccc-aaaa-5555-aa33-11111111111
        clientSecret:
          type: string
          description: Secreto único proporcionado por Moffin para autenticar la solicitud
          example: eeeee111-aa221-2313-1111-a15aa15c15aa
      required:
        - grantType
        - clientId
        - clientSecret
    AuthResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: Token de acceso JWT generado
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        refreshToken:
          type: string
          description: Token de actualización JWT
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        tokenType:
          type: string
          description: Tipo de token devuelto
          example: Bearer
        accessTokenExpiresAt:
          type: integer
          description: Fecha de expiración del token de acceso en formato Unix timestamp
          example: 1737686951
        refreshTokenExpiresAt:
          type: integer
          description: >-
            Fecha de expiración del token de actualización en formato Unix
            timestamp
          example: 1738205351
    CRFWebhookResponse:
      type: object
      properties:
        _id:
          type: string
          description: Identificador único de la consulta
          example: abcdef1234567890
        service:
          type: string
          example: CRF
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOFFIN
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PF
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: MOCKRFC123456
        query:
          type: object
          properties:
            rfc:
              type: string
              example: MOCKRFC123456
        response:
          type: object
          properties:
            RFC:
              type: string
              example: MOCKRFC123456
            RazonSocial:
              type: string
              example: EMPRESA MOCK S.A. DE C.V.
            ValidoDesde:
              type: string
              format: date-time
              example: '2021-06-08T12:35:54'
            ValidoHasta:
              type: string
              format: date-time
              example: '2025-06-08T12:36:34'
            RFCRepresentante:
              type: string
            CURPRepresentante:
              type: string
              example: MOCKCURP123456
            EmailContacto:
              type: string
              example: contacto@example.com
            EstadoCertificado:
              type: string
              example: Vigente
            NumeroCertificado:
              type: string
              example: '00001000000507699213'
            Valido:
              type: boolean
              example: true
            Municipio:
              type: string
              example: Cuauhtémoc
            Estado:
              type: string
              example: Ciudad de México
            Ciudad:
              type: string
              example: Ciudad de México
            OficinaPostal:
              type: string
              example: '06002'
            Zona:
              type: string
              example: Urbano
            EstadoISO:
              type: string
              example: CMX
            CodigoPostal:
              type: string
              example: '00000'
            RegimenesFiscales:
              type: array
              items:
                type: object
                properties:
                  codigo:
                    type: string
                    example: '611'
                  descripcion:
                    type: string
                    example: Ingresos por Dividendos (socios y accionistas)
                  personaFisica:
                    type: boolean
                    example: true
                  personaMoral:
                    type: boolean
                    example: false
        state:
          type: object
          properties:
            FISCAL_DATA:
              type: object
              properties:
                validationCode:
                  type: string
                  example: '20112068'
        organizationId:
          type: integer
          example: 1
        organizationSlug:
          type: string
          example: moffin
        profileId:
          type: integer
          example: 1217955
        createdAt:
          type: string
          format: date-time
          example: '2025-01-23T03:05:58.729Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-23T03:06:00.543Z'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          example:
            - El RFC no debe tener más de 13 caracteres.
    ErrorCURPResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          example:
            - >-
              El CURP debe seguir el formato oficial (4 letras, 6 números, sexo,
              5 letras y 2 caracteres alfanuméricos).
            - El CURP debe tener exactamente 18 caracteres.
    RFCWebhookResponse:
      type: object
      properties:
        _id:
          type: string
          example: 6791b7b4ddf6a1c971a08625
        service:
          type: string
          example: RFC
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOFFIN
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PM
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: CCC222222C19
        query:
          type: object
          properties:
            rfc:
              type: string
              example: CCC222222C19
        response:
          type: object
          properties:
            RFC:
              type: string
              example: CCC222222C19
            RazonSocial:
              type: string
              example: INTERNACIONAL SA DE CV
            ValidoDesde:
              type: string
              format: date-time
              example: '2023-10-20T13:37:35'
            ValidoHasta:
              type: string
              format: date-time
              example: '2027-10-20T13:38:15'
            RFCRepresentante:
              type: string
              example: ALCJ8888888B8
            CURPRepresentante:
              type: string
              example: AICL888888HOCLSN06
            EmailContacto:
              type: string
              example: diian@acme.com
            EstadoCertificado:
              type: string
              example: Vigente
            NumeroCertificado:
              type: string
              example: '00001000000703019308'
            Valido:
              type: boolean
              example: true
            Municipio:
              type: string
              example: Cuauhtémoc
            Estado:
              type: string
              example: Ciudad de México
            Ciudad:
              type: string
              example: Ciudad de México
            OficinaPostal:
              type: string
              example: '06002'
            Zona:
              type: string
              example: Urbano
            EstadoISO:
              type: string
              example: CMX
            CodigoPostal:
              type: string
              example: '06000'
        state:
          type: object
          properties:
            FISCAL_DATA:
              type: object
              properties:
                validationCode:
                  type: string
                  example: '20112451'
        organizationId:
          type: integer
          example: 1
        organizationSlug:
          type: string
          example: moffin
        profileId:
          type: integer
          example: 1183443
        createdAt:
          type: string
          format: date-time
          example: '2025-01-23T03:29:56.947Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-23T03:29:57.965Z'
    JobHistoryResponse:
      type: object
      properties:
        _id:
          type: string
          example: 6791b9d091fa0dfcd7e8fe67
        service:
          type: string
          example: JOB_HISTORY
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOFFIN
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PF
            query:
              type: object
              properties:
                curp:
                  type: string
                  example: AICA888888HMNJRC08
        query:
          type: object
          properties:
            curp:
              type: string
              example: AICA888888HMNJRC08
        response:
          type: object
          properties:
            nss:
              type: string
              example: '19999999999'
            curp:
              type: string
              example: AICA888888HMNJRC08
            fechaEmision:
              type: string
              example: 22/01/2025
            semanasCotizadas:
              type: integer
              example: 52
            semanasDescontadas:
              type: integer
              example: 0
            semanasReintegradas:
              type: integer
              example: 0
            empleos:
              type: array
              items:
                type: object
                properties:
                  patron:
                    type: string
                    example: ACME SA
                  registroPatronal:
                    type: string
                    example: R133333333
                  entidadFederativa:
                    type: string
                    example: JALISCO
                  fechaAlta:
                    type: string
                    example: 13/11/2017
                  fechaBaja:
                    type: string
                    example: 13/11/2018
                  salarioBase:
                    type: string
                    example: $160
        state:
          type: object
          properties:
            JOB_HISTORY:
              type: object
              properties:
                validationCode:
                  type: string
                  example: 3fa1aa24-c065-4c9c-8b54-164c7f416362
        organizationId:
          type: integer
          example: 1
        organizationSlug:
          type: string
          example: moffin
        profileId:
          type: integer
          example: 1209967
        createdAt:
          type: string
          format: date-time
          example: '2025-01-23T03:38:56.954Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-23T03:39:01.671Z'
    CSFResponse:
      type: object
      properties:
        _id:
          type: string
          example: 6791bc81d68f4ff2b76493d2
        service:
          type: string
          example: CSF
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOFFIN
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PM
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: MOCKRFC123456
        query:
          type: object
          properties:
            rfc:
              type: string
              example: MOCKRFC123456
        response:
          type: object
          properties:
            claveMensaje:
              type: integer
              example: 0
            pdf:
              type: string
              example: >-
                https://deorp2zq6pc3v.cloudfront.net/csf/ac7b0db2-5fcc-4fcf-9075-8b1395643c90-MOCKRFC123456-CSF.pdf
            datosSat:
              type: object
              properties:
                caracteristicasFiscales:
                  type: array
                  items:
                    type: object
                    properties:
                      codigo:
                        type: string
                        example: '626'
                      fechaAlta:
                        type: string
                        example: 09/07/1961
                      regimen:
                        type: string
                        example: Régimen Simplificado de Confianza
                cif:
                  type: string
                  example: '22111133331'
                claveMensaje:
                  type: string
                  example: '0'
                codigoValidacion:
                  type: string
                  example: ci1737604327.7255583
                datosIdentificacion:
                  type: object
                  properties:
                    fechaConstitucion:
                      type: string
                      example: 09/07/1961
                    fechaInicioOperaciones:
                      type: string
                      example: 09/07/1961
                    fechaUltimoCambioSituacion:
                      type: string
                      example: 09/07/1961
                    razonSocial:
                      type: string
                      example: ACME SA
                    regimenCapital:
                      type: string
                      example: S A P I DE CV
                    situacionContribuyente:
                      type: string
                      example: ACTIVO
                datosUbicacion:
                  type: object
                  properties:
                    al:
                      type: string
                      example: JALISCO 9998
                    colonia:
                      type: string
                      example: CHAPALITA ORIENTE
                    correoElectronico:
                      type: string
                      example: facturacion@acme.net
                    cp:
                      type: string
                      example: '45040'
                    entidadFederativa:
                      type: string
                      example: JALISCO
                    municipioDelegacion:
                      type: string
                      example: ZAPOPAN
                    nombreVialidad:
                      type: string
                      example: TEPEYAC
                    numeroExterior:
                      type: string
                      example: '9999'
                    numeroInterior:
                      type: string
                      example: '34'
                    tipoVialidad:
                      type: string
                      example: AVENIDA (AV.)
                estatus:
                  type: string
                  example: OK
                informacionAdicional:
                  type: object
                  properties:
                    actividadesEconomicas:
                      type: array
                      items:
                        type: object
                        properties:
                          actividad:
                            type: string
                            example: Transmisores, dispersores de dinero.Dispersores
                          fechaInicio:
                            type: string
                            example: 16/04/2021
                          orden:
                            type: string
                            example: '5'
                          porcentaje:
                            type: string
                            example: '2'
                    lugarFecha:
                      type: string
                      example: ZAPOPAN , JALISCO A 22 DE ENERO DE 2025
                rfc:
                  type: string
                  example: MOCKRFC123456
            codigoValidacion:
              type: string
              example: cs1737604226.9306736
        organizationId:
          type: integer
          example: 1
        organizationSlug:
          type: string
          example: moffin
        profileId:
          type: integer
          example: 27287
        createdAt:
          type: string
          example: '2025-01-23T03:50:25.858Z'
        updatedAt:
          type: string
          example: '2025-01-23T03:52:11.224Z'
    ErrorProfileNotFound:
      type: object
      properties:
        message:
          type: string
          example: >-
            El perfil no existe. Primero debe crear un perfil con CIEC
            utilizando el endpoint POST /api/query/sat/profile
    ComplianceOpinionResponse:
      type: object
      properties:
        _id:
          type: string
          example: 6791c34927ad40b9491c3455
        service:
          type: string
          example: 32D
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOFFIN
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PM
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: MOCKRFC123456
        query:
          type: object
          properties:
            rfc:
              type: string
              example: MOCKRFC123456
        response:
          type: object
          properties:
            opinion:
              type: string
              example: POSITIVA
              enum:
                - POSITIVA
                - NEGATIVA
            pdf:
              type: string
              example: >-
                https://deorp2zq6pc3v.cloudfront.net/32D/9b8a94bb-fc55-46db-afcf-f475d9020ae7-MOCKRFC123456-32D.pdf
        state:
          type: object
          properties:
            validationCode:
              type: string
              example: gf1737605987.659957
            retry:
              type: integer
              example: 1
        organizationId:
          type: integer
          example: 1
        organizationSlug:
          type: string
          example: moffin
        profileId:
          type: integer
          example: 27287
        createdAt:
          type: string
          example: '2025-01-23T04:19:21.953Z'
        updatedAt:
          type: string
          example: '2025-01-23T04:19:47.691Z'
    InvoiceResponse:
      type: object
      properties:
        _id:
          type: string
          example: 1234567890abcdef12345678
        service:
          type: string
          example: invoices
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOCK_AUTH
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PM
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: ABC123456T89
        query:
          type: object
          properties:
            rfc:
              type: string
              example: ABC123456T89
        response:
          type: object
          properties:
            periodo:
              type: string
              example: 2025-01
            totalEmitidas:
              type: string
              example: $100,000.00
            totalRecibidas:
              type: string
              example: $50,000.00
            totalDiferencia:
              type: string
              example: $50,000.00
            facturasEmitidas:
              type: array
              items:
                type: object
                properties:
                  folio:
                    type: string
                    example: MOCK1234-5678-ABCD-EFGH
                  rfcEmisor:
                    type: string
                    example: ABC123456T89
                  razonSocialEmisor:
                    type: string
                    example: EMPRESA MOCK
                  rfcReceptor:
                    type: string
                    example: XYZ987654A21
                  razonSocialReceptor:
                    type: string
                    example: CLIENTE MOCK
                  fechaEmision:
                    type: string
                    example: '2025-01-15T10:00:00'
                  fechaCertificacion:
                    type: string
                    example: '2025-01-15T10:30:00'
                  pac:
                    type: string
                    example: MOCKPAC123456
                  monto:
                    type: string
                    example: $10,000.00
                  efecto:
                    type: string
                    example: Ingreso
                  estatus:
                    type: string
                    example: Cancelable con aceptación
                  estado:
                    type: string
                    example: Vigente
                  estatusProcesoCancelacion:
                    type: string
                    example: null
                  fechaProcesoCancelacion:
                    type: string
                    example: null
                  rfcCuentaTerceros:
                    type: string
                    example: null
                  motivo:
                    type: string
                    example: null
                  folioSustitucion:
                    type: string
                    example: null
            facturasRecibidas:
              type: array
              items:
                type: object
                properties:
                  folio:
                    type: string
                    example: MOCK9876-5432-DCBA-HGFE
                  rfcEmisor:
                    type: string
                    example: XYZ987654A21
                  razonSocialEmisor:
                    type: string
                    example: PROVEEDOR MOCK
                  rfcReceptor:
                    type: string
                    example: ABC123456T89
                  razonSocialReceptor:
                    type: string
                    example: EMPRESA MOCK
                  fechaEmision:
                    type: string
                    example: '2025-01-10T12:00:00'
                  fechaCertificacion:
                    type: string
                    example: '2025-01-10T12:15:00'
                  pac:
                    type: string
                    example: MOCKPAC654321
                  monto:
                    type: string
                    example: $5,000.00
                  efecto:
                    type: string
                    example: Egreso
                  estatus:
                    type: string
                    example: Cancelable sin aceptación
                  estado:
                    type: string
                    example: Vigente
                  estatusProcesoCancelacion:
                    type: string
                    example: null
                  fechaProcesoCancelacion:
                    type: string
                    example: null
                  rfcCuentaTerceros:
                    type: string
                    example: null
            codigoValidacion:
              type: string
              example: mock123456789
            message:
              type: string
              example: null
        state:
          type: object
          properties:
            invoices:
              type: object
              properties:
                validationCode:
                  type: string
                  example: mock123456789
        organizationId:
          type: integer
          example: 99
        organizationSlug:
          type: string
          example: mock-organization
        profileId:
          type: integer
          example: 55555
        createdAt:
          type: string
          example: '2025-01-23T10:00:00.000Z'
        updatedAt:
          type: string
          example: '2025-01-23T10:05:00.000Z'
    ServiceQueriesResponse:
      type: object
      properties:
        message:
          type: string
          example: Service queries fetched successfully
        serviceQueries:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
                example: 672bfc42f4ebfc8b8c5440ce
              service:
                type: string
                example: JOB_HISTORY
              status:
                type: string
                example: SUCCESS
              authentication:
                type: string
                example: MOFFIN
              metadata:
                type: object
                properties:
                  clientType:
                    type: string
                    example: PF
                  query:
                    type: object
                    properties:
                      curp:
                        type: string
                        example: AICAC999999HHHCRB99
              query:
                type: object
                properties:
                  curp:
                    type: string
                    example: AICAC999999HHHCRB99
              response:
                type: object
                properties:
                  nss:
                    type: string
                    example: '99919999090'
                  curp:
                    type: string
                    example: AICAC999999HHHCRB99
                  fechaEmision:
                    type: string
                    example: 07/01/2025
                  semanasCotizadas:
                    type: integer
                    example: 165
                  semanasDescontadas:
                    type: integer
                    example: 0
                  semanasReintegradas:
                    type: integer
                    example: 0
                  empleos:
                    type: array
                    items:
                      type: object
                      properties:
                        patron:
                          type: string
                          example: ACME SA DE CV
                        registroPatronal:
                          type: string
                          example: R12121129120
                        entidadFederativa:
                          type: string
                          example: JALISCO
                        fechaAlta:
                          type: string
                          example: 01/03/2021
                        fechaBaja:
                          type: string
                          example: 30/04/2024
                        salarioBase:
                          type: string
                          example: $999.99
              state:
                type: object
                properties:
                  JOB_HISTORY:
                    type: object
                    properties:
                      validationCode:
                        type: string
                        example: db209053-be1b-4d50-ac9d-d3aa1444943f
              organizationId:
                type: integer
                example: 1
              organizationSlug:
                type: string
                example: moffin
              profileId:
                type: integer
                example: 11111119
              createdAt:
                type: string
                format: date-time
                example: '2024-11-06T23:31:13.902Z'
              updatedAt:
                type: string
                format: date-time
                example: '2025-01-07T15:49:04.175Z'
        total:
          type: integer
          example: 13
        limit:
          type: integer
          example: 1
        page:
          type: integer
          example: 1
    ServiceQueryByIdResponse:
      type: object
      properties:
        message:
          type: string
          example: Service query fetched successfully
        serviceQuery:
          type: object
          properties:
            _id:
              type: string
              example: mock_id_123456
            service:
              type: string
              example: RFC
            status:
              type: string
              example: SUCCESS
            authentication:
              type: string
              example: MOCK_AUTH
            metadata:
              type: object
              properties:
                clientType:
                  type: string
                  example: PM
                query:
                  type: object
                  properties:
                    rfc:
                      type: string
                      example: MOCKRFC123
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: MOCKRFC123
            response:
              type: object
              properties:
                RFC:
                  type: string
                  example: MOCKRFC123
                RazonSocial:
                  type: string
                  example: MOCK COMPANY SA DE CV
                ValidoDesde:
                  type: string
                  example: '2023-01-01T00:00:00'
                ValidoHasta:
                  type: string
                  example: '2027-01-01T00:00:00'
                EmailContacto:
                  type: string
                  example: contacto@mockcompany.com
            createdAt:
              type: string
              format: date-time
              example: '2025-01-23T03:29:56.947Z'
            updatedAt:
              type: string
              format: date-time
              example: '2025-01-23T03:29:57.965Z'
    CURPResponse:
      type: object
      properties:
        _id:
          type: string
          example: mock123456789
        service:
          type: string
          example: CURP
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOCK_AUTH
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PF
            query:
              type: object
              properties:
                curp:
                  type: string
                  example: MOCKCURP123456XX9
        query:
          type: object
          properties:
            curp:
              type: string
              example: MOCKCURP123456XX9
        response:
          type: object
          properties:
            rfc:
              type: string
              example: MOCKRFC123456
            estatus:
              type: string
              example: OK
            codigoValidacion:
              type: string
              example: mock-validation-code
            curp:
              type: string
              example: MOCKCURP123456XX9
            nombre:
              type: string
              example: JOHN
            apellidoPaterno:
              type: string
              example: DOE
            apellidoMaterno:
              type: string
              example: SMITH
            sexo:
              type: string
              example: HOMBRE
            fechaNacimiento:
              type: string
              format: date
              example: 09/07/1961
            paisNacimiento:
              type: string
              example: MEXICO
            estadoNacimiento:
              type: string
              example: CIUDAD DE MEXICO
            docProbatorio:
              type: integer
              example: 1
            datosDocProbatorio:
              type: object
              properties:
                anioReg:
                  type: string
                  example: '1990'
                claveEntidadRegistro:
                  type: string
                  example: '09'
                claveMunicipioRegistro:
                  type: string
                  example: ''
                entidadRegistro:
                  type: string
                  example: CIUDAD DE MEXICO
                foja:
                  type: string
                  example: ''
                folio:
                  type: string
                  example: ''
                libro:
                  type: string
                  example: ''
                municipioRegistro:
                  type: string
                  example: ''
                numActa:
                  type: string
                  example: ''
                numRegExtranjeros:
                  type: string
                  example: ''
                tomo:
                  type: string
                  example: ''
            estatusCurp:
              type: string
              enum:
                - AN
                - AH
                - RCC
                - RCN
                - BAP
                - BSU
                - BD
                - BDM
                - BDP
                - BJD
              x-enumDescriptions:
                - Normal registration
                - Registration with homonymy
                - Registration change affecting CURP
                - Registration change not affecting CURP
                - Unsubscribed due to apocryphal document
                - Unsubscribed without use
                - Unsubscribed due to death
                - Administrative unsubscription
                - Unsubscribed due to adoption
                - Judicial unsubscription
            codigoMensaje:
              type: string
              example: '0'
        organizationId:
          type: integer
          example: 99
        organizationSlug:
          type: string
          example: mock-organization
        profileId:
          type: integer
          example: 12345
        createdAt:
          type: string
          format: date-time
          example: '2025-01-23T19:26:07.076Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-23T19:26:07.259Z'
    CompanyShareholdersResponse:
      type: object
      properties:
        _id:
          type: string
          example: mock_id_123456
        service:
          type: string
          example: COMPANY_SHAREHOLDERS
        status:
          type: string
          example: SUCCESS
        authentication:
          type: string
          example: MOFFIN
        metadata:
          type: object
          properties:
            clientType:
              type: string
              example: PM
            query:
              type: object
              properties:
                rfc:
                  type: string
                  example: MOCKRFC123456
        query:
          type: object
          properties:
            rfc:
              type: string
              example: MOCKRFC123456
        response:
          type: object
          properties:
            RFC:
              type: string
              example: MOCKRFC123456
            RazonSocial:
              type: string
              example: EMPRESA MOCK S.A. DE C.V.
            Municipio:
              type: string
              example: Mock Municipio
            Estado:
              type: string
              example: Mock Estado
            Ciudad:
              type: string
              example: Mock Ciudad
            OficinaPostal:
              type: string
              example: '12345'
            Zona:
              type: string
              example: Urbano
            CodigoPostal:
              type: string
              example: '12300'
            RegimenJuridico:
              type: string
              example: S.A. DE C.V.
            EntidadFederativa:
              type: string
              example: MOCK FEDERATIVA
            Duracion:
              type: string
              example: '99'
            Inscripcion:
              type: string
              example: COMERCIO
            EstatusEmpresa:
              type: string
              example: Activa
            DomicilioSocial:
              type: string
              example: MOCK, D.F.
            Accionistas:
              type: array
              items:
                type: object
                properties:
                  Estatus:
                    type: string
                    example: Activo
                  Nacionalidad:
                    type: string
                    example: Mexicana
                  Nombre:
                    type: string
                    example: JUAN
                  ApellidoPaterno:
                    type: string
                    example: PEREZ
                  ApellidoMaterno:
                    type: string
                    example: LOPEZ
                  RFC:
                    type: string
                    example: DCR234234234
                  CURP:
                    type: string
                    example: CURPMOCK123234
                  Serie:
                    type: string
                    example: A
                  FechaNacimiento:
                    type: string
                    example: 17/03/1985
                  Acciones:
                    type: integer
                    example: 10
                  Valor:
                    type: integer
                    example: 100000
                  Porcentaje:
                    type: string
                    example: 100.00%
        state:
          type: object
          properties:
            COMPANY_SHAREHOLDERS:
              type: object
              properties:
                validationCode:
                  type: string
                  example: mock_validation_12345
        createdAt:
          type: string
          format: date-time
          example: '2025-01-27T08:56:36.578Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-01-27T08:56:38.811Z'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
