Upload Invoice

Upload a CFDI XML invoice file

POST /api/invoices/upload

Upload Invoice

cURL

curl --request POST \
  --url https://api.example.com/api/invoices/upload \
  --header 'Content-Type: application/json' \
  --data '
{
  "profileId": "<string>"
}
'

200

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

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

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

retencion_iva_amount · number

IVA withholding amount

retencion_isr_amount · number

ISR withholding amount

tipo · enum

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

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

complemento_pago · object

Payment complement information (for COMPLEMENTO_PAGO type)

validacion · object

Validation results for the uploaded invoice

created_at · string

Creation timestamp in ISO format

updated_at · string

Last update timestamp in ISO format

validacion · object

Validation state of the uploaded invoice

Show ValidationState

rfcVerificado · boolean

Whether RFC was verified against profile

regimenFiscalVerificado · boolean

Whether tax regime was verified

uuidDuplicado · boolean

Whether this UUID already exists in the system

advertencias · string[]

Array of warning messages that don’t prevent upload

errores · string[]

Array of error messages (empty if valid)

valido · boolean

Overall validation status

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