Skip to main content
POST
/
api
/
invoices
/
upload
Upload Invoice
curl --request POST \
  --url https://api.example.com/api/invoices/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "profileId": "<string>"
}
'
{
  "message": "<string>",
  "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": [
      {}
    ],
    "complemento_pago": {},
    "validacion": {},
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "validacion": {
    "rfcVerificado": true,
    "regimenFiscalVerificado": true,
    "uuidDuplicado": true,
    "advertencias": [
      "<string>"
    ],
    "errores": [
      "<string>"
    ],
    "valido": true
  },
  "tipo": {}
}

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.

​
Authentication

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

​
Request Body

This endpoint expects a multipart/form-data request with the following fields:
​
xml
file
required
XML file containing the CFDI invoice. The file must be a valid Mexican CFDI XML.
​
profileId
string
required
Profile ID to associate the invoice with. The system automatically determines if the invoice is an income (factura) or expense (gasto) based on the RFC in the XML.

​
Response

​
message
string
Success message
​
data
Invoice
The created invoice object
​
validacion
object
Validation state of the uploaded invoice
​
tipo
enum
Classification of the invoice: factura (income) or gasto (expense)

​
Example Request

curl -X POST "https://api.contafy.com/api/invoices/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "xml=@invoice.xml" \
  -F "profileId=prof_123"

const formData = new FormData();
formData.append('xml', file);
formData.append('profileId', 'prof_123');

const response = await fetch('https://api.contafy.com/api/invoices/upload', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: formData
});

const data = await response.json();

​
Example Response

{
  "message": "Factura procesada exitosamente",
  "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
    },
    "created_at": "2026-03-15T10:35:00Z",
    "updated_at": "2026-03-15T10:35:00Z"
  },
  "validacion": {
    "rfcVerificado": true,
    "regimenFiscalVerificado": true,
    "uuidDuplicado": false,
    "advertencias": [],
    "errores": [],
    "valido": true
  },
  "tipo": "factura"
}

​
Error Responses

​
401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Invalid or missing access token"
}
​
400 Bad Request
{
  "error": "Bad Request",
  "message": "Invalid XML file or missing required fields"
}
​
409 Conflict
{
  "error": "Conflict",
  "message": "Invoice with this UUID already exists",
  "validacion": {
    "uuidDuplicado": true,
    "valido": false
  }
}
​
422 Unprocessable Entity
{
  "error": "Unprocessable Entity",
  "message": "Invalid CFDI XML format",
  "validacion": {
    "errores": ["Invalid XML structure"],
    "valido": false
  }
}
​
500 Internal Server Error
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}