Endpoints en desuso

Hemos recibido retroalimentación de nuestros clientes sobre la necesidad de unificar los endpoints de creación de facturas. Desde 2019 hasta finales de 2025, Fiscalapi desarrolló y versionó endpoints específicos para cada tipo de factura, por ejemplo: un endpoint específico para facturas de ingreso, otro para facturas de crédito, otro para facturas de nómina, etc. Sin embargo, a lo largo de los años hemos recibido retroalimentación de nuestros clientes sobre el aumento del mantenimiento en sus integraciones, lo que nos ha llevado a unificar los endpoints de creación de facturas en uno solo: /api/v4/invoices. Como parte de la actualización de la API de Fiscalapi, estos endpoints han sido marcados como "en desuso" y serán descontinuados oficialmente el 1 de enero de 2026.

Endpoints en desuso

POST /api/v4/invoices/income
POST /api/v4/invoices/credit-note
POST /api/v4/invoices/payment
POST /api/v4/invoices/payroll
POST /api/v4/invoices/local-taxes

Nuevo endpoint

POST /api/v4/invoices

Este nuevo endpoint maneja todos los tipos de factura y/o complementos en un solo endpoint y será el único punto de entrada para la creación de facturas a partir del 1 de enero de 2026 sin importar el tipo de factura o complemento.

Compatibilidad con versiones anteriores

Compatibilidad total

Solo cambie el endpoint de la solicitud a /api/v4/invoices.

Facturas de ingreso: /api/v4/invoices/income → /api/v4/invoices
Notas de crédito: /api/v4/invoices/credit-note → /api/v4/invoices

Compatibilidad parcial

Requiere migración de payload request.

Complemento de pago: /api/v4/invoices/payment → /api/v4/invoices
Complemento de nómina: /api/v4/invoices/payroll → /api/v4/invoices
Complemento de impuestos locales: /api/v4/invoices/local-taxes → /api/v4/invoices

Diferencias en la estructura

Facturas de ingreso y notas de crédito: El payload request y response permanecen idénticos.

Complementos: El payload request requiere el objeto complement como contenedor. El payload response permanece igual.

Nivel de anidamiento por complemento

Complemento	Endpoint anterior	Nuevo endpoint
Nómina	`invoice.payroll`	`invoice.complement.payroll`
Pago	`invoice.payment`	`invoice.complement.payment`
Impuestos locales	`invoice.localTaxes`	`invoice.complement.localTaxes`

Los nuevos complementos se anidarán dentro del objeto complement.

Ejemplo de migración: Complemento de nómina

Estructura actual (endpoint en desuso /api/v4/invoices/payroll):

El objeto payroll se mueve de invoice.payroll a invoice.complement.payroll.

Payload request actual para complemento de nómina (endpoint en desuso)

   curl --location 'https://test.fiscalapi.com/api/v4/invoices/payroll' \
   --header 'X-TENANT-KEY: <my-tenant>' \
   --header 'X-TIME-ZONE: America/Mexico_City' \
   --header 'Content-Type: application/json' \
   --header 'X-API-KEY: <my-api-key>' \
   --data '{
     "versionCode": "4.0",
     "series": "NR",
     "date": "2025-04-17T08:56:40",
     "currencyCode": "MXN",
     "typeCode": "N",
     "expeditionZipCode": "20000",
     "issuer": {
       "id": "id_emisor",
     },
     "recipient": {
       "id": "id_receptor",
     },
     "payroll": {
         "version": "1.2",
         "payrollTypeCode": "O",
         "paymentDate": "2025-08-31",
         "initialPaymentDate": "2025-08-01",
         "finalPaymentDate": "2025-08-31",
         "daysPaid": 30,
         "earnings": {
           "earnings": [
             {
               "earningTypeCode": "001",
               "code": "1003",
               "concept": "Sueldo Nominal",
               "taxedAmount": 95030.00,
               "exemptAmount": 0.00
             },
             {
               "earningTypeCode": "005",
               "code": "5913",
               "concept": "Fondo de Ahorro Aportación Patrón",
               "taxedAmount": 0.00,
               "exemptAmount": 4412.46
             }
         
           ]
         },
         "deductions": [
           {
             "deductionTypeCode": "002",
             "code": "5003",
             "concept": "ISR Causado",
             "amount": 27645.52
           },
           {
             "deductionTypeCode": "004",
             "code": "5910",
             "concept": "Fondo de ahorro Empleado Inversión",
             "amount": 4412.46
           }
           
         ]
       }
   }'

Estructura nueva (endpoint unificado /api/v4/invoices):

El objeto payroll ahora está dentro del objeto complement.

Payload request nuevo para complemento de nómina (endpoint unificado)

   curl --location 'https://test.fiscalapi.com/api/v4/invoices' \
   --header 'X-TENANT-KEY: <my-tenant>' \
   --header 'X-TIME-ZONE: America/Mexico_City' \
   --header 'Content-Type: application/json' \
   --header 'X-API-KEY: <my-api-key>' \
   --data '{
     "versionCode": "4.0",
     "series": "NR",
     "date": "2025-04-17T08:56:40",
     "currencyCode": "MXN",
     "typeCode": "N",
     "expeditionZipCode": "20000",
     "issuer": {
       "id": "id_emisor",
     },
     "recipient": {
       "id": "id_receptor",
     },
     "complement": {
       "payroll": {
         "version": "1.2",
         "payrollTypeCode": "O",
         "paymentDate": "2025-08-31",
         "initialPaymentDate": "2025-08-01",
         "finalPaymentDate": "2025-08-31",
         "daysPaid": 30,
         "earnings": {
           "earnings": [
             {
               "earningTypeCode": "001",
               "code": "1003",
               "concept": "Sueldo Nominal",
               "taxedAmount": 95030.00,
               "exemptAmount": 0.00
             },
             {
               "earningTypeCode": "005",
               "code": "5913",
               "concept": "Fondo de Ahorro Aportación Patrón",
               "taxedAmount": 0.00,
               "exemptAmount": 4412.46
             }
         
           ]
         },
         "deductions": [
           {
             "deductionTypeCode": "002",
             "code": "5003",
             "concept": "ISR Causado",
             "amount": 27645.52
           },
           {
             "deductionTypeCode": "004",
             "code": "5910",
             "concept": "Fondo de ahorro Empleado Inversión",
             "amount": 4412.46
           }
           
         ]
       }
     }
   }'

Plan de migración

Pasos de migración

Identificar endpoints en uso: Verificar si utiliza endpoints "en desuso"
Facturas de ingreso y notas de crédito:
- Cambiar URL a /api/v4/invoices
- Payload request y response permanecen idénticos
Complementos:
- Cambiar URL a /api/v4/invoices
- El payload request requiere el objeto complement como contenedor de cualquier complemento, el payload response no cambia.
Actualizar SDKs: Si utiliza los SDKs oficiales de Fiscalapi, actualice a la última versión disponible

Recursos adicionales

Documentación actualizada: factura por valores , factura por referencias y Postman Api Reference.

Soporte técnico

Email: soporte@fiscalapi.com
Oficina: 33 598 003 84
WhatsApp: 33 2232 9212
Contacto: fiscalapi.com/contact-us