> ## Documentation Index
> Fetch the complete documentation index at: https://docs-mx.taxo.ws/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> Track all changes, improvements, and updates to the Taxo API

## Overview

This changelog documents all notable changes to the Taxo API. We follow semantic versioning and maintain backward compatibility whenever possible.

## Version 1.0.0

<sup>Released January 4, 2025</sup>

The initial release of Taxo API marks a complete implementation of enterprise-grade document extraction capabilities for Mexican tax documents.

### 🎉 Major Features

<AccordionGroup>
  <Accordion title="Job-Based Processing System" icon="cogs">
    Introduced asynchronous job processing for all document extractions:

    * Each extraction request creates a unique job with `publicId` identifier
    * Background processing allows handling large document volumes efficiently
    * Real-time status tracking through dedicated endpoints

    ```json theme={null}
    {
      "publicId": "JOB20250104123456789A",
      "status": "PROCESSING",
      "discoveryCount": 1500,
      "completedCount": 750
    }
    ```
  </Accordion>

  <Accordion title="Multi-Information Type Support" icon="file-invoice">
    Complete support for all major Mexican tax document types:

    * **INVOICE**: CFDI invoices with both XML and PDF formats
    * **TAX\_STATUS**: Constancia de Situación Fiscal documents
    * **TAX\_RETENTION**: Tax retention certificates

    Each type includes specific validation and processing rules.
  </Accordion>

  <Accordion title="Advanced Filtering System" icon="filter">
    Flexible filtering capabilities for precise document retrieval:

    ```json theme={null}
    "filters": {
      "emitter": {
        "operator": "equals",
        "value": "TBO140305DH0"
      }
    }
    ```

    Supported operators: `equals`, `contains`, `in`
  </Accordion>

  <Accordion title="Webhook Integration" icon="webhook">
    Real-time notifications system with semantic payload structure:

    * Event-driven notifications for job completion
    * Comprehensive payload with extraction context
    * HMAC-SHA256 signature verification for security

    Example event types: `invoice.ready`, `tax_status.ready`, `tax_retention.ready`
  </Accordion>
</AccordionGroup>

### 🔧 API Endpoints

Three core endpoints provide complete extraction workflow:

<CardGroup cols={3}>
  <Card title="Create Extraction" icon="plus">
    `POST /v1/extractions`

    Initiates new document extraction job with credential validation and filter configuration.
  </Card>

  <Card title="Job Status" icon="search">
    `GET /v1/extractions/{publicId}`

    Retrieves real-time job progress, document counts, and completion status.
  </Card>

  <Card title="Download Documents" icon="download">
    `GET /v1/extractions/{publicId}/documents/{documentId}/download`

    Secure document retrieval with format selection (XML/PDF).
  </Card>
</CardGroup>

### 🏗️ Technical Architecture

<AccordionGroup>
  <Accordion title="Strategy Pattern Implementation" icon="sitemap">
    Clean separation of concerns for different document types:

    * Dedicated processing strategies for each information type
    * Uniform API interface regardless of document complexity
    * Extensible architecture for future document types
  </Accordion>

  <Accordion title="Saga Processing Pattern" icon="route">
    Robust error handling and transaction management:

    * Compensating actions for failed operations
    * Consistent state management across distributed operations
    * Automatic retry mechanisms with exponential backoff
  </Accordion>

  <Accordion title="Security-First Design" icon="shield-check">
    Enterprise-grade security implementations:

    * Encrypted credential storage and transmission
    * JWT-based authentication with API key management
    * Comprehensive audit logging for compliance
  </Accordion>
</AccordionGroup>

### 📊 Rate Limits & Performance

Production-ready policies for enterprise usage:

| Operation           | Limit          | Window     |
| ------------------- | -------------- | ---------- |
| Extraction Creation | 10 requests    | per hour   |
| Status Checks       | 100 requests   | per minute |
| Document Downloads  | 1,000 requests | per hour   |

### 🔐 Enhanced Security

* **Credential Management**: Secure SAT credential handling with encrypted storage
* **API Authentication**: Bearer token authentication with organization-level access control
* **Document Retention**: 30-day secure storage with automatic cleanup
* **Webhook Security**: HMAC signature verification and replay attack prevention

### 📚 Documentation & Developer Experience

Comprehensive documentation suite includes:

* Interactive API reference with code examples
* Integration best practices and security guidelines
* Use case implementations for common scenarios
* Troubleshooting guides and error handling patterns

### 🌟 Key Improvements

<Tip>
  **Performance**: Parallel document processing reduces extraction time by up to 70% compared to sequential processing.
</Tip>

<Tip>
  **Reliability**: Built-in retry mechanisms and circuit breaker patterns ensure 99.9% successful extraction rate.
</Tip>

<Tip>
  **Developer Experience**: SDKs available for Node.js, Python, Java, and C# with consistent interfaces.
</Tip>

## Breaking Changes

### From Beta to 1.0.0

<Warning>
  This section applies only to beta users. New integrations can ignore these changes.
</Warning>

* **Job Identifiers**: Migrated from internal `extractionId` to public `publicId` format
* **Credential Structure**: Updated to nested `SAT` object for enhanced security
* **Direction Values**: Changed from `RECEIVED`/`ISSUED` to `INBOUND`/`OUTBOUND` for consistency
* **Filter Operators**: Standardized operator naming conventions

## Upcoming Features

<Note>
  These features are planned for future releases and subject to change.
</Note>

### Version 1.1.0 (Q2 2025)

* **Batch Processing**: Multiple RFC processing in single request
* **Document Validation**: Real-time CFDI validation against SAT schemas
* **Export Formats**: JSON metadata extraction from XML documents

### Version 1.2.0 (Q3 2025)

* **Advanced Analytics**: Document processing insights and trends
* **Custom Webhooks**: User-defined webhook payload customization
* **Bulk Downloads**: Archive creation for multiple documents

## Migration Guides

<CardGroup cols={2}>
  <Card title="Beta to v1.0" icon="arrow-right" href="/integration-guides/best-practices">
    Step-by-step migration guide for beta users upgrading to production API.
  </Card>

  <Card title="Integration Examples" icon="code" href="/use-cases/accounting-automation">
    Real-world implementation examples for common integration patterns.
  </Card>
</CardGroup>

## Support & Feedback

<Card>
  <Icon icon="headset" size={32} />

  **Need Help with API Changes?**

  * **Technical Support**: [api-support@taxo.co](mailto:api-support@taxo.co)
  * **API Status**: [status.taxo.co](https://status.taxo.co)
  * **Feature Requests**: Create an issue in our [GitHub repository](https://github.com/taxo/api-feedback)
</Card>

***

<Note>
  This changelog follows the [Keep a Changelog](https://keepachangelog.com/) format and adheres to [Semantic Versioning](https://semver.org/).
</Note>