Generación de documentos (OPG) - API de integración¶

La API de integración de OPG permite generar documentos PDF. El cliente puede interactuar directamente con esta API para la generación masiva de documentos.

Autenticación¶

El cliente se autentica mediante un bearer token para las solicitudes distintas a la generación del documento PDF.

Este token debe enviarse en el header Authorization de cada solicitud HTTP. Por ejemplo:

POST https://opg.obmessage.ai/api/v1/templates/
Authorization: Bearer {{JWT_TOKEN}}

Crear plantilla¶

Solicitud HTTP para crear plantilla¶

POST https://opg.obmessage.ai/api/v1/templates/
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "name": "string",
    "max_data_per_page": 16,
    "max_rows_per_page": 24,
    "status": true,
    "fixed_key_password": "string",
    "master_password": "string"
}

Pruébalo en Postman

Descripción de los campos¶

Campo	Descripción	Obligatorio
name	Nombre de la plantilla PDF.	Sí
max_data_per_page	En tablas dinámicas, indica cuántas filas se llenarán con datos.	Sí
max_rows_per_page	En tablas dinámicas, indica cuántas filas tendrá la tabla.	Sí
status	Estado de la plantilla.	Sí
fixed_key_password	Campo de contraseña dinámica por cada documento.	No
master_password	Contraseña maestra.	No

Trama JSON de ejemplo¶

POST https://opg.obmessage.ai/api/v1/templates/
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "name": "EstadoTC",
    "max_data_per_page": 16,
    "max_rows_per_page": 24,
    "status": true,
    "fixed_key_password": "",
    "master_password": ""
}

Respuesta¶

Se retorna el código 200 OK con el código de la plantilla:

{
    "id": "{{ID-TEMPLATE}}"
}

Edición de la plantilla¶

Enviar el código de la plantilla con los datos modificados.

PATCH https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "name": "EstadoTC",
    "max_data_per_page": 16,
    "max_rows_per_page": 24,
    "status": true,
    "fixed_key_password": "",
    "master_password": "ofimatic"
}

Pruébalo en Postman

Configuración de la plantilla¶

Enviar el código de la plantilla con la configuración del documento.

POST https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/settings
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "orientation": "string",
    "margin_left": 0.0,
    "margin_right": 0.0,
    "margin_top": 0.0,
    "margin_bottom": 0.0,
    "page_height": 279.4,
    "page_width": 215.9,
    "dpi": 200
}

Descripción de los campos¶

Campo	Descripción	Obligatorio
orientation	Orientación del documento. Ejemplo: `portrait`.	Sí
margin_left	Margen izquierdo del documento en milímetros.	Sí
margin_right	Margen derecho del documento en milímetros.	Sí
margin_top	Margen superior del documento en milímetros.	Sí
margin_bottom	Margen inferior del documento en milímetros.	Sí
page_height	Altura del documento en milímetros.	Sí
page_width	Ancho del documento en milímetros.	Sí
dpi	Resolución en píxeles.	Sí

Trama JSON de ejemplo¶

POST https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/settings
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "orientation": "portrait",
    "margin_left": 0.0,
    "margin_right": 0.0,
    "margin_top": 0.0,
    "margin_bottom": 10.0,
    "page_height": 279.4,
    "page_width": 215.9,
    "dpi": 200
}

Editar configuración de la plantilla¶

Enviar el código de la plantilla con la configuración modificada.

PATCH https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/settings
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "orientation": "portrait",
    "margin_left": 0.0,
    "margin_right": 0.0,
    "margin_top": 0.0,
    "margin_bottom": 10.0,
    "page_height": 279.4,
    "page_width": 215.9,
    "dpi": 200
}

Relación de campos variables¶

Creación y edición¶

Enviar el código de la plantilla con la relación de datos.

PUT https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/mappings
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

{
    "fixed_keys": [
        "NAME",
        "EMAIL",
        "ADDRESS",
        "CARDTYPE",
        "CARDNUMBER",
        "CORTE",
        "CICLO",
        "FACTURACION",
        "DISPONIBLE",
        "BALANCEANTERIOR",
        "PAGOS",
        "COMPRAS",
        "BALANCECORTE",
        "PAGUEANTESFECHA",
        "DISPONIBLEUS",
        "BALANCEANTERIORUS",
        "PAGOSUS",
        "COMPRASUS",
        "BALANCECORTEUS",
        "CUOTASVENCIDAS",
        "IMPORTEVENCIDO",
        "PAGOMINIMOPUNTOSOFIMATIC",
        "PAGOMINIMO",
        "PAGOTOTALPUNTOSOFIMATIC",
        "PAGOTOTAL",
        "CUOTASVENCIDASUS",
        "IMPORTEVENCIDOUS",
        "PAGOMINIMOPUNTOSOFIMATICUS",
        "PAGOMINIMOUS",
        "CARDNUMBERUS",
        "PAGOTOTALPUNTOSOFIMATICUS",
        "PAGOTOTALUS",
        "TOTALDECOMPRAS",
        "CUOTAPUNTOSOFIMATIC"
    ],
    "dynamic_keys": [
        {
            "key": "fecha_transaccion",
            "td_code": "<td style=\"text-align:center\">",
            "index": 0
        },
        {
            "key": "fecha_entrada",
            "td_code": "<td style=\"text-align:center\">",
            "index": 1
        },
        {
            "key": "numero_referencia",
            "td_code": "<td style=\"text-align:center\">",
            "index": 2
        },
        {
            "key": "concepto",
            "td_code": "<td style=\"text-align:center\">",
            "index": 3
        },
        {
            "key": "debito",
            "td_code": "<td style=\"text-align:center\">",
            "index": 4
        },
        {
            "key": "credito",
            "td_code": "<td style=\"text-align:center\">",
            "index": 5
        }
    ]
}

Pruébalo en Postman

Campo	Descripción	Obligatorio
fixed_keys	Campos con valor fijo dentro del documento.	Sí
dynamic_keys	Campos con valores dinámicos dentro de una tabla.	Sí

Crear documento¶

Crear cuerpo de documento mediante plantilla HTML¶

El documento se construye mediante plantillas HTML, las cuales pueden cargarse mediante las etiquetas html_content, html_header y html_footer, asociadas al ID de la plantilla creada.

Para más detalles sobre la construcción de la plantilla, consulte el archivo html_readme.pdf.

POST https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/html
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: multipart/form-data

--form 'html_content=@"/path/to/file"' \
--form 'html_header=@"/path/to/file"' \
--form 'html_footer=@"/path/to/file"'

Pruébalo en Postman

Campo	Descripción	Obligatorio
html_content	Contenido del documento.	Sí
html_header	Encabezado del documento.	No
html_footer	Pie de página del documento.	No

Editar plantilla HTML¶

PUT https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/html
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: multipart/form-data

--form 'html_content=@"/path/to/file"' \
--form 'html_header=@"/path/to/file"' \
--form 'html_footer=@"/path/to/file"'

Generar documento¶

Autenticación¶

El cliente se autentica mediante una llave API_KEY, que será entregada por Ofimatic SRL.

Este API_KEY debe enviarse en el header X-Api-Key de cada solicitud HTTP.

Generar PDF¶

POST https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/generate-pdf
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "fixed_data": {},
    "dynamic_data": [
        {}
    ]
}

Campo	Descripción	Obligatorio
fixed_data	Campos fijos definidos con sus valores.	Sí
dynamic_data	Arreglo de objetos con campos dinámicos y sus valores.	Sí

Trama JSON de ejemplo¶

{
    "fixed_data": {
        "NAME": "Juan Ant. Perez de Los Santos",
        "EMAIL": "demo@ofimatic.com",
        "ADDRESS": "Calle Nicolás Ureña de Mendoza #3, Los Prados, Santo Domingo",
        "CARDTYPE": "Clasica Internacional",
        "CARDNUMBER": "**** **** **** 1111",
        "CORTE": "30/04/2022",
        "CICLO": "5",
        "FACTURACION": "21",
        "DISPONIBLE": "100,000.00",
        "BALANCEANTERIOR": "40,000.00",
        "PAGOS": "10,000.00",
        "COMPRAS": "50.00",
        "BALANCECORTE": "5,900.00",
        "PAGUEANTESFECHA": "24/05/2022",
        "DISPONIBLEUS": "2,000.00",
        "BALANCEANTERIORUS": "1,000.00",
        "PAGOSUS": "1.00",
        "COMPRASUS": "165.00",
        "BALANCECORTEUS": "235.55",
        "CUOTASVENCIDAS": "2",
        "IMPORTEVENCIDO": "100.00",
        "PAGOMINIMOPUNTOSOFIMATIC": "2,300.00",
        "PAGOMINIMO": "523.00",
        "PAGOTOTALPUNTOSOFIMATIC": "963.00",
        "PAGOTOTAL": "3,543.22",
        "CUOTASVENCIDASUS": "2",
        "IMPORTEVENCIDOUS": "522.00",
        "PAGOMINIMOPUNTOSOFIMATICUS": "12.00",
        "PAGOMINIMOUS": "1,232.00",
        "CARDNUMBERUS": "**** **** **** 1112",
        "PAGOTOTALPUNTOSOFIMATICUS": "1,235.55",
        "PAGOTOTALUS": "3,543.01",
        "TOTALDECOMPRAS": "1,235.22",
        "CUOTAPUNTOSOFIMATIC": "0",
        "BALANCEALCORTE": "242.00",
        "CREDITODISPONIBLE": "50.00"
    },
    "dynamic_data": [
        {
            "fecha_transaccion": "2020-01-01",
            "fecha_entrada": "2020-01-01",
            "numero_referencia": "123456789123456789",
            "concepto": "Pruebas",
            "debito": "RD$ 1,000.00",
            "credito": "RD$ 2,000.00"
        },
        {
            "fecha_transaccion": "2020-01-01",
            "fecha_entrada": "2020-01-01",
            "numero_referencia": "123456789123456789",
            "concepto": "Pruebas",
            "debito": "RD$ 3,000.00",
            "credito": "RD$ 4,000.00"
        }
    ]
}

Pruébalo en Postman

Respuesta¶

Se retorna el código 200 OK con el código de generación y el documento en base64:

{
    "data": {
        "id": "{{ID-FILE}}",
        "file": "{{BASE-FILE}}"
    }
}

Consulta¶

Consulta de documentos generados¶

POST https://opg.obmessage.ai/api/v1/templates/{{ID-TEMPLATE}}/requests/{{ID-REQUEST}}
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

Pruébalo en Postman