# API y Servicios

# Antes de comenzar

Para iniciar la configuración de documentos o plantillas en Docs+ es necesario poseer credenciales de acceso a través de la plataforma PayGateway generadas por un técnico de soporte de PayGateway API.

Todos los servicios manejados por PayGateway API funcionan a través de peticiones HTTP en formato **JSON, en caso exista una excepción, el método en específico contendrá la manera de consumir dicho servicio.**

#### **Importante**  


El aplicativo +Docs es considerado un módulo de la plataforma PayGateway, por ello, comparte los mismos puntos de acceso, estructura de autenticación y manejo de servicios.

##### [Ir a documentación técnica de ](https://read.pygateway.com/books/pay-gateway/page/puntos-de-acceso-endpoints)[PayGateway](https://read.pygateway.com/books/pay-gateway)

![docplus_tecnica.png](https://read.pygateway.com/uploads/images/gallery/2023-12/scaled-1680-/docplus-tecnica.png)

# Puntos de acceso (endpoints)

El punto de conexión o endpoint para los servicios son los siguientes:

**Punto de enlace para entorno de producción:**

##### [https://api-global.docsplus.studio](https://api-global.docsplus.studio)

**Punto de enlace para entorno de desarrollo:**

##### *No existe un punto de acceso para desarrollo*

# Autenticación

En todos los servicios protegidos (no públicos) es necesaria realizar autenticación. Para ello, se proveen llaves de API, las cuales constan de dos partes:

**API Key:** Token identificador de la llave.

**Secret Key**: Token secreto de la llave.

Para el envío de solicitudes, debe concatenar el API key y Secret Key separados por dos puntos ":", dicho token debe enviarlo en el header de todas las solicitudes que necesiten autenticación utilizando el header http "Authorization" bajo el tipo de autenticación "Bearer".

**Por ejemplo:**

Incluya en el header de su petición:

[![image.png](https://read.pygateway.com/uploads/images/gallery/2023-12/scaled-1680-/image.png)](https://read.pygateway.com/uploads/images/gallery/2023-12/image.png)

# Descripción de servicios y parámetros

El aplicativo +Docs es considerado un módulo de la plataforma PayGateway, por ello, comparte los mismos puntos de acceso, estructura de autenticación y manejo de servicios.

[Ir a documentación técnica de ](https://read.pygateway.com/books/pay-gateway/page/puntos-de-acceso-endpoints)[PayGateway (Descripción de servicios y parámetros)](https://read.pygateway.com/books/pay-gateway/page/descripcion-de-servicios-y-parametros)

# Ejemplos de integración

A continuación encontrarás ejemplos de integración para los servicios más utilizados en +Docs

# Generar documento PDF

Para generar un documento mediante servicios, es necesario poseer un documento previamente configurado en el panel de control de +Docs.

<span style="color: rgb(22, 145, 121);">*NOTA: La generación de documentos mediante +Docs puede incurrir en costos adicionales para su balance mensual. Por favor, consulte con su asesor asignado sobre las tarifas y método de pago.* </span>

##### Generación de documento estándar  


`<strong>POST</strong>: formularios/docs-plus/generate`

**Request:**

```json
{
    "token": "102a4ee552c37cfd065n",
    "operation": "generate",
    "password": "",
    "data": {
        "urldemo": "https://google.com",
        "field1": "1234",
        "imagen": [
            "https://demo.com/imagen.png"
        ],
        "tabla_test": {
            "headers": [
                "Nombre",
                "Raza",
                "Peso"
            ],
            "rows": [
                [
                    "Spike",
                    "Pastor áleman",
                    "50lb"
                ],
                [
                    "Charly",
                    "Dálmata",
                    "30lb"
                ]
            ]
        }
    },
    "response": "binary"
}
```

##### Generar documento mediante servicio utilizando dos o más plantillas (unión o merge de plantillas)

`<strong>POST</strong>: formularios/docs-plus/generate-merge`

**Request:**

```json
{
    "forms": [
        {
            "token": "afb4fcf2e468594b8f6z",
            "data": {
                "NOMBRE": "Un nombre de prueba",
                "APELLIDO": "Un apellido de prueba"
            },
            "order": 0
        },
        {
            "token": "16vde98e06z08a.af57h",
            "data": {
                "SHORTCODE": "Un valor de prueba"
            },
            "order": 2
        }
    ],
    "response": "url"
}
```

# Compresión de imágenes

Permite la disminución de peso o tamaño de archivos tipo imagen mediante el uso de algoritmos avanzados de transformación, modificación y compresión. Todo ello, perdiendo la menor calidad posible.

<span style="color: rgb(22, 145, 121);">*NOTA: La compresión de imágenes mediante +Docs puede incurrir en costos adicionales para su balance mensual. Por favor, consulte con su asesor asignado sobre las tarifas y método de pago.*</span>

**POST:** /formularios/docs-plus/image-compress

> **Este servicio no debe consumirse como REST, sino enviando la información como 'form-data'.**

**Request (en postman):**![image.png](https://read.pygateway.com/uploads/images/gallery/2023-12/scaled-1680-/2nYimage.png)

##### Descripción de parámetros  


- **file (String)**: Campo donde se enviará la imagen (emulando campo de tipo FILE, HTML)
- **level (String)**: Nivel de compresión: ultralow, low, medium, high, ultra
- **resize (String)**: Permite cambiar el tamaño de la imagen, si se recibe una sola medida (ejemplo: 100) se conservará la relación de aspecto de la imagen y se cambiará de tamaño por su lado más grande. Si se reciben dos medidas separadas por coma (ejemplo: 100,100) se cambiará su tamaño estirando o estrechando la imagen de ser necesario.
- **response (String)**: Permite seleccionar el tipo de respuesta que entregará el servicio (con la imagen comprimida). <span style="color: rgb(53, 152, 219);">base64</span>: devolverá la imagen en base 64. <span style="color: rgb(53, 152, 219);">binary</span>: devolverá la imagen de forma binaria.

<div class="block block-table" data-pm-slice="1 1 []" id="bkmrk--1"><div class="block-content">  
</div></div>

# Procesamiento de OCR

Permite procesar un archivo con OCR utilizando algoritmos de última generación para detección de texto. Para procesar un documento mediante OCR, es necesario poseer una plantilla previamente configurada para OCR en el panel de control de +Docs.

<span style="color: rgb(22, 145, 121);">*NOTA: El procesamiento de OCR mediante +Docs puede incurrir en costos adicionales para su balance mensual. Por favor, consulte con su asesor asignado sobre las tarifas y método de pago.*</span>

**POST:** /formularios/docs-plus/ocr

> **Este servicio no debe consumirse como REST, sino enviando la información como 'form-data'.**

**Request (en postman):**

![image.png](https://read.pygateway.com/uploads/images/gallery/2023-12/scaled-1680-/VSEimage.png)

##### Descripción de parámetros  


<div class="block block-ul" data-pm-slice="3 3 []" id="bkmrk-templatetoken-%28strin"><div class="block-content">- **templateToken (String):** Token requerido para la identificación de la plantilla de OCR configurada en +Docs.
- **file (File):** Recibe el archivo que se desea procesar mediante OCR.
- **process (String):** Permite configurar el tipo de procesamiento, las opciones son las siguientes:
    
    <div class="block block-ul"><div class="block-content">
    - **auto**: permite auto detectar el tipo de archivo a procesar.
    - **image**: permite procesar archivos de tipo imagen.
    - **text**: permite procesar documentos de tipo texto como archivos .txt o con texto plano.
    - **pdfText**: permite procesar documentos de tipo PDF que sean tipo texto o "buscables".
    - **pdfImage**: permite procesar documentos de tipo PDF que sean de tipo imagen.
    
    </div></div>
- **removePages (int 0,1):** permite solicitar al servidor que eliminte las páginas (en caso sea un documento de múltiples páginas) y devuelva un solo listado de variables.
- **encodingFrom (String):** en caso el proceso de OCR esté enviando codificaciones incorrectas, permite configurar la codificación de entrada del archivo que estamos enviando, por defecto se intentará determinar automáticamente.
- **encodingTo (String):** define la codificación de salida del contenido procesado, por defecto la codificación de salida será UTF-8.
- **pageSeparator (String):** permite enviar la configuración de separador de página, para detectar automáticamente un salto de página en archivos de texto plano (sin páginas).
- **includeText (int 0,1):** permite solicitar al servidor que devuelva en un parámetro adicional todo el texto encontrado mediante el OCR sin procesar mediante la plantilla. Útil para procesos de prueba y debug.
- **detectQRBar (int 0,1):** permite solicitar al servidor que intente reconocer códigos QR que se encuentren en el documento enviado para procesamiento y devolverá el contenido de dicho QR en una variable adicional, esta funcionalidad solo trabajará con process de tipo image o pdfImage. El proceso puede aumentar el tiempo de procesamiento, por lo cual es recomendable no solicitar reconocimiento de QR en caso no sea necesario.

</div></div>*Para ver más información sobre el listado de parámetros diríjase a la sección "*Descripción de servicios y parámetros*" al inicio de esta guía.*

##### Recomendaciones para un OCR óptimo:

El servicio de OCR funcionará más eficiente enviando el tipo correcto de documento (parámetro process), por lo tanto, se recomienda enviar el tipado correcto o seleccionar la opción "auto".

##### Fiabilidad de OCR para extracción de tokens:

El porcentaje de fiabilidad del OCR de tipo imagen depende de la calidad de la imagen o documento subido.

<div class="block block-table" data-pm-slice="1 1 []" id="bkmrk-para-archivos-de-tip"><div class="block-content"><div class="block block-ul"><div class="block-content">- Para archivos de tipo imagen o PDF imagen: (25%-100%) de extracción
- Para archivos de tipo texto o PDF texto: (95%-100%)

</div></div>  
</div></div>