Saltar al contenido principal

Ficha técnica

Alcances necesarios​

El token para consumir la API de Recibibles del BTG Pay debe generarse utilizando el Authorization Code.

El alcance openid es obligatorio. Permite consultar el perfil del usuario BTG con acceso a la cuenta.

Es necesario incluir el siguiente alcance:

AlcanceDescripción
brn:btg:empresas:acquirer:dashboard.receivable-units.readonlyPermite la consulta de unidades recibibles del cliente

Recibibles — Visión General de la API

La API de Recibibles del BTG Pay permite que las aplicaciones asociadas consulten, en nombre del cliente, las unidades recibibles generadas por esas ventas. Esta documentación presenta los principales flujos disponibles y cómo utilizarlos para construir el dashboard del socio.

Todos los recursos son de solo lectura y reciben en el path el companyId, que es el CNPJ de la empresa cuyos datos serán consultados. Los flujos se organizan en torno al concepto central:

  • Unidad recibible — el valor neto a liquidar en una fecha futura, agrupado por marca y modalidad de venta.

Los valores monetarios están representados por objetos con los campos currency (moneda, ej.: BRL) y value (valor decimal como string, con dos decimales — ej.: "150.75").

Flujo de Recibibles​

Cada venta da origen a una o más unidades recibibles, que representan el valor neto a liquidar en una fecha futura. El flujo de recibibles permite al socio construir la agenda de cobros del cliente.

Listado de Unidades Recibibles​

El listado de unidades recibibles devuelve, para cada unidad, la fecha de pago, la marca de la tarjeta, la modalidad de venta y el valor neto a cobrar. Utilice esta consulta para mostrar la agenda de recibibles y para la conciliación financiera.

El listado acepta filtros por intervalo de fechas (startDate y endDate), por marca (cardBrand), por modalidad (saleType) y por identificador de unidad (unitId, en formato UUID). Al igual que el listado de ventas, la respuesta está paginada por cursor.

Solicitud — GET /{companyId}/acquirer/receivable-units?startDate=2026-07-01&endDate=2026-08-31&pageSize=20

Respuesta — 200 OK

{
  "_links": {
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "b2c3d4e5-6f70-4a1b-8c9d-0e1f2a3b4c5d",
      "dueDate": "2026-08-09",
      "cardBrand": "visa",
      "saleType": "credit_card",
      "balance": { "currency": "BRL", "value": "146.20" }
    }
  ]
}

El campo dueDate es la fecha de pago de la unidad recibible (formato yyyy-MM-dd) y el campo balance es el valor neto a cobrar, representado como objeto { currency, value }.

Paginación​

Los listados de ventas y de unidades recibibles utilizan paginación por cursor. Cada respuesta trae un objeto _links con los cursores prev y next. Para obtener la siguiente página, repita la solicitud indicando, en el parámetro cursor, el valor devuelto en _links.next. El cursor es opaco y debe tratarse como un identificador único de la posición del último ítem visto en la página actual. El tamaño de la página se controla mediante el parámetro pageSize.