Documentación de la API de Belvo (1.222.0)
Alcanza nuevas audiencias y convierte más usuarios conectándote fácil y seguramente a sus datos financieros, entendiendo su comportamiento y habilitando pagos instantáneos con finanzas abiertas. A través de nuestra API, puedes acceder a:
Belvo es una API de banca abierta para América Latina que permite a las empresas acceder a información bancaria y fiscal de manera segura y ágil.
A través de nuestra API, puedes acceder a:
- Información Bancaria en Brasil
- Información Laboral en Brasil
- Información Laboral en México
- Información Fiscal en México
- Información Fiscal en Chile
También puedes usar nuestra API para realizar pagos en:
- Brasil
- México
Si deseas la documentación de respuesta en formato Excel o CSV, por favor descárgalos desde nuestro Repositorio Público de GitHub: Diccionarios de Datos de Belvo Open Finance.
Nuestros archivos EXCEL y CSV están adicionalmente localizados en español y portugués (Brasil).
Disponible para:
- 🟢 Agregación y Enriquecimiento
- ⚪️ Iniciación de Pagos
Usa nuestro entorno Sandbox para construir tu integración. Ofrecemos datos ficticios que imitan casos de uso del mundo real, lo que significa que puedes probar todos los endpoints, usar el widget e implementar webhooks, tal como lo harías con datos reales.
Todo lo que necesitas para comenzar con el entorno Sandbox es obtener tus claves API. Realmente recomendamos que comiences creando tu integración en este entorno.
Disponible para:
- 🟢 Agregación y Enriquecimiento
- 🟢 Iniciación de Pagos
Después de haber probado tu integración en el entorno Sandbox y estar listo para ir en vivo, necesitarás solicitar acceso a nuestro entorno de Producción. Después de solicitar acceso, nuestro equipo de ventas se pondrá en contacto contigo para programar una reunión solo para asegurarse de que se cumplan tus necesidades, y luego solo necesitarás pasar por un proceso de certificación con uno de nuestros ingenieros para asegurarte de que tu integración esté funcionando de manera óptima. Para prepararte para la reunión de certificación, solo sigue nuestra lista de verificación de integración.
Una vez que tu integración esté certificada, todo lo que necesitarás hacer es:
- Solicitar claves API de Producción (y cambiar tus claves API de Sandbox en el código por estas nuevas).
- Cambiar la URL base a la que haces solicitudes de
sandbox.belvo.comaapi.belvo.com. - Si estás usando webhooks, asegúrate de establecer una URL de Producción para tus webhooks.
Usamos el siguiente código de estado HTTP en la respuesta dependiendo del éxito o fracaso:
| Código de Estado | Descripción |
|---|---|
200 | ✅ Éxito - El contenido está disponible en el cuerpo de la respuesta. |
201 | ✅ Éxito - El contenido fue creado exitosamente en Belvo. |
204 | ✅ Éxito - No hay contenido para devolver. |
400 | ❌ Error de Solicitud Incorrecta - La solicitud devolvió un error, detalle en el contenido. |
401 | ❌ No Autorizado - Las credenciales de Belvo proporcionadas no son válidas. |
404 | ❌ No Encontrado - El recurso al que intentas acceder no se puede encontrar. |
405 | ❌ Método No Permitido - El método HTTP que estás usando no es aceptado para este recurso. |
408 | ❌ Tiempo de Solicitud Agotado - La solicitud se agotó y fue terminada por el servidor. |
428 | ❌ Se Requiere Token MFA - La institución requirió un token MFA para conectar. |
500 | ❌ Error Interno del Servidor - El detalle del error está disponible en el cuerpo de la respuesta. |
Los errores de la API de Belvo se devuelven en formato JSON. Por ejemplo, un error podría verse así:
[
{
"request_id": "a6e1c493d7a29d91aed4338e6fcf077d",
"message": "Este campo es obligatorio.",
"code": "required",
"field": "link"
}
]Típicamente, una respuesta de error tendrá los siguientes parámetros:
request_id: un ID único para la solicitud, debes compartirlo con el equipo de soporte de Belvo para investigaciones.message: descripción del error en lenguaje humano.code: un código único para el error. Consulta la tabla a continuación para ver cómo manejar cada código de error.field(opcional): El campo específico en el cuerpo de la solicitud que tiene un problema.
Cuando necesites ayuda con un error específico, incluye el identificador de solicitud (request_id) en tu mensaje al equipo de soporte de Belvo. Esto acelerará las investigaciones y te permitirá volver a funcionar en poco tiempo.
Para una lista completa de errores y cómo solucionarlos, por favor consulta nuestro artículo dedicado Manejo de Errores.
Implementa un retroceso exponencial automatizado de hasta cinco reintentos. Recomendamos usar un intervalo base de tres segundos con un factor de dos. Por ejemplo, el primer reintento debe ser después de tres segundos, el segundo reintento después de seis segundos (2 * 3), el tercer reintento después de 12 segundos (2 * 6), el cuarto reintento después de 24 segundos (2 * 12), y el quinto reintento después de 48 segundos (2 * 24).
No debes reintentar hacer solicitudes si recibes una respuesta 40x, ya que esto es un error del cliente.
La única excepción es el error de "Demasiadas Sesiones", ya que significa que tu usuario final está accediendo a la cuenta desde otro navegador al mismo tiempo. En este caso, por favor implementa la misma política de reintentos que con los errores 50x.
En nuestro esquema, puedes ver que un campo ha sido marcado como deprecated. Esto significa que este campo ya no es mantenido por el equipo de Belvo. Aún puedes recibir datos para este campo dependiendo de la institución, sin embargo, no debes confiar en este campo.
En nuestra especificación de API, verás que algunos parámetros de respuesta tendrán una anotación de required. Según la especificación de OpenAPI, cuando un parámetro de respuesta está marcado como required, esto significa que la clave de respuesta debe ser devuelta. Sin embargo, el valor de ese parámetro de respuesta puede ser null.
📘 Info
En resumen, cualquier parámetro de respuesta marcado como requerido será devuelto por nuestra API, pero el valor puede ser establecido en null.
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/
https://sandbox.belvo.com/
Institutions
Una institución es una entidad de la que Belvo puede acceder a información. Puede ser una:
- institución bancaria, como Nubank Brasil.
- institución fiscal, como el Servicio de Administración Tributaria (SAT) en México.
- institución de empleo, como el Instituto Mexicano del Seguro Social (IMSS) en México o el Instituto Nacional do Seguro Social (INSS) en Brasil.
Links
Un Link es un conjunto de credenciales asociadas al acceso de un usuario final a una institución. Necesitarás registrar un Link antes de acceder a la información de ese usuario final específico, como los detalles de cuenta o transacciones.
Recomendamos usar el Belvo Hosted Widget para gestionar el proceso de conexión.
Owners
Un owner representa a la persona que tiene acceso a un Link y es el propietario de todas las cuentas dentro del Link.
Puedes usar este endpoint para obtener información útil sobre tu cliente, como:
- su nombre completo
- información de contacto clave
- información sobre el documento de identificación que usaron al abrir la cuenta
Accounts
Una cuenta es la representación de una cuenta bancaria dentro de una institución financiera. Un usuario puede tener una o más cuentas en una institución.
Por ejemplo, un usuario (o enlace) puede tener una cuenta corriente, varias tarjetas de crédito y una cuenta de préstamo.
Consultar la información de la cuenta de un usuario es útil ya que puedes obtener información sobre:
- qué tipos de cuentas tiene el usuario.
- el saldo de cada cuenta (ahorros, cuenta corriente, tarjeta de crédito, préstamo, etc.).
- información detallada sobre sus gastos con tarjeta de crédito.
- la situación actual de cualquier préstamo que puedan tener.
Employments Brazil
Nuestro recurso de empleos para Brasil te permite obtener una vista completa del historial laboral actual de tu usuario y la información salarial.
Para cada usuario, proporcionamos:
- historial laboral (incluyendo ocupaciones y datos del empleador)
- información salarial histórica y actual (por empleador)
En este momento, el recurso de empleos está disponible para:
- 🇧🇷 Brasil (INSS)
Employment Records Mexico
Nuestro recurso de registros de empleo para México te permite obtener una visión completa de las contribuciones actuales al seguro social y el historial laboral de tu usuario.
Con el recurso de registros de empleo de Belvo para México, puedes acceder a información sobre las contribuciones actuales al seguro social y el historial laboral de tu usuario. Para cada usuario, proporcionamos:
- datos personales
- historial laboral
- salario base diario histórico y actual
- ¡y más!
En este momento, el recurso de registros de empleo está disponible para:
- 🇲🇽 México (IMSS)
- 🇲🇽 México (ISSSTE)
Current Employments Mexico
El recurso de Empleos Actuales proporciona acceso en tiempo real al estado de empleo actual de individuos en México. Este recurso ofrece información detallada sobre si una persona está actualmente empleada o desempleada, junto con sus registros de empleo activos.
Solicitud
▶️ Uso
Con el método Listar Facturas, puedes:
- Listar facturas relacionadas con un
link.idespecífico (usando el parámetro de consultalink). - Obtener los detalles de un
invoice.idespecífico (usando el parámetro de consultaid). - [No Recomendado] Listar todas las facturas relacionadas con tu cuenta de Belvo (sin usar ningún parámetro de consulta).
📖 Paginación
Este método devuelve una respuesta paginada (por defecto: 100 elementos por página). Puedes usar el parámetro de consulta page_size para aumentar el número de elementos devueltos hasta un máximo de 1000 elementos. Puedes usar el parámetro de consulta page para navegar a través de los resultados. Para más detalles sobre cómo navegar por las respuestas paginadas de Belvo, consulta nuestro artículo Consejos de Paginación.
🔦 Filtrado de Respuestas
Consulta la lista de campos a continuación para ver una lista de campos por los que puedes filtrar tus respuestas. Para más información sobre cómo usar filtros, consulta nuestro artículo Filtrado de respuestas.
🚨 Campos Obsoletos
Este recurso puede devolver campos obsoletos. En la documentación de la respuesta, puedes ver que un campo ha sido marcado como obsoleto. Esto significa que este campo ya no es mantenido por el equipo de Belvo. Aún puedes recibir datos para este campo dependiendo de la institución, sin embargo, no deberías depender de este campo.
El link.id por el que deseas filtrar.
ℹ️ Recomendamos encarecidamente añadir el filtro link.id para mejorar tu rendimiento.
Un número de página dentro del conjunto de resultados paginados.
Indica cuántos resultados devolver por página. Por defecto, devolvemos 100 resultados por página.
ℹ️ El número mínimo de resultados devueltos por página es 1 y el máximo es 1000. Si introduces un valor mayor que 1000, nuestra API usará por defecto el valor máximo (1000).
Devuelve resultados solo para estos link.ids.
Omite ciertos campos para que no se devuelvan en la respuesta. Para más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
Devuelve solo los campos especificados en la respuesta. Para obtener más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
Devuelve información solo para este recurso id.
Devuelve información para estos ids de recursos.
Devuelve los elementos que se actualizaron por última vez en la base de datos de Belvo en esta fecha (en formato YYYY-MM-DD).
Devuelve los elementos que se actualizaron por última vez en la base de datos de Belvo después de esta fecha (en formato YYYY-MM-DD).
Devuelve los elementos que se actualizaron por última vez en la base de datos de Belvo después o en esta fecha (en formato YYYY-MM-DD).
Devuelve los elementos que se actualizaron por última vez en la base de datos de Belvo antes de esta fecha (en formato YYYY-MM-DD).
Devuelve los elementos que se actualizaron por última vez en la base de datos de Belvo antes o en esta fecha (en formato YYYY-MM-DD).
Devolver cuentas que fueron actualizadas por última vez en la base de datos de Belvo entre dos fechas (en formato YYYY-MM-DD).
Devolver facturas emitidas exactamente en esta fecha (YYYY-MM-DD).
Devuelve los saldos emitidos antes de esta fecha (YYYY-MM-DD).
Devuelve los saldos emitidos en esta fecha o antes (YYYY-MM-DD).
Devolver facturas emitidas después de esta fecha (YYYY-MM-DD).
Devolver facturas emitidas en esta fecha o posterior (YYYY-MM-DD)
Devolver facturas emitidas dentro de este rango de fechas (YYYY-MM-DD).
Devuelve una factura con este ID (según lo proporcionado por la institución).
Devuelve las facturas con estos IDs (según lo proporcionado por la institución).
Devuelve las facturas con este estado. Puede ser Vigente (válido) o Cancelado (cancelado).
Devolver facturas con estos estados. Pueden ser Vigente (válido) o Cancelado (cancelado).
Devolver facturas de este tipo. Puede ser OUTFLOW o INFLOW.
Devolver facturas de estos tipos. Puede ser OUTFLOW o INFLOW.
Devolver facturas que coincidan exactamente con este valor.
Devolver facturas menores que este valor.
Devolver facturas menores o iguales a este valor.
Devolver facturas mayores que este valor.
Devolver facturas mayores o iguales a este valor.
- Mock server
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/invoices/
- Sandbox
https://sandbox.belvo.com/api/invoices/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/invoices/?link=8848bd0c-9c7e-4f53-a732-ec896b11d4c4&page=1&page_size=100&link__in=5722d0ba-69d7-42dc-8ff5-33767b83c5d6&omit=string&fields=string&id=24ccab1d-3a86-4136-a6eb-e04bf52b356f&id__in=6b3dea0f-be29-49d1-aabe-1a6d588642e6&created_at=2022-05-05&created_at__gt=2022-05-05&created_at__gte=2022-05-04&created_at__lt=2022-04-01&created_at__lte=2022-03-30&created_at__range=2022-03-03&invoice_date=2022-05-05&invoice_date__lt=2022-03-02&invoice_date__lte=2022-03-01&invoice_date__gt=2022-05-06&invoice_date__gte=2022-05-04&invoice_date__range=2022-05-06&invoice_identification=862B9918-3K6H-4E0B-NAI9-2BE2D833B840&invoice_identification__in=992B9918-3G6H-4E0B-DAI9-2BE2D833B833&status=Vigente&status__in=Cancelado&type=OUTFLOW&type__in=OUTFLOW&total_amount=1000.02&total_amount__lt=540.02&total_amount__lte=541.02&total_amount__gt=520.02&total_amount__gte=519.02&total_amount__range=541.02'De acuerdo
La URL a la siguiente página de resultados. Cada página consta de hasta 100 elementos. Si no hay suficientes resultados para una página adicional, el valor es null.
En nuestro ejemplo de documentación, usamos {endpoint} como un valor de marcador de posición. En producción, este valor será reemplazado por el endpoint real que estás utilizando actualmente (por ejemplo, accounts o owners).
La URL a la página anterior de resultados. Si no hay una página anterior, el valor es null.
Ejemplo de una factura de tipo Ingreso.
{ "count": 110, "next": "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2", "previous": null, "results": [ { … } ] }
Solicitud
Recuperar información de la factura desde un enlace fiscal específico.
📘 Información
Puedes solicitar hasta un año (365 días) de facturas por solicitud. Si necesitas facturas por más de un año, simplemente realiza otra solicitud.
🚧 Advertencia
Este recurso puede devolver campos obsoletos. Por favor, consulta la documentación de la respuesta para más información.
Omite ciertos campos para que no se devuelvan en la respuesta. Para más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
Devuelve solo los campos especificados en la respuesta. Para obtener más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
Parámetro de encabezado recomendado para hacer que tu solicitud POST sea asincrónica (evitando así tiempos de espera y mejorando el flujo de datos).
Cuando realizas una solicitud asincrónica, Belvo responde con un payload 202 - Accepted, que incluye el request_id. Una vez que hayamos recuperado la información solicitada, recibirás un webhook con el enlace y los IDs de solicitud.
El link.id para el que deseas recuperar información.
La fecha desde la cual deseas comenzar a obtener datos, en formato YYYY-MM-DD.
⚠️ El valor de date_from no puede ser mayor que date_to.
La fecha en la que deseas dejar de recibir datos, en formato YYYY-MM-DD.
⚠️ El valor de date_to no puede ser mayor que la fecha de hoy (en otras palabras, no se permiten fechas futuras).
La dirección de la factura (desde la perspectiva del propietario del Link).
OUTFLOWindica una factura enviada.INFLOWindica una factura recibida.
Cuando se establece en true, recibirás la factura XML en la respuesta.
- Mock server
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/invoices/
- Sandbox
https://sandbox.belvo.com/api/invoices/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/invoices/?omit=string&fields=string' \
-H 'Content-Type: application/json' \
-H 'X-Belvo-Request-Mode: async' \
-d '{
"link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
"date_from": "2020-08-05",
"date_to": "2020-10-05",
"type": "INFLOW",
"attach_xml": false,
"save_data": true
}'Ok (cuando save_data=false)
Identificador único de Belvo para el elemento actual.
El link.id al que pertenecen los datos.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo.
El ID único de la institución fiscal para la factura.
La fecha de la factura, en formato YYYY-MM-DD.
El estado de la factura. Puede ser Vigente (válido) o Cancelado (cancelado).
La clasificación de la factura por parte de la institución fiscal.
Para el SAT de México, devolvemos uno de los siguientes valores:
EgresoIngresoNóminaPagoTraslado
La dirección de la factura (desde la perspectiva del propietario del Link).
OUTFLOWindica una factura enviada.INFLOWindica una factura recibida.
El régimen fiscal del remitente, según lo definido por la entidad legal en el país.
Indica si el remitente está o no en la lista de fraude fiscal del SAT por haber presentado datos incorrectos, tener pagos pendientes o haber realizado negocios que violan las regulaciones de la institución fiscal.
El SAT actualiza la lista de fraude fiscal cada tres meses.
Para más información sobre las razones por las cuales un contribuyente puede ser incluido en la lista de fraude fiscal, consulte el Artículo 69 y el Artículo 69-B del Código Fiscal de la Federación de México.
Los estados posibles son:
INVESTIGATING
La institución fiscal ha identificado irregularidades y ha abierto una investigación sobre el contribuyente.DISMISSED
La institución fiscal ha investigado al contribuyente y lo ha declarado inocente.CONFIRMED
La institución fiscal ha confirmado que el contribuyente es culpable.OVERTURNED
La institución fiscal ha reevaluado a un contribuyente previamente confirmado y, basándose en nueva evidencia, lo ha retirado de la lista de fraude fiscal.NO_TAX_FRAUD_STATUS
El receptor o remitente no se encuentra en la lista (en otras palabras, están cumpliendo con las regulaciones de la institución fiscal).
El régimen fiscal del receptor, según lo definido por la entidad legal en el país.
Indica si el receptor está o no en la lista de fraude fiscal del SAT por haber presentado datos incorrectos, tener pagos pendientes o haber realizado negocios que violan las regulaciones de la institución fiscal.
El SAT actualiza la lista de fraude fiscal cada tres meses.
Para obtener más información sobre las razones por las cuales un contribuyente puede ser incluido en la lista de fraude fiscal, consulte el Artículo 69 y el Artículo 69-B del Código Fiscal de la Federación de México.
Los estados posibles son:
INVESTIGATING
La institución fiscal ha identificado irregularidades y ha abierto una investigación sobre el contribuyente.DISMISSED
La institución fiscal ha investigado al contribuyente y lo ha declarado inocente.CONFIRMED
La institución fiscal ha confirmado que el contribuyente es culpable.OVERTURNED
La institución fiscal ha reevaluado a un contribuyente previamente confirmado y, basándose en nueva evidencia, lo ha retirado de la lista de fraude fiscal.NO_TAX_FRAUD_STATUS
El receptor o emisor no se encuentra en la lista (en otras palabras, está cumpliendo con las regulaciones de la institución fiscal).
Si la factura es cancelada, este campo indica el estado de la cancelación.
La fecha de la cancelación de la factura, en formato YYYY-MM-DD.
La fecha de la certificación fiscal, en formato YYYY-MM-DD.
El ID fiscal del proveedor de certificación.
El código de tipo de pago utilizado para esta factura, según lo definido por la entidad legal del país.
- 🇲🇽 México Artículo de referencia del catálogo SAT
El código del método de pago utilizado para esta factura, según lo definido por la entidad legal del país.
- 🇲🇽 México artículo de referencia del catálogo SAT. Para México, devolvemos
PUE,PPDonull.
El código de uso de la factura, tal como lo define la entidad legal del país.
Una lista de descripciones para cada artículo (producto comprado o servicio prestado) en la factura.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
La descripción del artículo de la factura (una factura puede tener uno o más artículos).
El código de identificación del producto o del servicio, tal como lo define la entidad legal en el país.\n- \U0001F1F2\U0001F1FD México.
La unidad de medida, según lo definido por la entidad legal en el país. \n- \U0001F1F2\U0001F1FD México Referencia del catálogo SAT.
La descripción del artículo, según lo definido por la entidad legal en el país.\n- \U0001F1F2\U0001F1FD México Referencia del catálogo SAT.
El precio total de este artículo antes de aplicar impuestos es (quantity x unit_amount).
El monto del impuesto para este artículo de factura (pre_tax_amount x tax_percentage).
El precio total para este artículo de factura (pre_tax_amount + tax_amount).
La moneda de la factura. Por ejemplo:
- 🇧🇷 BRL (Real Brasileño)
- 🇨🇴 COP (Peso Colombiano)
- 🇲🇽 MXN (Peso Mexicano)
- 🇺🇸 USD (Dólar Estadounidense)
El monto antes de impuestos de esta factura (suma del pre_tax_amount de cada artículo).
El tipo de cambio utilizado en esta factura para la moneda.
El monto del impuesto para esta factura (suma del tax_amount de cada artículo).
El monto total de la factura (subtotal_amount + tax_amount - discount_amount)
Una lista que detalla todos los pagos de facturas.
Marca de tiempo ISO-8601 cuando se realizó el pago.
Código de tipo de pago utilizado para esta factura, según lo definido por la entidad legal del país.
- 🇲🇽 México Artículo de referencia del catálogo SAT
La moneda del pago. Por ejemplo:
- 🇧🇷 BRL (Real Brasileño)
- 🇨🇴 COP (Peso Colombiano)
- 🇲🇽 MXN (Peso Mexicano)
Tenga en cuenta que pueden devolverse otras monedas además de las enumeradas anteriormente.
La tasa de cambio de currency a MXN cuando se realizó el pago.
El monto de la factura, en la moneda de la factura original.
El identificador interno de la institución fiscal para la operación.
El número de cuenta bancaria del beneficiario del pago.
El número de cuenta bancaria del emisor del pago.
La institución bancaria que fue utilizada por el emisor del pago.
Una lista de todas las facturas diferidas relacionadas afectadas por el pago.
El ID único de la institución fiscal para la factura diferida relacionada.
La moneda de la factura relacionada. Por ejemplo:
- 🇧🇷 BRL (Real Brasileño)
- 🇨🇴 COP (Peso Colombiano)
- 🇲🇽 MXN (Peso Mexicano)
Tenga en cuenta que pueden devolverse otras monedas además de las enumeradas anteriormente.
El monto de la factura antes del pago.
Detalles sobre el pago de nómina. Solo aplicable para facturas de nómina.
El tipo de nómina, según lo definido por la entidad legal del país.
- 🇲🇽 México Artículo de referencia del catálogo SAT
La fecha de inicio del período de pago, en formato YYYY-MM-DD.
La fecha de finalización del período de pago, en formato YYYY-MM-DD.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
Con qué frecuencia se realiza el pago de nómina.
Para el SAT de México, devolvemos uno de los siguientes valores:
DAILYWEEKLYTENTH_DAYFOURTEENTH_DAYFIFTEENTH_DAYMONTHLYBIMONTHLYPER_TASKCOMMISSIONONE_OFFOTHER_PERIODICITY
Un desglose de las ganancias para el pago de nómina.
Un desglose de las deducciones fiscales en el pago de nómina.
El número de control interno que el contribuyente asigna a la factura.
El tipo de exportación de la factura, según lo definido por la entidad legal en el país. Para más información, consulta nuestro artículo de referencia del catálogo SAT.
Objeto que contiene información sobre cualquier advertencia relacionada con esta factura.
Este campo ha quedado obsoleto. Para obtener más información sobre Belvo y la obsolescencia, consulte nuestra explicación de Campos obsoletos.
Este campo ha sido desaprobado. Para obtener más información sobre Belvo y la desaprobación, consulte nuestra explicación de Campos desaprobados.
La descripción del método de pago utilizado para esta factura.
Este campo ha sido desaprobado. Para obtener más información sobre Belvo y la desaprobación, consulte nuestra explicación de Campos desaprobados. Por favor, use sender_tax_fraud_status en su lugar.
Este campo ha sido desaprobado. Para obtener más información sobre Belvo y la desaprobación, consulte nuestra explicación de Campos desaprobados. Por favor, use receiver_tax_fraud_status en su lugar.
Ejemplo de una factura de tipo Ingreso.
[ { "id": "90d90e38-0087-4b6d-b6dc-94ea561bb9cb", "link": "1bd948f7-245d-4313-b604-34d1044cb908", "collected_at": "2022-02-09T08:45:50.406032Z", "created_at": "2022-02-09T08:46:20.406032Z", "invoice_identification": "862B9918-3K6H-4E0B-NAI9-2BE2D833B840", "invoice_date": "2020-12-24", "status": "Vigente", "invoice_type": "Ingreso", "type": "OUTFLOW", "sender_id": "GHTF980303F7", "sender_name": "Roberto Martinez Diaz", "sender_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "receiver_id": "MNMK3203409H1", "receiver_name": "ACNE SA DE CV", "receiver_tax_fraud_status": "NO_TAX_FRAUD_STATUS", "cancelation_status": null, "cancelation_update_date": null, "certification_date": "2020-12-24", "certification_authority": "FGV330542BG6", "payment_type": "04", "payment_type_description": null, "payment_method": "PUE", "usage": "G03", "place_of_issue": "11000", "version": "3.3", "invoice_details": [ … ], "currency": "MXN", "subtotal_amount": 25, "exchange_rate": 1, "tax_amount": 4, "discount_amount": 0, "total_amount": 29, "payments": [], "payroll": null, "folio": "28", "xml": "=XML-STRING=", "warnings": { … } } ]
Omite ciertos campos para que no se devuelvan en la respuesta. Para más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
Devuelve solo los campos especificados en la respuesta. Para obtener más información, consulta nuestro artículo del DevPortal Filtrando respuestas.
La sesión que deseas reanudar. Necesitas usar el valor de session que se proporciona en la respuesta 428 Token Required que recibes después de realizar tu solicitud POST.
El token MFA generado por la institución que se requiere para continuar una sesión.
El link.id que deseas reanudar. Debe ser el mismo link.id que recibes en la respuesta 428 Token Required que contiene el ID de session.
- Mock server
https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/invoices/
- Sandbox
https://sandbox.belvo.com/api/invoices/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PATCH \
-u <username>:<password> \
'https://developers.belvo.com/_mock/es/apis/belvoopenapispec/api/invoices/?omit=string&fields=string' \
-H 'Content-Type: application/json' \
-d '{
"session": "6e7b283c6efa449c9c028a16b5c249fa",
"token": "1234ab",
"link": "683005d6-f45c-4adb-b289-f1a12f50f80c",
"save_data": true
}'Ok (cuando save_data=false)
Identificador único de Belvo para el elemento actual.
El link.id al que pertenecen los datos.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
La marca de tiempo ISO-8601 de cuando se creó el punto de datos en la base de datos de Belvo.
El ID único de la institución fiscal para la factura.
La fecha de la factura, en formato YYYY-MM-DD.
El estado de la factura. Puede ser Vigente (válido) o Cancelado (cancelado).
La clasificación de la factura por parte de la institución fiscal.
Para el SAT de México, devolvemos uno de los siguientes valores:
EgresoIngresoNóminaPagoTraslado
La dirección de la factura (desde la perspectiva del propietario del Link).
OUTFLOWindica una factura enviada.INFLOWindica una factura recibida.
El régimen fiscal del remitente, según lo definido por la entidad legal en el país.
Indica si el remitente está o no en la lista de fraude fiscal del SAT por haber presentado datos incorrectos, tener pagos pendientes o haber realizado negocios que violan las regulaciones de la institución fiscal.
El SAT actualiza la lista de fraude fiscal cada tres meses.
Para más información sobre las razones por las cuales un contribuyente puede ser incluido en la lista de fraude fiscal, consulte el Artículo 69 y el Artículo 69-B del Código Fiscal de la Federación de México.
Los estados posibles son:
INVESTIGATING
La institución fiscal ha identificado irregularidades y ha abierto una investigación sobre el contribuyente.DISMISSED
La institución fiscal ha investigado al contribuyente y lo ha declarado inocente.CONFIRMED
La institución fiscal ha confirmado que el contribuyente es culpable.OVERTURNED
La institución fiscal ha reevaluado a un contribuyente previamente confirmado y, basándose en nueva evidencia, lo ha retirado de la lista de fraude fiscal.NO_TAX_FRAUD_STATUS
El receptor o remitente no se encuentra en la lista (en otras palabras, están cumpliendo con las regulaciones de la institución fiscal).
El régimen fiscal del receptor, según lo definido por la entidad legal en el país.
Indica si el receptor está o no en la lista de fraude fiscal del SAT por haber presentado datos incorrectos, tener pagos pendientes o haber realizado negocios que violan las regulaciones de la institución fiscal.
El SAT actualiza la lista de fraude fiscal cada tres meses.
Para obtener más información sobre las razones por las cuales un contribuyente puede ser incluido en la lista de fraude fiscal, consulte el Artículo 69 y el Artículo 69-B del Código Fiscal de la Federación de México.
Los estados posibles son:
INVESTIGATING
La institución fiscal ha identificado irregularidades y ha abierto una investigación sobre el contribuyente.DISMISSED
La institución fiscal ha investigado al contribuyente y lo ha declarado inocente.CONFIRMED
La institución fiscal ha confirmado que el contribuyente es culpable.OVERTURNED
La institución fiscal ha reevaluado a un contribuyente previamente confirmado y, basándose en nueva evidencia, lo ha retirado de la lista de fraude fiscal.NO_TAX_FRAUD_STATUS
El receptor o emisor no se encuentra en la lista (en otras palabras, está cumpliendo con las regulaciones de la institución fiscal).
Si la factura es cancelada, este campo indica el estado de la cancelación.
La fecha de la cancelación de la factura, en formato YYYY-MM-DD.
La fecha de la certificación fiscal, en formato YYYY-MM-DD.
El ID fiscal del proveedor de certificación.
El código de tipo de pago utilizado para esta factura, según lo definido por la entidad legal del país.
- 🇲🇽 México Artículo de referencia del catálogo SAT
El código del método de pago utilizado para esta factura, según lo definido por la entidad legal del país.
- 🇲🇽 México artículo de referencia del catálogo SAT. Para México, devolvemos
PUE,PPDonull.
El código de uso de la factura, tal como lo define la entidad legal del país.
Una lista de descripciones para cada artículo (producto comprado o servicio prestado) en la factura.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
La descripción del artículo de la factura (una factura puede tener uno o más artículos).
El código de identificación del producto o del servicio, tal como lo define la entidad legal en el país.\n- \U0001F1F2\U0001F1FD México.
La unidad de medida, según lo definido por la entidad legal en el país. \n- \U0001F1F2\U0001F1FD México Referencia del catálogo SAT.
La descripción del artículo, según lo definido por la entidad legal en el país.\n- \U0001F1F2\U0001F1FD México Referencia del catálogo SAT.
El precio total de este artículo antes de aplicar impuestos es (quantity x unit_amount).
El monto del impuesto para este artículo de factura (pre_tax_amount x tax_percentage).
El precio total para este artículo de factura (pre_tax_amount + tax_amount).
La moneda de la factura. Por ejemplo:
- 🇧🇷 BRL (Real Brasileño)
- 🇨🇴 COP (Peso Colombiano)
- 🇲🇽 MXN (Peso Mexicano)
- 🇺🇸 USD (Dólar Estadounidense)
El monto antes de impuestos de esta factura (suma del pre_tax_amount de cada artículo).
El tipo de cambio utilizado en esta factura para la moneda.
El monto del impuesto para esta factura (suma del tax_amount de cada artículo).
El monto total de la factura (subtotal_amount + tax_amount - discount_amount)
Una lista que detalla todos los pagos de facturas.
Marca de tiempo ISO-8601 cuando se realizó el pago.
Código de tipo de pago utilizado para esta factura, según lo definido por la entidad legal del país.
- 🇲🇽 México Artículo de referencia del catálogo SAT
La moneda del pago. Por ejemplo:
- 🇧🇷 BRL (Real Brasileño)
- 🇨🇴 COP (Peso Colombiano)
- 🇲🇽 MXN (Peso Mexicano)
Tenga en cuenta que pueden devolverse otras monedas además de las enumeradas anteriormente.
La tasa de cambio de currency a MXN cuando se realizó el pago.
El monto de la factura, en la moneda de la factura original.
El identificador interno de la institución fiscal para la operación.
El número de cuenta bancaria del beneficiario del pago.
El número de cuenta bancaria del emisor del pago.
La institución bancaria que fue utilizada por el emisor del pago.
Una lista de todas las facturas diferidas relacionadas afectadas por el pago.
El ID único de la institución fiscal para la factura diferida relacionada.
La moneda de la factura relacionada. Por ejemplo:
- 🇧🇷 BRL (Real Brasileño)
- 🇨🇴 COP (Peso Colombiano)
- 🇲🇽 MXN (Peso Mexicano)
Tenga en cuenta que pueden devolverse otras monedas además de las enumeradas anteriormente.
El monto de la factura antes del pago.
Detalles sobre el pago de nómina. Solo aplicable para facturas de nómina.
El tipo de nómina, según lo definido por la entidad legal del país.
- 🇲🇽 México Artículo de referencia del catálogo SAT
La fecha de inicio del período de pago, en formato YYYY-MM-DD.
La fecha de finalización del período de pago, en formato YYYY-MM-DD.
La marca de tiempo ISO-8601 cuando se recopiló el punto de datos.
Con qué frecuencia se realiza el pago de nómina.
Para el SAT de México, devolvemos uno de los siguientes valores:
DAILYWEEKLYTENTH_DAYFOURTEENTH_DAYFIFTEENTH_DAYMONTHLYBIMONTHLYPER_TASKCOMMISSIONONE_OFFOTHER_PERIODICITY
Un desglose de las ganancias para el pago de nómina.
Un desglose de las deducciones fiscales en el pago de nómina.
El número de control interno que el contribuyente asigna a la factura.
El tipo de exportación de la factura, según lo definido por la entidad legal en el país. Para más información, consulta nuestro artículo de referencia del catálogo SAT.
Objeto que contiene información sobre cualquier advertencia relacionada con esta factura.
Este campo ha quedado obsoleto. Para obtener más información sobre Belvo y la obsolescencia, consulte nuestra explicación de Campos obsoletos.
Este campo ha sido desaprobado. Para obtener más información sobre Belvo y la desaprobación, consulte nuestra explicación de Campos desaprobados.
La descripción del método de pago utilizado para esta factura.
Este campo ha sido desaprobado. Para obtener más información sobre Belvo y la desaprobación, consulte nuestra explicación de Campos desaprobados. Por favor, use sender_tax_fraud_status en su lugar.
Este campo ha sido desaprobado. Para obtener más información sobre Belvo y la desaprobación, consulte nuestra explicación de Campos desaprobados. Por favor, use receiver_tax_fraud_status en su lugar.
[ { "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": { … }, "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_status": "string", "cancelation_update_date": "2019-12-02", "certification_date": "2019-12-01", "certification_authority": "CCC333333CC33", "payment_type": "99", "payment_type_description": null, "payment_method": "PUE", "payment_method_description": null, "usage": "P01", "version": "3.3", "place_of_issue": "01165", "invoice_details": [ … ], "currency": "MXN", "subtotal_amount": 400, "exchange_rate": 0.052, "tax_amount": 64, "discount_amount": 10, "total_amount": 454, "related_invoices": [ … ], "payments": [ … ], "payroll": { … }, "folio": "26", "export_type": "01", "xml": "string", "warnings": { … }, "sender_blacklist_status": null, "receiver_blacklist_status": null } ]
Incomes
Utiliza el endpoint de Incomes para obtener información sobre las fuentes de ingresos de una cuenta en los últimos 365 días. Este endpoint es particularmente útil cuando deseas verificar los ingresos de una persona.
📘 Información
El recurso de incomes está solo disponible para cuentas de Checking y Savings asociadas con enlaces bancarios.
Recurring Expenses
La API de Gastos Recurrentes de Belvo te permite identificar los pagos regulares de un usuario para servicios de suscripción, como Netflix o membresías de gimnasio, así como pagos de servicios públicos, como facturas de electricidad o teléfono. Devolvemos información de hasta 365 días.
📘 Info
El recurso de gastos recurrentes está solo disponible para cuentas de Cheques, Ahorros y Tarjetas de Crédito asociadas con enlaces bancarios.
Customers (Brazil)
Un cliente es el pagador que va a transferir fondos a tu cuenta bancaria. Necesitas crear un cliente para recibir pagos entrantes en la cuenta bancaria de tu organización.
Este endpoint admite versionado a nivel de recurso. Al incluir el encabezado X-Belvo-API-Resource-Version: Payments-BR.V2, puedes acceder a los formatos de solicitud y respuesta más recientes (V2). Si no se proporciona el encabezado, se utilizará el formato predeterminado (V1). Consulta la documentación de la API para obtener detalles sobre las diferencias entre versiones.
Bank Accounts (Brazil)
Para recibir pagos entrantes en la cuenta bancaria de su organización, debe registrar las cuentas bancarias (individuales y comerciales) utilizando la API de Pagos de Belvo.
- Las cuentas bancarias individuales deben ser creadas para cada pagador (su cliente).
- Las cuentas bancarias comerciales deben ser creadas para el beneficiario del pago (su organización).
Este endpoint admite el versionado a nivel de recurso. Al incluir el encabezado X-Belvo-API-Resource-Version: Payments-BR.V2, puede acceder a los formatos de solicitud y respuesta más recientes (V2). Si no se proporciona el encabezado, se utilizará el formato predeterminado (V1). Consulte la documentación de la API para obtener detalles sobre las diferencias entre versiones.
Payment Intents (Brazil)
Un payment intent es un punto único de acceso para crear pagos utilizando cualquier método de pago ofrecido por Belvo.
Un payment intent captura toda la información del pago (como el monto a cobrar, la descripción del pago, el proveedor, etc.) y guía a tus clientes a través del flujo de pago.
Nota: Para las instituciones que requieren el
username_typeen el arrayform_fields, debes enviar este valor en tu solicitud PATCH.