List Invoices

Retrieve a paginated list of invoices with optional filtering

GET /api/invoices

List Invoices

cURL

curl --request GET \
  --url https://api.example.com/api/invoices

200

{
  "data": [
    {
      "id": "<string>",
      "profile_id": "<string>",
      "uuid": "<string>",
      "fecha": "<string>",
      "mes": 123,
      "año": 123,
      "total": 123,
      "subtotal": 123,
      "iva": 123,
      "iva_amount": 123,
      "retencion_iva_amount": 123,
      "retencion_isr_amount": 123,
      "tipo": {},
      "rfc_emisor": "<string>",
      "nombre_emisor": "<string>",
      "regimen_fiscal_emisor": "<string>",
      "rfc_receptor": "<string>",
      "nombre_receptor": "<string>",
      "regimen_fiscal_receptor": "<string>",
      "concepto": "<string>",
      "pagos": [
        {
          "fechaPago": "<string>",
          "formaPago": "<string>",
          "monedaPago": "<string>",
          "monto": 123,
          "numOperacion": "<string>"
        }
      ],
      "complemento_pago": {
        "fechaPago": "<string>",
        "formaPago": "<string>",
        "monedaPago": "<string>",
        "tipoCambio": 123,
        "monto": 123,
        "numOperacion": "<string>",
        "facturasRelacionadas": [
          {
            "uuid": "<string>",
            "monedaDR": "<string>",
            "tipoCambioDR": 123,
            "metodoPagoDR": "<string>",
            "numParcialidad": 123,
            "impSaldoAnt": 123,
            "impPagado": 123,
            "impSaldoInsoluto": 123
          }
        ]
      },
      "validacion": {
        "rfcVerificado": true,
        "regimenFiscalVerificado": true,
        "uuidDuplicado": true,
        "advertencias": [
          "<string>"
        ],
        "errores": [
          "<string>"
        ],
        "valido": true
      },
      "estadoPago": {
        "estado": {},
        "totalFactura": 123,
        "totalPagado": 123,
        "saldoPendiente": 123,
        "porcentajePagado": 123,
        "completamentePagado": true,
        "ultimoSaldoInsoluto": 123,
        "tieneComplementos": true,
        "tienePagosManuales": true
      },
      "profile": {
        "id": "<string>",
        "nombre": "<string>",
        "rfc": "<string>"
      },
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "limit": 123,
    "totalPages": 123
  }
}

Authentication

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

Authorization: Bearer YOUR_ACCESS_TOKEN

Query Parameters

profileId · string

Filter invoices by profile ID

mes · number

Filter by month (1-12)

año · number

Filter by year

regimen_fiscal · string

Filter by tax regime code

page · number · default: "1"

Page number for pagination

limit · number · default: "50"

Number of invoices per page

search · string

Search term to filter invoices by UUID, RFC, or name

Response

data · Invoice[]

Array of invoice objects

Show Invoice

id · string

Unique identifier for the invoice

profile_id · string

Profile ID this invoice belongs to

uuid · string

CFDI UUID (Folio Fiscal)

fecha · string

Invoice date in ISO format

mes · number

Month extracted from invoice date (1-12)

año · number

Year extracted from invoice date

total · number

Total amount of the invoice

subtotal · number

Subtotal before taxes

iva · number

IVA percentage rate

iva_amount · number

IVA transferred amount (impuesto trasladado)

retencion_iva_amount · number

IVA withholding amount

retencion_isr_amount · number

ISR withholding amount

tipo · enum

Payment type: PUE (payment in one exhibit), PPD (payment in installments), or COMPLEMENTO_PAGO (payment complement)

rfc_emisor · string

RFC of the issuer

nombre_emisor · string

Name of the issuer

regimen_fiscal_emisor · string

Tax regime code of the issuer

rfc_receptor · string

RFC of the recipient

nombre_receptor · string

Name of the recipient

regimen_fiscal_receptor · string

Tax regime code of the recipient

concepto · string

Invoice concept or description

pagos · array

Array of payment records

Show Pago

fechaPago · string

Payment date in ISO format

formaPago · string

Payment method code

monedaPago · string

Payment currency code

monto · number

Payment amount

numOperacion · string

Operation or transaction number

complemento_pago · object

Payment complement information (for COMPLEMENTO_PAGO type)

Show ComplementoPago

fechaPago · string

Payment date

formaPago · string

Payment method

monedaPago · string

Payment currency

tipoCambio · number

Exchange rate

monto · number

Payment amount

numOperacion · string

Operation number

facturasRelacionadas · array

Related invoices being paid

Show FacturaRelacionada

uuid · string

UUID of related invoice

monedaDR · string

Currency code

tipoCambioDR · number

Exchange rate

metodoPagoDR · string

Payment method

numParcialidad · number

Installment number

impSaldoAnt · number

Previous balance

impPagado · number

Amount paid

impSaldoInsoluto · number

Outstanding balance

validacion · object

Validation results

Show Validacion

rfcVerificado · boolean

Whether RFC was verified

regimenFiscalVerificado · boolean

Whether tax regime was verified

uuidDuplicado · boolean

Whether UUID is duplicated

advertencias · string[]

Array of warning messages

errores · string[]

Array of error messages

valido · boolean

Overall validation status

estadoPago · object

Payment status details

Show EstadoPago

estado · enum

Payment state: PAGADO, PAGO_PARCIAL, or NO_PAGADO

totalFactura · number

Total invoice amount

totalPagado · number

Total amount paid

saldoPendiente · number

Pending balance

porcentajePagado · number

Percentage paid (0-100)

completamentePagado · boolean

Whether fully paid

ultimoSaldoInsoluto · number

Last outstanding balance from payment complement

tieneComplementos · boolean

Whether has payment complements

tienePagosManuales · boolean

Whether has manual payments

profile · object

Profile information

Show Profile

id · string

Profile ID

nombre · string

Profile name

rfc · string

Profile RFC

created_at · string

Creation timestamp in ISO format

updated_at · string

Last update timestamp in ISO format

pagination · object

Pagination information

Show Pagination

total · number

Total number of invoices

page · number

Current page number

limit · number

Number of items per page

totalPages · number

Total number of pages

Example Request

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

{
  "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

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing access token"
}

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid query parameters"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}