### POST /v1/products/list Source: https://hubla.gitbook.io/docs/api-publica/configuracao Lists products with pagination. This is a good first call to verify authentication. ```APIDOC ## POST /v1/products/list ### Description Lists products with pagination. This is a good first call to verify authentication. ### Method POST ### Endpoint https://backend-bff-public-api.platform.hub.la/v1/products/list ### Parameters #### Request Body - **page** (integer) - Required - Page number for pagination. - **pageSize** (integer) - Required - Number of items per page. ### Request Example { "page": 1, "pageSize": 10 } ### Response #### Success Response (200) - **products** (array) - List of products. #### Response Example { "products": [] } ``` -------------------------------- ### Webhook payload for smart_installment.off_schedule (recovery and direct) Source: https://hubla.gitbook.io/docs/webhooks/eventos/parcelamento-inteligente Two JSON payloads for the smart_installment.off_schedule webhook event, one for recovery type and one for direct type. Both show the same structure with product, smartInstallment, and user details, differing in the installment number and the 'type' field. The event fires when a smart installment becomes off_schedule due to a late payment. ```json { "type": "smart_installment.off_schedule", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [{ "id": "3a96c85e-cf82-4236-b242-7431f405c521" }] }] }], "smartInstallment": { "id": "747fe2c2-7ec6-44c7-bf01-789bbca4fde6", "subscriptionId": "9b677bd4-a57d-4394-8729-42d1aaee874e", "sourceInvoiceId": "e96a0f25-85b1-486b-ae0a-d7bc45922053", "sellerId": "O4fgEI93QqYjs3IBdvUeS12JqbA3", "payerId": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "installment": 2, "installments": 12, "paymentMethod": "credit_card", "type": "recovery", "status": "off_schedule", "statusAt": [ { "status": "created", "when": "2024-11-27T02:21:16.280Z" }, { "status": "on_schedule", "when": "2024-11-27T02:21:19.960Z" }, { "status": "off_schedule", "when": "2025-05-27T15:21:24.129Z" } ], "amount": { "totalCents": 239172 }, "modifiedAt": "2025-05-27T15:21:24.129Z", "createdAt": "2024-11-27T02:21:16.280Z", "version": 4 }, "user": { "id": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "firstName": "John", "lastName": "Doe", "document": "08351973955", "email": "john.doe@hub.la", "phone": "+5511988646782" } }, "version": "2.0.0" } ``` ```json { "type": "smart_installment.off_schedule", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [{ "id": "3a96c85e-cf82-4236-b242-7431f405c521" }] }] }], "smartInstallment": { "id": "747fe2c2-7ec6-44c7-bf01-789bbca4fde6", "subscriptionId": "9b677bd4-a57d-4394-8729-42d1aaee874e", "sellerId": "O4fgEI93QqYjs3IBdvUeS12JqbA3", "payerId": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "installment": 1, "installments": 12, "paymentMethod": "credit_card", "type": "direct", "status": "off_schedule", "statusAt": [ { "status": "created", "when": "2024-11-27T02:21:16.280Z" }, { "status": "on_schedule", "when": "2024-11-27T02:21:19.960Z" }, { "status": "off_schedule", "when": "2025-05-27T15:21:24.129Z" } ], "amount": { "totalCents": 239172 }, "modifiedAt": "2025-05-27T15:21:24.129Z", "createdAt": "2024-11-27T02:21:16.280Z", "version": 4 }, "user": { "id": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "firstName": "John", "lastName": "Doe", "document": "08351973955", "email": "john.doe@hub.la", "phone": "+5511988646782" } }, "version": "2.0.0" } ``` -------------------------------- ### Exemplo de Implementação de Autenticação Source: https://hubla.gitbook.io/docs/pagina-incorporada-iframe/autenticacao Exemplo completo de como solicitar o token via postMessage e aguardar a resposta de forma assíncrona. ```javascript const requestId = crypto.randomUUID() function getHublaIdToken(): Promise { return new Promise((resolve, reject) => { const onMessage = (event: MessageEvent) => { const data = event.data if (!data || data.type !== 'ID_TOKEN_REPLY' || data.requestId !== requestId) return window.removeEventListener('message', onMessage) data.ok ? resolve(data.idToken) : reject(new Error(data.error?.code ?? 'UNKNOWN')) } window.addEventListener('message', onMessage) window.parent.postMessage({ type: 'ID_TOKEN_REQUEST', requestId }, '*') }) } // Envie o token ao SEU backend, que o valida antes de liberar o acesso do usuário. ``` -------------------------------- ### POST /webhooks/invoice.status_updated Source: https://hubla.gitbook.io/docs/webhooks/eventos/fatura Documentation for the invoice.status_updated webhook event, including the event payload structure and example. ```APIDOC ## [POST] /webhooks/invoice.status_updated ### Description This webhook event is triggered when an invoice's status is updated. It provides detailed information about the invoice, the associated products, subscriptions, and the user involved. ### Method POST ### Endpoint /webhooks/invoice.status_updated ### Parameters #### Request Body - **type** (string) - Required - The event type, e.g., "invoice.status_updated". - **event** (object) - Required - The event payload containing the invoice details. - **version** (string) - Required - The webhook version, e.g., "2.0.0". ### Request Example { "type": "invoice.status_updated", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [ { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [ { "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [ { "id": "3a96c85e-cf82-4236-b242-7431f405c521" } ] } ] } ], "invoice": { "id": "7614b1bb-1d1a-43ba-890c-50d74216eb56", "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "parentInvoiceId": null, "childInvoiceIds": [], "subscriptionId": "d7ab5027-5bca-476c-ac29-68f1359ee6ca", "payerId": "J0kmLJmCj1TO4m3pqW0GDlEjROQ2", "sellerId": "onVILjt4hEhXIdCrvCXBUpcBuvk2", "payer": { "id": "J0kmLJmCj1TO4m3pqW0GDlEjROQ2", "firstName": "John", "lastName": "Doe", "document": "12345678000190", "email": "johndoe.payer@example.com", "phone": "+5511999999999" }, "installments": 12, "paymentMethod": "credit_card", "currency": "BRL", "type": "sell", "status": "disputed", "statusAt": [ { "when": "2024-03-28T20:35:22.671Z", "status": "unpaid" }, { "when": "2024-03-28T20:35:33.512Z", "status": "paid" }, { "when": "2024-03-28T21:04:34.720Z", "status": "disputed" } ], "coupon": { "code": "VIP50OFF" }, "amount": { "subtotalCents": 120000, "subtotal": 1200, "discountCents": 24000, "discount": 240, "prorataCents": 0, "prorata": 0, "installmentFeeCents": 16320, "installmentFee": 163.2, "totalCents": 112320, "total": 1123.2 }, "receivers": [ { "id": "platform-identity", "name": "Hubla Tecnologia LTDA", "email": "suporte@hub.la", "phone": "+5531999715693", "role": "platform", "paysForFees": false, "totalCents": 25778, "currency": "BRL" }, { "id": "onVILjt4hEhXIdCrvCXBUpcBuvk2", "name": "Victor Lott", "email": "lott@hub.la", "phone": "+5533988891169", "role": "seller", "paysForFees": true, "totalCents": 86542, "currency": "BRL" } ], "paymentSession": { "ip": "220.172.165.140", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36", "url": "https://pay.hub.la/inAVzweR0QYw5y03K5mq", "cookies": { "fbp": "fb.1.1711654522671.1234567890", "fbclid": "IwAR3xK9mP2qL8nR5vT7wY1zA4bC6dE8fG0hI2jK4lM6nO8pQ", "gclid": "Cj0KCQjw1a6CBhCXARIsAGP1kWg9xY2vN5mP6qR8sT0uV2wX4yZ6aB8cD0eF", "hbId": "hb_7f3a9c2e1b4d8e6a", "gbraid": "0AAAAACabcdef1234567890ghijklmnop", "ttclid": "E.C.P.1234567890abcdef1234567890abcdef", "ttp": "01HN8K2M3P4Q5R6S7T8U9V0W1X" }, "utm": { "source": "email", "medium": "active-campaign", "campaign": "[LEAD][QUENTE][24][MAR]", "content": "2024032812H", "term": "PROMO10OFF" }, "params": { "SCK": "ze" } }, "billingAddress": { "countryCode": "BR", "state": "São Paulo", "city": "São Paulo", "neighborhood": "Bela Vista", "street": "Av. Paulista", "complement": "MASP", "number": "1578", "postalCode": "01310-200" }, "smartInstallment": { "cycleId": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "cycleType": "direct", "sourceInvoiceId": "ID da invoice que gerou o parcelamento inteligente", "installment": 1, "installments": 12 }, "saleDate": "2024-03-28T20:35:22.671Z", "dueDate": "2024-03-28T20:35:16.350Z", "createdAt": "2024-03-28T20:35:22.671Z", "modifiedAt": "2024-03-28T21:04:34.721Z", "version": 8 }, "subscriptions": [ { "id": "d7ab5027-5bca-476c-ac29-68f1359ee6ca", "type": "recurring", "billingCycleMonths": 1, "quantity": 1 } ], "user": { "id": "J0kmLJmCj1TO4m3pqW0GDlEjROQ2", "firstName": "John", "lastName": "Doe", "document": "12345678900", "email": "johndoe.user@example.com", "phone": "+5511999999999" } }, "version": "2.0.0" } ### Response #### Success Response (200) - **type** (string) - The event type. - **event** (object) - The event payload. - **version** (string) - The webhook version. #### Response Example { "type": "invoice.status_updated", "event": {}, "version": "2.0.0" } ``` -------------------------------- ### Webhook Event: smart_installment.off_schedule Source: https://hubla.gitbook.io/docs/webhooks/eventos/parcelamento-inteligente Documentation for the smart_installment.off_schedule webhook event, including payload examples and field descriptions. ```APIDOC ## Event: smart_installment.off_schedule ### Description This event is triggered when a smart installment has an installment in arrears, changing its status to 'off_schedule'. It can be used to remind the buyer to pay the installment and prevent the installment from remaining unpaid. ### Event Type `smart_installment.off_schedule` ### Trigger When the smart installment changes to the 'Em Atraso' (overdue) state because an installment is overdue. ### Payload Example (Recovery) ```json { "type": "smart_installment.off_schedule", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [{ "id": "3a96c85e-cf82-4236-b242-7431f405c521" }] }] }], "smartInstallment": { "id": "747fe2c2-7ec6-44c7-bf01-789bbca4fde6", "subscriptionId": "9b677bd4-a57d-4394-8729-42d1aaee874e", "sourceInvoiceId": "e96a0f25-85b1-486b-ae0a-d7bc45922053", "sellerId": "O4fgEI93QqYjs3IBdvUeS12JqbA3", "payerId": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "installment": 2, "installments": 12, "paymentMethod": "credit_card", "type": "recovery", "status": "off_schedule", "statusAt": [ { "status": "created", "when": "2024-11-27T02:21:16.280Z" }, { "status": "on_schedule", "when": "2024-11-27T02:21:19.960Z" }, { "status": "off_schedule", "when": "2025-05-27T15:21:24.129Z" } ], "amount": { "totalCents": 239172 }, "modifiedAt": "2025-05-27T15:21:24.129Z", "createdAt": "2024-11-27T02:21:16.280Z", "version": 4 }, "user": { "id": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "firstName": "John", "lastName": "Doe", "document": "08351973955", "email": "john.doe@hub.la", "phone": "+5511988646782" } }, "version": "2.0.0" } ``` ### Payload Example (Direct) ```json { "type": "smart_installment.off_schedule", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [{ "id": "3a96c85e-cf82-4236-b242-7431f405c521" }] }] }], "smartInstallment": { "id": "747fe2c2-7ec6-44c7-bf01-789bbca4fde6", "subscriptionId": "9b677bd4-a57d-4394-8729-42d1aaee874e", "sellerId": "O4fgEI93QqYjs3IBdvUeS12JqbA3", "payerId": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "installment": 1, "installments": 12, "paymentMethod": "credit_card", "type": "direct", "status": "off_schedule", "statusAt": [ { "status": "created", "when": "2024-11-27T02:21:16.280Z" }, { "status": "on_schedule", "when": "2024-11-27T02:21:19.960Z" }, { "status": "off_schedule", "when": "2025-05-27T15:21:24.129Z" } ], "amount": { "totalCents": 239172 }, "modifiedAt": "2025-05-27T15:21:24.129Z", "createdAt": "2024-11-27T02:21:16.280Z", "version": 4 }, "user": { "id": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "firstName": "John", "lastName": "Doe", "document": "08351973955", "email": "john.doe@hub.la", "phone": "+5511988646782" } }, "version": "2.0.0" } ``` ### Payload Fields - **type** (string) - The event type identifier, always `smart_installment.off_schedule`. - **event** (object) - The event data containing product, smartInstallment, and user details. - **product** (object) - Information about the product associated with the smart installment. - **id** (string) - The product ID. - **name** (string) - The product name. - **products** (array) - List of products, each with offers and cohorts. - **id** (string) - The product ID. - **name** (string) - The product name. - **offers** (array) - List of offers for the product. - **id** (string) - The offer ID. - **name** (string) - The offer name. - **cohorts** (array) - List of cohort IDs. - **id** (string) - The cohort ID. - **smartInstallment** (object) - Details of the smart installment. - **id** (string) - The smart installment ID. - **subscriptionId** (string) - The subscription ID. - **sourceInvoiceId** (string) - The source invoice ID (only present in recovery type). - **sellerId** (string) - The seller ID. - **payerId** (string) - The payer ID. - **installment** (integer) - The current installment number. - **installments** (integer) - Total number of installments. - **paymentMethod** (string) - The payment method (e.g., `credit_card`). - **type** (string) - The type of smart installment (`recovery` or `direct`). - **status** (string) - The current status, always `off_schedule` for this event. - **statusAt** (array) - History of status changes with timestamps. - **status** (string) - The status value. - **when** (string) - The timestamp when the status changed. - **amount** (object) - The amount details. - **totalCents** (integer) - The total amount in cents. - **modifiedAt** (string) - The last modification timestamp. - **createdAt** (string) - The creation timestamp. - **version** (integer) - The version of the smart installment. - **user** (object) - Information about the user (buyer). - **id** (string) - The user ID. - **firstName** (string) - The user's first name. - **lastName** (string) - The user's last name. - **document** (string) - The user's document number. - **email** (string) - The user's email. - **phone** (string) - The user's phone number. - **version** (string) - The webhook version, always `2.0.0`. ``` -------------------------------- ### Evento member.course_completed - payload de exemplo Source: https://hubla.gitbook.io/docs/webhooks/eventos/area-de-membros Payload do evento `member.course_completed` enviado quando um aluno conclui um curso na Área de Membros. Use `event.product.id` para identificar o curso, `event.user` para o aluno e `event.completedAt` para a data. Este evento não inclui `event.module`; deduplique por `x-hubla-idempotency`. ```json { "type": "member.course_completed", "event": { "user": { "id": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "firstName": "John", "lastName": "Doe", "email": "john.doe@hub.la" }, "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "offer": { "id": "inAVzweR0QYw5y03K5mq", "name": "Principal" }, "completedAt": "2026-09-21T23:00:00.000Z" }, "version": "2.0.0" } ``` -------------------------------- ### invoice.payment_failed Source: https://hubla.gitbook.io/docs/webhooks/eventos/fatura Documentation for the invoice.payment_failed webhook event, including trigger conditions, key fields, and a full payload example. ```APIDOC ## Event: invoice.payment_failed ### Description This event is triggered when a credit card payment attempt for an invoice fails. It is sent when the invoice status becomes "overdue" and the payment method is "credit_card". This event is distinct from `invoice.expired`, which covers the same overdue status for pix/boleto payments. ### Event Type `invoice.payment_failed` ### Trigger Conditions - Invoice status is `overdue` - Payment method is `credit_card` ### Key Fields - `event.invoice.status` (string) - Set to `overdue`. - `event.invoice.paymentMethod` (string) - Set to `credit_card`; distinguishes this event from `invoice.expired`. - `event.invoice.amount.totalCents` (number) - Amount of the failed charge in cents; also available in reais as `amount.total`. - `event.invoice.dueDate` (string) - Due date of the invoice. - `event.invoice.subscriptionId` (string) - Associated subscription ID. ### Payload Example ```json { "type": "invoice.payment_failed", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [ { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [ { "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [ { "id": "3a96c85e-cf82-4236-b242-7431f405c521" } ] } ] } ], "invoice": { "id": "7614b1bb-1d1a-43ba-890c-50d74216eb56", "subscriptionId": "d7ab5027-5bca-476c-ac29-68f1359ee6ca", "sellerId": "onVILjt4hEhXIdCrvCXBUpcBuvk2", "payerId": "J0kmLJmCj1TO4m3pqW0GDlEjROQ2", "payer": { "id": "J0kmLJmCj1TO4m3pqW0GDlEjROQ2", "firstName": "John", "lastName": "Doe", "document": "12345678000190", "email": "johndoe.payer@example.com", "phone": "+5511999999999" }, "installments": 12, "paymentMethod": "credit_card", "currency": "BRL", "type": "sell", "status": "overdue", "statusAt": [ { "status": "unpaid", "when": "2024-03-28T20:35:22.671Z" }, { "status": "overdue", "when": "2024-03-28T20:35:45.124Z" } ], "coupon": { "code": "VIP50OFF" }, "amount": { "subtotalCents": 120000, "subtotal": 1200, "discountCents": 24000, "discount": 240, "prorataCents": 0, "prorata": 0, "installmentFeeCents": 16320, "installmentFee": 163.2, "totalCents": 112320, "total": 1123.2 }, "receivers": [ { "id": "platform-identity", "name": "Hubla Tecnologia LTDA", "email": "suporte@hub.la", "phone": "+5531999715693", "role": "platform", "paysForFees": false, "totalCents": 25778, "currency": "BRL" }, { "id": "onVILjt4hEhXIdCrvCXBUpcBuvk2", "name": "Victor Lott", "email": "lott@hub.la", "phone": "+5533988891169", "role": "seller", "paysForFees": true, "totalCents": 86542, "currency": "BRL" } ], "firstPaymentSession": { "ip": "220.172.165.140", "utm": { "source": "email", "medium": "active-campaign", "campaign": "[LEAD][QUENTE][24][MAR]", "content": "2024032812H", "term": "PROMO10OFF" } }, "billingAddress": { "countryCode": "BR", "state": "São Paulo", "city": "São Paulo", "neighborhood": "Bela Vista", "street": "Av. Paulista", "complement": "MASP", "number": "1578", "postalCode": "01310-200" }, "smartInstallment": { "sourceInvoiceId": "ID da invoice que gerou o parcelamento inteligente", "installment": 1, "installments": 12 }, "saleDate": "2024-03-28T20:35:22.671Z", "dueDate": "2024-03-28T20:35:16.350Z", "createdAt": "2024-03-28T20:35:22.671Z", "modifiedAt": "2024-03-28T20:35:22.671Z", "version": 8 }, "user": { "id": "J0kmLJmCj1TO4m3pqW0GDlEjROQ2", "firstName": "John", "lastName": "Doe", "document": "12345678900", "email": "johndoe.user@example.com", "phone": "+5511999999999" } }, "version": "2.0.0" } ``` ### Usage Notes - To use this event, check that `event.invoice.status === "overdue"` and `event.invoice.paymentMethod === "credit_card"`. - Always validate the `paymentMethod` to avoid collision with `invoice.expired`. - This event is useful for implementing credit card recovery rules (retry/dunning), notifying customers to update their card, or pausing access for subscriptions with overdue payments. ``` -------------------------------- ### Exemplo de payload do evento smart_installment.completed (tipo direct) Source: https://hubla.gitbook.io/docs/webhooks/eventos/parcelamento-inteligente Exemplo do payload do evento smart_installment.completed para o tipo direct, com status completed e histórico de status. Inclui dados do produto, parcelamento e usuário. ```json { "type": "smart_installment.completed", "event": { "product": { "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0" }, "products": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Integrações com Webhook 2.0", "offers": [{ "id": "inAVzweR0QYw5y03K5mq", "name": "Principal", "cohorts": [{ "id": "3a96c85e-cf82-4236-b242-7431f405c521" }] }] }], "smartInstallment": { "id": "747fe2c2-7ec6-44c7-bf01-789bbca4fde6", "subscriptionId": "9b677bd4-a57d-4394-8729-42d1aaee874e", "sellerId": "O4fgEI93QqYjs3IBdvUeS12JqbA3", "payerId": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "installment": 12, "installments": 12, "paymentMethod": "credit_card", "type": "direct", "status": "completed", "statusAt": [ { "status": "created", "when": "2024-11-27T02:21:16.280Z" }, { "status": "on_schedule", "when": "2024-11-27T02:21:19.960Z" }, { "status": "completed", "when": "2025-11-27T15:21:24.129Z" } ], "amount": { "totalCents": 239172 }, "modifiedAt": "2025-11-27T15:21:24.129Z", "createdAt": "2024-11-27T02:21:16.280Z", "version": 4 }, "user": { "id": "Yf7Ahs5DOJRTLvFf84s4uOp7B7Q2", "firstName": "John", "lastName": "Doe", "document": "08351973955", "email": "john.doe@hub.la", "phone": "+551198864d6d782" } }, "version": "2.0.0" } ```