APIs de Cobro - Cobro por QR PIX | Portal API Red Enlace

Especificación Técnica Servicio API QR PIX OAUTH 2.0

1. INTRODUCCION

El presente documento describe los lineamientos y especificaciones técnicas para la integración con la API de Generación y Consulta de Códigos QR PIX de ATC (Redenlace Bolivia). El servicio permite a establecimientos y aplicaciones cliente generar códigos QR de cobro y verificar el estado de las transacciones asociadas.

La integración contempla los siguientes flujos:

Autenticación mediante OAuth 2.0 (Client Credentials) para obtención del Access Token.
Generación de un código QR de pago.
Verificación del estado de la transacción QR.
Cancelación de la transacción QR.

Credenciales

El Token Basic (Authorization), el client_id y el access_token de producción son proporcionados exclusivamente por ATC para cada integrador habilitado. Los valores mostrados en este documento corresponden únicamente al ambiente de pruebas.

Las llaves obtenidas a través de este Developer Portal son exclusivamente para el ambiente Sandbox. Para solicitar las llaves de Producción, se debe seguir el siguiente proceso:

Coordinar con el equipo de ATC para realizar las pruebas en el ambiente Sandbox.

Las pruebas en Sandbox deben ser aprobadas por nuestro equipo de integraciones.

Completar el formulario de checklist correspondiente que te otorgará nuestro equipo de integraciones.

Una vez concluidas y aprobadas las pruebas, y con el checklist debidamente llenado, se podrá solicitar la generación de las llaves productivas. Sin la aprobación de las pruebas en Sandbox y el checklist completo, no se generarán llaves de producción.

Todos los servicios de la API requieren el envío de los siguientes encabezados HTTP en cada petición. El Access Token debe obtenerse previamente mediante el servicio de autenticación OAuth 2.0 (ver sección 3.1).

Header	Descripción	Oblig.	Ejemplo
`Authorization`	Token de autorización. Se envía como `Bearer` seguido del `access_token` obtenido en la autenticación.	Sí	`Bearer 1442981c-....-....-b...-ea12258c9...`
`client_id`	Identificador único del cliente integrador. Proporcionado por ATC.	Sí	`1e063b89-....-....-....-ed73d60cbc67`
`Content-Type`	Formato del cuerpo de la petición. Para todos los servicios JSON.	Sí	`application/json`

Autenticación previa obligatoria Para obtener el access_token que se usa en el header Authorization, primero debe invocarse el servicio de autenticación OAuth (sección 3.1).

3. GENERAR TRANSACCION QR

3.1. Autenticación — Obtención del Access Token

Antes de poder generar un QR, el integrador debe obtener un Access Token válido mediante el flujo OAuth 2.0 Client Credentials.

Atributo	Valor
Método HTTP	`POST`
ENDPOINT (TEST)	`/oauth-client-credentials/access-token`
Content-Type	`application/x-www-form-urlencoded`
Query Param	`grant_type=client_credentials`

Header de autenticación

Header	Descripción	Obligatorio
`Authorization`	Codificado en Base64 (`client_id:client_secret, obtenidos después de crear una cuenta en el portal y una APP`).	Sí
`Content-Type`	`application/x-www-form-urlencoded`	Sí

Request — Autenticación (obtener Access Token)

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
Headers:
  Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
Headers:
  Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

Response — Access Token

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "access_token",
  "expires_in": 3600
}

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "access_token",
  "expires_in": 3600
}

Respuesta exitosa — Access Token

Campo	Tipo	Descripción
`access_token`	String	Token de portador para usar en los headers de los servicios QR.
`token_type`	String	Tipo de token. Siempre `Bearer`.
`expires_in`	Integer	Tiempo de validez en segundos.
`scope`	String	Alcance del token otorgado.

3.2. Servicio de Generación de QR

Una vez obtenido el Access Token, se puede invocar el servicio de generación del código QR de pago.

Atributo	Valor
Método HTTP	`POST`
ENDPOINT (TEST)	`/qr/pix/v2/generar`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{client_id provisto por ATC}`
Header: `Content-Type`	`application/json`

Request — Generar QR

http

600;">POST /qr/pix/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">POST /qr/pix/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Campos del Request Body

json

{
  "numeroReferencia": 311113,
  "glosa": "311113|Compras QR Calacoto La paz|7011|Compra por Web QR",
  "monto": 145.00,
  "moneda": "BOB",
  "canal": "WEB",
  "tiempoQr": "23:59:59",
  "cpf": "12345678901",
  "correoElectronico": "denizquevedo@gmail.com",
  "telefono": "+5917123456701",
  "campoExtra": "Reservador",
  "webhook": {
    "url": "https://qr.enlacede.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f"
  }
}

json

{
  "numeroReferencia": 311113,
  "glosa": "311113|Compras QR Calacoto La paz|7011|Compra por Web QR",
  "monto": 145.00,
  "moneda": "BOB",
  "canal": "WEB",
  "tiempoQr": "23:59:59",
  "cpf": "12345678901",
  "correoElectronico": "denizquevedo@gmail.com",
  "telefono": "+5917123456701",
  "campoExtra": "Reservador",
  "webhook": {
    "url": "https://qr.enlacede.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f"
  }
}

Campo	Tipo	Obligatorio	Descripción
`numeroReferencia`	String	Sí	Referencia interna del sistema originante (asignada por el integrador). Ej: `311113`.
`glosa`	String	Sí	Descripción del pago o concepto del cobro. Ej: `Pago de servicio`.
`monto`	Decimal	Sí	Importe del pago. Máximo 2 decimales. Ej: `10.50`.
`moneda`	String	Sí	Código ISO de moneda. Valores permitidos: `BOB`, `USD`.
`canal`	String	Sí	Identificador de canal (permite agrupar y distinguir). Ej: `WEB`, `MOVIL`, `DESKTOP`.
`tiempoQr`	String	No	Tiempo de vida del QR. Por defecto 100 segundos. `23:59:59` (valor máximo 8760 horas).
`cpf`	String	Sí	Número de identificación del comprador. Tamaño 11.
`correoElectronico`	String	No	Correo del comprador, máximo 80 caracteres.
`telefono`	String	Sí	Número de teléfono del comprador.
`campoExtra`	String	No	Es un campo reservado.
`webhook`	Objeto	Sí	Campo requerido para que el comercio reciba la respuesta de la transacción.

Detalle del Objeto "webhook"

Campo	Tipo	Descripción
`url`	String	URL del webhook.
`key`	String	Tipo de key utilizado (Ejemplo: `x-api-key`).
`value`	String	Valor del key usado.

Campos de la Respuesta Exitosa

json

{
  "moneda": "BOB",
  "monto": 145.0,
  "origenNumeroReferencia": "311113",
  "numeroReferencia": "200703",
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Estado en espera de la confirmación pago QR",
  "imagen": "{cadenaQR} en base64",
  "montoConversion": 592.52,
  "monedaConversion": "BRL",
  "tipoCambio": "0.8513",
  "qrExpiracion": "2026-04-21T21:00:49.219+00:00"
}

json

{
  "moneda": "BOB",
  "monto": 145.0,
  "origenNumeroReferencia": "311113",
  "numeroReferencia": "200703",
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Estado en espera de la confirmación pago QR",
  "imagen": "{cadenaQR} en base64",
  "montoConversion": 592.52,
  "monedaConversion": "BRL",
  "tipoCambio": "0.8513",
  "qrExpiracion": "2026-04-21T21:00:49.219+00:00"
}

Campo	Tipo	Descripción
`moneda`	String	Tipo de moneda de la transacción Bs/USD.
`monto`	String	Monto de la transacción Bs/USD.
`origenNumeroReferencia`	String	Código único de la transacción del comercio integrador.
`numeroReferencia`	String	Código único transaccional de ATC.
`codigoRespuesta`	String	Código de respuesta de la acción.
`detalleRespuesta`	String	Detalle de la respuesta de la acción.
`imagen`	String	Cadena con la imagen QR.
`montoConversion`	Number	Monto después de la conversión a la moneda extranjera, ejemplo a Reales (BRL).
`monedaConversion`	String	Moneda de la conversión, ejemplo Reales.
`tipoCambio`	Number	Valor del tipo de cambio de la conversión del monto a `montoConversion`.
`qrExpiracion`	String	Fecha en la que expira el QR generado.

4. Verificar Estado QR

Permite consultar el estado actual de un QR previamente generado. Se usa el numeroReferencia interno asignado por ATC (campo numeroReferencia de la respuesta de generación), no el numeroReferencia originante del integrador.

Atributo	Valor
Método HTTP	`GET`
ENDPOINT (TEST)	`/qr/pix/v2/verifica/200703`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{client_id provisto por ATC}`
Header: `Content-Type`	`application/json`
Parámetro de ruta	`{numeroReferencia}` — Referencia interna ATC. Ej: `200703`

Request — Consulta de Estado

http

600;">GET /qr/pix/v2/verifica/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">GET /qr/pix/v2/verifica/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Response — Estado QR

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "numeroReferencia": "6780",
    "monto": 696.0,
    "moneda": "BOB",
    "montoConversion": 592.52,
    "monedaConversion": "BRL",
    "tipoCambio": 0.8513,
    "reversa": null
  }
}

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "numeroReferencia": "6780",
    "monto": 696.0,
    "moneda": "BOB",
    "montoConversion": 592.52,
    "monedaConversion": "BRL",
    "tipoCambio": 0.8513,
    "reversa": null
  }
}

4.1. Campos de la Respuesta Exitosa

Campo	Tipo	Descripción
`codigoRespuesta`	String	Código del estado de la transacción.
`detalleRespuesta`	String	Descripción de estado de la transacción.
`data`	Object	Datos de la consulta.

Estructura "data"

Campo	Tipo	Descripción
`monto`	Number	Monto de la venta en moneda Bs/USD.
`moneda`	String	Moneda Bs/USD.

5. Cancelar Transacción QR PIX

Permite cancelar la transacción QR previamente generado. Se usa el numeroReferencia interno asignado por ATC (campo data.numeroReferencia de la respuesta de generación), no el numeroReferencia originante del integrador.

Atributo	Valor
Método HTTP	`GET`
ENDPOINT (TEST)	`/qr/pix/v1/cancela/{numeroReferencia}`
Header: `access_token`	`{access_token obtenido en autenticación}`
Header: `client_id`	`{client_id provisto por ATC}`
Header: `Content-Type`	`application/json`
Parámetro de ruta	`{numeroReferencia}` — Referencia interna ATC. Ej: `200682`

Request — Cancelar Transacción QR

http

600;">GET /qr/pix/v2/cancela/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">GET /qr/pix/v2/cancela/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

5.1. Campos de la Respuesta

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "numeroReferencia": "6780",
    "monto": 696.0,
    "moneda": "BOB",
    "montoConversion": 592.52,
    "monedaConversion": "BRL",
    "tipoCambio": 0.8513,
    "reversa": null
  }
}

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "numeroReferencia": "6780",
    "monto": 696.0,
    "moneda": "BOB",
    "montoConversion": 592.52,
    "monedaConversion": "BRL",
    "tipoCambio": 0.8513,
    "reversa": null
  }
}

Campo	Tipo	Descripción
`codigoRespuesta`	String	Código del estado de la transacción.
`detalleRespuesta`	String	Descripción de estado de la transacción.
`data`	Object	Datos de la consulta.

Estructura "data"

Campo	Tipo	Descripción
`monto`	Number	Monto de la venta en moneda Bs/USD.
`moneda`	String	Moneda Bs/USD.
`montoConversion`	String	Monto convertido a la moneda extranjera → ejemplo Reales (BRL).
`monedaConversion`	String	Moneda de conversión a la extranjera, ejemplo Reales (BRL).
`fechaSolicitud`	Datetime	Fecha de solicitud de la devolución.

6. Ejemplos

6.1. Generar Transacción QR

Request — Autenticación (obtener Access Token)

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
Headers:
  Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

http

600;">POST /oauth-client-credentials/access-token?grant_type=client_credentials
Headers:
  Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
  Content-Type: application/x-www-form-urlencoded

Response — Access Token

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "access_token",
  "expires_in": 3600
}

json

{
  "access_token": "1442981c-....-....-b...-ea12258c9...",
  "token_type": "access_token",
  "expires_in": 3600
}

Request — Generar QR

http

600;">POST /qr/pix/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">POST /qr/pix/v2/generar
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

json

{
  "numeroReferencia": 311113,
  "glosa": "311113|Compras QR Calacoto La paz|7011|Compra por Web QR",
  "monto": 145.00,
  "moneda": "BOB",
  "canal": "WEB",
  "tiempoQr": "23:59:59",
  "cpf": "12345678901",
  "correoElectronico": "denizquevedo@gmail.com",
  "telefono": "+5917123456701",
  "campoExtra": "Reservador",
  "webhook": {
    "url": "https://qr.enlacedev.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0d1"
  }
}

json

{
  "numeroReferencia": 311113,
  "glosa": "311113|Compras QR Calacoto La paz|7011|Compra por Web QR",
  "monto": 145.00,
  "moneda": "BOB",
  "canal": "WEB",
  "tiempoQr": "23:59:59",
  "cpf": "12345678901",
  "correoElectronico": "denizquevedo@gmail.com",
  "telefono": "+5917123456701",
  "campoExtra": "Reservador",
  "webhook": {
    "url": "https://qr.enlacedev.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0d1"
  }
}

Response — QR generado

json

{
  "moneda": "BOB",
  "monto": 145.0,
  "origenNumeroReferencia": "311113",
  "numeroReferencia": "200703",
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Estado en espera de la confirmación pago QR",
  "imagen": "{cadenaQR} en base64",
  "montoConversion": 592.52,
  "monedaConversion": "BRL",
  "tipoCambio": "0.8513",
  "qrExpiracion": "2026-04-21T21:00:49.219+00:00"
}

json

{
  "moneda": "BOB",
  "monto": 145.0,
  "origenNumeroReferencia": "311113",
  "numeroReferencia": "200703",
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Estado en espera de la confirmación pago QR",
  "imagen": "{cadenaQR} en base64",
  "montoConversion": 592.52,
  "monedaConversion": "BRL",
  "tipoCambio": "0.8513",
  "qrExpiracion": "2026-04-21T21:00:49.219+00:00"
}

6.2. Verificar Estado QR

Request — Consulta de Estado

http

600;">GET /qr/pix/v2/verifica/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">GET /qr/pix/v2/verifica/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

Response — Estado QR

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "numeroReferencia": "200703",
    "monto": 696.0,
    "moneda": "BOB",
    "montoConversion": 592.52,
    "monedaConversion": "BRL",
    "tipoCambio": 0.8513,
    "reversa": null
  }
}

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "numeroReferencia": "200703",
    "monto": 696.0,
    "moneda": "BOB",
    "montoConversion": 592.52,
    "monedaConversion": "BRL",
    "tipoCambio": 0.8513,
    "reversa": null
  }
}

6.3. Cancelar QR

Request — Consulta de Estado

http

600;">GET /qr/pix/v2/cancela/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

http

600;">GET /qr/pix/v2/cancela/200703
Headers:
  access_token: 1442981c-....-....-b...-ea12258c9...
  client_id: 1e063b89-....-....-....-ed73d60cbc67
  Content-Type: application/json

7. Ambientes

El siguiente cuadro contiene los datos de los ambientes disponibles con la URL base y el tipo de token requerido. Las credenciales específicas (Token Basic, client_id, access_token) son proporcionadas por ATC para cada ambiente y cada integrador habilitado.

Ambiente	URL Base	Credenciales	Estado
Sandbox	`https://atcgwapitest.redenlace.com.bo/sandbox`	Provisto por ATc	A solicitud
Producción	`https://api.redenlace.com.bo\`	Provisto por ATC	Restringido

Seguridad de credenciales

No almacene credenciales de ningún ambiente (especialmente producción) en repositorios de código fuente. Use variables de entorno o un gestor de secretos. Las credenciales de producción son distintas a las de desarrollo y son entregadas por ATC de forma segura tras aprobar la certificación.

En esta página

Especificación Técnica Servicio API QR PIX OAUTH 2.0

7. Ambientes

Especificación Técnica Servicio API QR PIX OAUTH 2.0

1. INTRODUCCION

Credenciales

2. HEADER

3. GENERAR TRANSACCION QR

3.1. Autenticación — Obtención del Access Token

Header de autenticación

Request — Autenticación (obtener Access Token)

Response — Access Token

Respuesta exitosa — Access Token

3.2. Servicio de Generación de QR

Request — Generar QR

Campos del Request Body

Detalle del Objeto "webhook"

Campos de la Respuesta Exitosa

4. Verificar Estado QR

Request — Consulta de Estado

Response — Estado QR

4.1. Campos de la Respuesta Exitosa

Estructura "data"

5. Cancelar Transacción QR PIX

Request — Cancelar Transacción QR

5.1. Campos de la Respuesta

Estructura "data"

6. Ejemplos

6.1. Generar Transacción QR

Request — Autenticación (obtener Access Token)

Response — Access Token

Request — Generar QR

Response — QR generado

6.2. Verificar Estado QR

Request — Consulta de Estado

Response — Estado QR

6.3. Cancelar QR

Request — Consulta de Estado

7. Ambientes

Seguridad de credenciales