Modes of operation

You can create invoices in two modes of operation: by reference (you send the IDs of people and products already saved in Fiscalapi) and by value (you send every issuer, recipient, and item value in the request). The recommended mode is by reference, because it's easier to integrate and Fiscalapi handles many technical details automatically.

By-reference mode

In by-reference mode, you create the invoice by sending only the IDs of its objects in the HTTP request, such as the issuer, the recipient, and the CFDI products (CFDI: Mexico's electronic invoice). Those objects must already exist in Fiscalapi: you create them through the API or manually in the dashboard.

Example: create an invoice by reference (IDs)

{
  "versionCode": "4.0",
  "series": "F",
  "date": "2024-11-12T18:53:57",
  "paymentFormCode": "01",
  "currencyCode": "MXN",
  "typeCode": "I",
  "expeditionZipCode": "01160",
  "paymentMethodCode": "PUE",
  "exchangeRate": 1,
  "issuer": {
    "id": "<id_del_emisor>"
  },
  "recipient": {
    "id": "<id_del_receptor>"
  },
  "items": [
    {
      "id": "<id_del_producto>",
      "quantity": 2.5
    }
  ]
}

By-value mode

In by-value mode, you create the invoice by sending every field of each object in the HTTP request, except the IDs. You don't need to create CFDI products, taxes, or people (person: any individual or legal entity registered in your tenant) in Fiscalapi beforehand.

Example: create an invoice by value

{
"versionCode": "4.0",
"series": "F",
"date": "2024-11-12T18:53:57",
"paymentFormCode": "01",
"paymentConditions": "Contado",
"currencyCode": "MXN",
"typeCode": "I",
"expeditionZipCode": "01160",
"paymentMethodCode": "PUE",
"exchangeRate": 1,
"exportCode": "01",
"issuer": {
"tin": "FUNK671228PH6",
"legalName": "KARLA FUENTE NOLASCO",
"taxRegimeCode": "621",
"taxCredentials": [
  {
    "base64File": "archivo_cer_base64...",
    "fileType": 0,
    "password": "12345678a"
  },
  {
    "base64File": "archivo_key_base64...",
    "fileType": 1,
    "password": "12345678a"
  }
]
},
"recipient": {
"tin": "EKU9003173C9",
"legalName": "ESCUELA KEMPER URGATE",
"zipCode": "42501",
"taxRegimeCode": "601",
"cfdiUseCode": "G01",
"email": "someone@somewhere.com"
},
"items": [
{
  "itemCode": "01010101",
  "quantity": 2.5,
  "unitOfMeasurementCode": "E48",
  "unitOfMeasurement": "Unidad de servicio",
  "description": "Computer model acme",
  "unitPrice": 1250.75,
  "taxObjectCode": "02",
  "itemSku": "7506022301699",
  "itemTaxes": [
    {
      "taxCode": "002",
      "taxTypeCode": "Tasa",
      "taxRate": 0.160000,
      "TaxFlagCode": "T"
    },
    {
      "taxCode": "002",
      "taxTypeCode": "Tasa",
      "taxRate": 0.106666,
      "TaxFlagCode": "R"
    }
  ]
}
]
}

Differences between the modes of operation

Both modes use the same endpoint, POST /api/v4/invoices, and produce the same result: an e-invoice that the SAT (Mexico's tax authority, Servicio de Administración Tributaria) recognizes as valid. The only difference is how you send the data to Fiscalapi.

Aspect	By reference	By value
Prior records	You first create your records (people, CFDI products), manually or through the API.	You don't need to create records in Fiscalapi.
Request size and complexity	Lower.	Higher.
Development and integration time	Shorter.	Longer.
Maintenance of your integration	Less.	More.
Errors during integration	Fewer.	More.

In by-reference mode, Fiscalapi manages the invoice details and your requests stay simple. In by-value mode, you have more flexibility, but you manage and validate all the information in every request.