InstitutionsFormFieldValues
{
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "001",
"description": "The code of the document."
},
"label": {
"type": "string",
"example": "Cédula de Ciudadanía",
"description": "The label for the field. For example:\n- Cédula de Ciudadanía\n- Cédula de Extranjería\n- Pasaporte\n"
},
"validation": {
"type": "string",
"example": "^.{1,}$",
"description": "The type of input validation used for the field."
},
"placeholder": {
"type": "string",
"example": "DEF4444908M22",
"description": "The placeholder text in the form field."
},
"validation_message": {
"type": "string",
"example": "Invalid document number",
"description": "The message displayed when an invalid input is provided in the form field."
}
}
}
InstitutionsGetAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InstitutionsGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
InstitutionsGetDetailsResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InstitutionsPaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Institution"
},
"description": "Array of institution objects."
}
}
}
]
}
InvalidAccessMode
{
"type": "object",
"title": "Invalid Access Mode",
"properties": {
"code": {
"type": "string",
"example": "invalid_link",
"description": "A unique error code (`invalid_access_mode_switch`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_access_mode_switch\" target=\"_blank\">400 invalid_access_mode_switch errors</a>.\n"
},
"message": {
"type": "string",
"example": "This link doesn't have stored credentials hence it can't be switched to recurrent mode\"",
"description": "A short description of the error. \n\n\nFor `invalid_access_mode_switch` errors, the description is:\n \n - `This link doesn't have stored credentials hence it can't be switched to recurrent mode\"`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to update a link from single to recurrent, but there are no login credentials stored for the user.\n"
}
InvalidLinkError
{
"type": "object",
"title": "Invalid Link",
"properties": {
"code": {
"type": "string",
"example": "invalid_link",
"description": "A unique error code (`invalid_link`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_link\" target=\"_blank\">400 invalid_link errors</a>.\n"
},
"message": {
"type": "string",
"example": "The link has been invalidated. You may need to update link credentials",
"description": "A short description of the error. \n\n\nFor `invalid_link` errors, the description is:\n \n - `The link has been invalidated. You may need to update link credentials`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you try to access an account but the user credentials are no longer valid, prompting an error from the institution.\n"
}
InvalidPeriodError
{
"type": "object",
"title": "Invalid Period",
"properties": {
"code": {
"type": "string",
"example": "invalid_period",
"description": "A unique error code (`invalid_period`) that allows you to classify and handle the error programmatically.\n\n\nℹ️ Check our DevPortal for more information on how to handle <a href=\"https://developers.belvo.com/docs/belvo-api-errors#400-invalid_period\" target=\"_blank\">400 invalid_period errors</a>.\n"
},
"message": {
"type": "string",
"example": "The number of days between date_from and date_to must be at least 90 days",
"description": "A short description of the error. \n\n\nFor `invalid_period` errors, the description is:\n \n - `The number of days between date_from and date_to must be at least 90 days`.\n"
},
"request_id": {
"type": "string",
"example": "9e7b283c6efa449c9c028a16b5c249fb",
"pattern": "[a-f0-9]{32}",
"description": "A 32-character unique ID of the request (matching a regex pattern of: `[a-f0-9]{32}`). Provide this ID when contacting the Belvo\nsupport team to accelerate investigations.\n"
}
},
"description": "This error occurs when you request incomes for a link within a given date range, however, the period between `date_from` and `date_to` is less than 90 days.\n"
}
InvoiceDetailDian
{
"type": "object",
"required": [
"description",
"product_identification",
"quantity",
"unit_amount",
"unit_description",
"unit_code",
"pre_tax_amount",
"tax_percentage",
"tax_amount",
"total_amount"
],
"properties": {
"quantity": {
"type": "number",
"format": "float",
"example": 1,
"nullable": true,
"description": "The quantity of this invoice item."
},
"tax_type": {
"type": "string",
"example": "IVA",
"nullable": true,
"description": "The item's tax type."
},
"unit_code": {
"type": "string",
"example": "EA",
"nullable": true,
"description": "The unit of measure, as defined by the legal entity in the country.\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice item (`pre_tax_amount` x\n`tax_percentage`).\n"
},
"description": {
"type": "string",
"example": "December 2019 accounting fees",
"nullable": true,
"description": "The description of the invoice item (an invoice can have one or more\nitems).\n"
},
"unit_amount": {
"type": "number",
"format": "float",
"example": 5900,
"nullable": true,
"description": "The price of one singular item."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 464,
"nullable": true,
"description": "The total price for this invoice item (`pre_tax_amount` + `tax_amount`)."
},
"pre_tax_amount": {
"type": "number",
"format": "float",
"example": 5900,
"nullable": true,
"description": "The total price for this item before tax is applied (`quantity` x\n`unit_amount`).\n"
},
"tax_percentage": {
"type": "number",
"format": "float",
"example": 16,
"nullable": true,
"description": "The tax percentage to apply."
},
"unit_description": {
"type": "string",
"example": "cada",
"nullable": true,
"description": "The description of the item, as defined by the legal entity in the country.\n"
},
"product_identification": {
"type": "string",
"example": "AE001",
"nullable": true,
"description": "The identification code of the product or the service, as defined by the legal entity in the country.\n"
}
}
}
InvoiceDetailRetainedTaxSat
{
"type": "object",
"required": [
"tax",
"tax_percentage",
"retained_tax_amount"
],
"properties": {
"tax": {
"type": "string",
"example": "ISR",
"nullable": true,
"description": "The type of retained tax (for example, ISR, IVA or IEPS)."
},
"tax_type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for SAT Mexico and will return `null`.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"tax_percentage": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The percentage of tax retained."
},
"retained_tax_amount": {
"type": "number",
"format": "float",
"example": 209.79,
"nullable": true,
"description": "The amount of retained tax."
}
}
}
InvoiceDetailSat
{
"type": "object",
"required": [
"description",
"product_identification",
"quantity",
"unit_amount",
"unit_description",
"unit_code",
"pre_tax_amount",
"tax_percentage",
"tax_amount",
"total_amount"
],
"properties": {
"quantity": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The quantity of this invoice item."
},
"tax_type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"unit_code": {
"type": "string",
"example": "E48",
"nullable": true,
"description": "The unit of measure, as defined by the legal entity in the country. \n- 🇲🇽 Mexico [SAT catalog reference](https://developers.belvo.com/docs/sat-catalogs#unit-code)\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice item (`pre_tax_amount` x\n`tax_percentage`).\n"
},
"description": {
"type": "string",
"example": "December 2019 accounting fees",
"nullable": true,
"description": "The description of the invoice item (an invoice can have one or more items).\n"
},
"unit_amount": {
"type": "number",
"format": "float",
"example": 200,
"nullable": true,
"description": "The price of one a singular item."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 464,
"nullable": true,
"description": "The total price for this invoice item (`pre_tax_amount` + `tax_amount`)."
},
"pre_tax_amount": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "The total price for this item before tax is applied (`quantity` x\n`unit_amount`).\n"
},
"retained_taxes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceDetailRetainedTaxSat"
},
"description": "The retained tax on the invoice item."
},
"tax_percentage": {
"type": "number",
"format": "float",
"example": 16,
"nullable": true,
"description": "The tax percentage to apply."
},
"unit_description": {
"type": "string",
"example": "Unidad de servicio",
"nullable": true,
"description": "The description of the item, as defined by the legal entity in the country.\n- 🇲🇽 Mexico [SAT catalog reference](https://developers.belvo.com/docs/sat-catalogs#unit-code)\n"
},
"product_identification": {
"type": "string",
"example": "84101600",
"nullable": true,
"description": "The identification code of the product or the service, as defined by the legal entity in the country.\n- 🇲🇽 [Mexico](http://200.57.3.89/Pys/catPyS.aspx)\n"
}
}
}
InvoiceDian
{
"type": "object",
"title": "🇨🇴 DIAN Colombia",
"required": [
"type",
"invoice_identification",
"invoice_date",
"invoice_type",
"subtotal_amount",
"tax_amount",
"discount_amount",
"total_amount",
"currency",
"exchange_rate",
"status",
"sender_name",
"sender_id",
"receiver_name",
"receiver_id",
"certification_authority",
"certification_date",
"cancelation_status",
"cancelation_update_date",
"payment_type",
"payment_type_description",
"invoice_details",
"payroll",
"payments",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier for the current invoice."
},
"xml": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"link": {
"type": "string",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "The `link.id` the invoice belongs to."
},
"type": {
"$ref": "#/components/schemas/EnumInvoiceType"
},
"folio": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"usage": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"status": {
"type": "string",
"example": "Aprobado",
"nullable": true,
"description": "The status of the invoice. Can be one of:\n\n - *Aprobado* (approved)\n - *Aprobado con notificación* (approved with notification)\n"
},
"payroll": {
"$ref": "#/components/schemas/InvoicesPayrollDian"
},
"version": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"currency": {
"type": "string",
"example": "COP",
"nullable": true,
"description": "The currency of the invoice. For example:\n \n - 🇧🇷 BRL (Brazilian Real)\n - 🇨🇴 COP (Colombian Peso)\n - 🇲🇽 MXN (Mexican Peso)\n - 🇺🇸 USD (United States Dollar)\n"
},
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsDian"
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"warnings": {
"$ref": "#/components/schemas/InvoiceWarningsDian"
},
"sender_id": {
"type": "string",
"example": "YHS922233648",
"nullable": true,
"description": "The fiscal ID of the invoice sender."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice (sum of each item's `tax_amount`).\n"
},
"receiver_id": {
"type": "string",
"example": "BBB222222BB22",
"nullable": true,
"description": "The fiscal ID of the invoice receiver."
},
"sender_name": {
"type": "string",
"example": "ACME Corp Colombia",
"nullable": true,
"description": "The name of the invoice sender."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"invoice_date": {
"type": "string",
"example": "2019-12-01",
"nullable": true,
"description": "The date of the invoice, in `YYYY-MM-DD` format."
},
"invoice_type": {
"$ref": "#/components/schemas/EnumInvoiceDianInvoiceType"
},
"payment_type": {
"type": "string",
"example": "47",
"nullable": true,
"description": "The payment type code used for this invoice, as defined by the country legal entity.\n\nFor detailed information regarding DIAN's payment types, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 454,
"nullable": true,
"description": "The total amount of the invoice (`subtotal_amount` + `tax_amount` -\n`discount_amount`)\n"
},
"exchange_rate": {
"type": "number",
"format": "float",
"example": 0.053,
"nullable": true,
"description": "The exchange rate used in this invoice for the currency.\n"
},
"receiver_name": {
"type": "string",
"example": "Roadrunner Traps Colombia",
"nullable": true,
"description": "The name of the invoice receiver."
},
"payment_method": {
"$ref": "#/components/schemas/EnumInvoiceDianPaymentMethod"
},
"place_of_issue": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"sender_details": {
"$ref": "#/components/schemas/InvoiceSenderDetailsDian"
},
"discount_amount": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The total amount discounted in this invoice.\n"
},
"expiration_date": {
"type": "string",
"format": "date",
"example": "2022-08-19",
"nullable": true,
"description": "The date when the invoice is set to expire, in `YYYY-MM-DD` format.\n\nFor example: If the invoice is paid in installments, this field indicates the date when the installment is to be paid.\n"
},
"invoice_details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceDetailDian"
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"subtotal_amount": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "The pretax amount of this invoice (sum of each item's `pre_tax_amount`).\n"
},
"receiver_details": {
"$ref": "#/components/schemas/InvoicesReceiverDetailsDian"
},
"cancelation_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"certification_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"invoice_identification": {
"type": "string",
"example": "89868fda605e6250a7ecb910dc57ed6f8147c6dc39ec90805bb655a0646e6cc3f991f93463f62e03d236b9cc9c293edc",
"nullable": true,
"description": "The fiscal institution's unique ID for the invoice."
},
"cancelation_update_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"certification_authority": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"sender_tax_fraud_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "Indicates whether or not the sender is on a 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.\n\n**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_type_description": {
"type": "string",
"example": null,
"nullable": true,
"description": "The description of the payment method used for this invoice.\n"
},
"receiver_tax_fraud_status": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_method_description": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The description of the payment method used for this invoice.*\n"
}
}
}
InvoiceSenderDetailsDian
{
"type": "object",
"nullable": true,
"properties": {
"email": {
"type": "string",
"example": "acme_colombia@gmail.com",
"nullable": true,
"description": "The sender's email address.\n"
},
"address": {
"type": "string",
"example": "Calle 144 No. 12-09",
"nullable": true,
"description": "The sender's address.\n"
},
"country": {
"type": "string",
"example": "Colombia",
"nullable": true,
"description": "The country where the sender pays their taxes.\n"
},
"regimen": {
"type": "string",
"example": "Régimen Simple de Tributación - SIMPLE",
"nullable": true,
"description": "The sender's regimen type.\n\nFor detailed information regarding DIAN's regimens, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"tax_scheme": {
"type": "string",
"example": "01-IVA",
"nullable": true,
"description": "The sender's fiscal responsibilities.\n\nFor detailed information regarding DIAN's tax schemes, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected."
},
"phone_number": {
"type": "string",
"example": "576606522566",
"nullable": true,
"description": "The sender's phone number.\n"
},
"tax_payer_type": {
"type": "string",
"example": "Persona Natural",
"nullable": true,
"description": "Indicates if the sender is a business or an individual. Can be either:\n \n - `Persona Jurídica`\n - `Persona Natural`\n"
}
},
"description": "Details regarding the sender.\n"
}
InvoiceWarningsDian
{
"type": "object",
"nullable": true,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"message": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
InvoiceWarningsSat
{
"type": "object",
"nullable": true,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"example": "sat_xml_limit_reached",
"nullable": true,
"description": "The warning code. Can be one of:\n\n - `sat_xml_limit_reached`\n - `sat_service_unavailable`\n - `null`\n"
},
"message": {
"type": "string",
"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",
"nullable": true,
"description": "The description of the warning.\n\nThe message will depend on the warning code:\n\n`sat_xml_limit_reached`<br>\nThe 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.\n\n`sat_service_unavailable` <br>\nDownloading invoices details is not available. The SAT portal raised a 503 error.\n"
}
},
"description": "Object containing information about any warnings related to this invoice.\n"
}
InvoiceWithIdSat
{
"type": "object",
"title": "🇲🇽 SAT Mexico",
"required": [
"type",
"invoice_identification",
"invoice_date",
"invoice_type",
"subtotal_amount",
"tax_amount",
"discount_amount",
"total_amount",
"currency",
"exchange_rate",
"status",
"sender_name",
"sender_id",
"receiver_name",
"receiver_id",
"certification_authority",
"certification_date",
"cancelation_status",
"cancelation_update_date",
"payment_type",
"payment_type_description",
"invoice_details",
"payroll",
"payments",
"collected_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "c749315b-eec2-435d-a458-06912878564f",
"description": "Belvo's unique identifier used to reference the current invoice."
},
"xml": {
"type": "string",
"nullable": true,
"description": "XML of the invoice document.\n"
},
"link": {
"type": "string",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "The `link.id` the invoice belongs to."
},
"type": {
"$ref": "#/components/schemas/EnumInvoiceType"
},
"folio": {
"type": "string",
"example": "26",
"nullable": true,
"description": "The internal control number that the taxpayer assigns to the invoice.\n"
},
"usage": {
"type": "string",
"example": "P01",
"nullable": true,
"description": "The invoice's usage code, as defined by the legal entity of the country. \n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#usage)\n"
},
"status": {
"type": "string",
"example": "Vigente",
"nullable": true,
"description": "The status of the invoice. Can be either *Vigente* (valid) or *Cancelado*\n(cancelled).\n"
},
"payroll": {
"$ref": "#/components/schemas/InvoicesPayrollSat"
},
"version": {
"type": "string",
"example": "3.3",
"nullable": true,
"description": "The CFDI version of the invoice.\n"
},
"currency": {
"type": "string",
"example": "MXN",
"nullable": true,
"description": "The currency of the invoice. For example:\n \n - 🇧🇷 BRL (Brazilian Real)\n - 🇨🇴 COP (Colombian Peso)\n - 🇲🇽 MXN (Mexican Peso)\n - 🇺🇸 USD (United States Dollar)\n"
},
"payments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsSat"
},
"description": "A list detailing all the invoice payments.\n"
},
"warnings": {
"$ref": "#/components/schemas/InvoiceWarningsSat"
},
"sender_id": {
"type": "string",
"example": "AAA111111AA11",
"nullable": true,
"description": "The fiscal ID of the invoice sender"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"tax_amount": {
"type": "number",
"format": "float",
"example": 64,
"nullable": true,
"description": "The amount of tax for this invoice (sum of each item's `tax_amount`).\n"
},
"receiver_id": {
"type": "string",
"example": "BBB222222BB22",
"nullable": true,
"description": "The fiscal ID of the invoice receiver."
},
"sender_name": {
"type": "string",
"example": "ACME CORP",
"nullable": true,
"description": "The name of the invoice sender."
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"invoice_date": {
"type": "string",
"example": "2019-12-01",
"nullable": true,
"description": "The date of the invoice, in `YYYY-MM-DD` format."
},
"invoice_type": {
"$ref": "#/components/schemas/EnumInvoiceSatInvoiceType"
},
"payment_type": {
"type": "string",
"example": "99",
"nullable": true,
"description": "The payment type code used for this invoice, as defined by the country legal entity.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payment-type)\n"
},
"total_amount": {
"type": "number",
"format": "float",
"example": 454,
"nullable": true,
"description": "The total amount of the invoice (`subtotal_amount` + `tax_amount` -\n`discount_amount`)\n"
},
"exchange_rate": {
"type": "number",
"format": "float",
"example": 0.052,
"nullable": true,
"description": "The exchange rate used in this invoice for the currency.\n"
},
"receiver_name": {
"type": "string",
"example": "BELVO CORP",
"nullable": true,
"description": "The name of the invoice receiver."
},
"payment_method": {
"$ref": "#/components/schemas/EnumInvoiceSatPaymentMethod"
},
"place_of_issue": {
"type": "string",
"example": "01165",
"nullable": true,
"description": "The postcode of where the invoice was issued.\n"
},
"discount_amount": {
"type": "number",
"format": "float",
"example": 10,
"nullable": true,
"description": "The total amount discounted in this invoice.\n"
},
"invoice_details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoiceDetailSat"
},
"description": "A list of descriptions for each item (purchased product or service provided) in the invoice.\n"
},
"subtotal_amount": {
"type": "number",
"format": "float",
"example": 400,
"nullable": true,
"description": "The pretax amount of this invoice (sum of each item's `pre_tax_amount`).\n"
},
"cancelation_status": {
"type": "string",
"nullable": true,
"description": "If the invoice is cancelled, this field indicates the status of the cancellation.\n"
},
"certification_date": {
"type": "string",
"format": "date",
"example": "2019-12-01",
"nullable": true,
"description": "The date of the fiscal certification, in `YYYY-MM-DD` format.\n"
},
"invoice_identification": {
"type": "string",
"example": "A1A1A1A1-2B2B-3C33-D44D-555555E55EE",
"nullable": true,
"description": "The fiscal institution's unique ID for the invoice."
},
"cancelation_update_date": {
"type": "string",
"format": "date",
"example": "2019-12-02",
"nullable": true,
"description": "The date of the invoice cancelation, in `YYYY-MM-DD` format.\n"
},
"certification_authority": {
"type": "string",
"example": "CCC333333CC33",
"nullable": true,
"description": "The fiscal ID of the certification provider.\n"
},
"sender_blacklist_status": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\nPlease use `sender_tax_fraud_status` instead.\n"
},
"sender_tax_fraud_status": {
"type": "string",
"example": "NO_TAX_FRAUD_STATUS",
"nullable": true,
"description": "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>\n\nSAT updates the tax fraud list every three months. <br><br>\n\nFor more information regarding the reason's a taxpayer can be put on the tax fraud list, please see [Article 69](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69.html) and [Article 69-B](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html) of Mexico's Código Fiscal de la Federación.\n<br><br>\n\nPossible statuses are:\n\n- `INVESTIGATING` <br>\nThe fiscal institution has identified irregularities and open an investigation regarding the taxpayer.\n<br>\n- `DISMISSED` <br>\nThe fiscal institution has investigated the taxpayer and declared them innocent.\n<br>\n- `CONFIRMED` <br>\nThe fiscal institution has confirmed that the taxpayer is guilty.\n<br>\n- `OVERTURNED` <br>\nThe fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.\n<br>\n- `NO_TAX_FRAUD_STATUS` <br>\nThe receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).\n"
},
"payment_type_description": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n"
},
"receiver_blacklist_status": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\nPlease use `receiver_tax_fraud_status` instead.\n"
},
"receiver_tax_fraud_status": {
"type": "string",
"example": "NO_TAX_FRAUD_STATUS",
"nullable": true,
"description": "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>\n\nSAT updates the tax fraud list every three months. <br><br>\n\nFor more information regarding the reason's a taxpayer can be put on the tax fraud list, please see [Article 69](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69.html) and [Article 69-B](http://omawww.sat.gob.mx/cifras_sat/Paginas/datos/vinculo.html?page=ListCompleta69B.html) of Mexico's Código Fiscal de la Federación.\n<br><br>\n\nPossible statuses are:\n\n- `INVESTIGATING` <br>\nThe fiscal institution has identified irregularities and open an investigation regarding the taxpayer.\n<br>\n- `DISMISSED` <br>\nThe fiscal institution has investigated the taxpayer and declared them innocent.\n<br>\n- `CONFIRMED` <br>\nThe fiscal institution has confirmed that the taxpayer is guilty.\n<br>\n- `OVERTURNED` <br>\nThe fiscal institution has reassessed a previously confirmed taxpayer and, based on new evidence, has taken the taxpayer off the tax fraud list.\n<br>\n- `NO_TAX_FRAUD_STATUS` <br>\nThe receiver or sender is not found in the list (in other words, they are complying with the fiscal institution's regulations).\n"
},
"payment_method_description": {
"type": "string",
"example": null,
"nullable": true,
"deprecated": true,
"description": "*This field has been deprecated. For more information regarding Belvo and deprecation, see our [Deprecated fields](https://developers.belvo.com/reference/using-the-api-reference#%EF%B8%8F-deprecated-fields) explanation.*\n\n*The description of the payment method used for this invoice.*\n"
}
}
}
InvoicesCompleteRequest201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesCompleteRequest400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
InvoicesCompleteRequest401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesCompleteRequest408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
InvoicesCompleteRequest428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
InvoicesCompleteRequest500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
InvoicesCompleteRequestResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesDeleteInvoice404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
InvoicesDeleteInvoiceResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesGetDetails401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesGetDetails404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
InvoicesGetDetailsResponse
{
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
InvoicesGetLinkInvoices201Response
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesGetLinkInvoices400Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}
InvoicesGetLinkInvoices401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesGetLinkInvoices408Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RequestTimeoutError"
},
"title": "Request Timeout",
"description": "Belvo has a limit regarding the time it takes to log in, retrieve account data, and log out. A timeout occurs when there is a very high amount of data and everything could not be obtained within the allotted time.\n \n"
}
InvoicesGetLinkInvoices500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
InvoicesGetLinkInvoicesResponse
{
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
}
}
InvoicesListAllResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
InvoicesPaymentsDian
{
"type": "object",
"required": [
"date",
"payment_type",
"currency",
"exchange_rate",
"amount",
"operation_number",
"beneficiary_account_number",
"payer_rfc",
"payer_account_number",
"payer_bank_name",
"related_documents"
],
"properties": {
"date": {
"type": "string",
"format": "date-time",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"currency": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payer_rfc": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"exchange_rate": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"beneficiary_rfc": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payer_bank_name": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"operation_number": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"related_documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsRelatedDocumentsDian"
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payer_account_number": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"beneficiary_account_number": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
}
}
InvoicesPaymentsRelatedDocumentsDian
{
"type": "object",
"required": [
"invoice_identification",
"currency",
"payment_method",
"previous_balance",
"amount_paid",
"outstanding_balance"
],
"properties": {
"currency": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"amount_paid": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_method": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"previous_balance": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"partiality_number": {
"type": "integer",
"format": "int32",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"outstanding_balance": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"invoice_identification": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "List of all the related deferred invoices affected by the payment."
}
InvoicesPaymentsRelatedDocumentsSat
{
"type": "object",
"required": [
"invoice_identification",
"currency",
"payment_method",
"previous_balance",
"amount_paid",
"outstanding_balance"
],
"properties": {
"currency": {
"type": "string",
"example": "MXN",
"nullable": true,
"description": "The currency of the related invoice. For example:\n \n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n \n Please note that other currencies other than in the list above may be returned.\n"
},
"amount_paid": {
"type": "number",
"format": "float",
"example": 8000,
"nullable": true,
"description": "The amount paid in this installment.\n"
},
"payment_method": {
"type": "string",
"example": "PPD",
"nullable": true,
"description": "The payment method of the related invoice.\n"
},
"previous_balance": {
"type": "number",
"format": "float",
"example": 18877.84,
"nullable": true,
"description": "The invoice amount before the payment.\n"
},
"partiality_number": {
"type": "integer",
"format": "int32",
"example": 1,
"description": "The payment installment number.\n"
},
"outstanding_balance": {
"type": "number",
"format": "float",
"example": 10877.84,
"nullable": true,
"description": "The amount remaining to be paid.\n"
},
"invoice_identification": {
"type": "string",
"example": "7EE015F3-6311-11EA-B02A-00155D014007",
"nullable": true,
"description": "The fiscal institution's unique ID for the related deferred invoice.\n"
}
},
"description": "List of all the related deferred invoices affected by the payment."
}
InvoicesPaymentsSat
{
"type": "object",
"required": [
"date",
"payment_type",
"currency",
"exchange_rate",
"amount",
"operation_number",
"beneficiary_account_number",
"payer_rfc",
"payer_account_number",
"payer_bank_name",
"related_documents"
],
"properties": {
"date": {
"type": "string",
"format": "date-time",
"example": "2020-03-17T12:00:00.000Z",
"nullable": true,
"description": "ISO-8601 timestamp when the payment was made.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 8000.5,
"nullable": true,
"description": "The invoice amount, in the currency of the original invoice.\n"
},
"currency": {
"type": "string",
"example": "BRL",
"nullable": true,
"description": "The currency of the payment. For example:\n\n- 🇧🇷 BRL (Brazilian Real)\n- 🇨🇴 COP (Colombian Peso)\n- 🇲🇽 MXN (Mexican Peso)\n\nPlease note that other currencies other than in the list above may be returned.\n"
},
"payer_rfc": {
"type": "string",
"example": "BKJM840515VB1",
"nullable": true,
"description": "The fiscal ID of the payment issuer.\n"
},
"payment_type": {
"type": "string",
"example": "03",
"nullable": true,
"description": "Payment type code used for this invoice, as defined by the country's legal entity.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payment-type)\n"
},
"exchange_rate": {
"type": "string",
"example": "3.75",
"nullable": true,
"description": "The `currency` to MXN currency exchange rate when the payment was made.\n"
},
"beneficiary_rfc": {
"type": "string",
"example": "BNM840515VB1",
"nullable": true,
"description": "The fiscal ID of the payment beneficiary.\n"
},
"payer_bank_name": {
"type": "string",
"example": "CITI BANAMEX",
"nullable": true,
"description": "The banking institution that was used by the payment issuer.\n"
},
"operation_number": {
"type": "string",
"example": "831840",
"nullable": true,
"description": "The fiscal institution's internal identifier for the operation.\n"
},
"related_documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InvoicesPaymentsRelatedDocumentsSat"
},
"description": "A list of all the related deferred invoices affected by the payment.\n"
},
"payer_account_number": {
"type": "string",
"example": "13343663245699",
"nullable": true,
"description": "The bank account number of the payment issuer.\n"
},
"beneficiary_account_number": {
"type": "string",
"example": "12343453245633",
"nullable": true,
"description": "The bank account number of the payment beneficiary.\n"
}
}
}
InvoicesPayrollDian
{
"type": "object",
"nullable": true,
"required": [
"version",
"type",
"payment_date",
"date_from",
"date_to",
"days",
"amount"
],
"properties": {
"days": {
"type": "integer",
"format": "int32",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"type": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"amount": {
"type": "number",
"format": "float",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"date_to": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"version": {
"type": "string",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"date_from": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
},
"payment_date": {
"type": "string",
"format": "date",
"example": null,
"nullable": true,
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
},
"description": "**Note**: This field is not applicable for DIAN Colombia and will return `null`.\n"
}
InvoicesPayrollSat
{
"type": "object",
"nullable": true,
"required": [
"version",
"type",
"payment_date",
"date_from",
"date_to",
"days",
"amount"
],
"properties": {
"days": {
"type": "integer",
"format": "int32",
"example": 30,
"nullable": true,
"description": "The number of days covered by the payment.\n"
},
"type": {
"type": "string",
"example": "O",
"nullable": true,
"description": "The payroll type, as defined by the legal entity of the country.\n\n- 🇲🇽 Mexico [SAT catalog reference article](https://developers.belvo.com/docs/sat-catalogs#payroll-type)\n"
},
"amount": {
"type": "number",
"format": "float",
"example": 20400.1,
"description": "The total amount of the payroll payment.\n"
},
"date_to": {
"type": "string",
"format": "date",
"example": "2018-07-31",
"nullable": true,
"description": "The end date of the payment period, in `YYYY-MM-DD` format.\n"
},
"version": {
"type": "string",
"example": "1.2",
"description": "The version of the payroll object.\n"
},
"date_from": {
"type": "string",
"format": "date",
"example": "2018-07-01",
"nullable": true,
"description": "The start date of the payment period, in `YYYY-MM-DD` format.\n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:01:41.941Z",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected.\n"
},
"payment_date": {
"type": "string",
"format": "date",
"description": "The payment date, in `YYYY-MM-DD` format.\n"
}
},
"description": "Details regarding the payroll payment. Only applicable for payroll invoices.\n"
}
InvoicesReceiverDetailsDian
{
"type": "object",
"nullable": true,
"properties": {
"email": {
"type": "string",
"example": "acme_colombia@gmail.com",
"nullable": true,
"description": "The receiver's email address.\n"
},
"address": {
"type": "string",
"example": "Calle 144 No. 12-09",
"nullable": true,
"description": "The receiver's address.\n"
},
"country": {
"type": "string",
"example": "Colombia",
"nullable": true,
"description": "The country where the receiver pays their taxes.\n"
},
"regimen": {
"type": "string",
"example": "Régimen Simple de Tributación - SIMPLE",
"nullable": true,
"description": "The receiver's regimen type.\n\nFor detailed information regarding DIAN's regimens, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"tax_scheme": {
"type": "string",
"example": "01-IVA",
"nullable": true,
"description": "The receiver's fiscal responsibilities.\n\nFor detailed information regarding DIAN's tax schemes, please see their [official PDF](https://www.dian.gov.co/impuestos/factura-electronica/Documents/Anexo_tecnico_factura_electronica_vr_1_7_2020.pdf). \n"
},
"collected_at": {
"type": "string",
"format": "date-time",
"example": "2020-04-23T21:32:55.336854+00:00",
"nullable": true,
"description": "The ISO-8601 timestamp when the data point was collected."
},
"phone_number": {
"type": "string",
"example": "576606522566|",
"nullable": true,
"description": "The receiver's phone number.\n"
},
"tax_payer_type": {
"type": "string",
"example": "Persona Natural",
"nullable": true,
"description": "Indicates if the receiver is a business or an individual. Can be either:\n \n - `Persona Jurídica`\n - `Persona Natural`\n"
}
},
"description": "Details regarding the receiver.\n"
}
InvoicesRequest
{
"type": "object",
"required": [
"date_from",
"date_to",
"link",
"type"
],
"properties": {
"link": {
"type": "string",
"format": "uuid",
"example": "d4617561-1c01-4b2f-83b6-a594f7b3bc57",
"description": "The fiscal `link.id` to use."
},
"type": {
"$ref": "#/components/schemas/EnumInvoiceType"
},
"date_to": {
"type": "string",
"example": "2020-02-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date you want to stop getting invoices for, in `YYYY-MM-DD` format.\n\n⚠️ The number of days between `date_from` and `date_to` cannot be over 365.\n\n⚠️ The value of `date_to` cannot be greater than today's date (in other words, no future dates).\n"
},
"date_from": {
"type": "string",
"example": "2020-01-01",
"pattern": "[0-9]{4}-[0-9]{2}-[0-9]{2}",
"description": "The date from which you want to start getting invoices for, in `YYYY-MM-DD` format.\n\n⚠️ The value of `date_from` cannot be greater than `date_to`.\n"
},
"save_data": {
"type": "boolean",
"default": true,
"example": true,
"description": "Indicates whether or not to persist the data in Belvo. By default, this is set to `true` and we return a 201 Created response.\n\nWhen set to `false`, the data won't be persisted and we return a 200 OK response.\n"
},
"attach_xml": {
"type": "boolean",
"default": false,
"description": "When set to `true`, you will receive the XML invoice in the\nresponse.\n"
}
}
}
InvoicesResponsePaginatedResponse
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/common_pagination_properties"
},
{
"properties": {
"results": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/InvoiceWithIdSat"
},
{
"$ref": "#/components/schemas/InvoiceDian"
}
]
},
"description": "Array of invoice objects."
}
}
}
]
}
Link
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"example": "30cb4806-6e00-48a4-91c9-ca55968576c8",
"description": "Belvo's unique ID for the current Link."
},
"status": {
"$ref": "#/components/schemas/EnumLinkStatus"
},
"stale_in": {
"type": "string",
"example": "90d",
"nullable": true,
"description": "Indicates how long any data will be stored in Belvo's database for the link (both single and recurrent), relative to the `last_accessed_at` parameter.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-02-09T08:45:50.406032Z",
"description": "The ISO-8601 timestamp of when the data point was last updated in Belvo's database.\n"
},
"created_by": {
"type": "string",
"format": "uuid",
"example": "bcef7f35-67f2-4b19-b009-cb38795faf09",
"description": "The unique ID for the user that created this link."
},
"access_mode": {
"$ref": "#/components/schemas/EnumLinkAccessModeResponse"
},
"external_id": {
"type": "string",
"example": "56ab5706-6e00-48a4-91c9-ca55968678d9",
"nullable": true,
"minLength": 3,
"description": "The `external_id` you provided as an additional identifier for the link.\nFor more information, see our [Link creation\narticle](https://developers.belvo.com/docs/link-creation-best-practices#adding-your-own-identifier).\n"
},
"institution": {
"type": "string",
"example": "erebor_mx_retail",
"description": "Belvo's name for the institution.\n"
},
"refresh_rate": {
"$ref": "#/components/schemas/EnumLinkRefreshRate"
},
"fetch_resources": {
"type": "array",
"items": {
"type": "string",
"example": "ACCOUNTS",
"description": "A Belvo resource that the institution supports."
},
"example": [
"ACCOUNTS",
"TRANSACTIONS"
],
"description": "An array of resources that you will receive a historical update for.\n"
},
"last_accessed_at": {
"type": "string",
"format": "date-time",
"example": "2019-09-27T13:02:03.584Z",
"nullable": true,
"description": "The ISO-8601 timestamp of Belvo's most recent successful access to the institution for the given link.\n"
},
"credentials_storage": {
"type": "string",
"example": "27d",
"description": "Indicates how long credentials are stored. For links where `access_mode=recurrent`, this is set to `store`.\n\nWe return one of the following values:\n\n - `store` - credentials are stored (until the link is deleted).\n - `nostore` - credentials are not stored.\n - Any value between `1d` and `365d` to indicate the number of days the credentials are stored (from when the link was `created_at`).\n \n"
},
"institution_user_id": {
"type": "string",
"example": "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c=",
"pattern": "[A-Za-z0-9\\-=_]{44}",
"description": "<div style=\"background-color:#f4f6f8; border-left: 6px solid #0663F9;padding: 12px;margin-left: 25px; border-radius: 4px; margin-right: 25px\">\n<strong>Info:</strong> Only applicable for links created <b>after 08-02-2022</b>.\n</div>\n\n\nA unique 44-character string that can be used to identify a user at a given institution.\n\n\n📚 Check out our [Avoiding duplicated links](https://developers.belvo.com/docs/link-creation-best-practices#avoiding-duplicated-links) DevPortal article for more information and tips on how to use it.\n"
}
}
}
LinksChangeAccessMode401Response
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/UnauthorizedError"
},
{
"$ref": "#/components/schemas/401_consent_without_accounts_error"
}
]
}
}
LinksChangeAccessMode404Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/NotFoundError"
},
"description": "You made a request where you:\n\n - provided the wrong URL.\n - used an ID (for a link, account, transaction, and so on) that is not associated with your Belvo account.\n \n"
}
LinksChangeAccessMode428Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenRequiredResponse"
}
}
LinksChangeAccessMode500Response
{
"type": "array",
"items": {
"$ref": "#/components/schemas/UnexpectedError"
},
"title": "Unexpected Error",
"description": "This error occurs when we (Belvo) have encountered an internal system error (sorry about that) or due to an unsupported response from the institution.\n \n"
}
LinksChangeAccessModeResponse
{
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/InvalidAccessMode"
},
{
"$ref": "#/components/schemas/TooManySessionsError"
},
{
"$ref": "#/components/schemas/LoginError"
},
{
"$ref": "#/components/schemas/SessionExpiredError"
},
{
"$ref": "#/components/schemas/ValidationError"
},
{
"$ref": "#/components/schemas/InstitutionDownError"
},
{
"$ref": "#/components/schemas/InstitutionUnavailableError"
},
{
"$ref": "#/components/schemas/InstitutionInactiveError"
},
{
"$ref": "#/components/schemas/UnsupportedOperationError"
},
{
"$ref": "#/components/schemas/InvalidLinkError"
},
{
"$ref": "#/components/schemas/UnconfirmedLinkError"
}
]
}
}