Skip to main content
GET
https://api.taxo.co
/
v1
/
extractions
/
{publicId}
/
documents
/
{documentId}
/
download
Download Document
curl --request GET \
  --url https://api.taxo.co/v1/extractions/{publicId}/documents/{documentId}/download
{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "El documento solicitado no existe o no pertenece a esta extracción",
    "details": {
      "extractionId": "JOB20250104123456789A",
      "documentId": "doc_invalid"
    }
  }
}

Description

This endpoint allows you to download individual documents from a completed extraction job. Use the job’s publicId and the specific document ID to perform the download.
Los documentos solo están disponibles para descargas durante 30 días después de completado el job.

Parameters

publicId
string
required
ID público único del job completado (ej. “JOB20250104123456789A”)
documentId
string
required
ID único del documento a descargar
type
string
Formato del archivo a descargar:
  • XML: Archivo XML original del SAT (por defecto)
  • PDF: Representación visual del documento
Nota: No todos los documentos tienen ambos formatos disponibles.
download
boolean
Si es true, incluye el header Content-Disposition: attachment para forzar la descarga en navegadores. Por defecto: false

Response

La respuesta es el contenido binario del archivo solicitado.

Headers de respuesta

Content-Type
string
Tipo MIME del archivo:
  • application/xml para archivos XML
  • application/pdf para archivos PDF
Content-Length
number
Tamaño del archivo en bytes
Content-Disposition
string
Header de descarga (solo si se especifica download=true)Ejemplo: attachment; filename="factura_12345678-1234-1234-1234-123456789012.xml"
X-Document-UUID
string
UUID fiscal del documento (solo para facturas CFDI)
X-Document-Type
string
Tipo de documento descargado
X-File-Format
string
Formato del archivo: XML o PDF

Ejemplos

curl -X GET "https://api.taxo.co/v1/extractions/JOB20250104123456789A/documents/doc_550e8400/download?type=XML" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o "factura.xml"

Descarga masiva de documentos

Para descargar múltiples documentos eficientemente:
async function downloadAllDocuments(extractionId, documents, maxConcurrency = 5) {
  const results = [];
  const errors = [];
  
  // Función para procesar documentos en lotes
  async function processBatch(batch) {
    const promises = batch.map(async (doc) => {
      try {
        // Descargar ambos formatos si están disponibles
        const downloads = [];
        
        for (const format of doc.availableFormats) {
          const result = await downloadDocument(extractionId, doc.id, format);
          downloads.push(result);
        }
        
        return { documentId: doc.id, downloads, success: true };
      } catch (error) {
        console.error(`Error descargando ${doc.id}:`, error.message);
        errors.push({ documentId: doc.id, error: error.message });
        return { documentId: doc.id, success: false, error: error.message };
      }
    });
    
    return await Promise.all(promises);
  }
  
  // Procesar documentos en lotes para controlar concurrencia
  for (let i = 0; i < documents.length; i += maxConcurrency) {
    const batch = documents.slice(i, i + maxConcurrency);
    console.log(`Procesando lote ${Math.floor(i / maxConcurrency) + 1}/${Math.ceil(documents.length / maxConcurrency)}`);
    
    const batchResults = await processBatch(batch);
    results.push(...batchResults);
    
    // Pequeña pausa entre lotes para no sobrecargar el servidor
    if (i + maxConcurrency < documents.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  
  console.log(`\n✅ Descarga completada:`);
  console.log(`   Exitosos: ${results.filter(r => r.success).length}`);
  console.log(`   Fallidos: ${errors.length}`);
  
  return { results, errors };
}

// Uso con documentos de una extracción completada
const extractionStatus = await getExtractionStatus('JOB20250104123456789A');

if (extractionStatus.status === 'COMPLETED') {
  const downloadResults = await downloadAllDocuments(
    extractionStatus.publicId,
    extractionStatus.documents,
    3 // máximo 3 descargas simultáneas
  );
  
  console.log(`Documentos descargados: ${downloadResults.results.length}`);
}

Formatos disponibles por tipo de documento

  • XML: Archivo CFDI original del SAT con todos los datos fiscales
  • PDF: Representación visual de la factura (cuando está disponible)
  • PDF: Único formato disponible para constancias fiscales
  • XML: Archivo XML de la retención
  • PDF: Representación visual (cuando está disponible)

Códigos de error

{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "El documento solicitado no existe o no pertenece a esta extracción",
    "details": {
      "extractionId": "JOB20250104123456789A",
      "documentId": "doc_invalid"
    }
  }
}

Mejores prácticas

Verificación de integridad: Calcula hashes MD5 o SHA256 de los archivos descargados para verificar su integridad.
Límites de descarga: Respeta los rate limits para evitar ser bloqueado. Máximo 1000 descargas por hora.
Almacenamiento local: Los documentos descargados son válidos legalmente. Asegúrate de almacenarlos de forma segura y con respaldos.