Saltar al contenido principal

Ficha técnica

Alcances necesarios​

El token para consumir la API de Ventas de BTG Pay debe ser generado usando 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.sales.readonlyPermite la consulta de ventas.

Ventas — Visión General de la API

La API de Ventas de BTG Pay permite que las aplicaciones asociadas consulten, en nombre del cliente, el historial de ventas. Esta documentación presenta los principales flujos disponibles y cómo utilizarlos para construir el dashboard del asociado.

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:

  • Venta — la transacción capturada, con su monto bruto, monto neto, método de pago y el canal donde fue realizada.

Los valores monetarios son representados por objetos con los campos currency (moneda, ej.: BRL) y value (valor decimal como string, con dos decimales — ej.: "150.75"). Los enums de modalidad, canal y marca son retornados en minúsculas (credit_card, pos, visa).

Flujo de Ventas​

El flujo de ventas proporciona visibilidad sobre las transacciones del cliente. A partir de él, el asociado construye la lista de ventas del dashboard y profundiza en cada transacción individual.

Listado de Ventas​

El punto de entrada del flujo es el listado de ventas. Retorna el historial de transacciones capturadas, permitiendo que su aplicación muestre, para cada venta, la modalidad de pago, el canal, los montos bruto y neto y las fechas del ciclo de vida de la transacción.

El listado acepta filtros por intervalo de fechas (startDate y endDate, en el formato yyyy-MM-dd), por marca de tarjeta (cardBrand) y por modalidad de venta (saleType — credit_card, debit_card o pix). La respuesta está paginada por cursor: cada página trae el cursor de la siguiente en _links.next, que debe ser enviado en el parámetro cursor para avanzar. Cuando next viene null, no hay más páginas.

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

Respuesta — 200 OK

{
  "_links": {
    "prev": null,
    "next": {
      "href": "/30306294000145/acquirer/sales?cursor=eyJpZCI6Ii4uLiJ9",
      "method": "GET"
    }
  },
  "data": [
    {
      "id": "8f3a1c2e-0b4d-4e2a-9c1f-7a6b5d4e3c2b",
      "type": "credit_card",
      "channel": "pos",
      "grossAmount": { "currency": "BRL", "value": "150.75" },
      "netAmount": { "currency": "BRL", "value": "146.20" },
      "paymentMethod": {
        "cardBrand": "visa",
        "cardNumber": "**** **** **** 1234",
        "installments": 3
      },
      "saleDate": "2026-07-10T14:32:05Z",
      "capturedAt": "2026-07-10T14:32:07Z",
      "authorizedAt": "2026-07-10T14:32:06Z"
    }
  ]
}

Detalles de la Venta​

Para cada venta listada, es posible acceder a su vista detallada. Esta consulta retorna los mismos datos del listado para la venta específica, siendo utilizada para mostrar la pantalla de detalle de una transacción en el dashboard del asociado.

El identificador de la venta (saleId) es el mismo campo id retornado en el listado. Si la venta no existe, la API retorna 404 Not Found.

Solicitud — GET /{companyId}/acquirer/sales/{saleId}

Respuesta — 200 OK

{
  "id": "8f3a1c2e-0b4d-4e2a-9c1f-7a6b5d4e3c2b",
  "type": "credit_card",
  "channel": "pos",
  "grossAmount": { "currency": "BRL", "value": "150.75" },
  "netAmount": { "currency": "BRL", "value": "146.20" },
  "paymentMethod": {
    "cardBrand": "visa",
    "cardNumber": "**** **** **** 1234",
    "installments": 3
  },
  "saleDate": "2026-07-10T14:32:05Z",
  "capturedAt": "2026-07-10T14:32:07Z",
  "authorizedAt": "2026-07-10T14:32:06Z"
}

El campo channel indica dónde se realizó la venta: web (e-commerce), pos (terminal de punto de venta) o tef (transferencia electrónica de fondos). El campo type indica la modalidad de pago: credit_card, debit_card o pix.

Paginación​

Los listados de ventas y de unidades por cobrar 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 retornado en _links.next. El cursor es opaco y debe ser tratado como un identificador único de la posición del último ítem visto en la página actual. El tamaño de la página es controlado por el parámetro pageSize.