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

Guía Técnica de Integración: API QR PIX – OAuth 2.0

1. Introducción y Flujo General

Esta API permite a los comercios e integradores generar códigos QR para cobros vía PIX, verificar su estado y cancelarlos si es necesario.

El flujo de integración se divide en 4 pasos fundamentales:

Autenticación: Obtener un Access Token usando OAuth 2.0.
Generación: Crear la transacción y obtener la imagen del QR.
Verificación: Consultar el estado del QR (pagado, pendiente, cancelado).
Cancelación: Anular un QR que aún no ha sido pagado.

2. Gestión de Ambientes (URLs Base)

Toda petición a la API se construye sobre una URL Base. Las credenciales (Token Basic, client_id) son provistas por ATC y son diferentes para cada ambiente.

Ambiente	URL Base	Estado / Acceso
Desarrollo	https://atcgwapitest.redenlace.com.bo/desarrollo	Activo (Pruebas iniciales).
Sandbox	https://atcgwapitest.redenlace.com.bo/sandbox	A solicitud.
Certificación (QA)	https://atcgwapitest.redenlace.com.bo/qa	A solicitud (Validación final).
Producción	(URL provista por ATC tras aprobación)	Restringido (Dinero real).

🛡️

Advertencia de Seguridad :

Nunca almacene credenciales (especialmente de producción) en repositorios de código fuente. Utilice variables de entorno o gestores de secretos.

3. Estándar de Cabeceras (Headers) Globales

Para consumir los servicios de negocio (Generar, Verificar, Cancelar), la documentación establece los siguientes headers obligatorios en cada petición:

Header	Descripción	Ejemplo / Valor
Authorization	Token de autorización. Se envía como Bearer seguido del access_token. (Nota: En los ejemplos prácticos de la sección 6, ATC muestra el uso del header access_token directamente. Se recomienda seguir el ejemplo práctico de la sección 6 para evitar errores 401).	Bearer 1442981c-... o access_token: 1442981c-...
client_id	Identificador único del cliente integrador (UUID). Provisto por ATC.	1e063b89-33cb-4a13-a625-ed73d60cbc67
Content-Type	Formato del cuerpo de la petición. Para los servicios de negocio siempre es JSON.	application/json

4. Paso 1: Autenticación (Obtención del Access Token)

Antes de generar un QR, el sistema debe autenticarse mediante el flujo OAuth 2.0 Client Credentials para obtener un token de acceso temporal.

Método HTTP: POST
URL: {URL_Base}/oauth-client-credentials/access-token?grant_type=client_credentials
Content-Type: application/x-www-form-urlencoded (¡Atención! Este es el único endpoint que NO usa JSON).
Headers de Autenticación

Header	Descripción
Authorization	Token Basic provisto por ATC. Debe codificarse en Base64 concatenando client_id:client_secret.

Ejemplo de Petición (Request)

html

600;">POST /desarrollo/oauth-client-credentials/access-token?grant_type=client_credentials HTTP/1.1
Host: atcgwapitest.redenlace.com.bo
Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
Content-Type: application/x-www-form-urlencoded

html

600;">POST /desarrollo/oauth-client-credentials/access-token?grant_type=client_credentials HTTP/1.1
Host: atcgwapitest.redenlace.com.bo
Authorization: Basic ODBiM2M1NWQtNWNiNi00OWRlLTkxYTAtMDcwZDM1M2IwMDQ3OmQ2OWVlZjQxLTFkMmYtNDBlZC1iNGQ0LTc5MzFiYjljYmI3NA==
Content-Type: application/x-www-form-urlencoded

Respuesta Exitosa (Response)

json

{
  "access_token": "c3c9fad6-91eb-4779-9f60-1e5d1fa56431",
  "token_type": "access_token",
  "expires_in": 3600,
  "scope": "read write"
}

json

{
  "access_token": "c3c9fad6-91eb-4779-9f60-1e5d1fa56431",
  "token_type": "access_token",
  "expires_in": 3600,
  "scope": "read write"
}

access_token: Es la "llave" temporal que debes guardar y enviar en los headers de los siguientes pasos (Generar, Verificar, Cancelar).

token_type: Indica el tipo de token (siempre será access_token o Bearer según el estándar).

expires_in: Tiempo de vida del token en segundos (ej. 3600 segundos = 1 hora). Tu sistema debe solicitar un token nuevo antes de que este tiempo expire.

scope: Alcance o permisos otorgados con este token.

5. Paso 2: Generar Transacción QR

Una vez obtenido el Access Token, se invoca este servicio para crear el código QR de pago.

Método HTTP: POST
URL: {URL_Base}/qr/pix/v2/generar
Cuerpo de la Petición (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": "cliente@email.com",
  "telefono": "+59171234567",
  "campoExtra": "Reservador",
  "webhook": {
    "url": "https://tu-dominio.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0..."
  }
}

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": "cliente@email.com",
  "telefono": "+59171234567",
  "campoExtra": "Reservador",
  "webhook": {
    "url": "https://tu-dominio.com/confirmed.php",
    "key": "x-api-key",
    "value": "f4a1b6d9c3e8f1a2b3c4d5e6f7a8b9c0..."
  }
}

Detalle de los Campos del Request

Campo	Tipo	Obl.	Explicación Detallada
numeroReferencia	String	✅	Tu código interno de la transacción (ej. ID de la orden de compra). Debe ser único por comercio.
glosa	String	✅	Descripción del pago o concepto del cobro. Es lo que verá el cliente en su aplicativo bancario.
monto	Decimal	✅	Importe a cobrar. Permite máximo 2 decimales (ej. 145.50).
moneda	String	✅	Código ISO de la moneda en la que cobra el comercio. Valores permitidos: BOB (Bolivianos) o USD (Dólares).
canal	String	✅	Identificador de origen para agrupar y distinguir transacciones en tus reportes (ej. WEB, MOVIL, DESKTOP).
tiempoQr	String	❌	Tiempo de vida del QR. Por defecto son 100 segundos. El valor máximo es 23:59:59 (8760 horas).
cpf	String	✅	Número de identificación del comprador (formato CPF brasileño, tamaño fijo de 11 dígitos).
correoElectronico	String	❌	Correo del comprador. Máximo 80 caracteres.
telefono	String	✅	Número de teléfono del comprador (incluir código de país).
campoExtra	String	❌	Campo reservado para metadata adicional del integrador.
webhook	Objeto	✅	Configuración de notificación. Permite que ATC avise a tu sistema cuando la transacción cambie de estado.

Detalle del Objeto webhook

Campo	Tipo	Explicación
url	String	Endpoint de tu servidor que recibirá la notificación (Callback). Debe ser HTTPS.
key	String	Nombre del header que ATC enviará para autenticar el webhook (ej. x-api-key).
value	String	Valor secreto de la llave. Tu servidor debe validar que este valor coincida para aceptar la notificación.

Respuesta Exitosa (Response)

json

{
  "moneda": "BOB",
  "monto": 145.0,
  "origenNumeroReferencia": "311113",
  "numeroReferencia": "6780",
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Estado en espera de la confirmación pago QR",
  "imagen": "iVBORw0KGgoAAAANSUhEUgAAASwAAACCC...",
  "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": "6780",
  "codigoRespuesta": "PENDING",
  "detalleRespuesta": "Estado en espera de la confirmación pago QR",
  "imagen": "iVBORw0KGgoAAAANSUhEUgAAASwAAACCC...",
  "montoConversion": 592.52,
  "monedaConversion": "BRL",
  "tipoCambio": 0.8513,
  "qrExpiracion": "2026-04-21T21:00:49.219+00:00"
}

moneda / monto: Confirma la moneda y monto original que solicitaste (ej. 145.00 BOB).

origenNumeroReferencia: Es el numeroReferencia que tú enviaste en el request. Sirve para que tu sistema confirme que la respuesta corresponde a la petición correcta.

numeroReferencia: ¡Muy Importante! Este es el Código Único Transaccional de ATC (ej. 6780). Debes guardar este valor en tu base de datos, ya que es el ID que usarás para los pasos de Verificar y Cancelar.

codigoRespuesta / detalleRespuesta: Indica el estado inicial. Al generarse, siempre será PENDING (en espera de pago).

imagen: Cadena de texto en formato Base64 que representa la imagen del código QR. Tu frontend debe decodificar esta cadena para renderizar la imagen que el cliente escaneará.

montoConversion / monedaConversion: Como es PIX, el sistema calcula el equivalente en la moneda extranjera (ej. Reales Brasileños - BRL). Muestra cuánto pagará el cliente en su moneda local.

tipoCambio: El valor de la tasa de cambio aplicada para realizar la conversión a la moneda extranjera.

qrExpiracion: Fecha y hora exacta (formato ISO 8601) en la que el QR dejará de ser válido y expirará.

6. Paso 3: Verificar Estado QR

Permite consultar el estado actual de un QR (si ya fue pagado, si expiró, etc.).

⚠️NOTA: Para este endpoint, se debe usar el

numeroReferencia

interno asignado por ATC

(el que viene en la respuesta del Paso 2),

NO

el

numeroReferencia

originante de tu sistema.

Método HTTP: GET
URL: {URL_Base}/qr/pix/v2/verifica/{numeroReferencia} (Ejemplo: .../verifica/200703)
Ejemplo de Petición (Request)

html

600;">GET /desarrollo/qr/pix/v2/verifica/200703 HTTP/1.1
Host: atcgwapitest.redenlace.com.bo
access_token: c3c9fad6-91eb-4779-9f60-1e5d1fa56431
client_id: 80b3c55d-5cb6-49de-91a0-070d353b0047
Content-Type: application/json

html

600;">GET /desarrollo/qr/pix/v2/verifica/200703 HTTP/1.1
Host: atcgwapitest.redenlace.com.bo
access_token: c3c9fad6-91eb-4779-9f60-1e5d1fa56431
client_id: 80b3c55d-5cb6-49de-91a0-070d353b0047
Content-Type: application/json

Respuesta Exitosa (Response)

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
  }
}

codigoRespuesta: Código del estado actual de la transacción (ej. PENDING, PAID, CANCELLED, EXPIRED).

detalleRespuesta: Descripción legible del estado actual.

data: Objeto que contiene el detalle financiero de la consulta.

numeroReferencia: El ID interno de ATC.

monto / moneda: Monto y moneda originales de la venta.

montoConversion / monedaConversion / tipoCambio: Detalles de la conversión a moneda extranjera (BRL).

reversa: Si la transacción fue pagada pero luego sufrió una devolución o contracargo, este campo contendrá la información de la reversa. Si es null, significa que no hay reversas aplicadas y el pago está firme.

7. Paso 4: Cancelar Transacción QR PIX

Permite cancelar o anular una transacción QR previamente generada que aún no haya sido pagada o procesada.

⚠️

N

OTA: Al igual que en la verificación, se debe usar el

numeroReferencia

interno asignado por ATC

(el ID de ATC), no el de tu sistema.

Método HTTP: GET
URL: {URL_Base}/qr/pix/v2/cancela/{numeroReferencia} (Nota: La tabla 5 menciona v1, pero el ejemplo 6.3 usa v2. Se recomienda usar v2 por consistencia con el resto de la API OAuth).
Ejemplo de Petición (Request)

html

600;">GET /desarrollo/qr/pix/v2/cancela/200703 HTTP/1.1
Host: atcgwapitest.redenlace.com.bo
access_token: d2bcbf04-c7df-4525-b3ba-01abae1b102b
client_id: 80b3c55d-5cb6-49de-91a0-070d353b0047
Content-Type: application/json

html

600;">GET /desarrollo/qr/pix/v2/cancela/200703 HTTP/1.1
Host: atcgwapitest.redenlace.com.bo
access_token: d2bcbf04-c7df-4525-b3ba-01abae1b102b
client_id: 80b3c55d-5cb6-49de-91a0-070d353b0047
Content-Type: application/json

Respuesta Exitosa (Response)

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "monto": 145.0,
    "moneda": "BOB",
    "montoConversion": "592.52",
    "monedaConversion": "BRL",
    "fechaSolicitud": "2026-04-20T15:30:00.000+00:00"
  }
}

json

{
  "codigoRespuesta": "CANCELLED",
  "detalleRespuesta": "Transaccion cancelada",
  "data": {
    "monto": 145.0,
    "moneda": "BOB",
    "montoConversion": "592.52",
    "monedaConversion": "BRL",
    "fechaSolicitud": "2026-04-20T15:30:00.000+00:00"
  }
}

codigoRespuesta / detalleRespuesta: Confirma que la acción de cancelación fue procesada correctamente (ej. CANCELLED).

data: Objeto con el resumen de la transacción cancelada.

monto / moneda: Monto original de la venta.

montoConversion / monedaConversion: Equivalente en moneda extranjera que fue anulado.

fechaSolicitud: Fecha y hora exacta (formato ISO 8601) en la que se procesó la solicitud de cancelación/devolución. Útil para auditoría y conciliación.

8. Resumen de Consideraciones para el Desarrollador

Manejo de los dos numeroReferencia: La documentación hace una distinción crítica. Tu sistema genera un numeroReferencia (origen), pero ATC devuelve otro numeroReferencia (interno de ATC). Para los endpoints de Verificar y Cancelar, es obligatorio usar el ID interno de ATC.
Formato de la Imagen: El campo imagen en la respuesta de generación no es una URL pública. Es una cadena de caracteres en Base64. Tu aplicación debe decodificar esta cadena para mostrar el código QR al usuario final.
Uso del Header de Autenticación: Aunque la sección teórica (Sección 2) menciona el uso de Authorization: Bearer {token}, los ejemplos prácticos de la sección 6 envían el token en un header llamado simplemente access_token. Se recomienda al desarrollador probar ambos formatos o seguir estrictamente el formato de los ejemplos prácticos (access_token: {valor}) para garantizar la compatibilidad con el gateway de ATC.
Webhooks (Callbacks): El objeto webhook es fundamental para no tener que hacer consultas manuales (polling) constantemente. Asegúrate de que la URL de tu webhook sea accesible públicamente y valida siempre el key y value para garantizar que la notificación proviene realmente de ATC.

En esta página

Guía Técnica de Integración: API QR PIX – OAuth 2.0

 1. Introducción y Flujo General

2. Gestión de Ambientes (URLs Base)

3. Estándar de Cabeceras (Headers) Globales

4. Paso 1: Autenticación (Obtención del Access Token)

5. Paso 2: Generar Transacción QR

6. Paso 3: Verificar Estado QR

 7. Paso 4: Cancelar Transacción QR PIX

8. Resumen de Consideraciones para el Desarrollador