openapi: 3.0.3

info:
  title: API Celeste
  version: 1.0.0
  description: |
    API Celeste es la plataforma de integración que permite a aplicaciones externas
    conectarse con los servicios de Celeste para ejecutar operaciones como
    autenticación, registro de factura electrónica de venta y consulta de factura.

    Esta documentación describe los pasos necesarios para registrar una aplicación,
    autenticarse y ejecutar operaciones dentro del ecosistema Celeste.

servers:
  - url: https://api.celestefacturacion.com
    description: API pública de producción

tags:
  - name: Autenticación
    description: Operaciones relacionadas con la generación de token de acceso.
  - name: Factura electrónica de venta
    description: Operaciones para registrar y consultar facturas electrónicas de venta.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Bearer Token

  schemas:
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          example: nit
        message:
          type: string
          example: El campo nit solo debe contener números.

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: La solicitud contiene campos inválidos o no permitidos.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'

    AuthRequest:
      type: object
      required:
        - cliente-id
        - usuario-token
        - nit
      properties:
        cliente-id:
          type: string
          format: uuid
          example: b77eb05a-794a-4742-9131-b03f16a4dadc
        usuario-token:
          type: string
          example: 196be359e51b1095375421554159c9d1
        nit:
          type: string
          example: "123456789"

    AuthResponse:
      type: object
      properties:
        access_token:
          type: string
          example: AeZRQ8BghrsaOuDbkjT_REj77fNsKqSyCHB-tjuvCt0Ijq6edDWnIqf4YwbM-_kzUl0IvpXyE0dAyOI3RtWuzrHuJTb...
        expires_in:
          type: integer
          example: 300
        token_type:
          type: string
          example: bearer

    Anotacion:
      type: object
      properties:
        note:
          type: string
          example: "Placa: VSF145, Kilometraje : null, Nro Transaccion : "

    FormaPago:
      type: object
      properties:
        forma_pago_dian:
          type: integer
          example: 1
        medio_pago_dian_codigo:
          type: string
          example: "10"
        medio_pago_dian_nombre:
          type: string
          example: Efectivo
        franquicia_tarjeta:
          type: string
          example: VISA
        ultimos_digitos:
          type: string
          example: "5678"
        caja:
          type: string
          example: caja principal
        fecha_vencimiento:
          type: string
          format: date
          example: "2026-02-07"
        valor:
          type: number
          format: float
          example: 20000.0

    TerceroReceptor:
      type: object
      properties:
        dv:
          type: string
          example: ""
        nit:
          type: string
          example: "222222222"
        pais:
          type: string
          example: Colombia
        email:
          type: string
          format: email
          example: clientepuntodeventa222@gmail.com
        nombre:
          type: string
          example: CONSUMIDOR
        nombre2:
          type: string
          example: ""
        apellido:
          type: string
          example: FINAL
        apellido2:
          type: string
          example: ""
        direccion:
          type: string
          example: CL 5 15 82
        municipio:
          type: string
          example: POPAYÁN
        telefonos:
          type: string
          example: 8214010-3156128040
        codigo_pais:
          type: string
          example: CO
        departamento:
          type: string
          example: Cauca
        razon_social:
          type: string
          example: CONSUMIDOR FINAL
        nombre_empresa:
          type: string
          example: ""
        codigo_municipio:
          type: string
          example: "001"
        codigo_departamento:
          type: string
          example: "19"
        tipo_identificacion_dian:
          type: integer
          example: 13

    Descuento:
      type: object
      properties:
        valor_descuento:
          type: number
          example: 10000
        porcentaje_descuento:
          type: number
          example: 10
        base_descuento:
          type: number
          example: 100000

    ProductoFacturaVenta:
      type: object
      properties:
        producto_codigo:
          type: string
          example: "1450"
        unidad_medida:
          type: string
          example: GL
        cantidad:
          type: string
          example: "3"
        subtotal:
          type: string
          example: "45000"
        descripcion:
          type: string
          example: gl Corriente
        producto_gratuito:
          type: boolean
          example: false
        valor_unitario:
          type: number
          example: 15000
        descuento:
          $ref: '#/components/schemas/Descuento'

    DatosGeneralesDocumento:
      type: object
      properties:
        tipo_moneda:
          type: string
          example: COP
        hora_generacion:
          type: string
          example: "10:48:24"
        fecha_generacion:
          type: string
          format: date
          example: "2026-02-07"
        fecha_vencimiento:
          type: string
          format: date
          example: "2026-02-07"
        resolucion_numero:
          type: integer
          example: 18764102336448
        gen_uuid:
          type: string
          format: uuid
          example: 554bde42-d5dd-4594-a18c-5c1ca7035789
        observaciones:
          type: string
          example: ""

    DocumentoFacturaVenta:
      type: object
      properties:
        anotaciones:
          type: array
          items:
            $ref: '#/components/schemas/Anotacion'
        formas_pago:
          type: array
          items:
            $ref: '#/components/schemas/FormaPago'
        tercero_receptor:
          $ref: '#/components/schemas/TerceroReceptor'
        descripcion_productos:
          type: array
          items:
            $ref: '#/components/schemas/ProductoFacturaVenta'
        datos_generales_documento:
          $ref: '#/components/schemas/DatosGeneralesDocumento'

    FacturaVentaRequest:
      type: object
      properties:
        documento:
          $ref: '#/components/schemas/DocumentoFacturaVenta'

    FacturaVentaResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Factura registrada correctamente.
        data:
          type: object
          properties:
            gen_uuid:
              type: string
              format: uuid
              example: 554bde42-d5dd-4594-a18c-5c1ca7035789
            fecha_factura:
              type: string
              format: date
              example: "2026-04-11"
            numero_factura:
              type: string
              example: "0883"

    ConsultaFacturaVentaResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Factura consultada correctamente.
        data:
          type: object
          properties:
            numero_factura:
              type: integer
              example: 6750
            fecha_factura:
              type: string
              format: date
              example: "2026-02-07"
            estado:
              type: string
              example: aprobada
            attached_document:
              type: string
              description: Documento PDF codificado en base64
              example: JVBERi0xLjUKJeLjz9MKMyAwIG9iago8PC9Db2xvclNwYWNlL...

paths:
  /webhook/api/auth:
    post:
      tags:
        - Autenticación
      summary: Generar token de acceso
      description: |
        Genera un token de acceso para consumir los endpoints protegidos de la API.

        El token tiene una vigencia de 300 segundos (5 minutos).

        Content-Type requerido: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
            examples:
              ejemplo:
                value:
                  cliente-id: b77eb05a-794a-4742-9131-b03f16a4dadc
                  usuario-token: 196be359e51b1095375421554159c9d1
                  nit: "22222222222"
      responses:
        '200':
          description: Autenticación exitosa y token generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              examples:
                ok:
                  value:
                    access_token: AeZRQ8BghrsaOuDbkjT_REj77fNsKqSyCHB-tjuvCt0Ijq6edDWnIqf4YwbM-_kzUl0IvpXyE0dAyOI3RtWuzrHuJTb...
                    expires_in: 300
                    token_type: bearer
        '400':
          description: Campos inválidos, faltantes o body mal estructurado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                badRequest:
                  value:
                    success: false
                    status: 400
                    error: Bad Request
                    message: La solicitud contiene campos inválidos o no permitidos.
                    details:
                      - field: nit
                        message: El campo nit solo debe contener números.
        '401':
          description: Credenciales inválidas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  value:
                    success: false
                    status: 401
                    error: Unauthorized
                    message: Credenciales inválidas.
        '415':
          description: Content-Type distinto de application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupportedMediaType:
                  value:
                    success: false
                    status: 415
                    error: Unsupported Media Type
                    message: Esta petición solo acepta solicitudes con Content-Type 'application/json'.

  /webhook/api/factura:
    post:
      tags:
        - Factura electrónica de venta
      summary: Registrar factura electrónica de venta
      description: |
        Registra una factura electrónica de venta.

        Requiere un token válido enviado en el header:
        Authorization: Bearer <token>

        Content-Type requerido: application/json
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacturaVentaRequest'
            examples:
              ejemploCompleto:
                value:
                  documento:
                    anotaciones:
                      - note: "Placa: VSF145, Kilometraje : null, Nro Transaccion : "
                      - note: "-VENDEDOR- A partir de aquí nombre del vendedor si se requiere"
                    formas_pago:
                      - forma_pago_dian: 1
                        medio_pago_dian_codigo: "10"
                        medio_pago_dian_nombre: Efectivo
                        caja: nombre de la caja o surtidor
                        fecha_vencimiento: "2026-02-07"
                        valor: 20000.0
                      - forma_pago_dian: 1
                        medio_pago_dian_codigo: "49"
                        medio_pago_dian_nombre: Tarjeta Debito
                        franquicia_tarjeta: VISA
                        ultimos_digitos: "5678"
                        caja: nombre de la caja o surtidor
                        fecha_vencimiento: "2026-02-07"
                        valor: 10000.0
                      - forma_pago_dian: 1
                        medio_pago_dian_codigo: "50"
                        medio_pago_dian_nombre: Tarjeta Credito
                        franquicia_tarjeta: MASTER CARD
                        ultimos_digitos: "1234"
                        caja: nombre de la caja o surtidor
                        fecha_vencimiento: "2026-02-07"
                        valor: 15000.0
                    tercero_receptor:
                      dv: ""
                      nit: "222222222"
                      pais: Colombia
                      email: clientepuntodeventa222@gmail.com
                      nombre: CONSUMIDOR
                      nombre2: ""
                      apellido: FINAL
                      apellido2: ""
                      direccion: CL 5 15 82
                      municipio: POPAYÁN
                      telefonos: 8214010-3156128040
                      codigo_pais: CO
                      departamento: Cauca
                      razon_social: CONSUMIDOR FINAL
                      nombre_empresa: ""
                      codigo_municipio: "001"
                      codigo_departamento: "19"
                      tipo_identificacion_dian: 13
                    descripcion_productos:
                      - producto_codigo: "1450"
                        unidad_medida: GL
                        cantidad: "3"
                        subtotal: "45000"
                        descripcion: gl Corriente
                        producto_gratuito: false
                        valor_unitario: 15000
                        descuento:
                          valor_descuento: 10000
                          porcentaje_descuento: 10
                          base_descuento: 100000
                    datos_generales_documento:
                      tipo_moneda: COP
                      hora_generacion: "10:48:24"
                      fecha_generacion: "2026-02-07"
                      fecha_vencimiento: "2026-02-07"
                      resolucion_numero: 18764102336448
                      gen_uuid: 554bde42-d5dd-4594-a18c-5c1ca7035789
                      observaciones: ""
      responses:
        '200':
          description: Factura registrada correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacturaVentaResponse'
              examples:
                ok:
                  value:
                    success: true
                    status: 200
                    message: Factura registrada correctamente.
                    data:
                      gen_uuid: 554bde42-d5dd-4594-a18c-5c1ca7035789
                      fecha_factura: "2026-04-11"
                      numero_factura: "0883"
        '400':
          description: Errores de validación en JSON, estructura o campos obligatorios
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                badRequest:
                  value:
                    success: false
                    status: 400
                    error: Bad Request
                    message: La solicitud no cumple con la estructura o los campos obligatorios requeridos.
                    details:
                      - field: documento.formas_pago
                        message: Debe contener al menos una forma de pago.
        '401':
          description: Problemas de autorización con el token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  value:
                    success: false
                    status: 401
                    error: Unauthorized
                    message: El token de acceso ha expirado.
        '415':
          description: Content-Type distinto de application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unsupportedMediaType:
                  value:
                    success: false
                    status: 415
                    error: Unsupported Media Type
                    message: Esta petición solo acepta solicitudes con Content-Type 'application/json'.

  /webhook/633a691d-2135-4415-8a31-805bd765ca60/api/factura/{uuid}/{fecha}:
    get:
      tags:
        - Factura electrónica de venta
      summary: Consultar factura electrónica de venta
      description: |
        Consulta una factura electrónica de venta mediante su UUID y fecha.

        El parámetro fecha debe enviarse en formato yyyymmdd.

        Requiere header:
        Authorization: Bearer <token>
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: uuid
          required: true
          description: UUID de la factura
          schema:
            type: string
            format: uuid
            example: 554bde42-d5dd-4594-a18c-5c1ca7035789
        - in: path
          name: fecha
          required: true
          description: Fecha en formato yyyymmdd
          schema:
            type: string
            example: "20260207"
      responses:
        '200':
          description: Factura encontrada correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsultaFacturaVentaResponse'
              examples:
                ok:
                  value:
                    success: true
                    status: 200
                    message: Factura consultada correctamente.
                    data:
                      numero_factura: 6750
                      fecha_factura: "2026-02-07"
                      estado: aprobada
                      attached_document: JVBERi0xLjUKJeLjz9MKMyAwIG9iago8PC9Db2xvclNwYWNlL...
        '400':
          description: Parámetros de URL inválidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                badRequest:
                  value:
                    success: false
                    status: 400
                    error: Bad Request
                    message: Los parámetros de la URL no son válidos.
                    details:
                      - field: fecha
                        message: La fecha debe estar en formato yyyymmdd.
        '401':
          description: Problemas de autorización con el token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  value:
                    success: false
                    status: 401
                    error: Unauthorized
                    message: Token inválido o expirado.
        '404':
          description: No existe una factura asociada a los parámetros enviados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  value:
                    success: false
                    status: 404
                    error: Not Found
                    message: No se encontró una factura con el uuid y la fecha suministrados.