Enviar documento

POST /api/documents/v4

Este endpoint permite crear y enviar un documento electrónico al Ministerio de Hacienda. En resumen se debe enviar los siguientes detalles:

• Metadatos sobre el documento (condición de venta, plazos, codigos de actividad, etc.)
• Receptor del documento si así se requiere.
• Detalles del documento (incluye descuentos, impuestos, exoneraciones, etc.), pero sin los montos de cálculo en sus líneas. El API calculará los montos totales.
• Informacion de referencia
• Otros Cargos

Aquí se especifica la clase de salida: SendDocumentResponse

Parámetros

Aquí se especifica la clase de entrada en su totalidad: SendDocumentRequest

includeData (bool) (opcional)

Este parámetro se puede enviar por medio del query string. Su valor por defecto es false. Le indica al endpoint si debe devolver valores “data”, o sea, si debe devolver en este endpoint el XML creado y firmado.

Esto permite que los clientes que consumen el API pueden elegir entre obtener los XML directos en las respuestas o obtenerlos después en llamadas individuales.

Respuestas Esperadas

HTTP 200 OK

El documento ha sido procesado exitosamente y se ha enviado al Ministerio de Hacienda.

HTTP 400 Bad Request

El documento de entrada presenta errores, ver la documentación de validaciones.

Ejemplo de respuesta con error con descripción completa:

    {
    "statusCode": 400,
    "message": "One or more errors occurred!",
    "errors": {
        "sendDocumentRequest.ReceptorRequest.CorreoElectronico": [
            "Correo electrónico inválido. Solamente se aceptan correos electrónicos válidos separados por punto y coma (;). Evite espacios en la cadena."
        ]
        }
    }

HTTP 500 Internal Server Error

Ocurrio un error interno o hubo un problema en la comunicación con Hacienda.

Ejemplo de respuesta con error con descripción completa:

    {
        "id_externo": "12",
        "consecutivo": "20",
        "numero_documento": "02000001040000000020",
        "clave": "50630052500310137293502000001040000000020119079365",
        "estado": "05",
        "estado_humanizado": "NotSendYet",
        "xml": "",
        "mensaje_api": "El servidor de Hacienda no responde."
        "mensaje_api_key": "SendingDocumentError"
    }

Ejemplo de un error por tener el certificado expirado:

{
    "id_externo": "50",
    "consecutivo": "259",
    "numero_documento": "02000001010000000259",
    "clave": "50601082500310137293502000001010000000259119079365",
    "estado": "00",
    "estado_humanizado": "Pending",
    "xml": "",
    "mensaje_api": "El certificado se encuentra vencido, debe generar un nuevo certificado.",
    "mensaje_api_key": "ExpiredClientCertificate"
}

Ejemplo de respuesta con error interno muy grave:

    {
        "error": "Error interno. Disculpas. Puede reportar el error suministrando este código: 326d96d9-5200-4a64-a84d-986e99f62c5f"
    }

Ejemplo

Llamada

    curl -X 'POST' \
    'https://api44.qupos.com/api/documents/v4' \
    -H 'accept: text/plain' \
    -H 'AuthToken: TOKEN_UNICO' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Basic bmNxOk5DUVXXXXXXXXAwNzA1' \
    -H 'Content-Type: application/json' \
    -d '{
            "id_externo" : "56",
            "tipo_documento": "01",
            "registro_fiscal8707": "123456789112",
            "codigo_actividad_emisor": "123456",
            "fecha_emision": "2025-05-06T13:00:00",
            "clave": "50603042300310140926100200001050000019023171187576",
            ...
    }'

Respuesta

    {
        "id_externo": "50",
        "consecutivo": "285",
        "numero_documento": "02000001010000000285",
        "clave": "50612082500310137293502000001010000000285119079365",
        "estado": "04",
        "estado_humanizado": "Sent",
        "xml": "",
        "mensaje_api": "",
        "mensaje_api_key": ""
    }