Skip to main content

​
GET /api/invoices/:id

Retrieves detailed information for a specific invoice, including payment status and validation details.

​
Authentication

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

​
Path Parameters

​
id
string
required
UUID of the invoice to retrieve

​
Response

​
data
object
Complete invoice object 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” (paid in one payment), “PPD” (paid 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
Fiscal regime code of the issuer (3-digit SAT code)
​
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 (for PPD invoices)
​
fechaPago
string
Payment date
​
formaPago
string
Payment method code (SAT catalog)
​
monedaPago
string
Payment currency (e.g., “MXN”)
​
monto
number
Payment amount
​
numOperacion
string
Operation/transaction number (optional)
​
numParcialidad
number
Installment number
​
complementoUUID
string
UUID of the payment complement (if from complement)
​
origen
string
Payment origin: “COMPLEMENTO” or “MANUAL”
​
complemento_pago
object
Payment complement data (if applicable)
​
pagos
array
Array of payment complement items
​
validacion
object
Validation results
​
rfcVerificado
boolean
Whether RFC was verified
​
regimenFiscalVerificado
boolean
Whether fiscal regime was verified
​
uuidDuplicado
boolean
Whether UUID is duplicated
​
advertencias
array
Array of validation warnings (strings)
​
errores
array
Array of validation errors (strings)
​
valido
boolean
Whether the invoice passed all validations
​
profile
object
Associated profile information
​
id
string
Profile UUID
​
nombre
string
Profile name
​
rfc
string
Profile RFC
​
estadoPago
object
Detailed payment status information
​
estado
string
Payment state: “PAGADO” (fully paid), “PAGO_PARCIAL” (partially paid), or “NO_PAGADO” (not paid)
​
totalFactura
number
Total invoice amount
​
totalPagado
number
Total amount paid to date
​
saldoPendiente
number
Outstanding balance
​
porcentajePagado
number
Percentage paid (0-100)
​
completamentePagado
boolean
Whether the invoice is fully paid
​
ultimoSaldoInsoluto
number
Last outstanding balance from payment complement (if applicable)
​
tieneComplementos
boolean
Whether payment complements exist
​
tienePagosManuales
boolean
Whether manual payments have been recorded
​
fechasComplementos
array
Array of payment dates from complements (for annotations)
​
created_at
string
Creation timestamp (ISO 8601 format)
​
updated_at
string
Last update timestamp (ISO 8601 format)

​
Error Codes

​
401
error
Unauthorized - User not authenticated
​
404
error
Not Found - Invoice not found or doesn’t belong to authenticated user
​
500
error
Internal Server Error - Error retrieving invoice

​
Example Request

curl -X GET https://api.tresacontafy.com/api/invoices/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response (PUE - Fully Paid)

{
  "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,
      "ultimoSaldoInsoluto": null,
      "tieneComplementos": false,
      "tienePagosManuales": false,
      "fechasComplementos": []
    },
    "created_at": "2024-03-15T10:35:00.000Z",
    "updated_at": "2024-03-15T10:35:00.000Z"
  }
}

​
Example Response (PPD - Partially Paid)

{
  "data": {
    "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 - Fase 1",
    "pagos": [
      {
        "fechaPago": "2024-03-20T00:00:00.000Z",
        "formaPago": "03",
        "monedaPago": "MXN",
        "monto": 2900.00,
        "numOperacion": "TRF-20240320-001",
        "numParcialidad": 1,
        "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,
      "ultimoSaldoInsoluto": 2900.00,
      "tieneComplementos": true,
      "tienePagosManuales": false,
      "fechasComplementos": ["2024-03-20T00:00:00.000Z"]
    },
    "created_at": "2024-03-10T14:25:00.000Z",
    "updated_at": "2024-03-20T09:15:00.000Z"
  }
}

​
Example Response (Not Found)

{
  "error": "Factura no encontrada"
}

​
Notes

  • The endpoint verifies that the invoice belongs to one of the authenticated user’s profiles
  • Payment status is calculated dynamically based on payment complements and manual payments
  • For PPD invoices, the pagos array contains all partial payments recorded via payment complements or manual entries
  • The estadoPago object provides comprehensive payment tracking information for invoices paid in installments

Build docs developers (and LLMs) love

Get started for freeTalk to us