Skip to main content

​
GET /api/invoices

Retrieves a paginated list of invoices for the authenticated user, with support for filtering by profile, date, type, fiscal regime, and text search.

​
Authentication

Requires Bearer token authentication. The token must be included in the Authorization header.

​
Query Parameters

​
profileId
string
Filter invoices by profile UUID. If not provided, returns invoices from all user’s profiles.
​
mes
number
Filter by month (1-12)
​
año
number
Filter by year
​
tipo
string
Filter by payment type. Valid values:
  • PUE - Paid in one payment
  • PPD - Paid in installments
  • COMPLEMENTO_PAGO - Payment complement
​
regimen_fiscal
string
Filter by fiscal regime of the issuer (3-digit SAT code, e.g., “612”)
​
search
string
Search text across multiple fields:
  • RFC emisor
  • Nombre emisor
  • RFC receptor
  • Nombre receptor
  • Concepto (description)
Search is case-insensitive and supports partial matches.
​
page
number
default:"1"
Page number for pagination (minimum: 1)
​
limit
number
default:"50"
Number of items per page (minimum: 1, maximum: 100)

​
Response

​
data
array
Array of invoice objects with payment status
​
id
string
UUID of the invoice
​
profile_id
string
UUID of the associated profile
​
uuid
string
Fiscal UUID from the CFDI
​
fecha
string
Invoice date (ISO 8601 format)
​
mes
number
Month (1-12)
​
año
number
Year
​
total
number
Total amount including taxes
​
subtotal
number
Subtotal before taxes
​
iva
number
IVA amount
​
iva_amount
number
Transferred IVA amount
​
retencion_iva_amount
number
IVA withholding amount
​
retencion_isr_amount
number
ISR withholding amount
​
tipo
string
Payment type: “PUE”, “PPD”, or “COMPLEMENTO_PAGO”
​
rfc_emisor
string
RFC of the issuer
​
nombre_emisor
string
Name of the issuer
​
regimen_fiscal_emisor
string
Fiscal regime code of the issuer
​
rfc_receptor
string
RFC of the recipient
​
nombre_receptor
string
Name of the recipient
​
regimen_fiscal_receptor
string
Fiscal regime code of the recipient
​
concepto
string
Description or concept of the invoice
​
pagos
array
Array of partial payments
​
complemento_pago
object
Payment complement data
​
validacion
object
Validation results
​
profile
object
Associated profile information
​
id
string
Profile UUID
​
nombre
string
Profile name
​
rfc
string
Profile RFC
​
estadoPago
object
Payment status information
​
estado
string
“PAGADO”, “PAGO_PARCIAL”, or “NO_PAGADO”
​
totalFactura
number
Total invoice amount
​
totalPagado
number
Total amount paid
​
saldoPendiente
number
Outstanding balance
​
porcentajePagado
number
Percentage paid (0-100)
​
completamentePagado
boolean
Whether fully paid
​
tieneComplementos
boolean
Whether payment complements exist
​
tienePagosManuales
boolean
Whether manual payments exist
​
created_at
string
Creation timestamp
​
updated_at
string
Last update timestamp
​
pagination
object
Pagination metadata
​
total
number
Total number of invoices matching the filters
​
page
number
Current page number
​
limit
number
Number of items per page
​
totalPages
number
Total number of pages

​
Error Codes

​
401
error
Unauthorized - User not authenticated
​
500
error
Internal Server Error - Error retrieving invoices

​
Example Request

curl -X GET "https://api.tresacontafy.com/api/invoices?profileId=550e8400-e29b-41d4-a716-446655440000&mes=3&año=2024&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X GET "https://api.tresacontafy.com/api/invoices?search=consultoría&tipo=PUE" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "profile_id": "550e8400-e29b-41d4-a716-446655440000",
      "uuid": "12345678-1234-1234-1234-123456789012",
      "fecha": "2024-03-15T10:30:00.000Z",
      "mes": 3,
      "año": 2024,
      "total": 11600.00,
      "subtotal": 10000.00,
      "iva": 1600.00,
      "iva_amount": 1600.00,
      "retencion_iva_amount": 0.00,
      "retencion_isr_amount": 0.00,
      "tipo": "PUE",
      "rfc_emisor": "ABC123456789",
      "nombre_emisor": "Empresa Ejemplo SA de CV",
      "regimen_fiscal_emisor": "612",
      "rfc_receptor": "XYZ987654321",
      "nombre_receptor": "Cliente Ejemplo",
      "regimen_fiscal_receptor": "605",
      "concepto": "Servicios de consultoría",
      "pagos": [],
      "complemento_pago": null,
      "validacion": {
        "rfcVerificado": true,
        "regimenFiscalVerificado": true,
        "uuidDuplicado": false,
        "advertencias": [],
        "errores": [],
        "valido": true
      },
      "profile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "nombre": "Mi Perfil Fiscal",
        "rfc": "ABC123456789"
      },
      "estadoPago": {
        "estado": "PAGADO",
        "totalFactura": 11600.00,
        "totalPagado": 11600.00,
        "saldoPendiente": 0.00,
        "porcentajePagado": 100,
        "completamentePagado": true,
        "tieneComplementos": false,
        "tienePagosManuales": false
      },
      "created_at": "2024-03-15T10:35:00.000Z",
      "updated_at": "2024-03-15T10:35:00.000Z"
    },
    {
      "id": "8d1e7780-8536-51ef-b825-f18gd2g01bf8",
      "profile_id": "550e8400-e29b-41d4-a716-446655440000",
      "uuid": "87654321-4321-4321-4321-210987654321",
      "fecha": "2024-03-10T14:20:00.000Z",
      "mes": 3,
      "año": 2024,
      "total": 5800.00,
      "subtotal": 5000.00,
      "iva": 800.00,
      "iva_amount": 800.00,
      "retencion_iva_amount": 0.00,
      "retencion_isr_amount": 0.00,
      "tipo": "PPD",
      "rfc_emisor": "ABC123456789",
      "nombre_emisor": "Empresa Ejemplo SA de CV",
      "regimen_fiscal_emisor": "612",
      "rfc_receptor": "DEF456789012",
      "nombre_receptor": "Otro Cliente",
      "regimen_fiscal_receptor": "601",
      "concepto": "Desarrollo de software",
      "pagos": [
        {
          "fechaPago": "2024-03-20T00:00:00.000Z",
          "formaPago": "03",
          "monedaPago": "MXN",
          "monto": 2900.00,
          "complementoUUID": "11111111-1111-1111-1111-111111111111",
          "origen": "COMPLEMENTO"
        }
      ],
      "complemento_pago": null,
      "validacion": {
        "rfcVerificado": true,
        "regimenFiscalVerificado": true,
        "uuidDuplicado": false,
        "advertencias": [],
        "errores": [],
        "valido": true
      },
      "profile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "nombre": "Mi Perfil Fiscal",
        "rfc": "ABC123456789"
      },
      "estadoPago": {
        "estado": "PAGO_PARCIAL",
        "totalFactura": 5800.00,
        "totalPagado": 2900.00,
        "saldoPendiente": 2900.00,
        "porcentajePagado": 50,
        "completamentePagado": false,
        "tieneComplementos": true,
        "tienePagosManuales": false
      },
      "created_at": "2024-03-10T14:25:00.000Z",
      "updated_at": "2024-03-20T09:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

​
Notes

  • Invoices are sorted by date in descending order (newest first)
  • The payment status (estadoPago) is calculated dynamically for each invoice based on payment complements and manual payments
  • Search is performed using case-insensitive pattern matching across multiple fields
  • Only invoices belonging to the authenticated user’s profiles are returned
  • The limit parameter is capped at 100 to prevent excessive data transfer

Build docs developers (and LLMs) love

Get started for freeTalk to us