Cómo conectar Quaza a la API Pix de Banco do Brasil para cobrar con Pix dinámico y validar la integración — lo que llamamos homologar.
Qué es el gateway Banco do Brasil
El gateway Pix de Banco do Brasil conecta Quaza directamente a la API Pix del BB. Con él, los QR Codes de cobranza (Pix dinámico) se generan por internet y el pago vuelve confirmado automáticamente.
Homologar es validar tus credenciales con el BB: informás las claves de tu aplicación Pix, hacés clic en Probar gateway y Quaza confirma la conexión.
Cómo funciona la homologación
Configurás las credenciales de la aplicación Pix, Quaza pide autorización al BB y, si son correctas, la integración queda conectada:
Glosario
| Término |
Qué significa |
| Gateway |
Integración vía API: la cobranza y la baja del pago ocurren en tiempo real, por internet. |
| Homologar |
Validar tus credenciales con el BB. En Quaza, es el botón Probar gateway. |
| Ambiente |
Homologación = ambiente de pruebas (sandbox) del BB; Producción = valiendo (exige certificado). |
| Client ID / Client Secret |
Las credenciales de tu aplicación Pix en el portal de desarrolladores del BB. Van en la Clave Principal y en la Clave Secreta. |
| Clave de aplicación |
La clave del desarrollador (developer application key) de la aplicación Pix. Va en el campo Token Público. |
| Certificado |
Archivo digital exigido por el BB en Producción, enviado por el botón Importar certificado. La contraseña del certificado va en el Token Privado. |
| Tarea "Financiero - Gateway" |
Rutina automática que sincroniza los pagos de las cobranzas del gateway. |
Antes de empezar
Vas a necesitar:• Una cuenta Persona Jurídica en Banco do Brasil con la API Pix habilitada.
• Una aplicación Pix creada en el portal de desarrolladores del BB (Client ID, Client Secret y la clave de aplicación).
• Para Producción: el certificado digital y su contraseña.
Paso a paso
Abrí la configuración para cobranza y andá a la pestaña Gateway:
Configuración para cobranza → pestaña Gateway
1 En Integración con gateway, seleccioná Gateway - Banco do Brasil Pix.
2 En Ambiente, elegí Homologación (sandbox) para probar o Producción.
3 En Clave Principal, pegá el Client ID.
4 En Clave Secreta, pegá el Client Secret.
5 En Token Público, pegá la clave de aplicación del desarrollador.
6 En Token Privado (solo en Producción), informá la contraseña del certificado.
Guardá y hacé clic en Probar gateway.
Pestaña Gateway: (1) Integración con gateway = Gateway - Banco do Brasil Pix, (2) Ambiente, (3) Clave Principal (Client ID), (4) Clave Secreta (Client Secret), (5) Token Público (clave de aplicación) y (6) Token Privado (contraseña del certificado, en Producción).
En Producción, importá el certificado. Antes de probar, usá el botón Importar certificado (en el costado de la pantalla) para enviar el certificado digital del BB. Sin él, la conexión en Producción falla. En Homologación (sandbox) el certificado normalmente no se exige.
El botón "Probar gateway"
El botón Probar gateway pide una autorización a Banco do Brasil usando las credenciales de tu aplicación Pix. Si son correctas (y, en Producción, con el certificado importado), aparece Conectado con éxito — la integración está homologada.
¿Dio error al probar? Verificá el Client ID, el Client Secret y la clave de aplicación; el Ambiente; y, en Producción, si el certificado fue importado y la contraseña (Token Privado) es correcta.
Tareas automáticas
Una vez homologado, no necesitás dar de baja el pago manualmente — Quaza lo hace con tareas que corren solas:
| Tarea |
Qué hace |
| Financiero - Gateway |
Sincroniza el estado de pago de las cobranzas del gateway, dentro de la ventana de días configurada (campos "Verificación de cobros"). Es la tarea principal de la integración. |
| Financiero - Gateway (aviso) |
Genera los avisos y notificaciones relacionados a las cobranzas del gateway. |
Errores frecuentes
1. Producción exige certificado. El BB pide un certificado digital en Producción, importado por el botón Importar certificado; su contraseña va en el Token Privado. En Homologación (sandbox) normalmente no hace falta.
2. Homologación (sandbox) no es Producción. Las credenciales y el ambiente de pruebas del BB no valen para cobranzas reales.
3. Son varias claves. El BB Pix usa Clave Principal (Client ID), Clave Secreta (Client Secret) y Token Público (clave de aplicación). Si falta una, la prueba falla.
4. Todo viene de la aplicación Pix del BB. Creá la aplicación en el portal de desarrolladores del BB y copiá de ahí las credenciales.
Preguntas frecuentes
¿Quién puede configurar la homologación?El operador del área financiera con acceso a la Configuración para cobranza. Como involucra credenciales y certificado, suele hacerlo quien administra la cobranza de la empresa.
¿Dónde consigo el Client ID, el Client Secret y la clave de aplicación?En el portal de desarrolladores de Banco do Brasil, en tu aplicación Pix. Quaza no genera esas claves.
¿Necesito certificado?En Producción, sí — importado por el botón Importar certificado, con la contraseña en el Token Privado. En Homologación (sandbox) normalmente no.
¿El pago se da de baja solo?Sí. La tarea Financiero - Gateway sincroniza los pagos automáticamente, dentro de la ventana de días configurada.
¿Puedo probar antes de poner en producción?Sí. Usá el ambiente Homologación (sandbox) del BB para validar antes de ir a Producción.
"Probar gateway" dio error. ¿Qué hago?Verificá las tres claves, el ambiente y — en Producción — el certificado importado y la contraseña (Token Privado).
¿Necesito importar archivo de retorno?No. En el gateway el pago vuelve confirmado automáticamente.
Cambié las claves o el certificado. ¿Debo probar de nuevo?Sí. Cada vez que cambiés una credencial, el certificado o el ambiente, guardá y hacé clic en Probar gateway.
¿Este gateway es solo Pix?Sí, es el Pix dinámico del BB. Para boleto del BB existe un gateway propio de boleto.
Documentos relacionados