openapi: 3.0.0
info:
  title: API Proveedores GEC
  version: 1.0.0
  description: Rest API de Proveedores GEC - EMPRESS
servers:
  - url: https://sandbox-proveedores-gobcolima.gob-digital.mx
    description: Sandbox
tags:
  - name: Proveedores
    description: Operaciones de consulta de proveedores
  - name: Actividades SAT
    description: Operaciones del catalogo de actividades SAT
  - name: Documentos
    description: Operaciones de consulta del catalogo de documentos requeridos
paths:
  /api/proveedores:
    get:
      summary: Obtener proveedores
      description: |
        Retorna una lista de proveedores aplicando filtros opcionales.
        Todos los parametros son opcionales y se envian via query string.
      tags:
        - Proveedores
      parameters:
        - $ref: '#/components/parameters/ApiKeyHeader'
        - in: query
          name: IdProv
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 99999999
          description: Identificador del proveedor como entero (máximo 8 dígitos)
        - in: query
          name: NombreComercial
          required: false
          schema:
            type: string
            maxLength: 500
          description: Nombre Comercial del proveedor (máximo 500 caracteres)
        - in: query
          name: DenominacionRazonSocial
          required: false
          schema:
            type: string
            maxLength: 500
          description: Denominación o Razón Social del proveedor (máximo 500 caracteres)
        - in: query
          name: Rfc
          required: false
          schema:
            type: string
            maxLength: 13
          description: RFC del proveedor (máximo 13 caracteres)
        - in: query
          name: ActividadSAT
          required: false
          style: form
          explode: true
          schema:
            oneOf:
              - type: array
                items:
                  type: string
                  pattern: '^\d{1,4}$'
              - type: string
                pattern: '^\d{1,4}$'
          description: Actividad SAT. Permite uno solo (?ActividadSAT=1) o múltiples repetidos (?ActividadSAT=1&ActividadSAT=2), de 1 a 4 digitos
      responses:
        '200':
          description: Lista de proveedores obtenida correctamente
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProveedorDTO'
        '400':
          description: Error de validacion en request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '401':
          description: API key faltante o invalida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
    post:
      summary: Registrar nuevo proveedor
      description: |
        Registra un nuevo proveedor en el padron.
        Si la solicitud se envía como application/json, se crea el proveedor sin intento de carga de archivos y la respuesta exitosa es 201.
        Si la solicitud se envía como multipart/form-data, se pueden adjuntar documentos; en ese caso, si la creación del proveedor fue exitosa pero falló la carga de archivos, la respuesta es 202.
        Para documentos adjuntos, se debe consultar previamente el catalogo de /api/documentos para conocer los nombres de parametros de archivo requeridos (cada IdDoc es un parámetro) y enviar un solo archivo PDF por cada IdDoc.
        Cada archivo adjunto debe ser PDF y su tamaño no debe exceder 8 MB.
        Requiere API Key en el header para autenticacion.
      tags:
        - Proveedores
      parameters:
        - $ref: '#/components/parameters/ApiKeyHeader'
      requestBody:
        required: true
        description: |
          El alta permite dos modalidades: application/json para solo datos, o multipart/form-data para enviar datos y documentos.
          En multipart/form-data, cada IdDoc acepta un solo archivo PDF y cada archivo debe pesar 8 MB o menos.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NuevoProveedorDTO'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/NuevoProveedorDTO'
            encoding:
              ActividadesSAT:
                style: form
                explode: true
      responses:
        '201':
          description: Proveedor creado correctamente sin error en la carga de archivos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistroProveedorResponseDTO'
              example:
                IdProv: '0'
                DenomRazonSocial: ''
                Rfc: PAP181818AA
                Code: '1'
                Mensaje: Proveedor creado exitosamente
        '202':
          description: Proveedor creado correctamente, pero hubo un problema en la carga de archivos. Solo aplica cuando la solicitud fue multipart/form-data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistroProveedorResponseDTO'
              example:
                IdProv: '0'
                DenomRazonSocial: ''
                Rfc: PAP181818AA
                Code: 7
                Mensaje: Proveedor creado exitosamente, pero hubo un problema en la carga de archivos
        '400':
          description: Error de validacion en request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '401':
          description: API key faltante o invalida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
  /api/proveedores/{IdProv}/documentos:
    patch:
      summary: Actualizar documentos de un proveedor
      description: |
        Actualiza los documentos de un proveedor registrado.
        El proveedor se identifica por el parametro de ruta `IdProv` y por el RFC enviado en el cuerpo.
        Los archivos se envian en formato multipart/form-data usando como nombre de campo el IdDoc del catalogo de documentos requeridos.
        Cada IdDoc acepta un solo archivo PDF y cada archivo no debe exceder 8 MB.
        Requiere API Key en el header para autenticacion.
      tags:
        - Proveedores
      parameters:
        - $ref: '#/components/parameters/ApiKeyHeader'
        - in: path
          name: IdProv
          required: true
          schema:
            type: string
          description: Identificador del proveedor a actualizar
      requestBody:
        required: true
        description: |
          Cada campo de documento debe enviarse como un único archivo PDF.
          No se permiten arreglos ni múltiples archivos por el mismo IdDoc, y el tamaño máximo por archivo es 8 MB.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                Rfc:
                  type: string
                  minLength: 12
                  maxLength: 13
                  description: RFC del proveedor a actualizar
                '1':
                  type: string
                  format: binary
                  description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
                '2':
                  type: string
                  format: binary
                  description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
                '3':
                  type: string
                  format: binary
                  description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
                '4':
                  type: string
                  format: binary
                  description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
                '5':
                  type: string
                  format: binary
                  description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
              required:
                - Rfc
            encoding:
              Rfc:
                style: form
      responses:
        '200':
          description: Documentos del proveedor actualizados correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistroProveedorResponseDTO'
              example:
                IdProv: '123'
                DenomRazonSocial: PROVEEDOR DEMO SA DE CV
                Rfc: PDM181818AA12
                Code: '1'
                Mensaje: Documentos de proveedor actualizados exitosamente
        '400':
          description: Error de validacion en request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '401':
          description: API key faltante o invalida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
  /api/actividades-sat:
    get:
      summary: Obtener catalogo de actividades SAT
      description: |
        Retorna el catalogo de actividades economicas del SAT.
        Requiere API Key en el header para autenticacion.
      tags:
        - Actividades SAT
      parameters:
        - $ref: '#/components/parameters/ApiKeyHeader'
      responses:
        '200':
          description: Catalogo obtenido correctamente
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActividadSATDTO'
                example:
                  - IdClave: 1
                    Actividad: Agricultura
                  - IdClave: 2
                    Actividad: Ganaderia
        '400':
          description: Error de validacion en request o en la obtencion del catalogo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '401':
          description: API key faltante o invalida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
  /api/documentos:
    get:
      summary: Obtener catalogo de documentos requeridos
      description: |
        Retorna el catalogo de documentos requeridos para alta de proveedor.
        Permite filtrar por tipo de persona: F (fisica) o M (moral).
        Si no se envia tipoPersona, retorna todos los documentos.
      tags:
        - Documentos
      parameters:
        - $ref: '#/components/parameters/ApiKeyHeader'
        - in: query
          name: tipoPersona
          required: false
          schema:
            type: string
            enum:
              - F
              - M
          description: Tipo de persona para filtrar documentos (F fisica, M moral). Si se omite, se devuelven todos.
      responses:
        '200':
          description: Catalogo de documentos obtenido correctamente
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentoDTO'
              example:
                - IdDoc: '1'
                  Documento: IDENTIFICACION OFICIAL
                  AplicaPara: FISICA/MORAL
                  EsRequerido: SI
                - IdDoc: '4'
                  Documento: ACTA CONSTITUTIVA
                  AplicaPara: MORAL
                  EsRequerido: SI
        '400':
          description: Error de validacion en request o en la obtencion del catalogo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '401':
          description: API key faltante o invalida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomErrorResponse'
components:
  parameters:
    ApiKeyHeader:
      in: header
      name: x-emp-api-key
      required: true
      schema:
        type: string
      description: API Key requerida para autenticacion
  schemas:
    ErrorDetail:
      type: object
      properties:
        path:
          type: string
          example: /query/IdProv
        message:
          type: string
          example: must match pattern "^\\d{0,8}$"
        location:
          type: string
          example: query
      required:
        - path
        - message
    CustomErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          example: REQUEST_VALIDATION_FAILED
        message:
          type: string
          example: Request validation failed
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          nullable: true
      required:
        - success
        - code
        - message
        - details
    ActividadSATDTO:
      type: object
      properties:
        IdClave:
          type: integer
          format: int32
          minimum: 0
          maximum: 32767
        Actividad:
          type: string
      required:
        - IdClave
        - Actividad
    DocumentoDTO:
      type: object
      properties:
        IdDoc:
          type: string
          description: Identificador del documento
          example: '1'
        Documento:
          type: string
          description: Nombre o descripcion del documento
          example: IDENTIFICACION OFICIAL
        AplicaPara:
          type: string
          description: Tipo de persona al que aplica el documento (por ejemplo FISICA, MORAL o FISICA/MORAL)
          example: FISICA/MORAL
        EsRequerido:
          type: string
          enum:
            - SI
            - NO
          description: Indica si el documento es obligatorio
          example: SI
      required:
        - IdDoc
        - Documento
        - AplicaPara
        - EsRequerido
    ProveedorDTO:
      type: object
      properties:
        IdProv:
          type: string
        Rfc:
          type: string
        NombreComercial:
          type: string
        DenomRazonSocial:
          type: string
        Dat_ASat:
          type: array
          items:
            $ref: '#/components/schemas/ActividadSATDTO'
      required:
        - IdProv
        - Rfc
        - NombreComercial
        - DenomRazonSocial
        - Dat_ASat
    RegistroProveedorResponseDTO:
      type: object
      properties:
        IdProv:
          type: string
          description: Identificador del proveedor generado por el legacy
          example: '0'
        DenomRazonSocial:
          type: string
          description: Denominacion o razon social registrada
          example: ''
        Rfc:
          type: string
          description: RFC registrado del proveedor
          example: PAP181818AA
        Code:
          oneOf:
            - type: string
            - type: integer
          description: Codigo devuelto por el backend legacy
          example: '1'
        Mensaje:
          type: string
          description: Mensaje descriptivo del resultado de la operacion
          example: Proveedor creado exitosamente
      required:
        - IdProv
        - DenomRazonSocial
        - Rfc
        - Code
        - Mensaje
    NuevoProveedorDTO:
      type: object
      description: Solicitud de alta de proveedor. Validaciones de datos generales se aplican en esta API; validacion final de documentos se delega al backend legacy.
      properties:
        Persona:
          type: string
          enum:
            - F
            - M
          description: Tipo de persona. F=Fisica, M=Moral
        Genero:
          type: string
          enum:
            - M
            - F
            - O
          description: Genero. Obligatorio si Persona=F
        DenominacionRazonSocial:
          type: string
          maxLength: 500
          description: Denominacion o Razon social (maximo 500 caracteres).
        Rfc:
          type: string
          minLength: 12
          maxLength: 13
          description: RFC del proveedor (12 - 13 caracteres)
        NombreComercial:
          type: string
          maxLength: 500
          description: Nombre comercial (maximo 500 caracteres).
        CURP:
          type: string
          minLength: 18
          maxLength: 18
          pattern: '^[A-Z0-9]{18}$'
          description: CURP (longitud fija 18, solo letras mayusculas y numeros). Requerido si Persona=F
        Calle:
          type: string
          minLength: 3
          maxLength: 50
          description: Calle del domicilio (maximo 50 caracteres)
        NoExterior:
          type: string
          maxLength: 5
          description: Numero exterior del domicilio (maximo 5 caracteres)
          pattern: '^[0-9][a-zA-Z0-9]{0,4}$'
        NoInterior:
          type: string
          maxLength: 5
          nullable: true
          description: Numero interior del domicilio (maximo 5 caracteres)
        Colonia:
          type: string
          maxLength: 30
          minLength: 3
          description: Colonia del domicilio (maximo 30 caracteres)
        Localidad:
          type: string
          maxLength: 30
          minLength: 3
          description: Localidad del domicilio (maximo 30 caracteres)
        Municipio:
          type: string
          maxLength: 50
          minLength: 3
          description: Municipio del domicilio (maximo 50 caracteres)
        Estado:
          type: string
          maxLength: 50
          minLength: 3
          description: Estado del domicilio (maximo 50 caracteres)
        Pais:
          type: string
          maxLength: 50
          minLength: 3
          description: Pais del domicilio (maximo 50 caracteres)
        CodigoPostal:
          type: string
          pattern: '^\d{5}$'
          description: Codigo postal de 5 digitos
        ActividadesSAT:
          oneOf:
            - type: array
              minItems: 1
              items:
                type: string
                pattern: '^\d{1,4}$'
            - type: string
              pattern: '^\d{1,4}$'
          description: IDs de actividades SAT (1 a 4 digitos), uno solo o multiples
        ServiciosProductos:
          type: string
          maxLength: 8000
          minLength: 10
          description: Descripcion de servicios o productos principales que ofrece (maximo 8000 caracteres)
        Telefono:
          type: string
          maxLength: 13
          pattern: '^\d{10,13}$'
          description: "Telefono de contacto (hasta 13 digitos, solo numeros)"
        PersonaContacto:
          type: string
          maxLength: 50
          description: Persona de contacto (maximo 50 caracteres)
        CelularContacto:
          type: string
          maxLength: 13
          pattern: '^\d{10,13}$'
          description: "Celular de contacto (hasta 13 digitos, solo numeros)"
        RepresentanteLegal:
          type: string
          maxLength: 500
          minLength: 5
          description: Nombre del representante legal (maximo 500 caracteres). Requerido si Persona=M
        CorreoElectronico:
          type: string
          format: email
          maxLength: 100
          description: Correo electronico de contacto (formato email, maximo 100 caracteres)
        '1':
          type: string
          format: binary
          description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
        '2':
          type: string
          format: binary
          description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
        '3':
          type: string
          format: binary
          description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
        '4':
          type: string
          format: binary
          description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
        '5':
          type: string
          format: binary
          description: Ejemplo de parametro de archivo. El nombre final lo determina el campo IdDoc del catálogo de /api/documentos. Solo PDF, 1 archivo por IdDoc, máximo 8 MB.
      required:
        - Persona
        - DenominacionRazonSocial
        - NombreComercial
        - Rfc
        - Calle
        - NoExterior
        - Colonia
        - Localidad
        - Municipio
        - Estado
        - Pais
        - CodigoPostal
        - ActividadesSAT
        - ServiciosProductos
        - Telefono
        - PersonaContacto
        - CelularContacto
        - CorreoElectronico
      example:
        Persona: F
        Genero: O
        Rfc: ABC123456XYZ
        CURP: QCMPAVTAGI6LA06CLM
        DenominacionRazonSocial: Juan Perez Gomez
        NombreComercial: J Perez Soluciones
        Calle: Calle Principal
        NoExterior: "123"
        NoInterior: "A"
        Colonia: Centro
        Localidad: Colima
        Municipio: Colima
        Estado: Colima
        Pais: Mexico
        CodigoPostal: 28000
        ActividadesSAT:
          - "001"
          - "015"
        ServiciosProductos: Asesoria en tecnologia
        Telefono: "3331234567"
        PersonaContacto: Maria Lopez
        CelularContacto: "3121234567"
        CorreoElectronico: contacto@empresa.com
        '1': identificacion.pdf
        '2': comprobante-domicilio.pdf
        '3': constancia-fiscal.pdf