# Retrieve invoices for a link

Retrieve invoice information from a specific fiscal link.

> 📘 Info
>
> You can ask for up to  year (365 days) of invoices per request. If you need invoices for more than one year, just make another request.

> 🚧 Warning
>
> This resource may return deprecated fields. Please check the response documentation for more information.


Endpoint: POST /api/invoices/
Version: 1.222.0
Security: basicAuth

## Header parameters:

  - `X-Belvo-Request-Mode` (string)
    Recommended header parameter to make your POST request asynchronous (thus preventing timeouts and improving your data flow).

When you make an asynchronous request, Belvo responds with a  payload, including the . Once we have retrieved the requested information, you will receive a webhook with the link and request IDs.
    Enum: "async"

## Query parameters:

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

## Request fields (application/json):

  - `link` (string, required)
    The  you want to retrieve information for.
    Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058"

  - `date_from` (string, required)
    The date from which you want to start getting data for, in  format.


⚠️ The value of  cannot be greater than .
    Example: "2020-08-05"

  - `date_to` (string, required)
    The date you want to stop getting data for, in  format.


⚠️ The value of  cannot be greater than today's date (in other words, no future dates).
    Example: "2020-10-05"

  - `type` (string,null, required)
    The direction of the invoice (from the perspective of the Link owner).
-  indicates a sent invoice.
-  indicates a received invoice.
    Enum: "OUTFLOW", "INFLOW", null

  - `attach_xml` (boolean)
    When set to , you will receive the XML invoice in the response.

  - `save_data` (boolean)
    Indicates whether or not to persist the data in Belvo. By default, this is set to  and we return a 201 Created response.

When set to , the data won't be persisted and we return a 200 OK response.
    Example: true

## Response 200 fields (application/json):

  - `id` (string)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `link` (string,null)
    The  the data belongs to.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `created_at` (string)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `invoice_identification` (string,null, required)
    The fiscal institution's unique ID for the invoice.
    Example: "A1A1A1A1-2B2B-3C33-D44D-555555E55EE"

  - `invoice_date` (string,null, required)
    The date of the invoice, in  format.
    Example: "2019-12-01"

  - `status` (string,null, required)
    The status of the invoice. Can be either  (valid) or 
(cancelled).
    Example: "Vigente"

  - `invoice_type` (string,null, required)
    The fiscal institution's classification of the invoice.

For Mexico's SAT, we return one of the following values:

  - 
  - 
  - 
  - 
  -
    Enum: "Egreso", "Ingreso", "Nómina", "Pago", "Traslado"

  - `type` (string,null, required)
    The direction of the invoice (from the perspective of the Link owner).
-  indicates a sent invoice.
-  indicates a received invoice.
    Enum: "OUTFLOW", "INFLOW", null

  - `tax_details` (object)
    General information about the taxes of the invoice.

  - `tax_details.total_tax_retained` (number)
    Total amount of retained taxes.
    Example: 194.27

  - `tax_details.total_tax_transferred` (number)
    Total amount of transferred taxes.
    Example: 150.4

  - `tax_details.retained_taxes` (array)
    List of retained taxes.

  - `tax_details.retained_taxes.tax` (string)
    The type of retained tax (for example, ISR, IVA or IEPS).
    Example: "ISR"

  - `tax_details.retained_taxes.tax_percentage` (number,null)
    The percentage of tax retained.

  - `tax_details.retained_taxes.pre_tax_amount` (number,null)
    The amount before tax.

  - `tax_details.retained_taxes.tax_amount` (number)
    The amount of retained tax.
    Example: 94

  - `tax_details.transferred_taxes` (array)
    List of transferred taxes.

  - `tax_details.transferred_taxes.tax` (string)
    The type of transferred tax (for example, ISR, IVA or IEPS).
    Example: "IVA"

  - `tax_details.transferred_taxes.tax_percentage` (number)
    The percentage of tax transferred.
    Example: 16

  - `tax_details.transferred_taxes.tax_amount` (number)
    The amount of transferred tax.
    Example: 150.4

  - `sender_id` (string,null, required)
    The fiscal ID of the invoice sender
    Example: "AAA111111AA11"

  - `sender_fiscal_regime` (string,null)
    The tax regime of the sender, as defined by the legal entity in the country.
    Example: "601"

  - `sender_name` (string,null, required)
    The name of the invoice sender.
    Example: "ACME CORP"

  - `sender_tax_fraud_status` (string,null)
    Indicates whether or not the sender is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.

SAT updates the tax fraud list every three months. 

For more information regarding the reason's a taxpayer can be put on the tax fraud list, please see Article 69 and Article 69-B of Mexico's Código Fiscal de la Federación.


Possible statuses are:

-  
The fiscal institution has identified irregularities and open an investigation regarding the taxpayer.

-  
The fiscal institution has investigated the taxpayer and declared them innocent.

-  
The fiscal institution has confirmed that the taxpayer is guilty.

-  
The fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.

-  
The receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).
    Example: "NO_TAX_FRAUD_STATUS"

  - `receiver_id` (string,null, required)
    The fiscal ID of the invoice receiver.
    Example: "BBB222222BB22"

  - `receiver_postal_code` (string)
    The postal code of the receiver.
    Example: "11560"

  - `receiver_fiscal_regime` (string,null)
    The tax regime of the receiver, as defined by the legal entity in the country.
    Example: "601"

  - `receiver_name` (string,null, required)
    The name of the invoice receiver.
    Example: "BELVO CORP"

  - `receiver_tax_fraud_status` (string,null)
    Indicates whether or not the receiver is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.

SAT updates the tax fraud list every three months. 

For more information regarding the reason's a taxpayer can be put on the tax fraud list, please see Article 69 and Article 69-B of Mexico's Código Fiscal de la Federación.


Possible statuses are:

-  
The fiscal institution has identified irregularities and open an investigation regarding the taxpayer.

-  
The fiscal institution has investigated the taxpayer and declared them innocent.

-  
The fiscal institution has confirmed that the taxpayer is guilty.

-  
The fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.

-  
The receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).
    Example: "NO_TAX_FRAUD_STATUS"

  - `cancelation_status` (string,null, required)
    If the invoice is cancelled, this field indicates the status of the cancellation.

  - `cancelation_update_date` (string,null, required)
    The date of the invoice cancelation, in  format.
    Example: "2019-12-02"

  - `certification_date` (string,null, required)
    The date of the fiscal certification, in  format.
    Example: "2019-12-01"

  - `certification_authority` (string,null, required)
    The fiscal ID of the certification provider.
    Example: "CCC333333CC33"

  - `payment_type` (string,null, required)
    The payment type code used for this invoice, as defined by the country legal entity.

- 🇲🇽 Mexico SAT catalog reference article
    Example: "99"

  - `payment_method` (string,null)
    The payment method code used for this invoice, as defined by the legal entity of the country.

- 🇲🇽 Mexico SAT catalog reference article. For Mexico, we return , , or .
    Enum: "PUE", "PPD", null

  - `usage` (string,null)
    The invoice's usage code, as defined by the legal entity of the country. 

- 🇲🇽 Mexico SAT catalog reference article
    Example: "P01"

  - `version` (string,null)
    The CFDI version of the invoice.
    Example: "3.3"

  - `place_of_issue` (string,null)
    The postcode of where the invoice was issued.
    Example: "01165"

  - `invoice_details` (array, required)
    A list of descriptions for each item (purchased product or service provided) in the invoice.

  - `invoice_details.description` (string,null, required)
    The description of the invoice item (an invoice can have one or more items).
    Example: "December 2019 accounting fees"

  - `invoice_details.product_identification` (string,null, required)
    The identification code of the product or the service, as defined by the legal entity in the country.\n- \U0001F1F2\U0001F1FD Mexico.
    Example: "84101600"

  - `invoice_details.quantity` (number,null, required)
    The quantity of this invoice item.
    Example: 10

  - `invoice_details.unit_code` (string,null, required)
    The unit of measure, as defined by the legal entity in the country. \n- \U0001F1F2\U0001F1FD Mexico SAT catalog reference.
    Example: "E48"

  - `invoice_details.unit_description` (string,null, required)
    The description of the item, as defined by the legal entity in the country.\n- \U0001F1F2\U0001F1FD Mexico SAT catalog reference.
    Example: "Unidad de servicio"

  - `invoice_details.unit_amount` (number,null, required)
    The price of one a singular item.
    Example: 200

  - `invoice_details.tax_type` (string,null)
    The item's tax type.

  - `invoice_details.pre_tax_amount` (number,null, required)
    The total price for this item before tax is applied ( x ).
    Example: 400

  - `invoice_details.tax_percentage` (number,null, required)
    The tax percentage to apply.
    Example: 16

  - `invoice_details.tax_amount` (number,null, required)
    The amount of tax for this invoice item ( x ).
    Example: 64

  - `invoice_details.total_amount` (number,null, required)
    The total price for this invoice item ( + ).
    Example: 464

  - `invoice_details.retained_taxes` (array)
    The retained tax on the invoice item.

  - `invoice_details.retained_taxes.retained_tax_amount` (number,null, required)
    The amount of retained tax.
    Example: 209.79

  - `invoice_details.transferred_taxes` (array)
    The transferred taxes related to the invoice.

  - `invoice_details.transferred_taxes.transferred_tax_amount` (number,null, required)
    The amount of transferred tax.
    Example: 209.79

  - `currency` (string,null, required)
    The currency of the invoice. For example:
 
 - 🇧🇷 BRL (Brazilian Real)
 - 🇨🇴 COP (Colombian Peso)
 - 🇲🇽 MXN (Mexican Peso)
 - 🇺🇸 USD (United States Dollar)
    Example: "MXN"

  - `subtotal_amount` (number,null, required)
    The pretax amount of this invoice (sum of each item's ).
    Example: 400

  - `exchange_rate` (number,null, required)
    The exchange rate used in this invoice for the currency.
    Example: 0.052

  - `tax_amount` (number,null, required)
    The amount of tax for this invoice (sum of each item's ).
    Example: 64

  - `discount_amount` (number,null, required)
    The total amount discounted in this invoice.
    Example: 10

  - `total_amount` (number,null, required)
    The total amount of the invoice ( +  - )
    Example: 454

  - `related_invoices` (array)
    A list of related invoices.

  - `related_invoices.relationship_type` (string,null)
    The type of relationship between this invoice and the related invoice, as defined by the legal entity in the country. For more information, see our SAT catalog reference article.
    Example: "01"

  - `related_invoices.related_invoice_identification` (string,null)
    The SAT ID of the related invoice.
    Example: "INV-123456"

  - `payments` (array, required)
    A list detailing all the invoice payments.

  - `payments.date` (string,null, required)
    ISO-8601 timestamp when the payment was made.
    Example: "2020-03-17T12:00:00.000Z"

  - `payments.payment_type` (string,null, required)
    Payment type code used for this invoice, as defined by the country's legal entity.

- 🇲🇽 Mexico SAT catalog reference article
    Example: "03"

  - `payments.currency` (string,null, required)
    The currency of the payment. For example:

- 🇧🇷 BRL (Brazilian Real)
- 🇨🇴 COP (Colombian Peso)
- 🇲🇽 MXN (Mexican Peso)

Please note that other currencies other than in the list above may be returned.
    Example: "BRL"

  - `payments.exchange_rate` (string,null, required)
    The  to MXN currency exchange rate when the payment was made.
    Example: "3.75"

  - `payments.amount` (number,null, required)
    The invoice amount, in the currency of the original invoice.
    Example: 8000.5

  - `payments.operation_number` (string,null, required)
    The fiscal institution's internal identifier for the operation.
    Example: "831840"

  - `payments.beneficiary_rfc` (string,null)
    The fiscal ID of the payment beneficiary.
    Example: "BNM840515VB1"

  - `payments.beneficiary_account_number` (string,null, required)
    The bank account number of the payment beneficiary.
    Example: "12343453245633"

  - `payments.payer_rfc` (string,null, required)
    The fiscal ID of the payment issuer.
    Example: "BKJM840515VB1"

  - `payments.payer_account_number` (string,null, required)
    The bank account number of the payment issuer.
    Example: "13343663245699"

  - `payments.payer_bank_name` (string,null, required)
    The banking institution that was used by the payment issuer.
    Example: "CITI BANAMEX"

  - `payments.related_documents` (array, required)
    A list of all the related deferred invoices affected by the payment.

  - `payments.related_documents.invoice_identification` (string,null, required)
    The fiscal institution's unique ID for the related deferred invoice.
    Example: "7EE015F3-6311-11EA-B02A-00155D014007"

  - `payments.related_documents.currency` (string,null, required)
    The currency of the related invoice. For example:
    
- 🇧🇷 BRL (Brazilian Real)
- 🇨🇴 COP (Colombian Peso)
- 🇲🇽 MXN (Mexican Peso)
  
  Please note that other currencies other than in the list above may be returned.
    Example: "MXN"

  - `payments.related_documents.payment_method` (string,null, required)
    The payment method of the related invoice.
    Example: "PPD"

  - `payments.related_documents.partiality_number` (integer)
    The payment installment number.
    Example: 1

  - `payments.related_documents.previous_balance` (number,null, required)
    The invoice amount before the payment.
    Example: 18877.84

  - `payments.related_documents.amount_paid` (number,null, required)
    The amount paid in this installment.
    Example: 8000

  - `payments.related_documents.outstanding_balance` (number,null, required)
    The amount remaining to be paid.
    Example: 10877.84

  - `payroll` (object,null, required)
    Details regarding the payroll payment. Only applicable for payroll invoices.

  - `payroll.days` (integer,null, required)
    The number of days covered by the payment.
    Example: 30

  - `payroll.type` (string,null, required)
    The payroll type, as defined by the legal entity of the country.

- 🇲🇽 Mexico SAT catalog reference article
    Example: "O"

  - `payroll.amount` (number, required)
    The total amount of the payroll payment.
    Example: 20400.1

  - `payroll.version` (string, required)
    The version of the payroll object.
    Example: "1.2"

  - `payroll.date_from` (string,null, required)
    The start date of the payment period, in  format.
    Example: "2018-07-01"

  - `payroll.date_to` (string,null, required)
    The end date of the payment period, in  format.
    Example: "2018-07-31"

  - `payroll.payment_date` (string, required)
    The payment date, in  format.
    Example: "2018-07-16"

  - `payroll.periodicity` (string,null)
    How often the payroll payment is made.

For Mexico's SAT, we return one of the following values:

  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  -
    Enum: "DAILY", "WEEKLY", "TENTH_DAY", "FOURTEENTH_DAY", "FIFTEENTH_DAY", "MONTHLY", "BIMONTHLY", "PER_TASK", "COMMISSION", "ONE_OFF", "OTHER_PERIODICITY", "null"

  - `payroll.earnings_breakdown` (array,null)
    A breakdown of the earnings for the payroll payment.

  - `payroll.earnings_breakdown.type` (string,null)
    The type of income. For a full list of possible values, please see the payroll earnings breakdown type table.
    Example: "CHRISTMAS_BONUS"

  - `payroll.earnings_breakdown.taxable_amount` (number)
    The amount of the income that is taxable.
    Example: 1505

  - `payroll.earnings_breakdown.vat_free_amount` (number)
    The amount of the income that is not subject to VAT.

  - `payroll.tax_deductions` (array,null)
    A breakdown of the tax deductions on the payroll payment.

  - `payroll.tax_deductions.type` (string,null)
    The type of tax deduction. For a full list of possible values, please see the payroll tax deductions type table.
    Example: "UNION_FEES"

  - `payroll.tax_deductions.amount` (number)
    The amount of the tax deduction.
    Example: 1505

  - `payroll.other_payments` (array,null)
    A breakdown of other payments for the payroll.

  - `payroll.other_payments.type` (string,null)
    The type of other payment. For a full list of possible values, please see the payroll other payments type table.
    Example: "EMPLOYMENT_SUBSIDY"

  - `payroll.other_payments.amount` (number)
    The amount of the other payment.
    Example: 1505

  - `folio` (string,null)
    The internal control number that the taxpayer assigns to the invoice.
    Example: "26"

  - `export_type` (string,null)
    The export type of the invoice, as defined by the legal entity in the country. For more information, see our SAT catalog reference article.
    Example: "01"

  - `xml` (string,null)
    XML of the invoice document.

  - `warnings` (object,null)
    Object containing information about any warnings related to this invoice.

  - `warnings.code` (string,null, required)
    The warning code. Can be one of:

  - 
  - 
  -
    Example: "sat_xml_limit_reached"

  - `warnings.message` (string,null, required)
    The description of the warning.

The message will depend on the warning code:


The daily limit for XML downloads set by SAT was reached so this invoice might be missing data. Please check https://tinyurl.com/yydzhy5d for more information on this error.

 
Downloading invoices details is not available. The SAT portal raised a 503 error.
    Example: "The daily limit for XML downloads set by SAT was reached so this invoice\nmight be missing data. Please check https://tinyurl.com/yydzhy5d for more\ninformation on this error.\n"

  - `payment_type_description` (string,null, required)
    

  - `payment_method_description` (string,null)
    

  - `sender_blacklist_status` (string,null)
    Please use  instead.

  - `receiver_blacklist_status` (string,null)
    Please use  instead.

## Response 201 fields (application/json):

  - `id` (string)
    Belvo's unique identifier for the current item.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `link` (string,null)
    The  the data belongs to.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2022-02-09T08:45:50.406032Z"

  - `created_at` (string)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `invoice_identification` (string,null, required)
    The fiscal institution's unique ID for the invoice.
    Example: "A1A1A1A1-2B2B-3C33-D44D-555555E55EE"

  - `invoice_date` (string,null, required)
    The date of the invoice, in  format.
    Example: "2019-12-01"

  - `status` (string,null, required)
    The status of the invoice. Can be either  (valid) or 
(cancelled).
    Example: "Vigente"

  - `invoice_type` (string,null, required)
    The fiscal institution's classification of the invoice.

For Mexico's SAT, we return one of the following values:

  - 
  - 
  - 
  - 
  -
    Enum: "Egreso", "Ingreso", "Nómina", "Pago", "Traslado"

  - `type` (string,null, required)
    The direction of the invoice (from the perspective of the Link owner).
-  indicates a sent invoice.
-  indicates a received invoice.
    Enum: "OUTFLOW", "INFLOW", null

  - `tax_details` (object)
    General information about the taxes of the invoice.

  - `tax_details.total_tax_retained` (number)
    Total amount of retained taxes.
    Example: 194.27

  - `tax_details.total_tax_transferred` (number)
    Total amount of transferred taxes.
    Example: 150.4

  - `tax_details.retained_taxes` (array)
    List of retained taxes.

  - `tax_details.retained_taxes.tax` (string)
    The type of retained tax (for example, ISR, IVA or IEPS).
    Example: "ISR"

  - `tax_details.retained_taxes.tax_percentage` (number,null)
    The percentage of tax retained.

  - `tax_details.retained_taxes.pre_tax_amount` (number,null)
    The amount before tax.

  - `tax_details.retained_taxes.tax_amount` (number)
    The amount of retained tax.
    Example: 94

  - `tax_details.transferred_taxes` (array)
    List of transferred taxes.

  - `tax_details.transferred_taxes.tax` (string)
    The type of transferred tax (for example, ISR, IVA or IEPS).
    Example: "IVA"

  - `tax_details.transferred_taxes.tax_percentage` (number)
    The percentage of tax transferred.
    Example: 16

  - `tax_details.transferred_taxes.tax_amount` (number)
    The amount of transferred tax.
    Example: 150.4

  - `sender_id` (string,null, required)
    The fiscal ID of the invoice sender
    Example: "AAA111111AA11"

  - `sender_fiscal_regime` (string,null)
    The tax regime of the sender, as defined by the legal entity in the country.
    Example: "601"

  - `sender_name` (string,null, required)
    The name of the invoice sender.
    Example: "ACME CORP"

  - `sender_tax_fraud_status` (string,null)
    Indicates whether or not the sender is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.

SAT updates the tax fraud list every three months. 

For more information regarding the reason's a taxpayer can be put on the tax fraud list, please see Article 69 and Article 69-B of Mexico's Código Fiscal de la Federación.


Possible statuses are:

-  
The fiscal institution has identified irregularities and open an investigation regarding the taxpayer.

-  
The fiscal institution has investigated the taxpayer and declared them innocent.

-  
The fiscal institution has confirmed that the taxpayer is guilty.

-  
The fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.

-  
The receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).
    Example: "NO_TAX_FRAUD_STATUS"

  - `receiver_id` (string,null, required)
    The fiscal ID of the invoice receiver.
    Example: "BBB222222BB22"

  - `receiver_postal_code` (string)
    The postal code of the receiver.
    Example: "11560"

  - `receiver_fiscal_regime` (string,null)
    The tax regime of the receiver, as defined by the legal entity in the country.
    Example: "601"

  - `receiver_name` (string,null, required)
    The name of the invoice receiver.
    Example: "BELVO CORP"

  - `receiver_tax_fraud_status` (string,null)
    Indicates whether or not the receiver is on SAT's tax fraud list for having submitted incorrect data, having outstanding payments, or having conducted business that is in violation of the fiscal institution's regulations.

SAT updates the tax fraud list every three months. 

For more information regarding the reason's a taxpayer can be put on the tax fraud list, please see Article 69 and Article 69-B of Mexico's Código Fiscal de la Federación.


Possible statuses are:

-  
The fiscal institution has identified irregularities and open an investigation regarding the taxpayer.

-  
The fiscal institution has investigated the taxpayer and declared them innocent.

-  
The fiscal institution has confirmed that the taxpayer is guilty.

-  
The fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.

-  
The receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).
    Example: "NO_TAX_FRAUD_STATUS"

  - `cancelation_status` (string,null, required)
    If the invoice is cancelled, this field indicates the status of the cancellation.

  - `cancelation_update_date` (string,null, required)
    The date of the invoice cancelation, in  format.
    Example: "2019-12-02"

  - `certification_date` (string,null, required)
    The date of the fiscal certification, in  format.
    Example: "2019-12-01"

  - `certification_authority` (string,null, required)
    The fiscal ID of the certification provider.
    Example: "CCC333333CC33"

  - `payment_type` (string,null, required)
    The payment type code used for this invoice, as defined by the country legal entity.

- 🇲🇽 Mexico SAT catalog reference article
    Example: "99"

  - `payment_method` (string,null)
    The payment method code used for this invoice, as defined by the legal entity of the country.

- 🇲🇽 Mexico SAT catalog reference article. For Mexico, we return , , or .
    Enum: "PUE", "PPD", null

  - `usage` (string,null)
    The invoice's usage code, as defined by the legal entity of the country. 

- 🇲🇽 Mexico SAT catalog reference article
    Example: "P01"

  - `version` (string,null)
    The CFDI version of the invoice.
    Example: "3.3"

  - `place_of_issue` (string,null)
    The postcode of where the invoice was issued.
    Example: "01165"

  - `invoice_details` (array, required)
    A list of descriptions for each item (purchased product or service provided) in the invoice.

  - `invoice_details.description` (string,null, required)
    The description of the invoice item (an invoice can have one or more items).
    Example: "December 2019 accounting fees"

  - `invoice_details.product_identification` (string,null, required)
    The identification code of the product or the service, as defined by the legal entity in the country.\n- \U0001F1F2\U0001F1FD Mexico.
    Example: "84101600"

  - `invoice_details.quantity` (number,null, required)
    The quantity of this invoice item.
    Example: 10

  - `invoice_details.unit_code` (string,null, required)
    The unit of measure, as defined by the legal entity in the country. \n- \U0001F1F2\U0001F1FD Mexico SAT catalog reference.
    Example: "E48"

  - `invoice_details.unit_description` (string,null, required)
    The description of the item, as defined by the legal entity in the country.\n- \U0001F1F2\U0001F1FD Mexico SAT catalog reference.
    Example: "Unidad de servicio"

  - `invoice_details.unit_amount` (number,null, required)
    The price of one a singular item.
    Example: 200

  - `invoice_details.tax_type` (string,null)
    The item's tax type.

  - `invoice_details.pre_tax_amount` (number,null, required)
    The total price for this item before tax is applied ( x ).
    Example: 400

  - `invoice_details.tax_percentage` (number,null, required)
    The tax percentage to apply.
    Example: 16

  - `invoice_details.tax_amount` (number,null, required)
    The amount of tax for this invoice item ( x ).
    Example: 64

  - `invoice_details.total_amount` (number,null, required)
    The total price for this invoice item ( + ).
    Example: 464

  - `invoice_details.retained_taxes` (array)
    The retained tax on the invoice item.

  - `invoice_details.retained_taxes.retained_tax_amount` (number,null, required)
    The amount of retained tax.
    Example: 209.79

  - `invoice_details.transferred_taxes` (array)
    The transferred taxes related to the invoice.

  - `invoice_details.transferred_taxes.transferred_tax_amount` (number,null, required)
    The amount of transferred tax.
    Example: 209.79

  - `currency` (string,null, required)
    The currency of the invoice. For example:
 
 - 🇧🇷 BRL (Brazilian Real)
 - 🇨🇴 COP (Colombian Peso)
 - 🇲🇽 MXN (Mexican Peso)
 - 🇺🇸 USD (United States Dollar)
    Example: "MXN"

  - `subtotal_amount` (number,null, required)
    The pretax amount of this invoice (sum of each item's ).
    Example: 400

  - `exchange_rate` (number,null, required)
    The exchange rate used in this invoice for the currency.
    Example: 0.052

  - `tax_amount` (number,null, required)
    The amount of tax for this invoice (sum of each item's ).
    Example: 64

  - `discount_amount` (number,null, required)
    The total amount discounted in this invoice.
    Example: 10

  - `total_amount` (number,null, required)
    The total amount of the invoice ( +  - )
    Example: 454

  - `related_invoices` (array)
    A list of related invoices.

  - `related_invoices.relationship_type` (string,null)
    The type of relationship between this invoice and the related invoice, as defined by the legal entity in the country. For more information, see our SAT catalog reference article.
    Example: "01"

  - `related_invoices.related_invoice_identification` (string,null)
    The SAT ID of the related invoice.
    Example: "INV-123456"

  - `payments` (array, required)
    A list detailing all the invoice payments.

  - `payments.date` (string,null, required)
    ISO-8601 timestamp when the payment was made.
    Example: "2020-03-17T12:00:00.000Z"

  - `payments.payment_type` (string,null, required)
    Payment type code used for this invoice, as defined by the country's legal entity.

- 🇲🇽 Mexico SAT catalog reference article
    Example: "03"

  - `payments.currency` (string,null, required)
    The currency of the payment. For example:

- 🇧🇷 BRL (Brazilian Real)
- 🇨🇴 COP (Colombian Peso)
- 🇲🇽 MXN (Mexican Peso)

Please note that other currencies other than in the list above may be returned.
    Example: "BRL"

  - `payments.exchange_rate` (string,null, required)
    The  to MXN currency exchange rate when the payment was made.
    Example: "3.75"

  - `payments.amount` (number,null, required)
    The invoice amount, in the currency of the original invoice.
    Example: 8000.5

  - `payments.operation_number` (string,null, required)
    The fiscal institution's internal identifier for the operation.
    Example: "831840"

  - `payments.beneficiary_rfc` (string,null)
    The fiscal ID of the payment beneficiary.
    Example: "BNM840515VB1"

  - `payments.beneficiary_account_number` (string,null, required)
    The bank account number of the payment beneficiary.
    Example: "12343453245633"

  - `payments.payer_rfc` (string,null, required)
    The fiscal ID of the payment issuer.
    Example: "BKJM840515VB1"

  - `payments.payer_account_number` (string,null, required)
    The bank account number of the payment issuer.
    Example: "13343663245699"

  - `payments.payer_bank_name` (string,null, required)
    The banking institution that was used by the payment issuer.
    Example: "CITI BANAMEX"

  - `payments.related_documents` (array, required)
    A list of all the related deferred invoices affected by the payment.

  - `payments.related_documents.invoice_identification` (string,null, required)
    The fiscal institution's unique ID for the related deferred invoice.
    Example: "7EE015F3-6311-11EA-B02A-00155D014007"

  - `payments.related_documents.currency` (string,null, required)
    The currency of the related invoice. For example:
    
- 🇧🇷 BRL (Brazilian Real)
- 🇨🇴 COP (Colombian Peso)
- 🇲🇽 MXN (Mexican Peso)
  
  Please note that other currencies other than in the list above may be returned.
    Example: "MXN"

  - `payments.related_documents.payment_method` (string,null, required)
    The payment method of the related invoice.
    Example: "PPD"

  - `payments.related_documents.partiality_number` (integer)
    The payment installment number.
    Example: 1

  - `payments.related_documents.previous_balance` (number,null, required)
    The invoice amount before the payment.
    Example: 18877.84

  - `payments.related_documents.amount_paid` (number,null, required)
    The amount paid in this installment.
    Example: 8000

  - `payments.related_documents.outstanding_balance` (number,null, required)
    The amount remaining to be paid.
    Example: 10877.84

  - `payroll` (object,null, required)
    Details regarding the payroll payment. Only applicable for payroll invoices.

  - `payroll.days` (integer,null, required)
    The number of days covered by the payment.
    Example: 30

  - `payroll.type` (string,null, required)
    The payroll type, as defined by the legal entity of the country.

- 🇲🇽 Mexico SAT catalog reference article
    Example: "O"

  - `payroll.amount` (number, required)
    The total amount of the payroll payment.
    Example: 20400.1

  - `payroll.version` (string, required)
    The version of the payroll object.
    Example: "1.2"

  - `payroll.date_from` (string,null, required)
    The start date of the payment period, in  format.
    Example: "2018-07-01"

  - `payroll.date_to` (string,null, required)
    The end date of the payment period, in  format.
    Example: "2018-07-31"

  - `payroll.payment_date` (string, required)
    The payment date, in  format.
    Example: "2018-07-16"

  - `payroll.periodicity` (string,null)
    How often the payroll payment is made.

For Mexico's SAT, we return one of the following values:

  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  - 
  -
    Enum: "DAILY", "WEEKLY", "TENTH_DAY", "FOURTEENTH_DAY", "FIFTEENTH_DAY", "MONTHLY", "BIMONTHLY", "PER_TASK", "COMMISSION", "ONE_OFF", "OTHER_PERIODICITY", "null"

  - `payroll.earnings_breakdown` (array,null)
    A breakdown of the earnings for the payroll payment.

  - `payroll.earnings_breakdown.type` (string,null)
    The type of income. For a full list of possible values, please see the payroll earnings breakdown type table.
    Example: "CHRISTMAS_BONUS"

  - `payroll.earnings_breakdown.taxable_amount` (number)
    The amount of the income that is taxable.
    Example: 1505

  - `payroll.earnings_breakdown.vat_free_amount` (number)
    The amount of the income that is not subject to VAT.

  - `payroll.tax_deductions` (array,null)
    A breakdown of the tax deductions on the payroll payment.

  - `payroll.tax_deductions.type` (string,null)
    The type of tax deduction. For a full list of possible values, please see the payroll tax deductions type table.
    Example: "UNION_FEES"

  - `payroll.tax_deductions.amount` (number)
    The amount of the tax deduction.
    Example: 1505

  - `payroll.other_payments` (array,null)
    A breakdown of other payments for the payroll.

  - `payroll.other_payments.type` (string,null)
    The type of other payment. For a full list of possible values, please see the payroll other payments type table.
    Example: "EMPLOYMENT_SUBSIDY"

  - `payroll.other_payments.amount` (number)
    The amount of the other payment.
    Example: 1505

  - `folio` (string,null)
    The internal control number that the taxpayer assigns to the invoice.
    Example: "26"

  - `export_type` (string,null)
    The export type of the invoice, as defined by the legal entity in the country. For more information, see our SAT catalog reference article.
    Example: "01"

  - `xml` (string,null)
    XML of the invoice document.

  - `warnings` (object,null)
    Object containing information about any warnings related to this invoice.

  - `warnings.code` (string,null, required)
    The warning code. Can be one of:

  - 
  - 
  -
    Example: "sat_xml_limit_reached"

  - `warnings.message` (string,null, required)
    The description of the warning.

The message will depend on the warning code:


The daily limit for XML downloads set by SAT was reached so this invoice might be missing data. Please check https://tinyurl.com/yydzhy5d for more information on this error.

 
Downloading invoices details is not available. The SAT portal raised a 503 error.
    Example: "The daily limit for XML downloads set by SAT was reached so this invoice\nmight be missing data. Please check https://tinyurl.com/yydzhy5d for more\ninformation on this error.\n"

  - `payment_type_description` (string,null, required)
    

  - `payment_method_description` (string,null)
    

  - `sender_blacklist_status` (string,null)
    Please use  instead.

  - `receiver_blacklist_status` (string,null)
    Please use  instead.

## Response 202 fields (application/json):

  - `request_id` (string)
    The unique ID for this request. We recommend you store this value to later identify which webhook event relates to an asynchronous request.
    Example: "b5d0106ac9cc43d5b36199fe831f6bbe"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For  errors, the description is:

  -
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code () that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For  errors, the description is:
  
  - .
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: ). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"