Introducción

Bienvenido a MailMerge API! podrás utilizar la siguiente API para procesar plantillas hechas en Microsoft Word con combinación de correspondencia utilizando un JSON como fuente de datos.

Consta de 4 simples pasos:

En la plantilla de Word, incrustar los campos combinables, puedes utilizar cualquier nombre de campo, algo que puedas identificar fácilmente su contenido. Puedes repetir el nombre del campo en varias secciones del documento si así se require y se tomará como un solo campo combinable.
Hacer login en nuestra API para que se le proporcione un token que utilizará en todo el proceso, si no cuenta con usuario y contraseña, contacta con tu administrador para que se te asigne un usuario.
Subir a nuestra plataforma la plantilla, como respuesta recibirás un JSON con el listado de campos detectados en el documento.
Enviar un JSON con los campos y sus valores, como respuesta se le descargará el mismo archivo que subiste en el paso 3 con los datos combinados.

¡Tenemos enlaces en Shell, PHP, JavaScript! Puedes ver ejemplos de código en el área oscura a la derecha, y puedes cambiar el lenguaje de programación de los ejemplos con las pestañas en la parte superior derecha.

Autenticación

Para loggearse a la plataforma utilice éste endpoint:

$URI = env('MAILMERGE_API', 'https://mailmerge.789.com.mx/api/v1');
$client = new \GuzzleHttp\Client();
$user = array("username" => "admin@789.mx", "password" => "***********");
try {
    $response = $client->request('POST', "{$URI}/login", [
        'headers' => [
            'Content-Type' => 'application/json',
        ],
        'body' => json_encode($user),
    ]);
    $resp = json_decode($response->getBody()->getContents(), true);
    if (isset($resp["access_token"])) {
        //guardar tokens en cookies
    }
    return $resp;
} catch (RequestException $e) {
    $response = $e->getResponse();
    $responseBody = $response ? $response->getBody()->getContents() : null;
    return json_decode($responseBody, true);
}

curl --request POST \
  --url https://mailmerge.789.com.mx/api/v1/login \
  --header 'content-type: application/json' \
  --data '{
    "username": "admin@789.mx",
    "password": "**********"
}'

fetch("https://mailmerge.789.com.mx/api/v1/login", {
  "method": "POST",
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "username": "admin@789.mx",
    "password": "***********"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

Asegúrate de reemplazar ************ por su contraseña.

MailMerge API, utiliza tokens del tipo Bearer para los siguientes endpoints, la API va a requerir que se incluya el token en los encabezados como se muestra a continuación.

Authorization: Bearer miaccesstoken

Debes reemplazar miaccesstoken por tu propio token.

Como respuesta recibirás un JSON con los tokens e información del objeto usuario

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpiI6MTU5NDMxNzUzMiwianRpIjoiMWNkZWYwMGUtZmNkNi00ZmQ4LTgwMTQtMzQ0NDcyYzI0ZTk3IiwiZXhwIjoxNTk2OTQ1NTMyLCJpZGVudGl0eSI6MSwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MifQ.abMyXsbYjVoWi5DRd_5JYuYtU5JXm-e199Tw0evj5uA",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzzMTc1MzIsIm5iZiI6MTU5NDMxNzUzMiwianRpIjoiMDc0OGFiYWQtZThmYS00OWIzLTg0OTctMjdiMTdiMDRhNjkzIiwiZXhwIjoxNjEwMDg1NTMyLCJpZGVudGl0eSI6MSwidHlwZSI6InJlZnJlc2gifQ.wGbJJokmkxa_FDXvLHiK3q-tRZlCoUma7G0hoj2AAW0",
  "user": {
    "id": 1,
    "fullname": "Administrator",
    "username": "admin@789.mx",
    "created_at": "2020-06-19T04:52:46.772120"
  }
}

El refresh_token te servirá para obtener un nuevo token en caso de que el actual esté expirado o próximo a expirar. Sólo debes llamar el siguiente endpoint https://mailmerge.789.com.mx/api/v1/refresh e incluir en el encabezado Autorization: Bearer miaccesstoken

Cerrar sesión

/api/v1/logout

Si desea cerrar su sesión en la plataforma, puedes utilizar el siguiente endpoint:

https://mailmerge.789.com.mx/api/v1/logout

En el encabezado es requerido el token de acceso Authorization: Bearer miaccesstoken

Carga de plantilla de Microsoft Word

/api/v1/upload

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->addForm(array(
  'data' => '14'
), NULL);

$request->setRequestUrl('https://mailmerge.789.com.mx/api/v1/upload');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTIzNjU5ODUsIwMjAtMDYtMTJUMjA6NDI6MjAuNzkxMjIwIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMTJUMjA6NDI6MjAuNzkxMjIwIn19.ovuXMqNqoRvlxFTe5rgbQebYVOHV8LJ9rr9CR6Si_LI'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

curl --request POST \
  --url https://mailmerge.789.com.mx/api/v1/upload \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTIzNjU5ODVudGl0eSI6IjIwMjAtMDYtMTJUMjA6NDI6MjAuNzkxMjIwIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMTJUMjA6NDI6MjAuNzkxMjIwIn19.ovuXMqNqoRvlxFTe5rgbQebYVOHV8LJ9rr9CR6Si_LI' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file= \
  --form data=14

var form = new FormData();
form.append("file", "");
form.append("data", "14");

fetch("https://mailmerge.789.com.mx/api/v1/upload", {
  "method": "POST",
  "headers": {
    "content-type": "multipart/form-data; boundary=---011000010111000001101001",
    "authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYxNTkyNDQ4Nzg1LCJpZGVudGl0eSI6IjIwMjAtMDYtMTJUMjA6NDI6MjAuNzkxMjIwIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMTJUMjA6NDI6MjAuNzkxMjIwIn19.ovuXMqNqoRvlxFTe5rgbQebYVOHV8LJ9rr9CR6Si_LI"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

Esta es la respuesta que recibirás

{
  "id": 1,
  "identification": 14,
  "filepath": "templates/uploads/Pagare_PF_789890fddec-35e2-4ba5-b7cf-5b5a8b0e7d72.docx",
  "created_at": "2020-06-22T18:30:12.914718",
  "fields": [
    "nombre_aval",
    "fecha_termina",
    "fecha_contrato",
    "fecha_inicia",
    "porcentaje_moratorio_letra",
    "nombre_cliente",
    "monto_pagare_letra",
    "monto_pagare",
    "porcentaje_moratorio",
    "plazo"
  ]
}

Este endpoint carga un archivo tipo Microsoft Word que sirve como plantilla con los campos combinables incrustados a lo largo del documento.

HTTP Request

POST https://mailmerge.789.com.mx/api/v1/upload

Parámetros

Parameter	Requerido	Description
file	Si	Aquí va el documento en formato de Microsoft Word.
data	Si	Ésta es la referencia del archivo, éste ID es el número registrado en tu base de datos para referenciar el documento que estas procesando. En la respuesta viene como "identification"

Obtener los campos de un archivo previamente subido

/api/v1/document/{refid}

<?php

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://mailmerge.789.com.mx/api/v1/document/14');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOj1MTUzNDAyLCJpZGVudGl0eSI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIn19.7rlCm1FCthSqv2hIDaIe-DrC8SZmO51vtQvY9-vgbfY'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

curl --request GET \
  --url https://mailmerge.789.com.mx/api/v1/document/14 \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1ODAyLCJpZGVudGl0eSI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIn19.7rlCm1FCthSqv2hIDaIe-DrC8SZmO51vtQvY9-vgbfY'

fetch("https://mailmerge.789.com.mx/api/v1/document/14", {
  "method": "GET",
  "headers": {
    "authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1OTNDAyLCJpZGVudGl0eSI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIn19.7rlCm1FCthSqv2hIDaIe-DrC8SZmO51vtQvY9-vgbfY"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

Esta es la respuesta que recibirás

{
  "id": 1,
  "identification": 14,
  "filepath": "templates/uploads/PagarePF7892102cc3a-5f12-4056-87d3-7c04bcd0f42d.docx",
  "created_at": "2020-06-19T00:01:33.938620",
  "fields": [
    "fecha_contrato",
    "nombre_aval",
    "nombre_cliente",
    "porcentaje_moratorio_letra",
    "porcentaje_moratorio",
    "fecha_inicia",
    "plazo",
    "fecha_termina",
    "monto_pagare_letra",
    "monto_pagare"
  ]
}

Si deseas obtener nuevamente la lista de campos de un documento previamente cargado, sólo utilizas éste endpoint colocando al final la referencia de el documento, el número de identificación que tienes en tu base de datos que hace referencia a ésta plantilla.

HTTP Request

GET https://mailmerge.789.com.mx/api/v1/document/id

Parámetros

Parameter	Requerido	Description
id	Si	Ésta es la referencia del archivo, éste ID es el número registrado en tu base de datos para referenciar el documento que estas procesando

Combinar platilla con datos

/api/v1/document/{refid}/merge

<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
  "fields": {
    "monto_pagare": "1500",
    "nombre_aval": "JANE DOE",
    "monto_pagare_letra": "MIL QUINIENTOS PESOS 00/100 MONEDA NACIONAL",
    "porcentaje_moratorio": "2",
    "fecha_inicia": "2 DE ENERO DE 2020",
    "fecha_contrato": "2 DE ENERO DE 2020",
    "fecha_termina": "2 DE ENERO DE 2021",
    "nombre_cliente": "JOHN DOE",
    "plazo": "12",
    "porcentaje_moratorio_letra": "DOS PORCIENTO"
  },
  "tables": []
}');

$request->setRequestUrl('https://mailmerge.789.com.mx/api/v1/document/14/merge');
$request->setRequestMethod('PUT');
$request->setBody($body);

$request->setHeaders(array(
  'content-type' => 'application/json',
  'authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjNDAyLCJpZGVudGl0eSI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIn19.7rlCm1FCthSqv2hIDaIe-DrC8SZmO51vtQvY9-vgbfY'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

curl --request PUT \
  --url https://mailmerge.789.com.mx/api/v1/document/14/merge \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1O1MTUzNDAyLCJpZGVudGl0eSI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIn19.7rlCm1FCthSqv2hIDaIe-DrC8SZmO51vtQvY9-vgbfY' \
  --header 'content-type: application/json' \
  --data '{
  "fields": {
    "monto_pagare": "1500",
    "nombre_aval": "JANE DOE",
    "monto_pagare_letra": "MIL QUINIENTOS PESOS 00/100 MONEDA NACIONAL",
    "porcentaje_moratorio": "2",
    "fecha_inicia": "2 DE ENERO DE 2020",
    "fecha_contrato": "2 DE ENERO DE 2020",
    "fecha_termina": "2 DE ENERO DE 2021",
    "nombre_cliente": "JOHN DOE",
    "plazo": "12",
    "porcentaje_moratorio_letra": "DOS PORCIENTO"
  },
  "tables": []
}'

fetch("https://mailmerge.789.com.mx/api/v1/document/14/merge", {
  "method": "PUT",
  "headers": {
    "content-type": "application/json",
    "authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjENDAyLCJpZGVudGl0eSI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIiwiZnJlc2giOnRydWUsInR5cGUiOiJhY2Nlc3MiLCJ1c2VyX2NsYWltcyI6eyJyb2xlcyI6IjIwMjAtMDYtMThUMTg6MDU6MjMuODY1NDgzIn19.7rlCm1FCthSqv2hIDaIe-DrC8SZmO51vtQvY9-vgbfY"
  },
  "body": {
    "fields": {
      "monto_pagare": "1500",
      "nombre_aval": "JANE DOE",
      "monto_pagare_letra": "MIL QUINIENTOS PESOS 00/100 MONEDA NACIONAL",
      "porcentaje_moratorio": "2",
      "fecha_inicia": "2 DE ENERO DE 2020",
      "fecha_contrato": "2 DE ENERO DE 2020",
      "fecha_termina": "2 DE ENERO DE 2021",
      "nombre_cliente": "JOHN DOE",
      "plazo": "12",
      "porcentaje_moratorio_letra": "DOS PORCIENTO"
    },
    "tables": []
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

Recibirás como respuesta un archivo binario en formato Microsoft Word, tu código debe estar preparado para leer el contenido de la respuesta y guardarlo en un archivo local.

HTTP Request

PUT https://mailmerge.789.com.mx/api/v1/document/{refid}/merge

Parámetros

Parameter	Requerido	Description
id	Si	Ésta es la referencia del archivo, éste ID es el número registrado en tu base de datos para referenciar el documento que estas procesando

Body

En el cuerpo del request, incluir un json con el mapeo de los campos combinables y los datos que van a ser reemplazados en el documento. La seccion "tables" dejarlo como un arreglo vacío

{
  "fields": {
    "monto_pagare": "1500",
    "nombre_aval": "JANE DOE",
    "monto_pagare_letra": "MIL QUINIENTOS PESOS 00/100 MONEDA NACIONAL",
    "porcentaje_moratorio": "2",
    "fecha_inicia": "2 DE ENERO DE 2020",
    "fecha_contrato": "2 DE ENERO DE 2020",
    "fecha_termina": "2 DE ENERO DE 2021",
    "nombre_cliente": "JOHN DOE",
    "plazo": "12",
    "porcentaje_moratorio_letra": "DOS PORCIENTO"
  },
  "tables": []
}

En esta sección deberas enviar un JSON válido con dos claves (fields, tables) en el objeto "fields" envias el mapeo de tus campos combinables y los datos que deseas reemplazar, en "tables" va un arreglo vacío.

Errores

Esta es la lista de errores que puede arrojar MailMerge API

Codigo	Significado
400	Bad Request -- Su solicitud no es válida.
401	Unauthorized -- Su token expiró o no es válido.
403	Forbidden -- Su solicitud está oculta o no encontrada.
404	Not Found -- Registro no encontrado.
405	Method Not Allowed -- Esta tratando de utilizar un método no reconocido.
406	Not Acceptable -- Su solicitud no es un json válido.
429	Too Many Requests -- Demasiadas solicitudes
500	Internal Server Error -- Error interno del servidor.