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

# List Invoices

> Retrieve a paginated list of invoices with optional filtering

## Authentication

This endpoint requires authentication. Include your access token in the Authorization header.

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Query Parameters

<ParamField query="profileId" type="string">
  Filter invoices by profile ID
</ParamField>

<ParamField query="mes" type="number">
  Filter by month (1-12)
</ParamField>

<ParamField query="año" type="number">
  Filter by year
</ParamField>

<ParamField query="regimen_fiscal" type="string">
  Filter by tax regime code
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of invoices per page
</ParamField>

<ParamField query="search" type="string">
  Search term to filter invoices by UUID, RFC, or name
</ParamField>

## Response

<ResponseField name="data" type="Invoice[]">
  Array of invoice objects

  <Expandable title="Invoice">
    <ResponseField name="id" type="string">
      Unique identifier for the invoice
    </ResponseField>

    <ResponseField name="profile_id" type="string">
      Profile ID this invoice belongs to
    </ResponseField>

    <ResponseField name="uuid" type="string">
      CFDI UUID (Folio Fiscal)
    </ResponseField>

    <ResponseField name="fecha" type="string">
      Invoice date in ISO format
    </ResponseField>

    <ResponseField name="mes" type="number">
      Month extracted from invoice date (1-12)
    </ResponseField>

    <ResponseField name="año" type="number">
      Year extracted from invoice date
    </ResponseField>

    <ResponseField name="total" type="number">
      Total amount of the invoice
    </ResponseField>

    <ResponseField name="subtotal" type="number">
      Subtotal before taxes
    </ResponseField>

    <ResponseField name="iva" type="number">
      IVA percentage rate
    </ResponseField>

    <ResponseField name="iva_amount" type="number" optional>
      IVA transferred amount (impuesto trasladado)
    </ResponseField>

    <ResponseField name="retencion_iva_amount" type="number" optional>
      IVA withholding amount
    </ResponseField>

    <ResponseField name="retencion_isr_amount" type="number" optional>
      ISR withholding amount
    </ResponseField>

    <ResponseField name="tipo" type="enum">
      Payment type: `PUE` (payment in one exhibit), `PPD` (payment in installments), or `COMPLEMENTO_PAGO` (payment complement)
    </ResponseField>

    <ResponseField name="rfc_emisor" type="string">
      RFC of the issuer
    </ResponseField>

    <ResponseField name="nombre_emisor" type="string">
      Name of the issuer
    </ResponseField>

    <ResponseField name="regimen_fiscal_emisor" type="string" optional>
      Tax regime code of the issuer
    </ResponseField>

    <ResponseField name="rfc_receptor" type="string">
      RFC of the recipient
    </ResponseField>

    <ResponseField name="nombre_receptor" type="string">
      Name of the recipient
    </ResponseField>

    <ResponseField name="regimen_fiscal_receptor" type="string" optional>
      Tax regime code of the recipient
    </ResponseField>

    <ResponseField name="concepto" type="string" optional>
      Invoice concept or description
    </ResponseField>

    <ResponseField name="pagos" type="array">
      Array of payment records

      <Expandable title="Pago">
        <ResponseField name="fechaPago" type="string">
          Payment date in ISO format
        </ResponseField>

        <ResponseField name="formaPago" type="string">
          Payment method code
        </ResponseField>

        <ResponseField name="monedaPago" type="string">
          Payment currency code
        </ResponseField>

        <ResponseField name="monto" type="number">
          Payment amount
        </ResponseField>

        <ResponseField name="numOperacion" type="string" optional>
          Operation or transaction number
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="complemento_pago" type="object" optional>
      Payment complement information (for COMPLEMENTO\_PAGO type)

      <Expandable title="ComplementoPago">
        <ResponseField name="fechaPago" type="string">
          Payment date
        </ResponseField>

        <ResponseField name="formaPago" type="string">
          Payment method
        </ResponseField>

        <ResponseField name="monedaPago" type="string">
          Payment currency
        </ResponseField>

        <ResponseField name="tipoCambio" type="number">
          Exchange rate
        </ResponseField>

        <ResponseField name="monto" type="number">
          Payment amount
        </ResponseField>

        <ResponseField name="numOperacion" type="string" optional>
          Operation number
        </ResponseField>

        <ResponseField name="facturasRelacionadas" type="array">
          Related invoices being paid

          <Expandable title="FacturaRelacionada">
            <ResponseField name="uuid" type="string">
              UUID of related invoice
            </ResponseField>

            <ResponseField name="monedaDR" type="string">
              Currency code
            </ResponseField>

            <ResponseField name="tipoCambioDR" type="number">
              Exchange rate
            </ResponseField>

            <ResponseField name="metodoPagoDR" type="string">
              Payment method
            </ResponseField>

            <ResponseField name="numParcialidad" type="number">
              Installment number
            </ResponseField>

            <ResponseField name="impSaldoAnt" type="number">
              Previous balance
            </ResponseField>

            <ResponseField name="impPagado" type="number">
              Amount paid
            </ResponseField>

            <ResponseField name="impSaldoInsoluto" type="number">
              Outstanding balance
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="validacion" type="object">
      Validation results

      <Expandable title="Validacion">
        <ResponseField name="rfcVerificado" type="boolean">
          Whether RFC was verified
        </ResponseField>

        <ResponseField name="regimenFiscalVerificado" type="boolean">
          Whether tax regime was verified
        </ResponseField>

        <ResponseField name="uuidDuplicado" type="boolean">
          Whether UUID is duplicated
        </ResponseField>

        <ResponseField name="advertencias" type="string[]">
          Array of warning messages
        </ResponseField>

        <ResponseField name="errores" type="string[]">
          Array of error messages
        </ResponseField>

        <ResponseField name="valido" type="boolean">
          Overall validation status
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="estadoPago" type="object" optional>
      Payment status details

      <Expandable title="EstadoPago">
        <ResponseField name="estado" type="enum">
          Payment state: `PAGADO`, `PAGO_PARCIAL`, or `NO_PAGADO`
        </ResponseField>

        <ResponseField name="totalFactura" type="number">
          Total invoice amount
        </ResponseField>

        <ResponseField name="totalPagado" type="number">
          Total amount paid
        </ResponseField>

        <ResponseField name="saldoPendiente" type="number">
          Pending balance
        </ResponseField>

        <ResponseField name="porcentajePagado" type="number">
          Percentage paid (0-100)
        </ResponseField>

        <ResponseField name="completamentePagado" type="boolean">
          Whether fully paid
        </ResponseField>

        <ResponseField name="ultimoSaldoInsoluto" type="number" optional>
          Last outstanding balance from payment complement
        </ResponseField>

        <ResponseField name="tieneComplementos" type="boolean">
          Whether has payment complements
        </ResponseField>

        <ResponseField name="tienePagosManuales" type="boolean">
          Whether has manual payments
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="profile" type="object" optional>
      Profile information

      <Expandable title="Profile">
        <ResponseField name="id" type="string">
          Profile ID
        </ResponseField>

        <ResponseField name="nombre" type="string">
          Profile name
        </ResponseField>

        <ResponseField name="rfc" type="string">
          Profile RFC
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Creation timestamp in ISO format
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Last update timestamp in ISO format
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="Pagination">
    <ResponseField name="total" type="number">
      Total number of invoices
    </ResponseField>

    <ResponseField name="page" type="number">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of items per page
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

```bash theme={null}
curl -X GET "https://api.contafy.com/api/invoices?profileId=prof_123&mes=3&año=2026&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "inv_abc123",
      "profile_id": "prof_123",
      "uuid": "12345678-90AB-CDEF-1234-567890ABCDEF",
      "fecha": "2026-03-15T10:30:00Z",
      "mes": 3,
      "año": 2026,
      "total": 11600.00,
      "subtotal": 10000.00,
      "iva": 16,
      "iva_amount": 1600.00,
      "tipo": "PUE",
      "rfc_emisor": "XAXX010101000",
      "nombre_emisor": "Empresa Ejemplo SA de CV",
      "regimen_fiscal_emisor": "601",
      "rfc_receptor": "BAXX010101000",
      "nombre_receptor": "Cliente Ejemplo",
      "regimen_fiscal_receptor": "612",
      "concepto": "Servicios de consultoría",
      "pagos": [],
      "complemento_pago": null,
      "validacion": {
        "rfcVerificado": true,
        "regimenFiscalVerificado": true,
        "uuidDuplicado": false,
        "advertencias": [],
        "errores": [],
        "valido": true
      },
      "estadoPago": {
        "estado": "PAGADO",
        "totalFactura": 11600.00,
        "totalPagado": 11600.00,
        "saldoPendiente": 0,
        "porcentajePagado": 100,
        "completamentePagado": true,
        "ultimoSaldoInsoluto": null,
        "tieneComplementos": false,
        "tienePagosManuales": false
      },
      "created_at": "2026-03-15T10:35:00Z",
      "updated_at": "2026-03-15T10:35:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}
```

## Error Responses

<ResponseField name="401 Unauthorized">
  ```json theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing access token"
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request">
  ```json theme={null}
  {
    "error": "Bad Request",
    "message": "Invalid query parameters"
  }
  ```
</ResponseField>

<ResponseField name="500 Internal Server Error">
  ```json theme={null}
  {
    "error": "Internal Server Error",
    "message": "An unexpected error occurred"
  }
  ```
</ResponseField>