# BonifiQ Developers ## Docs - [APIs Privadas](https://developers.bonifiq.com.br/api-private/introduction.md): As APIs privadas permitem que você faça chamadas para a BonifiQ via backend da sua aplicação - [APIs Públicas](https://developers.bonifiq.com.br/api-public/introduction.md): As APIs públicas permitem que você faça chamadas diretamente do navegador (pelo frontend) - [Introdução](https://developers.bonifiq.com.br/api-widget/00-introduction.md): Documentação de referência da API Widget da BonifiQ - [Autenticação](https://developers.bonifiq.com.br/api-widget/01-authentication.md): Endpoints para login seguro e autenticação de consumidores - [Cliente](https://developers.bonifiq.com.br/api-widget/02-customer.md): Endpoints para consulta de informações do cliente e seu saldo de pontos - [Recompensas](https://developers.bonifiq.com.br/api-widget/03-rewards.md): Endpoints para listar e resgatar recompensas disponíveis - [Recompensas no Checkout](https://developers.bonifiq.com.br/api-widget/04-rewards-checkout.md): Endpoints para gerenciar recompensas durante o processo de checkout - [Cashback](https://developers.bonifiq.com.br/api-widget/05-cashback.md): Endpoints para validar, aplicar e gerenciar cashback no checkout - [Objetivos e Missões](https://developers.bonifiq.com.br/api-widget/06-objectives.md): Endpoints para listar objetivos e completar missões de fidelidade - [Tiers (Níveis)](https://developers.bonifiq.com.br/api-widget/07-tiers.md): Endpoints para consultar níveis de fidelidade - [Quiz](https://developers.bonifiq.com.br/api-widget/08-quiz.md): Endpoints para gerenciar quizzes e enquetes do programa de fidelidade - [Termos e Regulamento](https://developers.bonifiq.com.br/api-widget/10-terms.md): Endpoint para consultar os termos e regulamento do programa de fidelidade - [Disables an affiliate by email or document.](https://developers.bonifiq.com.br/api/private/affiliate/disables-an-affiliate-by-email-or-document.md) - [Reactivates an affiliate by originalId.](https://developers.bonifiq.com.br/api/private/affiliate/reactivates-an-affiliate-by-originalid.md) - [To create and update an affiliate, it's possible to create a customer for the same.](https://developers.bonifiq.com.br/api/private/affiliate/to-create-and-update-an-affiliate-its-possible-to-create-a-customer-for-the-same.md) - [Redeems cashback for a checkout](https://developers.bonifiq.com.br/api/private/checkout/redeems-cashback-for-a-checkout.md): This endpoint allows you to apply cashback discount to a checkout/cart. - [Removes an already applied cashback from a checkout.](https://developers.bonifiq.com.br/api/private/checkout/removes-an-already-applied-cashback-from-a-checkout.md): Use this endpoint when your integration needs to explicitly undo a checkout cashback redeem before the order is created. Depending on the platform integration, BonifiQ also cancels the underlying redeem after removing the cashback from the checkout. ## When to use Call this endpoint whe… - [Revalidates a previously redeemed checkout cashback against the current cart state.](https://developers.bonifiq.com.br/api/private/checkout/revalidates-a-previously-redeemed-checkout-cashback-against-the-current-cart-state.md): Use this endpoint after the shopper changes the cart contents, total amount or other platform-side checkout data. BonifiQ compares the current checkout with the redeemed cashback and decides whether the cashback can remain applied or must be removed. ## When to use Call this endpoint af… - [Creates a coupon for the given customer.](https://developers.bonifiq.com.br/api/private/coupons/creates-a-coupon-for-the-given-customer.md) - [Inactives the given coupon on the bonifiq system.](https://developers.bonifiq.com.br/api/private/coupons/inactives-the-given-coupon-on-the-bonifiq-system.md) - [Retrieves the promotion rules and details associated with a specific coupon code.](https://developers.bonifiq.com.br/api/private/coupons/retrieves-the-promotion-rules-and-details-associated-with-a-specific-coupon-code.md): This endpoint returns the promotion information linked to the provided coupon code, including type, value, requirements, and validity period. ### How to use Provide the desired coupon code in the URL. The response will contain the promotion details if available. - The `type… - [Returns if found a coupon based on the given coupon code.](https://developers.bonifiq.com.br/api/private/coupons/returns-if-found-a-coupon-based-on-the-given-coupon-code.md) - [Add or remove cashback from a customer](https://developers.bonifiq.com.br/api/private/customer/add-or-remove-cashback-from-a-customer.md): This endpoint allows you to add or remove cashback to/from a customer balance. Internally it will convert the value into points and debit it from customer,.. ## Some important remarks - Use `OperationType=0` if you want to add cashback. Use `OperationType=1` if you want to remove cashback - If you w… - [Add or remove points from a customer](https://developers.bonifiq.com.br/api/private/customer/add-or-remove-points-from-a-customer.md): This endpoint allows you to add or remove points to/from a customer. ## Some important remarks - Use `OperationType=0` if you want to add points. Use `OperationType=1` if you want to remove points - If you want to add points, use a `positive` number (eg: 10). - If you want to remove points, use a `… - [Allows a customer to refer (recommend) the store to a friend by using the Referral Objective](https://developers.bonifiq.com.br/api/private/customer/allows-a-customer-to-refer-recommend-the-store-to-a-friend-by-using-the-referral-objective.md) - [Change the Status of the customer in BonifiQ](https://developers.bonifiq.com.br/api/private/customer/change-the-status-of-the-customer-in-bonifiq.md): An active customer (`IsEnabled=true`) can receive points and participate in the program points. An inactive customer (`IsEnabled=false`) will not receive points nor will be able to redeem rewards. - [Change the tier of a customer in BonifiQ](https://developers.bonifiq.com.br/api/private/customer/change-the-tier-of-a-customer-in-bonifiq.md): This endpoint allows you to manually change the tier of a customer. The tier affects how the customer accrues points and which rewards are available to them. - [Checks whether a customer exists and returns only its basic identification data.](https://developers.bonifiq.com.br/api/private/customer/checks-whether-a-customer-exists-and-returns-only-its-basic-identification-data.md) - [Creates a new customer](https://developers.bonifiq.com.br/api/private/customer/creates-a-new-customer.md) - [Creates or updates a customer using the OriginalId provided in the request body.](https://developers.bonifiq.com.br/api/private/customer/creates-or-updates-a-customer-using-the-originalid-provided-in-the-request-body.md): This endpoint performs an upsert operation for customer data. ## Matching rule - Uses OriginalId as the unique key - If the customer does not exist, it is created (Operation = created) - If the customer already exists, it is updated (Operation = updated) ## Response Returns… - [Filter a list of customers based on the filter parameters. The return can be paginated.](https://developers.bonifiq.com.br/api/private/customer/filter-a-list-of-customers-based-on-the-filter-parameters-the-return-can-be-paginated.md): You can get a list of all customers from BonifiQ and their respective points. - [Get a customer information from its ID](https://developers.bonifiq.com.br/api/private/customer/get-a-customer-information-from-its-id.md) - [Redeem points for a cashback value](https://developers.bonifiq.com.br/api/private/customer/redeem-points-for-a-cashback-value.md) - [Remove the current tier from a customer](https://developers.bonifiq.com.br/api/private/customer/remove-the-current-tier-from-a-customer.md): This endpoint removes the current tier association from the customer and moves them back to the **base tier** of the program (if one exists). - [Retrieve pending purchase points and cashback for a given customer.](https://developers.bonifiq.com.br/api/private/customer/retrieve-pending-purchase-points-and-cashback-for-a-given-customer.md): This endpoint returns orders that still do not have granted purchase points and are either still waiting for the scoring status or already eligible but not processed yet. The summary includes the total pending points and, when cashback is active, the total pending cashback. - [Retrieve the amount of points of a given customer](https://developers.bonifiq.com.br/api/private/customer/retrieve-the-amount-of-points-of-a-given-customer.md) - [Returns a list of unused coupons that the customer have redeemed in the past](https://developers.bonifiq.com.br/api/private/customer/returns-a-list-of-unused-coupons-that-the-customer-have-redeemed-in-the-past.md) - [Returns a timeline history of points usage from the customer](https://developers.bonifiq.com.br/api/private/customer/returns-a-timeline-history-of-points-usage-from-the-customer.md): This endpoint includes tier changes. If 'IsTierHistory' is true, disregard the use of 'PointType' and use 'TierUpdate' instead. - [Set the birthday date of the given customer](https://developers.bonifiq.com.br/api/private/customer/set-the-birthday-date-of-the-given-customer.md): ## Birthday format Although we use only the day and month part of the Birthday for compatibility reasons the API expects a `DateTime` as the Birthday date. - [Update a customer based on the Id from the client store](https://developers.bonifiq.com.br/api/private/customer/update-a-customer-based-on-the-id-from-the-client-store.md) - [Returns the customizations as configured in the BonifiQ admin panel](https://developers.bonifiq.com.br/api/private/customization/returns-the-customizations-as-configured-in-the-bonifiq-admin-panel.md): Returns the customizations as configured in the BonifiQ admin panel - [Import a customer to be rewarded by a custom objective](https://developers.bonifiq.com.br/api/private/objectives/import-a-customer-to-be-rewarded-by-a-custom-objective.md) - [Return all objectives (active and inactive) for the client](https://developers.bonifiq.com.br/api/private/objectives/return-all-objectives-active-and-inactive-for-the-client.md) - [Return all the active objectives for the client](https://developers.bonifiq.com.br/api/private/objectives/return-all-the-active-objectives-for-the-client.md) - [Returns a especific Type of Objective if it is active and](https://developers.bonifiq.com.br/api/private/objectives/returns-a-especific-type-of-objective-if-it-is-active-and.md) - [Add an order or purchase](https://developers.bonifiq.com.br/api/private/order/add-an-order-or-purchase.md): An important part of the program points is awarding point for purchases that customers made. In order for points to be given we need to receive purchases that the customers made. - [Get v1pvtorder](https://developers.bonifiq.com.br/api/private/order/get-v1pvtorder.md) - [Partially cancel an order](https://developers.bonifiq.com.br/api/private/order/partially-cancel-an-order.md): If your customer returns or ask for refund for some part of their purchase you can you this endpoint to cancel the corresponding points/cashback for that purchase - [request for cancelling a purchase order](https://developers.bonifiq.com.br/api/private/order/request-for-cancelling-a-purchase-order.md) - [request for setting a purchase order completed.](https://developers.bonifiq.com.br/api/private/order/request-for-setting-a-purchase-order-completed.md) - [Lists points set to expire within the specified date range (paginated).](https://developers.bonifiq.com.br/api/private/points/lists-points-set-to-expire-within-the-specified-date-range-paginated.md): Retrieves a paginated list of points scheduled to expire. - [Retrieves a paginated list of customer points generated on or after a specified date. This endpoint allows for filtering points by a start date and supports pagination. Each item in the list includes detailed point information along with associated customer data.](https://developers.bonifiq.com.br/api/private/points/retrieves-a-paginated-list-of-customer-points-generated-on-or-after-a-specified-datethis-endpoint-allows-for-filtering-points-by-a-start-date-and-supports-paginationeach-item-in-the-list-includes-detailed-point-information-along-with-associated-customer-data.md) - [After sending the challenge request the app must ask the user for the PIN Code.](https://developers.bonifiq.com.br/api/private/pos/after-sending-the-challenge-request-the-app-must-ask-the-user-for-the-pin-code.md): The PIN Code could be received by the customer in SMS or e-mail. - [Cancel an existing reward. By canceling the customer will have their points back. The reward will be in the canceled state.](https://developers.bonifiq.com.br/api/private/pos/cancel-an-existing-reward-by-canceling-the-customer-will-have-their-points-back-the-reward-will-be-in-the-canceled-state.md): This endpoint requires to inform the Reward Id to be cancelled. This ID is the `RewardId` field received when calling the /rewards/{id}/redeem endpoint. - [Cancel an existing reward using the OriginalKey](https://developers.bonifiq.com.br/api/private/pos/cancel-an-existing-reward-using-the-originalkey.md): This endpoint requires to inform the `OriginalKey` to be cancelled. This the same field received when calling the /rewards/{id}/redeem endpoint. - [Creates a challenge (OTP) to confirm that the customer is the owner of the points](https://developers.bonifiq.com.br/api/private/pos/creates-a-challenge-otp-to-confirm-that-the-customer-is-the-owner-of-the-points.md): When this endpoint is called BonifiQ sends a unique PIN code to the customer Phone (SMS) or E-mail. - [Partially cancel an order](https://developers.bonifiq.com.br/api/private/pos/partially-cancel-an-order.md): If your customer returns or ask for refund for some part of their purchase you can you this endpoint to cancel the corresponding points/cashback for that purchase - [Returns a list of available rewards for a given customer and purchase.](https://developers.bonifiq.com.br/api/private/pos/returns-a-list-of-available-rewards-for-a-given-customer-and-purchase.md): This method returns a list of all rewards available even if they cannot be used by the given customer at the moment. - [This is shortcut for the original /orders endpoint to add orders into BonifiQ](https://developers.bonifiq.com.br/api/private/pos/this-is-shortcut-for-the-original-orders-endpoint-to-add-orders-into-bonifiq.md): An important part of the program points is awarding point for purchases that customers made. In order for points to be given we need to receive purchases that the customers made. - [This is shortcut for the original /orders/cancel endpoint for canceling orders.](https://developers.bonifiq.com.br/api/private/pos/this-is-shortcut-for-the-original-orderscancel-endpoint-for-canceling-orders.md): When an order is cancelled BonifiQ will remove the points from customer (if they have been already given) - [This method can be used to redeem a reward in behalf of a customer.](https://developers.bonifiq.com.br/api/private/pos/this-method-can-be-used-to-redeem-a-reward-in-behalf-of-a-customer.md): There are 2 types of rewards: - Discount Rewards: Percent (10%) or Value (R$10,00). This rewards are simples as they use pre-configured values - Cashback: As a value (R$5,00). The used value must be informed in the `Value` field of the request body They both can be used with this method. Ju… - [creates a new product register.](https://developers.bonifiq.com.br/api/private/product/creates-a-new-product-register.md) - [Returns a estimated value of points give from a list of products.](https://developers.bonifiq.com.br/api/private/product/returns-a-estimated-value-of-points-give-from-a-list-of-products.md) - [Updates a given product based on a given Id from the client store.](https://developers.bonifiq.com.br/api/private/product/updates-a-given-product-based-on-a-given-id-from-the-client-store.md) - [Retrieves a list of available quizzes.](https://developers.bonifiq.com.br/api/private/quiz/retrieves-a-list-of-available-quizzes.md) - [Submits answers for a specific quiz by a customer.](https://developers.bonifiq.com.br/api/private/quiz/submits-answers-for-a-specific-quiz-by-a-customer.md) - [Get v1pvtreportslistpointsavailablenotification](https://developers.bonifiq.com.br/api/private/reports/get-v1pvtreportslistpointsavailablenotification.md) - [Get v1pvtreportslistreceivedpoints](https://developers.bonifiq.com.br/api/private/reports/get-v1pvtreportslistreceivedpoints.md) - [Returns a list of cashback transactions filtered by redeem date.](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-cashback-transactions-filtered-by-redeem-date.md) - [Returns a list of customers with their points balance, points to expire and point history.](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-customers-with-their-points-balance-points-to-expire-and-point-history.md): This endpoint returns detailed customer information including: - Basic customer data (name, email, phone, document) - Points balance and cashback balance - List of points that will expire soon - Complete point transaction history with branch information - [Returns a list of generated coupons filtered by creation date.](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-generated-coupons-filtered-by-creation-date.md): This endpoint returns coupons that were generated through point redemption, excluding cashback coupons. Each coupon includes information about its current status, type, value, and associated customer. - [Returns a list of orders filtered by date.](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-orders-filtered-by-date.md): The result can be filtered by date: - OrderPlacementDate: date when the order was placed by the customer. - DateCreated: date when the order was created in the BonifiQ system. - UpdatedDate: date when the order was last updated in the BonifiQ system. - [Returns a list of points filtered by creation date](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-points-filtered-by-creation-date.md) - [Returns a list of points that will expire soon and can be sent a notification to the customer warning about the expiration. The date range is based on the days before expiration configured in the BonifiQ Admin Panel](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-points-that-will-expire-soon-and-can-be-sent-a-notification-to-the-customer-warning-about-the-expirationthe-date-range-is-based-on-the-days-before-expiration-configured-in-the-bonifiq-admin-panel.md) - [Returns a list of sales (orders that used an BonifiQ reward) filtered by date.](https://developers.bonifiq.com.br/api/private/reports/returns-a-list-of-sales-orders-that-used-an-bonifiq-reward-filtered-by-date.md): The result can be filtered by date: - OrderPlacementDate: date when the order was placed by the customer. - DateCreated: date when the order was created in the BonifiQ system. - UpdatedDate: date when the order was last updated in the BonifiQ system. - [on a Given ID, returns the Rewards configuration if found.](https://developers.bonifiq.com.br/api/private/rewardconfigurations/on-a-given-id-returns-the-rewards-configuration-if-found.md) - [Redeem a reward for the customer given on the request body](https://developers.bonifiq.com.br/api/private/rewardconfigurations/redeem-a-reward-for-the-customer-given-on-the-request-body.md) - [Returns a list of available rewards for a given customer and purchase.](https://developers.bonifiq.com.br/api/private/rewardconfigurations/returns-a-list-of-available-rewards-for-a-given-customer-and-purchase.md): This method returns a list of all rewards available even if they cannot be used by the given customer at the moment. - [Returns all rewards configuration - either available or not](https://developers.bonifiq.com.br/api/private/rewardconfigurations/returns-all-rewards-configuration--either-available-or-not.md) - [Cancel an existing reward. By canceling the customer will have their points back. The reward will be in the canceled state.](https://developers.bonifiq.com.br/api/private/rewards/cancel-an-existing-reward-by-canceling-the-customer-will-have-their-points-back-the-reward-will-be-in-the-canceled-state.md): This endpoint requires to inform the Reward Id to be cancelled. This ID is the `RewardId` field received when calling the /{id}/redeem endpoint. - [Post v1pvtrewardsupdatemetadata](https://developers.bonifiq.com.br/api/private/rewards/post-v1pvtrewardsupdatemetadata.md) - [Return an existant reward already redeemed](https://developers.bonifiq.com.br/api/private/rewards/return-an-existant-reward-already-redeemed.md) - [Returns the terms for the program points. Terms can be changed in the BonifiQ admin panel. Terms can contains HTML tags that must be rendered to the user when showing it](https://developers.bonifiq.com.br/api/private/terms/returns-the-terms-for-the-program-points-terms-can-be-changed-in-the-bonifiq-admin-panelterms-can-contains-html-tags-that-must-be-rendered-to-the-user-when-showing-it.md) - [Get v1pvttiers](https://developers.bonifiq.com.br/api/private/tiers/get-v1pvttiers.md) - [Get v1pvttiers 1](https://developers.bonifiq.com.br/api/private/tiers/get-v1pvttiers-1.md) - [Get v1pvttiers benefits](https://developers.bonifiq.com.br/api/private/tiers/get-v1pvttiers-benefits.md) - [Get v1pvttiers targets](https://developers.bonifiq.com.br/api/private/tiers/get-v1pvttiers-targets.md) - [Post v1pvttiersavailable](https://developers.bonifiq.com.br/api/private/tiers/post-v1pvttiersavailable.md) - [Retrieve the amount of points of a given customer](https://developers.bonifiq.com.br/api/public/customer/retrieve-the-amount-of-points-of-a-given-customer.md) - [Returns the current Tier in which the customer is in. Returns null if no Tier is associated with the customer.](https://developers.bonifiq.com.br/api/public/customer/returns-the-current-tier-in-which-the-customer-is-inreturns-null-if-no-tier-is-associated-with-the-customer.md) - [Returns the customizations as configured in the BonifiQ admin panel](https://developers.bonifiq.com.br/api/public/customization/returns-the-customizations-as-configured-in-the-bonifiq-admin-panel.md): Returns the customizations as configured in the BonifiQ admin panel - [Calculate how many points will be generate for a giving product, according to Purchase Objective configuration](https://developers.bonifiq.com.br/api/public/product/calculate-how-many-points-will-be-generate-for-a-giving-product-according-to-purchase-objective-configuration.md) - [Returns a estimated value of points and cashback from a given list of products.](https://developers.bonifiq.com.br/api/public/product/returns-a-estimated-value-of-points-and-cashback-from-a-given-list-of-products.md): The `Id` and `Price` are required fields - [Retrieves a specific tier by its identifier.](https://developers.bonifiq.com.br/api/public/tiers/retrieves-a-specific-tier-by-its-identifier.md) - [Retrieves all available tiers in the loyalty program.](https://developers.bonifiq.com.br/api/public/tiers/retrieves-all-available-tiers-in-the-loyalty-program.md) - [Retrieves all benefits associated with a specific tier.](https://developers.bonifiq.com.br/api/public/tiers/retrieves-all-benefits-associated-with-a-specific-tier.md) - [Retrieves all targets associated with a specific tier.](https://developers.bonifiq.com.br/api/public/tiers/retrieves-all-targets-associated-with-a-specific-tier.md) - [Guias de Integração](https://developers.bonifiq.com.br/guias/index.md): Guias focados em casos de uso específicos para integrar a BonifiQ com sua plataforma - [Integração com PDV (Point of Sale)](https://developers.bonifiq.com.br/guias/pos-integration.md): Guia completo para integração de sistemas de PDV com a BonifiQ - [Quando Usar Cada API](https://developers.bonifiq.com.br/guias/quando-usar.md): Entenda qual API da BonifiQ usar em cada cenário de integração - [Construindo sua Interface de Fidelidade](https://developers.bonifiq.com.br/guias/widget-custom.md): Guia completo para desenvolvedores que querem criar sua própria interface de fidelidade usando a API Widget da BonifiQ - [Introdução](https://developers.bonifiq.com.br/index.md): Seja bem vindo ao portal de desenvolvedores da BonifiQ - [Configuração](https://developers.bonifiq.com.br/webhooks/00-configuracao.md): Como configurar webhooks na plataforma BonifiQ - [Introdução](https://developers.bonifiq.com.br/webhooks/01-introducao.md): Primeiros passos e estrutura base dos webhooks do sistema de Fidelidade - [Webhooks - Comunicações](https://developers.bonifiq.com.br/webhooks/02-webhook-comunicacoes.md): Payloads de webhook para eventos de comunicação do sistema de Fidelidade - [Webhooks - Transações de Pontos](https://developers.bonifiq.com.br/webhooks/03-webhook-pontos.md): Payloads de webhook para transações de pontos do sistema de Fidelidade - [Webhooks - Pedidos](https://developers.bonifiq.com.br/webhooks/04-webhook-pedidos.md): Payloads de webhook para eventos de pedidos do sistema de Fidelidade - [Webhooks - Afiliados](https://developers.bonifiq.com.br/webhooks/05-webhook-afiliados.md): Payloads de webhook para eventos de afiliados do sistema de Fidelidade - [Webhooks - Clientes](https://developers.bonifiq.com.br/webhooks/06-webhook-clientes.md): Payloads de webhook para eventos de clientes do sistema de Fidelidade ## OpenAPI Specs - [swagger](https://api.bonifiq.com.br/swagger/Public%20APIs/swagger.json)