Generación de documentos (OPG)

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.

Secuencia recomendada

1. Obtenga un token Bearer para administrar plantillas y una llave de API para generar PDF.
2. Cree la plantilla y conserve el id retornado.
3. Configure las dimensiones y los márgenes de página.
4. Defina el mapeo de campos fijos y dinámicos.
5. Cargue el cuerpo HTML y, cuando corresponda, el encabezado y pie.
6. Genere el PDF con el ID de la plantilla y los datos correspondientes.
7. Lea data.id y decodifique data.file desde base64 para revisar el PDF.

Los ejemplos utilizan {{ID-TEMPLATE}}, {{JWT_TOKEN}} y {{API_KEY}} como marcadores. Sustitúyalos por los valores de su integración.

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/
Authorization: Bearer {{JWT_TOKEN}}
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 detalles adicionales sobre la construcción del HTML, solicite a soporte el documento complementario html_readme.pdf; no está incluido en este sitio.

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

Comprobar el documento generado

Abra el PDF decodificado y revise las páginas, los valores fijos, las filas de tabla y el diseño. Conserve el identificador recibido para seguimiento. Si la generación falla, revise la respuesta antes de repetir la solicitud y compruebe que las claves de los datos coinciden con el mapeo configurado.