POST /firma ​

Descripción ​

El endpoint /firma es un método POST que se utiliza para generar una firma electrónica para una factura o documento específico.

Este endpoint recibe la información de la factura en el cuerpo de la solicitud (body), y también requiere ciertas credenciales de autenticación en los encabezados (headers). Estas credenciales incluyen el código PFX, el alias PFX y la llave PFX del emisor. Esta información es necesaria para autenticar correctamente al emisor y permitir la generación de la firma electrónica.

El cuerpo de la solicitud debe contener la información detallada de la factura, incluyendo datos como el formato, el email del cliente, el establecimiento, entre otros. Además, debe incluir una lista de los ítems o productos/servicios que se están facturando, junto con su información detallada.

Una vez que la solicitud ha sido procesada correctamente y la firma electrónica ha sido generada, este endpoint retorna una respuesta con el status HTTP 200 y los datos asociados a la firma generada.

En caso de que la solicitud no pueda ser procesada correctamente, el servidor puede devolver varios códigos de error, que indican el tipo de problema que se encontró al tratar de procesar la solicitud.

Este endpoint es una parte crucial en el proceso de facturación electrónica, ya que permite autenticar y validar los documentos de factura de manera segura y eficiente.

Método HTTP ​

POST

URL ​

/firma

Encabezados (Headers) ​

Cuerpo de la solicitud (Body) ​

Nota: Para la propiedad items, cada ítem tiene las siguientes propiedades:

Ejemplo de solicitud ​

POST /firma
Headers:
{
  "codigo_pfx": "codigo_emisor",
  "alias_pfx": "alias_emisor",
  "llave_pfx": "llave_emisor"
}
Body:
{
  "formato": "PDF",
  "email": "cliente@example.com",
  "establecimiento": "1",
  "tc": "1",
  "escenario": "1",
  "frases": [
    1,
    2,
    3
  ],
  "nombre_comercial": "Flora S.A.",
  "direccion_comercial": "Zona 10, Guatemala",
  "municipio_comercial": "Guatemala",
  "departamento_comercial": "Guatemala",
  "tipo": "LOCAL",
  "items": [
    {
      "tipo_producto": "B",
      "producto": "Producto 1",
      "precio_quetzales": "100.00",
      "iva": "12.00",
      "descuento": "5.00",
      "cantidad": "1"
    },
    {
      "tipo_producto": "S",
      "producto": "Servicio 1",
      "precio_quetzales": "200.00",
      "iva": "24.00",
      "descuento": "10.00",
      "cantidad": "2"
    }
  ],
  "nit": "6738648",
  "moneda": "GTQ",
  "fecha_emision": "2023-05-17",
  "correo_copia": "emisor@example.com",
  "nit_emisor": "974706",
  "nombre_emisor": "FLORA, S.A.",
  "nombre_cliente": "LUIS FERNANDO MUNOZ CHACON",
  "direccion": "Zona 1, Guatemala",
  "serie": "001",
  "documento": "10001",
  "tipo_venta": "Contado"
}

Respuesta ​

Si la solicitud es exitosa, el servidor responderá con el código de estado HTTP 200 y los datos asociados a la firma generada.

A la espera de la información adicional...

Ejemplo de Respuesta ​

{
  "status": 200,
  "data": {
    "resultado": true,
    "descripcion": "Documento firmado con éxito",
    "archivo": "<base64>"
  }
}

export interface Response {
    status: number;
    data:   Data;
}

export interface Data {
    resultado:   boolean;
    descripcion: string;
    archivo:     string;
}

Códigos de Error ​

• 400 Bad Request: Si los parámetros requeridos no están presentes o no tienen un formato válido.
• 401 Unauthorized: Si las credenciales de autenticación (codigo_pfx, alias_pfx, y llave_pfx) no son válidas.
• 404 Not Found: Si no se encuentra la factura asociada para firmar.
• 500 Internal Server Error: Si ocurre un error en el servidor al procesar la solicitud.

Ejemplo de Código en Node.js (Express.js) ​

Router.post('/firma', async (req, res, next) => {
  try {
    const { headers, body } = req
    const { status, data } = await infileController.createFirma(headers, body)
    return res.json({ status, data })
  } catch (error) {
    throw error
  }
})