Sign in

v1

latestOpenAPI 3.0.22026-08-061464031.4 MB
Invoices

Retrieve invoices for a link

Retrieve invoice information from a specific fiscal link.

📘 Info

You can ask for up to one 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.

post/api/invoices/

Query parameters

omitstring

Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

fieldsstring

Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

Headers

X-Belvo-Request-Mode'async'
Example:async

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 202 - Accepted payload, including the request_id. Once we have retrieved the requested information, you will receive a webhook with the link and request IDs.

Request body

linkstring uuid required

The link.id you want to retrieve information for.

date_fromstring date required

The date from which you want to start getting data for, in YYYY-MM-DD format.

⚠️ The value of date_from cannot be greater than date_to.

date_tostring date required

The date you want to stop getting data for, in YYYY-MM-DD format.

⚠️ The value of date_to cannot be greater than today's date (in other words, no future dates).

type'OUTFLOW' | 'INFLOW' | 'null' nullable required

The direction of the invoice (from the perspective of the Link owner).

  • OUTFLOW indicates a sent invoice.
  • INFLOW indicates a received invoice.
attach_xmlboolean

When set to true, you will receive the XML invoice in the response.

save_databoolean

Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

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

Example request

{
  "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
  "date_from": "2020-08-05",
  "date_to": "2020-10-05",
  "type": "INFLOW",
  "save_data": true
}

Response

Ok (when save_data=false)

idstring uuid

Belvo's unique identifier for the current item.

linkstring uuid nullable

The link.id the data belongs to.

collected_atstring date-time required

The ISO-8601 timestamp when the data point was collected.

created_atstring date-time

The ISO-8601 timestamp of when the data point was created in Belvo's database.

invoice_identificationstring nullable required

The fiscal institution's unique ID for the invoice.

invoice_datestring nullable required

The date of the invoice, in YYYY-MM-DD format.

statusstring nullable required

The status of the invoice. Can be either Vigente (valid) or Cancelado (cancelled).

invoice_type'Egreso' | 'Ingreso' | 'Nómina' | 'Pago' | 'Traslado' nullable required

The fiscal institution's classification of the invoice.

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

  • Egreso
  • Ingreso
  • Nómina
  • Pago
  • Traslado
type'OUTFLOW' | 'INFLOW' | 'null' nullable required

The direction of the invoice (from the perspective of the Link owner).

  • OUTFLOW indicates a sent invoice.
  • INFLOW indicates a received invoice.
sender_idstring nullable required

The fiscal ID of the invoice sender

sender_fiscal_regimestring nullable

The tax regime of the sender, as defined by the legal entity in the country.

sender_namestring nullable required

The name of the invoice sender.

sender_tax_fraud_statusstring nullable

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.<br><br>

SAT updates the tax fraud list every three months. <br><br>

For more information regarding the reason's a taxpayer can be put on the tax fraud list, please see <a href="http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69.html" target="_blank">Article 69</a> and <a href="http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html" target="_blank">Article 69-B</a> of Mexico's Código Fiscal de la Federación. <br><br>

Possible statuses are:

  • INVESTIGATING <br> The fiscal institution has identified irregularities and open an investigation regarding the taxpayer. <br>
  • DISMISSED <br> The fiscal institution has investigated the taxpayer and declared them innocent. <br>
  • CONFIRMED <br> The fiscal institution has confirmed that the taxpayer is guilty. <br>
  • OVERTURNED <br> The fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list. <br>
  • NO_TAX_FRAUD_STATUS <br> The receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).
receiver_idstring nullable required

The fiscal ID of the invoice receiver.

receiver_postal_codestring

The postal code of the receiver.

receiver_fiscal_regimestring nullable

The tax regime of the receiver, as defined by the legal entity in the country.

receiver_namestring nullable required

The name of the invoice receiver.

receiver_tax_fraud_statusstring nullable

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.<br><br>

SAT updates the tax fraud list every three months. <br><br>

For more information regarding the reason's a taxpayer can be put on the tax fraud list, please see <a href="http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69.html" target="_blank">Article 69</a> and <a href="http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html" target="_blank">Article 69-B</a> of Mexico's Código Fiscal de la Federación. <br><br>

Possible statuses are:

  • INVESTIGATING <br> The fiscal institution has identified irregularities and open an investigation regarding the taxpayer. <br>
  • DISMISSED <br> The fiscal institution has investigated the taxpayer and declared them innocent. <br>
  • CONFIRMED <br> The fiscal institution has confirmed that the taxpayer is guilty. <br>
  • OVERTURNED <br> The fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list. <br>
  • NO_TAX_FRAUD_STATUS <br> The receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).
cancelation_statusstring nullable required

If the invoice is cancelled, this field indicates the status of the cancellation.

cancelation_update_datestring date nullable required

The date of the invoice cancelation, in YYYY-MM-DD format.

certification_datestring date nullable required

The date of the fiscal certification, in YYYY-MM-DD format.

certification_authoritystring nullable required

The fiscal ID of the certification provider.

payment_typestring nullable required

The payment type code used for this invoice, as defined by the country legal entity.

  • 🇲🇽 Mexico <a href="https://developers.belvo.com/docs/sat-catalogs#payment-type" target="_blank">SAT catalog reference article</a>
payment_type_descriptionstring nullable required

This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.

payment_method'PUE' | 'PPD' | 'null' nullable

The payment method code used for this invoice, as defined by the legal entity of the country.

  • 🇲🇽 Mexico <a href="https://developers.belvo.com/docs/sat-catalogs#payment-method" target="_blank">SAT catalog reference article</a>. For Mexico, we return PUE, PPD, or null.
payment_method_descriptionstring nullable

This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation.

The description of the payment method used for this invoice.

usagestring nullable

The invoice's usage code, as defined by the legal entity of the country.

  • 🇲🇽 Mexico <a href="https://developers.belvo.com/docs/sat-catalogs#usage" target="_blank">SAT catalog reference article</a>
versionstring nullable

The CFDI version of the invoice.

place_of_issuestring nullable

The postcode of where the invoice was issued.

currencystring nullable required

The currency of the invoice. For example:

  • 🇧🇷 BRL (Brazilian Real)
  • 🇨🇴 COP (Colombian Peso)
  • 🇲🇽 MXN (Mexican Peso)
  • 🇺🇸 USD (United States Dollar)
subtotal_amountnumber float nullable required

The pretax amount of this invoice (sum of each item's pre_tax_amount).

exchange_ratenumber float nullable required

The exchange rate used in this invoice for the currency.

tax_amountnumber float nullable required

The amount of tax for this invoice (sum of each item's tax_amount).

discount_amountnumber float nullable required

The total amount discounted in this invoice.

total_amountnumber float nullable required

The total amount of the invoice (subtotal_amount + tax_amount - discount_amount)

foliostring nullable

The internal control number that the taxpayer assigns to the invoice.

seriesstring nullable

The series of the invoice, as defined by the taxpayer. This is an optional field used to group invoices.

export_typestring nullable

The export type of the invoice, as defined by the legal entity in the country. For more information, see our <a href="https://developers.belvo.com/docs/sat-catalogs#export-type" target="_blank">SAT catalog reference article</a>.

xmlstring nullable

XML of the invoice document.

sender_blacklist_statusstring nullable

This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation. Please use sender_tax_fraud_status instead.

receiver_blacklist_statusstring nullable

This field has been deprecated. For more information regarding Belvo and deprecation, see our Deprecated fields explanation. Please use receiver_tax_fraud_status instead.

Example response

[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "collected_at": "2022-02-09T08:45:50.406032Z",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "invoice_identification": "A1A1A1A1-2B2B-3C33-D44D-555555E55EE",
    "invoice_date": "2019-12-01",
    "status": "Vigente",
    "invoice_type": "Ingreso",
    "type": "INFLOW",
    "tax_details": {
      "total_tax_retained": 194.27,
      "total_tax_transferred": 150.4,
      "retained_taxes": [
        {
          "tax_type": "Tasa",
          "tax": "ISR",
          "tax_amount": 94
        }
      ],
      "transferred_taxes": [
        {
          "tax_type": "Tasa",
          "tax": "IVA",
          "tax_percentage": 16,
          "pre_tax_amount": 940,
          "tax_amount": 150.4
        }
      ]
    },
    "sender_id": "AAA111111AA11",
    "sender_fiscal_regime": "601",
    "sender_name": "ACME CORP",
    "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS",
    "receiver_id": "BBB222222BB22",
    "receiver_postal_code": "11560",
    "receiver_fiscal_regime": "601",
    "receiver_name": "BELVO CORP",
    "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS",
    "cancelation_update_date": "2019-12-02",
    "certification_date": "2019-12-01",
    "certification_authority": "CCC333333CC33",
    "payment_type": "99",
    "payment_method": "PUE",
    "usage": "P01",
    "version": "3.3",
    "place_of_issue": "01165",
    "invoice_details": [
      {
        "collected_at": "2022-02-09T08:45:50.406032Z",
        "description": "December 2019 accounting fees",
        "product_identification": "84101600",
        "quantity": 10,
        "unit_code": "E48",
        "unit_description": "Unidad de servicio",
        "unit_amount": 200,
        "discount": 10,
        "tax_subject_code": "02",
        "identifier_number": "PROD-12345",
        "pre_tax_amount": 400,
        "tax_percentage": 16,
        "tax_amount": 64,
        "total_amount": 464,
        "retained_taxes": [
          {
            "collected_at": "2022-02-09T08:45:50.406032Z",
            "tax_type": "Tasa",
            "tax": "ISR",
            "tax_percentage": 10,
            "retained_tax_amount": 209.79
          }
        ],
        "transferred_taxes": [
          {
            "collected_at": "2022-02-09T08:45:50.406032Z",
            "tax_type": "Tasa",
            "tax": "IVA",
            "tax_percentage": 10,
            "transferred_tax_amount": 209.79
          }
        ]
      }
    ],
    "currency": "MXN",
    "subtotal_amount": 400,
    "exchange_rate": 0.052,
    "tax_amount": 64,
    "discount_amount": 10,
    "total_amount": 454,
    "related_invoices": [
      {
        "relationship_type": "01",
        "related_invoice_identification": "INV-123456"
      }
    ],
    "payments": [
      {
        "date": "2020-03-17T12:00:00.000Z",
        "payment_type": "03",
        "currency": "BRL",
        "exchange_rate": "3.75",
        "amount": 8000.5,
        "operation_number": "831840",
        "beneficiary_rfc": "BNM840515VB1",
        "beneficiary_account_number": "12343453245633",
        "payer_rfc": "BKJM840515VB1",
        "payer_account_number": "13343663245699",
        "payer_bank_name": "CITI BANAMEX",
        "related_documents": [
          {
            "invoice_identification": "7EE015F3-6311-11EA-B02A-00155D014007",
            "currency": "MXN",
            "payment_method": "PPD",
            "partiality_number": 1,
            "previous_balance": 18877.84,
            "amount_paid": 8000,
            "outstanding_balance": 10877.84
          }
        ]
      }
    ],
    "payroll": {
      "days": 30,
      "type": "O",
      "amount": 20400.1,
      "version": "1.2",
      "date_from": "2018-07-01",
      "date_to": "2018-07-31",
      "collected_at": "2022-02-09T08:45:50.406032Z",
      "payment_date": "2018-07-16",
      "periodicity": "MONTHLY",
      "earnings_breakdown": [
        {
          "type": "CHRISTMAS_BONUS",
          "taxable_amount": 1505
        }
      ],
      "tax_deductions": [
        {
          "type": "UNION_FEES",
          "amount": 1505
        }
      ],
      "other_payments": [
        {
          "type": "EMPLOYMENT_SUBSIDY",
          "amount": 1505
        }
      ]
    },
    "folio": "26",
    "series": "A",
    "export_type": "01",
    "warnings": {
      "code": "sat_xml_limit_reached",
      "message": "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"
    }
  }
]