Skip to main content

​
Overview

The Tresa Contafy API provides powerful endpoints to upload, parse, and validate Mexican CFDI (Comprobante Fiscal Digital por Internet) invoices. The system automatically:
  • Parses XML CFDI files (versions 3.3 and 4.0)
  • Validates RFC, fiscal regime, and UUID duplicates
  • Classifies as income (factura) or expense (gasto)
  • Handles payment complements (Complemento de Pago)
  • Performs automatic payment matching for PPD invoices

​
Authentication

All invoice endpoints require authentication. Include your JWT token in the Authorization header: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Uploading Invoices

1

Prepare your CFDI XML file

Ensure you have a valid CFDI XML file (version 3.3 or 4.0). The file should have a .xml extension.
2

Select a profile

You need a profile ID to associate the invoice with. If you don’t have one, create a profile first.
3

Upload the invoice

Send a POST request to /api/invoices/upload with the XML file and profile ID.

​
Upload Endpoint

curl -X POST https://api.contafy.com/api/invoices/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "[email protected]" \
  -F "profileId=550e8400-e29b-41d4-a716-446655440000"

​
Request Parameters

​
xml
file
required
The CFDI XML file to upload (max 10MB)
​
profileId
string
required
UUID of the profile to associate the invoice with

​
Response

{
  "message": "Factura guardada exitosamente",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "uuid": "AAAABBBB-1111-2222-3333-444444444444",
    "fecha": "2024-03-15T10:30:00.000Z",
    "total": 11600.00,
    "subtotal": 10000.00,
    "iva": 1600.00,
    "tipo": "PUE",
    "rfc_emisor": "XAXX010101000",
    "nombre_emisor": "Mi Empresa SA de CV",
    "rfc_receptor": "XEXX010101000",
    "nombre_receptor": "Cliente SA de CV"
  },
  "estadoPago": {
    "estado": "PAGADO",
    "montoPagado": 11600.00,
    "montoRestante": 0
  },
  "validacion": {
    "valido": true,
    "rfcVerificado": true,
    "regimenFiscalVerificado": true,
    "uuidDuplicado": false,
    "advertencias": [],
    "errores": []
  },
  "tipo": "factura"
}

​
Testing with Parse Endpoint

Before uploading, you can test XML parsing without saving to the database: 
curl -X POST https://api.contafy.com/api/invoices/parse \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "[email protected]" \
  -F "profileId=550e8400-e29b-41d4-a716-446655440000"
The /parse endpoint validates and extracts data but does not save the invoice to the database. Use it for testing and validation.

​
Automatic Classification

The API automatically classifies CFDI documents based on the profile’s RFC:
  • Income Invoice (Factura): Profile RFC matches the rfcEmisor (issuer)
  • Expense (Gasto): Profile RFC matches the rfcReceptor (receiver)
  • Payment Complement: Detected by tipo: "COMPLEMENTO_PAGO"

​
Payment Types

​
PUE (Pago en Una Exhibición)

Single payment invoices are automatically marked as paid: 
{
  "tipo": "PUE",
  "estadoPago": {
    "estado": "PAGADO",
    "montoPagado": 11600.00,
    "montoRestante": 0
  }
}

​
PPD (Pago en Parcialidades o Diferido)

Installment or deferred payment invoices require payment complements: 
{
  "tipo": "PPD",
  "estadoPago": {
    "estado": "PENDIENTE",
    "montoPagado": 0,
    "montoRestante": 11600.00
  }
}

​
Payment Complements (Complemento de Pago)

Upload payment complements the same way as invoices. The system automatically:
  1. Validates the complement against existing invoices
  2. Matches it to related invoices by UUID
  3. Updates payment status of matched invoices
{
  "message": "Complemento de pago procesado exitosamente",
  "matching": {
    "facturasEncontradas": 2,
    "matches": [
      {
        "facturaId": "123e4567-e89b-12d3-a456-426614174000",
        "uuid": "AAAABBBB-1111-2222-3333-444444444444",
        "montoPagado": 5800.00,
        "montoFactura": 11600.00
      }
    ]
  }
}

​
Validation Errors

The API performs comprehensive fiscal validations: 
{
  "error": "El CFDI no pasó las validaciones fiscales",
  "validacion": {
    "valido": false,
    "rfcVerificado": false,
    "errores": [
      "El RFC del emisor no coincide con el perfil"
    ],
    "advertencias": [
      "El régimen fiscal 601 no está registrado en el perfil"
    ]
  }
}

​
Common Validation Errors

UUID Duplicado: The invoice UUID already exists in the database (HTTP 409)
RFC No Coincide: The RFC in the CFDI doesn’t match the profile as issuer or receiver
Régimen Fiscal No Registrado: The fiscal regime is not configured in the profile (warning only)

​
Rate Limits

Invoice upload endpoints have specific rate limits:
  • 300 requests per 5 minutes per user
  • Applies to both /parse and /upload endpoints
  • Based on user ID (not IP address)
{
  "error": "Demasiadas solicitudes para procesar XML. Intenta nuevamente en unos minutos."
}

​
Retrieving Invoices

​
List All Invoices

curl -X GET "https://api.contafy.com/api/invoices?profileId=550e8400-e29b-41d4-a716-446655440000&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Query Parameters

​
profileId
string
Filter by profile UUID
​
mes
integer
Filter by month (1-12)
​
año
integer
Filter by year
​
tipo
string
Filter by type: PUE, PPD, or COMPLEMENTO_PAGO
​
regimen_fiscal
string
Filter by 3-digit SAT fiscal regime code
​
search
string
Search by RFC, name, or concept
​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"50"
Results per page (max 100)

​
Get Single Invoice

curl -X GET https://api.contafy.com/api/invoices/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Deleting Invoices

curl -X DELETE https://api.contafy.com/api/invoices/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Deleting an invoice is permanent and cannot be undone. Payment complements linked to this invoice will remain in the database.

​
Best Practices

  1. Always validate first: Use the /parse endpoint to test XML files before uploading
  2. Handle duplicates gracefully: Check for HTTP 409 errors and inform users
  3. Monitor rate limits: Implement exponential backoff for bulk uploads
  4. Store profileId: Cache the profile ID to avoid extra lookups
  5. Process payment complements: Upload payment complements after their related invoices

​
Plan Limits

Invoice uploads are subject to your subscription plan:
  • FREE: 1 profile, unlimited invoices
  • BASIC: 5 profiles, unlimited invoices
  • PRO: 20 profiles, unlimited invoices
  • ENTERPRISE: Unlimited profiles and invoices
While invoices per month are unlimited on all plans, profile limits apply. See Subscription Management for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us