Download OpenAPI specification:Download
API de integración de envío de mensajes EMAIL Certificados desde aplicaciones mediante peticiones https.
En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las Peticiones, por seguridad deben ralizarse en POST y con protocolo HTTPS Seguro.
Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.
Para generar el string codificado en Base64, simplemente genere el string UsuarioApi:APIToken y codifíquelo en base64 mediante cualquier función base64encode.
Conexiones en vacío: Es importante tener en cuenta que una conexión errónea de forma repetida será tratada por el sistema como spam y podrá llegar a bloquear temporalmente la conexión.
Es conveniente evitar realizar repetidas conexiones con datos erróneos o conexiones rápidas ‘en vacío’ (sin realizar envíos) con los mismos datos para obtener el número de créditos o el mismo report.
Para obtener reports de forma óptima en tiempo real se recomienda configurar la API en el panel para recibirlos en un script de su web.
Respuesta de las peticiones:
La mayoría de las funciones disponen de un parámetro denominado ‘Resp’. Este parámetro define el formato de la respuesta que se devolverá. Puede ser TXT, JSON, XML o no definido.
Se recomienda siempre definir este parámetro ya que todas las funciones, por compatibilidad con versiones anteriores de la API, responden por defecto (si no se define este parámetro) tal y como lo hacían en versiones antiguas. En estos resultados de versiones de API anteriores se obvian algunas de las variables que se incluyen en esta versión de la API y que consideramos importantes para facilitar la integración e información de la cuenta.
En los ejemplos incluidos siempre se tiene en cuenta que ha definido el parámetro. Si está trabajando directamente con la API versión >= 5, asumiremos que ha definido el parámetro en todas las peticiones.
Funcionamiento recomendado:
El funcionamiento recomendado, por ser el más sencillo y, a la vez, el más profesional es el siguiente:
- PROCESO 1: Envío de EMAIL Certificado: Descrito en la función EnviarEMAILCertificado de este documento.
- PROCESO 2: Recepción automática de reports en su web (proceso descrito en el la sección 'Recepción de reports de entrega'.
Autenticación HTTP Basic. Use su Usuario API como usuario y su API Token como contraseña (los encuentra en su panel, en Tus Datos → Configurar Cuenta). El header resultante es Authorization: Basic base64(UsuarioAPI:APIToken). La mayoría de las librerías HTTP lo construyen automáticamente (curl -u, requests auth=, basic_auth de Ruby, etc.) sin necesidad de codificar el base64 a mano.
basicFunción de envío de mensajes Email Certificados desde aplicaciones. Definición de parámetros necesarios.
ATENCIÓN: Chequee la sección de recepción de reports en tiempo real si desea recibir el estado de los correos y las interacciones del destinatario en tiempo real en un script de su web.
| Remitente required | string Example: Remitente=tucorreo@tudominio.com Remitente del Correo Certificado. Debe ser un email válido y haber sido validado previamente en el panel de control de usuario. |
| Destinatarios required | Array of arrays Example: Destinatarios=[{"Nombre":"Pedro Pérez","Email":"destinatario@eldominio.com","Variable_1":"Variable para personalizar asunto y mensaje por destinatario"}] Array JSON con los destinatario del correo certificado. Puede añadir variables si desea personalizar Asunto y Mensaje por destinatario. Por ejemplo: AVANZADO: En caso de querer proteger la notificación con OTP, DNI, Certificado, etc.. debes añadir las opciones siguientes como variables a cada destinatario:
|
| Asunto required | string Example: Asunto=Esto es una Notificacion para {{Nombre}} con motivo de {{Variable_1}} El asunto del correo electrónico certificado / de la notificación |
| Mensaje required | string Example: Mensaje=A la atención de {{Nombre}} con NIF {{DNI}}, Te enviamos esta notificación ..... Mensaje que se enviará al/ a los destinatarios |
| Fecha | string Example: Fecha=2022-05-01 15:10 Fecha en la que queda programado el envío, el mensaje se enviará en esa fecha. Por defecto "" que significa enviar inmediatamente. Formato Año-Mes-dia hora:minuto. La referencia horaria es CET/CEST (Zona horaria de España). |
| Aceptacion | string Enum: "SI" "NO" Example: Aceptacion=NO Parámetro que se utiliza para solicitar aceptación o rechazo explícito por parte del destinatario previa a la visualización de la notificación. Opciones 'SI' o 'NO' (NO por defecto) |
| Caducidadaceptacion | integer Example: Caducidadaceptacion=10 (Obligatorio si se activa Aceptación) Es el tiempo durante el cual el destinatario podrá aceptar o rechazar la notificación. Tras este tiempo, si no se ha aceptado ni rechazado, expirará. Valor de 1 a 30 días |
| Adjuntos | Array of arrays Array en JSON con los adjuntos si desea incluirlos en el mensaje. Por ejemplo : |
| Referenciausuario | string Example: Referenciausuario=Tu referencia Parámetro que se utiliza como referencia para el usuario. Si se selecciona recibir el report en una URL, recibirá este parámetro en el resultado del envío. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
| Report | string Example: Report=0 Si desea recibir reports por correo electrónico o en un script de su web (activando en panel de usuario la configuración API). |
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Remitente required | string |
| Destinatarios required | Array of any |
| Asunto required | string |
| Mensaje required | string |
| Fecha | string |
| Aceptacion | string |
| Caducidadaceptacion | integer |
| Adjuntos | Array of any |
| Referenciausuario | string |
| Resp | string |
| Report | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| Error | string En caso de Res -3 , obtendrá un error descriptivo del problema en este parámetro. |
| Destinatarios | Array of arrays Datos de los destinatarios en un array en el que se añade idMensaje por cada destinatario. El idMensaje es el Identificador del mensaje o grupo de mensajes enviados. Sirve, por ejemplo, como identificación para obtener el report del mensaje enviado (si el teléfono ha sido dado de baja, tiempos de entrega, etc…). Se recibirá en las peticiones si activa la recepción de reports en tiempo real en un script de su web/servidor. |
| Cred | double Créditos que restan en la cuenta de usuario tras el envío. |
| Enviados | integer Número de mensajes efectivamente enviados. |
| NoEnviados | integer Número de destinatarios erróneos/no enviados. |
| Duplicados | integer Número de destinatarios no enviados debido a que estaban duplicados. |
| CreditosUsados | integer Número de Créditos utilizados. |
{- "Remitente": "tucorreo@tudominio.com",
- "Destinatarios": "[{\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\",\"Variable_1\":\"Variable para personalizar asunto y mensaje por destinatario\"}]",
- "Asunto": "Esto es una Notificacion para {{Nombre}} con motivo de {{Variable_1}}",
- "Mensaje": "A la atención de {{Nombre}} con NIF {{DNI}}, Te enviamos esta notificación .....",
- "Fecha": "2022-05-01 15:10",
- "Aceptacion": "NO",
- "Caducidadaceptacion": "10",
- "Adjuntos": [
- null
], - "Referenciausuario": "Tu referencia",
- "Resp": "JSON",
- "Report": "0"
}[- {
- "Res": "10",
- "Error": "Falta parámetro obligatorio",
- "Destinatarios": "[{\"Nombre\": \"Pedro Pérez\",\"Email\": \"destinatario@eldominio.com\",\"IDMENSAJE\": \"108366478\",\"Variable_1\": \"Variable para personalizar asunto y mensaje por destinatario\"}]",
- "Cred": "12000",
- "Enviados": "2",
- "NoEnviados": "0",
- "Duplicados": "0",
- "CreditosUsados": "18"
}
]RECEPCIÓN EN TIEMPO REAL DE LOS ESTADOS DE ENTREGA EN UN SCRIPT DE SU SERVIDOR.
Activando la opción de recibir los reports en tiempo real en un script en su servidor desde su panel de usuario, recibirá una petición POST con el formato indicado cada vez que cada mensaje enviado cambie de estado.
Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA
Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.
| Servicio required | string Tipo de report que está recibiendo (el objetivo es distinguir entre los reports de los diferentes servicios). Los servicios a los que se refiere esta especificación puede recibir
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Resultado required | integer Estado de la notificación enviada. Los estados posibles son:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Remitente required | string Remitente utilizado en el envío. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Destinatario required | string Correo del destinatario al que se refiere el report. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Fecha required | string Fecha del report (fecha en la que la operadora que da servicio al móvil destino comunica el nuevo estado) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Asunto required | string Asunto del mensaje enviado | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| idMensaje required | integer Identificador único recibido como respuesta en la función de envío (idMensaje recibido en la función de envío) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Referencia required | string Referencia del usuario que se envió durante la petición de envío. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| CSV | string Código Seguro de Verificación recibido sólo en caso de que ya disponga de certificados generados |
{- "Servicio": "EMAILCERTIFICADO",
- "Resultado": "11",
- "Remitente": "tucorreo@tudominio.com",
- "Destinatario": "destino@dominio.com",
- "Fecha": "2020-12-03 11:14:24",
- "Asunto": "Asunto del email",
- "idMensaje": "10573758",
- "Referencia": "Su referencia si la indicó",
- "CSV": "ASYYFRE5492HN776TFD"
}Función para cancelar un Email Certificado programado previamente mediante la función de envío.
| Idmensaje required | integer Example: Idmensaje=1283876988 Identificador devuelto en la función de envío. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Idmensaje required | integer |
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| Cred | double Créditos que restan en la cuenta de usuario tras el envío. |
{- "Idmensaje": "1283876988",
- "Resp": "JSON"
}[- {
- "Res": "1",
- "Cred": "12000"
}
]Función para reprogramar un email previamente programado mediante la función de envío que fue programado para ser procesado en el futuro..
| Idmensaje required | integer Example: Idmensaje=1283876988 Identificador devuelto en la función de envío. |
| Fecha required | string Example: Fecha=2022-12-03 11:14:24 Nueva fecha de envío. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Idmensaje required | integer |
| Fecha required | string |
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| Cred | double Créditos que restan en la cuenta de usuario tras el envío. |
{- "Idmensaje": "1283876988",
- "Fecha": "2022-12-03 11:14:24",
- "Resp": "JSON"
}[- {
- "Res": "10",
- "Cred": "12000"
}
]Obtención del fichero PDF con el certificado del mensaje enviado a un móvil mediante la API. Esta función se ejecuta, habitualmente, como respuesta a una recepción de report con estado de certificado (ejemplo resultado 14 -entregado y certificado- en EMAIL Certificado y 17, 160 ó 181 -contrato firmado/perfeccionado y certificado- en caso de EMAIL Contrato). Se descarga un report y PDF si se especifica el Teléfono o todos los destinatarios del mensaje si no se especifica.
| Idmensaje required | integer Example: Idmensaje=1283876988 Identificador devuelto en la función de envío. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Idmensaje required | integer |
| Resp | string |
{- "Idmensaje": "1283876988",
- "Resp": "JSON"
}En caso de éxito se descarga un fichero zip. Contenido del ZIP: - Certificados en formato PDF - Fichero CSV con el resultado del mensaje certificado a cada destinatario.
Función para obtener el report de un email certificado enviado. Se recomienda activar la recepción de reports en su web en lugar de utilizar esta función. Las peticiones en bucle (petición continua del estado de/de los mismos mensajes en blucle) se consideran ataque y puede bloquear su conexión.
| Idmensaje required | integer Example: Idmensaje=1283876988 Identificador devuelto en la función de envío. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Idmensaje required | integer |
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| Programado | string Fecha a la que se envió o enviará el mensaje. |
| Remitente | string Remitente del email certificado. |
| Destinatario | string Destinatario del email certificado. |
| Cred | double Créditos que restan en la cuenta de usuario tras el envío. |
| Estado | integer Estado actual del mensaje. |
| txtEstado | string Descripción en texto del estado del mensaje. |
{- "Idmensaje": "1283876988",
- "Resp": "JSON"
}[- {
- "Res": "10",
- "Programado": "2021-10-10 10:10",
- "Remitente": "tucorreo@tudominio.com",
- "Destinatario": "destinatario@dominio.com",
- "Cred": "12000",
- "Estado": "11",
- "txtEstado": "Mensaje entregado, abierto, leído y certificado"
}
]Función que devuelve el número de créditos en la cuenta. Es una función de uso muy esporádico ya que la mayoría de las funciones devuelven en sus respuestas el número de Créditos restante en el usuario. Por tanto, se suele utilizar simplemente como prueba de funcionamiento o para obtener el número de créditos de forma ocasional
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.
| Resp | string |
| Res required | integer <int32> Respuesta de la función solicitada
|
| Cred required | double Créditos que restan en la cuenta de usuario tras el envío. |
{- "Resp": "JSON"
}[- {
- "Res": "10",
- "Cred": "12000"
}
]