Trabajo manual con la API con la herramienta Postman

Si no quiere integrar nuestra API a los procesos actuales, o no no tiene a dónde integrar, le ayudará este manual para enviar las demandas API mediante la herramienta Postman. Gracias a ella tiene un entorno preparado para enviar preguntas y para nuestras funciones preconfiguradas. Sin cualquier conocimiento de programación puede aprovechar la API de SSLmarket y ahorrar su tiempo.

La ventaja de integrar la API de SSLmarket a otros entornos consiste en el hecho de que la solución la puede realizar de forma compleja. La solución descrita en el manual nunca puede funcionar de forma automatizada, es manual, pero al menos le ahorrará el tiempo.

Instalación de la aplicación Postman

Descargue en el sitio web la versión para su ordenador fijo. La aplicación Postman existe también en la versión web sin embargo, esta no es adecuada para nuestros objetivos (no funciona).

La versión para Windows se instala de forma clásica, en Linux Postman probablemente estará disponible en forma de un paquete snap. Pues bien, en el terminal introduzca:

sudo snap install postman
Luego active el programa. Después de la activación, el programa le pedirá que acceda a la cuenta de usuario o que se la cree; sin embargo, esto se puede ignorar gracias a un pequeño enlace completamente abajo en el fondo de la ventana. Acceder a la cuenta Postman trae la ventaja de una sincronización de los proyectos entre cada una de las instancias. Puede continuar fácilmente en su trabajo también en su casa. Si no quiere aprovechar las ventajas de la cuenta y sincronización, o solo está probando, no necesita acceder a la cuenta.

Configuración de la aplicación para SSLmarket

Para hacerle lo máximo fácil el trabajo con la API y el programa hemos preparado para usted una "colección" de llamadas en el archivo JSON, que es suficiente importar y dentro de un rato tiene todas las funciones a su disposición. Importe la colección (el botón izquierdo arriba "importar"), después elija el archivo JSON preparado por nosotros. En Collections verá el ítem SSLmarket y diez funciones. Haga clic en la colección SSLmarket con el botón derecho y configure las variables en "Edit → Variables".

editace proměnných
Editar las variables para Collection. Haga clic para ampliar.

Lo más importante es activar la variable X-Auth-Token con un valor de la cuenta cliente. Las otras variables las unirá desde luego lógicamente con valores correctos sin embargo, más abajo encontrará la lista.

Explicación de los campos

  • X-Auth-Token: campo para introducir la clave API
  • owner_###: datos del futuro titular del certificado para la especificación
  • auth_###: datos del contacto autorizador, que en los certificados con validación confirma el pedido
  • tech_###: datos del contacto técnico; este no participa en la validación pero recibirá el certificado emitido por correo electrónico
  • invoice_###: campo para especificar los datos de facturación; esta información define al cliente en la factura
nastavené proměnné
Configuración de las variables para Collection. Haga clic para aumentar.

Estos datos iniciales van a salir en las variables (por ejemplo, cuando introduzca el pedido) y no será necesario volver a introducirlos. Si no entiende bien alguno de los campos lo encontrará en la documentación API.

Después de finalizar la configuración e introducir toda la información puede empezar a enviar las demandas a la API de SSLmarket.

Envío de las demandas

Después de configurar el programa puede empezar a enviar las demandas y sobre todo pedidos nuevos. La CSR tiene que estar sin espacios ni compaginado, estos es necesario configurarlos mediante la secuencia escape. Véase más en el siguiente párrafo.

Elija en la colección la función API que quiere utilizar. Luego verá en la parte derecha (grande) de la ventana en el marcador Body la construcción de la pregunta. Por ejemplo, cuando introduce el pedido hay información completa sobre el futuro certificado (la cantidad se corresponde con el pedido en la web). La información entre paréntesis significa que se utilizará aquella variable que haya definido antes: por ejemplo {{owner_name}} Estos ítems los configura solo si necesita utilizar datos diferentes de los datos iniciales.

Datos para introducir el pedido

Los datos del solicitante y los contactos se le cargarán de los datos iniciales preparados. En cada pedido es necesario concretar estos datos específicos:

  • domain: Common name del certificado
  • dns_names: lista de los SANs en el certificado
  • years: número de años de la validez del pedido (la validez del certificado es limitada pero el pedido puede ser para varios años)
  • csr: aquí introduzca la CSR (tiene que estar sin interlineado ni espacios, véase más abajo). Es un dato no obligatorio y la CSR la puede introducir en SSLmarket incluso después de introducir el pedido mediante la API.
  • dv_auth_method: opciones de la forma de validación DCV (correo, dns, ftp)

Cuando introduzca todos los datos y la demanda esté preparada la enviará a la API haciendo clic en el botón azul Send.

El proceso y el resultado de la demanda los podrá ver en la parte inferior de la ventana. Si el resultado es exitoso recibirá la información solicitada o el número del pedido, si haya introducido el pedido. En caso contrario recibirá un aviso sobre error, que especificará lo que es incorrecto o lo que falta en la pregunta.

Ejemplo de un pedido introducido correctamente:

{
    "order_id": "155252"
}

Ejemplo de un aviso sobre error:

   {
    "error": [
        "dv_auth_method => isEmpty: El ítem es obligatorio y no puede estar vacío"
    ]
}

Posibles colisiones durante el envío de las demandas

  • URL utilizado: Utilice un URL del endpoint en la forma www.sslmarket.tld y no solamente sslmarket.tld. En el dominio básico se produce un redireccionamiento, que luego causa problemas con requests.
  • CSR request: Tenga cuidado de que la CSR no esté dividida en varios renglones. Si tiene problemas con introducir la CSR en forma correcta envíe el pedido sin ella e introdúzcala de forma estándar a través de la administración.
    • La CSR no se puede enviar dividida en renglones, a pesar de que así la recibirá de su servidor.
    • La CSR no puede contener espacios, finales de los renglones o compaginado de los párrafos; termine los renglones con la "secuencia escape" rn.
    • Configurará fácilmente la CSR a una forma adecuada con un solo clic utilizando la herramienta Remove or replace line breaks. Elija la opción „Replace line breaks with customer text“ y como un custom text introduzca rn. Cancele las otras opciones y haga clic en el botón verde de más abajo.

Preguntas frecuentes para uso manual de la API

Desde el punto de vista de funciones disponibles desde luego no, las dos formas dan los mismos resultados. El uso de la API de SSLmarket mediante la herramienta Postman le ahorrará tiempo y gastos de integración de la API a otro sistema sin embargo, es necesario activar las operaciones manualmente, lo cual es la única desventaja de esta forma. No es posible automatizar pedidos o renovaciones de los certificados, esto necesita su propia solución con implementación de nuestra API.

Todos los pedidos los encontrará en su cuenta cliente tal como los introduciría de manera normal a través de la web. Su demanda identifica para la cuenta correcta la clave API generada.

La facturación funciona de manera normal, con lo cual para utilizar la API recomendamos la cuenta de crédito con un pago automático de los pedidos.