openapi: 3.0.3
info:
  title: Documentación Oficial Facturándola API (CFDI 4.0 y Plataforma Integral)
  description: |
    # Documentación Oficial de la Plataforma Facturándola API

    Especificación técnica completa y exhaustiva para la integración con la plataforma **Facturándola**.
    Cubre todos los módulos del sistema: Autenticación JWT, Gestión de Emisores y Certificados CSD/FIEL, Catálogo de Receptores, Timbrado CFDI 4.0 en Tiempo Real, Lotes Masivos CSV (32 columnas), Complemento de Pago 2.0, Carta Porte 2.0/3.0, Retenciones, Personalización de PDFs, Pasarelas de Pago y Herramientas del SAT.

    ---

    ## Entornos de Integración

    | Entorno | Base URL | Descripción |
    | :--- | :--- | :--- |
    | **Sandbox / Pruebas** | `https://api-sandbox.facturandola.com` | Entorno de pruebas y desarrollo sin validez fiscal. |
    | **Producción** | `https://api.facturandola.com` | Entorno de emisión real timbrado ante el SAT / PAC. |

    ---

    ## Autenticación y Seguridad

    Todas las peticiones a endpoints protegidos deben incluir el encabezado HTTP de autorización Bearer con el JWT expedido:

    ```http
    Authorization: Bearer <TU_JWT_TOKEN>
    Accept: application/json
    ```

    ---

    ## Estructura del Timbrado Masivo (Bulk CSV - 32 Columnas)

    Para la emisión en lote mediante el endpoint `POST /api/v1/factura/bulk`, se envía un archivo `.csv` codificado en UTF-8 con exactamente 32 columnas (aceptando encabezados en `snake_case` o `CamelCase`).
  version: 2.0.0
  contact:
    name: Soporte Técnico Facturándola
    url: https://facturandola.com
    email: soporte@facturandola.com

servers:
  - url: https://api.facturandola.com
    description: Servidor de Producción (Facturándola)
  - url: https://api-sandbox.facturandola.com
    description: Servidor Sandbox (Pruebas)

security:
  - BearerAuth: []

tags:
  - name: Autenticación
    description: Control de acceso, inicio de sesión, renovación de tokens JWT y perfil de usuario.
  - name: Emisores y Certificados CSD/FIEL
    description: Administración de empresas emisoras, sellos digitales CSD (.cer/.key), FIEL y estatus de cuenta.
  - name: Clientes / Receptores
    description: Gestión del catálogo de receptores fiscales, actualización de domicilios y regímenes.
  - name: Preregistro y Terceros
    description: Administración de solicitudes de preregistro y clientes por cuenta de terceros.
  - name: Timbrado CFDI 4.0
    description: Emisión individual en tiempo real, borradores, descargas de XML/PDF y cancelación ante el SAT.
  - name: Timbrado Masivo (Bulk CSV)
    description: Emisión masiva en lote procesando archivos CSV de 32 columnas.
  - name: Complemento de Pago 2.0
    description: Generación y timbrado de Recibos Electrónicos de Pago (REP 2.0).
  - name: Carta Porte
    description: Emisión de comprobantes de ingreso o traslado con el complemento Carta Porte 2.0 / 3.0.
  - name: Retenciones
    description: Emisión de comprobantes de retención de impuestos e información de pagos.
  - name: Catálogos del SAT
    description: Consulta de claves oficiales del SAT (Productos/Servicios, Códigos Postales, Regímenes, etc.).
  - name: Configuración Visual PDF
    description: Personalización de plantillas de impresión, logotipo y colores corporativos.
  - name: Herramientas y SAT
    description: Validación de RFCs en la lista LCO del SAT y extracción de datos desde PDFs de CSF.

paths:

  # ============================================================================
  # 1. AUTENTICACIÓN
  # ============================================================================
  /auth/login:
    post:
      tags:
        - Autenticación
      summary: Iniciar Sesión (Petición de Token JWT)
      description: Autentica al usuario con email y contraseña para obtener el JWT de acceso.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: usuario@facturandola.com
                password:
                  type: string
                  format: password
                  example: MiPasswordSeguro123
      responses:
        '200':
          description: Token JWT generado correctamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                  user:
                    type: object
                    properties:
                      uuid:
                        type: string
                        example: 8f3b9c71-2d4e-4b10-a935-6e2104d872bc
                      email:
                        type: string
                        example: usuario@facturandola.com
        '401':
          description: Credenciales incorrectas.

  /api/v1/token/validate:
    get:
      tags:
        - Autenticación
      summary: Validar Estatus de Token JWT
      description: Verifica la validez y tiempo de vida restante del JWT actual.
      responses:
        '200':
          description: Estado del token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true

  /api/v1/token/refresh:
    post:
      tags:
        - Autenticación
      summary: Refrescar Token JWT
      description: Genera un nuevo JWT de acceso antes de que el actual expire.
      responses:
        '200':
          description: Nuevo token expedido.

  /auth/touch:
    put:
      tags:
        - Autenticación
      summary: Renovar Sesión de Usuario
      description: Mantiene activa la sesión del usuario.
      responses:
        '200':
          description: Sesión renovada.

  /auth/logout:
    put:
      tags:
        - Autenticación
      summary: Cerrar Sesión
      description: Invalida el token JWT actual.
      responses:
        '200':
          description: Sesión cerrada exitosamente.

  /me:
    get:
      tags:
        - Autenticación
      summary: Obtener Perfil del Usuario Autenticado
      description: Devuelve la información básica y permisos del usuario en sesión.
      responses:
        '200':
          description: Datos del usuario.

  # ============================================================================
  # 2. EMISORES Y CERTIFICADOS CSD / FIEL
  # ============================================================================
  /api/v1/empresa:
    get:
      tags:
        - Emisores y Certificados CSD/FIEL
      summary: Listar o Consultar Empresas Emisoras
      description: Obtiene el listado de empresas asociadas a la organización o la información de una empresa en específico mediante su UUID o RFC.
      parameters:
        - name: uuid
          in: query
          required: false
          schema:
            type: string
          description: UUID opcional para filtrar una empresa específica.
      responses:
        '200':
          description: Información de emisores.
    post:
      tags:
        - Emisores y Certificados CSD/FIEL
      summary: Registrar Nueva Empresa Emisora
      description: Da de alta una nueva empresa emisora con sus datos fiscales base.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rfc
                - razon_social
                - codigo_postal
                - regimen_fiscal
              properties:
                rfc:
                  type: string
                  example: BOSR900321FC8
                razon_social:
                  type: string
                  example: RAUL BONFIL SAMANO
                codigo_postal:
                  type: string
                  example: "11590"
                regimen_fiscal:
                  type: string
                  example: "626"
                email:
                  type: string
                  example: emisor@facturandola.com
      responses:
        '201':
          description: Empresa creada correctamente.
    put:
      tags:
        - Emisores y Certificados CSD/FIEL
      summary: Actualizar Datos de Empresa Emisora
      description: Permite actualizar la razón social, régimen fiscal, domicilio o estatus (activación/suspensión).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                razon_social:
                  type: string
                codigo_postal:
                  type: string
                regimen_fiscal:
                  type: string
                status:
                  type: string
                  enum: [activo, suspendido]
      responses:
        '200':
          description: Datos actualizados.

  /api/v1/empresa/certificate:
    post:
      tags:
        - Emisores y Certificados CSD/FIEL
      summary: Validar y Cargar Certificado CSD (.cer / .key)
      description: Adjunta y valida los archivos del Certificado de Sello Digital (CSD) requeridos para el timbrado oficial ante el SAT.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - certificate
                - key
                - password
              properties:
                certificate:
                  type: string
                  format: binary
                  description: Archivo .cer del CSD.
                key:
                  type: string
                  format: binary
                  description: Archivo .key del CSD.
                password:
                  type: string
                  format: password
                  description: Contraseña de la clave privada del CSD.
      responses:
        '200':
          description: Certificado CSD validado y cargado correctamente.

  /api/v1/empresa/fiel:
    post:
      tags:
        - Emisores y Certificados CSD/FIEL
      summary: Validar y Cargar Firma Electrónica (FIEL)
      description: Adjunta y verifica la validez de la Firma Electrónica Avanzada (FIEL / e.firma) de la empresa.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - certificate
                - key
                - password
              properties:
                certificate:
                  type: string
                  format: binary
                key:
                  type: string
                  format: binary
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: FIEL validada correctamente.

  # ============================================================================
  # 3. CLIENTES / RECEPTORES
  # ============================================================================
  /api/v1/cliente:
    get:
      tags:
        - Clientes / Receptores
      summary: Listar o Consultar Clientes Receptores
      description: Obtiene el catálogo de clientes registrados.
      responses:
        '200':
          description: Listado de clientes.
    post:
      tags:
        - Clientes / Receptores
      summary: Registrar Cliente Receptor
      description: Registra un cliente con sus datos fiscales de la CSF.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rfc
                - razon_social
                - codigo_postal
                - regimen_fiscal
              properties:
                rfc:
                  type: string
                  example: GME181011EV4
                razon_social:
                  type: string
                  example: CLIENTE DE PRUEBAS SA DE CV
                codigo_postal:
                  type: string
                  example: "06500"
                regimen_fiscal:
                  type: string
                  example: "601"
                uso_cfdi:
                  type: string
                  example: "G03"
                email:
                  type: string
                  example: cliente@ejemplo.com
      responses:
        '201':
          description: Cliente registrado exitosamente.
    put:
      tags:
        - Clientes / Receptores
      summary: Actualizar Cliente Receptor
      description: Modifica los datos fiscales o correo de un cliente existente.
      responses:
        '200':
          description: Cliente actualizado.

  # ============================================================================
  # 4. PREREGISTRO Y TERCEROS
  # ============================================================================
  /api/v1/preregistro/:
    post:
      tags:
        - Preregistro y Terceros
      summary: Alta de Preregistro de Cliente
      description: Registra una solicitud de preregistro de empresa o cliente.
      responses:
        '201':
          description: Preregistro creado.
    put:
      tags:
        - Preregistro y Terceros
      summary: Actualizar Preregistro
      responses:
        '200':
          description: Preregistro modificado.

  # ============================================================================
  # 5. TIMBRADO CFDI 4.0 INDIVIDUAL & BORRADORES
  # ============================================================================
  /api/v1/factura:
    get:
      tags:
        - Timbrado CFDI 4.0
      summary: Listar Facturas Emitidas
      description: Obtiene el historial de comprobantes timbrados con opciones de filtrado.
      responses:
        '200':
          description: Lista de facturas.
    post:
      tags:
        - Timbrado CFDI 4.0
      summary: Timbrar CFDI 4.0 en Tiempo Real (JSON)
      description: Genera, firma y timbra una factura CFDI 4.0 de forma inmediata enviando el payload completo en JSON.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacturaInput'
      responses:
        '201':
          description: Factura timbrada exitosamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  cfdi_uuid:
                    type: string
                    example: 4f9b2d8e-71ac-4b03-9e12-8c5d3a71b9e0
                  timbrado_at:
                    type: string
                    example: "2026-09-06 14:00:00"

  /api/v1/borrador/factura:
    post:
      tags:
        - Timbrado CFDI 4.0
      summary: Crear Borrador de Factura (Pre-factura)
      description: Almacena una factura sin realizar el timbrado oficial ante el PAC.
      responses:
        '201':
          description: Borrador guardado.
    put:
      tags:
        - Timbrado CFDI 4.0
      summary: Cancelar Factura o Borrador
      description: Solicita la cancelación del CFDI ante el SAT indicando el motivo correspondiente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - motivo
              properties:
                motivo:
                  type: string
                  enum: ["01", "02", "03", "04"]
                  example: "02"
                uuid_sustitucion:
                  type: string
                  example: ""
      responses:
        '200':
          description: Solicitud de cancelación procesada.
    get:
      tags:
        - Timbrado CFDI 4.0
      summary: Descargar PDF o XML de Comprobante
      description: Permite descargar la representación impresa o el XML firmado.
      parameters:
        - name: uuid
          in: query
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: true
          schema:
            type: string
            enum: [pdf, xml]
      responses:
        '200':
          description: Archivo solicitado.

  # ============================================================================
  # 6. TIMBRADO MASIVO (BULK CSV)
  # ============================================================================
  /api/v1/factura/bulk:
    post:
      tags:
        - Timbrado Masivo (Bulk CSV)
      summary: Timbrado Masivo mediante Archivo CSV (32 Columnas)
      description: |
        Endpoint de alto rendimiento para procesar y timbrar cientos o miles de facturas en lote. Requiere un archivo `.csv` con la estructura oficial de 32 columnas.

        ### Columnas Obligatorias del CSV:
        * `uso_cfdi`, `tipo_de_comprobante` (I), `cfdi` (4.0), `forma_pago`, `moneda`, `tipo_cambio`, `metodo_de_pago`, `exportacion` (01), `rfc_emisor`, `rfc_receptor`, `razon_social_receptor`, `codigo_postal_receptor` (5 dígitos), `regimen_fiscal_receptor`, `clave_prod_serv`, `unidad`, `descripcion`, `cantidad`, `valor_unitario`, `objeto_imp` (02), `iva_tasa`.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Archivo .csv en UTF-8.
                version:
                  type: string
                  default: "4.0"
      responses:
        '200':
          description: Archivo recibido y puesto en cola de procesamiento.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  group_uuid:
                    type: string
                    example: c8d19e42-7f31-41b9-a5e0-19b842df0147
                  total_rows:
                    type: integer
                    example: 50

  # ============================================================================
  # 7. COMPLEMENTO DE PAGO 2.0 (REP)
  # ============================================================================
  /api/v1/complemento-pago:
    post:
      tags:
        - Complemento de Pago 2.0
      summary: Timbrar Recibo Electrónico de Pago (REP 2.0)
      description: Emite y timbra un CFDI de Pago 2.0 vinculando las facturas pagadas en parcialidades o diferidas (PPD).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fecha_pago
                - forma_pago_pago
                - moneda_pago
                - monto
                - documentos_relacionados
              properties:
                fecha_pago:
                  type: string
                  example: "2026-09-06T12:00:00"
                forma_pago_pago:
                  type: string
                  example: "03"
                moneda_pago:
                  type: string
                  example: "MXN"
                monto:
                  type: number
                  example: 5000.00
                documentos_relacionados:
                  type: array
                  items:
                    type: object
                    properties:
                      id_documento:
                        type: string
                        example: 1b6e4d9f-0c28-4f81-b549-3a79d0c61e82
                      num_parcialidad:
                        type: integer
                        example: 1
                      imp_saldo_ant:
                        type: number
                        example: 5000.00
                      imp_pagado:
                        type: number
                        example: 5000.00
                      imp_saldo_insoluto:
                        type: number
                        example: 0.00
      responses:
        '201':
          description: Complemento de pago timbrado exitosamente.

  # ============================================================================
  # 8. CARTA PORTE 2.0 / 3.0
  # ============================================================================
  /api/v1/carta-porte:
    post:
      tags:
        - Carta Porte
      summary: Timbrar CFDI con Complemento Carta Porte (2.0 / 3.0)
      description: Genera un CFDI de Ingreso o Traslado con la información de transporte terrestre, ubicaciones y mercancías.
      responses:
        '201':
          description: Carta porte timbrada.

  # ============================================================================
  # 9. RETENCIONES E INFORMACIÓN DE PAGOS
  # ============================================================================
  /api/v1/retenciones:
    get:
      tags:
        - Retenciones
      summary: Listar Comprobantes de Retención
      responses:
        '200':
          description: Listado de retenciones.
    post:
      tags:
        - Retenciones
      summary: Timbrar Comprobante de Retenciones
      description: Emite retenciones de impuestos para pagos nacionales o extranjeros.
      responses:
        '201':
          description: Retención emitida.
    put:
      tags:
        - Retenciones
      summary: Cancelar Retención
      responses:
        '200':
          description: Retención cancelada.

  # ============================================================================
  # 10. CATÁLOGOS OFICIALES DEL SAT
  # ============================================================================
  /api/v1/catalogos/producto-servicio:
    get:
      tags:
        - Catálogos del SAT
      summary: Buscar Claves SAT de Productos y Servicios
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Término de búsqueda o clave numérica (Ej. 90101501).
      responses:
        '200':
          description: Claves encontradas.

  /api/v1/catalogos/codigo-postal:
    get:
      tags:
        - Catálogos del SAT
      summary: Consultar Código Postal y Municipio/Estado SAT
      parameters:
        - name: cp
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Datos de la localidad fiscal.

  /api/v1/catalogos/regimen-fiscal:
    get:
      tags:
        - Catálogos del SAT
      summary: Consultar Catálogo de Regímenes Fiscales
      responses:
        '200':
          description: Catálogo de regímenes.

  # ============================================================================
  # 11. CONFIGURACIÓN VISUAL Y PERSONALIZACIÓN DE PDF
  # ============================================================================
  /api/v1/configuracion:
    get:
      tags:
        - Configuración Visual PDF
      summary: Consultar Configuración de Plantilla PDF Activa
      responses:
        '200':
          description: Plantilla activa.
    post:
      tags:
        - Configuración Visual PDF
      summary: Actualizar Plantilla, Logotipo y Colores de PDF
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                logo_url:
                  type: string
                color_primario:
                  type: string
                  example: "#8b5cf6"
                plantilla_id:
                  type: string
                  example: "facturandola-40"
      responses:
        '200':
          description: Configuración guardada.

  # ============================================================================
  # 12. HERRAMIENTAS Y SCRAPERS
  # ============================================================================
  /api/v1/tools/rfc/validate:
    post:
      tags:
        - Herramientas y SAT
      summary: Validar RFC en Lista LCO / LRFC del SAT
      description: Verifica si un RFC está registrado activamente ante el SAT para emitir y recibir comprobantes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rfc
              properties:
                rfc:
                  type: string
                  example: BOSR900321FC8
      responses:
        '200':
          description: Estatus del RFC ante el SAT.

  /scrapers/dfile:
    post:
      tags:
        - Herramientas y SAT
      summary: Decodificar y Extraer Datos de Constancia de Situación Fiscal (PDF)
      description: Lee un PDF de Constancia de Situación Fiscal (CSF) y extrae automáticamente el RFC, Nombre/Razón Social, Código Postal y Régimen Fiscal.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Datos del contribuyente extraídos del PDF.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    FacturaInput:
      type: object
      required:
        - emisor
        - receptor
        - factura
        - conceptos
      properties:
        emisor:
          type: object
          properties:
            rfc:
              type: string
              example: BOSR900321FC8
        receptor:
          type: object
          properties:
            rfc:
              type: string
              example: GME181011EV4
            razon_social:
              type: string
              example: CLIENTE DE PRUEBAS SA DE CV
            codigo_postal:
              type: string
              example: "06500"
            regimen:
              type: string
              example: "601"
            uso_cfdi:
              type: string
              example: "G03"
            email:
              type: string
              example: cliente@ejemplo.com
        factura:
          type: object
          properties:
            version:
              type: string
              example: "4.0"
            tipo_comprobante:
              type: string
              example: "I"
            forma_pago:
              type: string
              example: "01"
            metodo_pago:
              type: string
              example: "PUE"
            moneda:
              type: string
              example: "MXN"
            exportacion:
              type: string
              example: "01"
        conceptos:
          type: array
          items:
            type: object
            properties:
              clave_prod_serv:
                type: string
                example: "90101501"
              cantidad:
                type: number
                example: 1
              unidad:
                type: string
                example: "E48"
              descripcion:
                type: string
                example: "Consumo de Alimentos"
              valor_unitario:
                type: number
                example: 1000.00
              iva_tasa:
                type: number
                example: 0.16
