{"components":{"schemas":{"CartDiscountSelection":{"additionalProperties":false,"properties":{"strategy":{"default":"code_order","enum":["code_order","highest_discount_per_product"],"type":"string"}},"type":"object"},"CartItem":{"additionalProperties":false,"properties":{"id":{"minLength":1,"type":"string"},"quantity":{"minimum":1,"type":"integer"},"unitary_price":{"description":"Preço unitário em BRL, com no máximo duas casas decimais.","minimum":0,"multipleOf":0.01,"type":"number"}},"required":["id","quantity","unitary_price"],"type":"object"},"CouponCatalog":{"additionalProperties":{"$ref":"#/components/schemas/CouponMetadata"},"description":"Catálogo indexado pelo coupon_id referenciado nos itens.","type":"object"},"CouponMetadata":{"additionalProperties":false,"properties":{"code":{"type":"string"},"discount_type":{"enum":["percentage","fixed_amount"],"type":"string"},"name":{"type":"string"}},"required":["code","name","discount_type"],"type":"object"},"CreateIssuanceRequest":{"additionalProperties":false,"properties":{"cart":{"items":{"$ref":"#/components/schemas/CartItem"},"maxItems":500,"minItems":1,"type":"array"},"coupon_id":{"format":"uuid","type":"string"},"external_reference":{"maxLength":200,"minLength":1,"type":"string"},"metadata":{"type":["object","null"]},"subject":{"additionalProperties":false,"properties":{"cart_id":{"type":["string","null"]},"user_id":{"type":["string","null"]}},"type":"object"},"valid_until":{"format":"date-time","type":["string","null"]}},"required":["coupon_id","external_reference","subject","cart"],"type":"object"},"DiscountApplication":{"additionalProperties":false,"properties":{"coupon":{"description":"Chave no catálogo coupons.","type":"string"},"discount_base":{"$ref":"#/components/schemas/DiscountBase"},"discount_unitary":{"$ref":"#/components/schemas/Money"},"discounted_quantity":{"minimum":1,"type":"integer"}},"required":["coupon","discounted_quantity","discount_base","discount_unitary"],"type":"object"},"DiscountBase":{"description":"Percentual natural em percentage ou valor em BRL em fixed_amount.","minimum":0,"multipleOf":0.01,"type":"number"},"EligibilityContext":{"additionalProperties":false,"properties":{"attributes":{"default":{},"type":"object"},"location":{"additionalProperties":false,"properties":{"city":{"type":["string","null"]},"country":{"type":["string","null"]},"state":{"type":["string","null"]}},"type":["object","null"]},"payment_method":{"enum":["pix","credit_card",null],"type":["string","null"]},"user":{"additionalProperties":false,"properties":{"age":{"maximum":150,"minimum":0,"type":["integer","null"]},"id":{"type":["string","null"]},"sex":{"enum":["male","female","other",null],"type":["string","null"]}},"type":["object","null"]}},"type":"object"},"EligibleContext":{"additionalProperties":false,"properties":{"attributes":{"default":{},"type":"object"},"brand_id":{"type":["string","null"]},"cart":{"default":[],"items":{"$ref":"#/components/schemas/CartItem"},"type":"array"},"location":{"additionalProperties":false,"properties":{"city":{"type":["string","null"]},"country":{"type":["string","null"]},"state":{"type":["string","null"]}},"type":["object","null"]},"payment_method":{"enum":["pix","credit_card",null],"type":["string","null"]},"public":{"default":true,"type":["boolean","null"]},"unit_id":{"type":["string","null"]},"user":{"additionalProperties":false,"properties":{"age":{"maximum":150,"minimum":0,"type":["integer","null"]},"id":{"type":["string","null"]},"sex":{"enum":["male","female","other",null],"type":["string","null"]}},"type":["object","null"]}},"type":"object"},"EligibleCoupon":{"additionalProperties":false,"properties":{"code":{"type":"string"},"coupon_id":{"type":"string"},"discount_max":{"$ref":"#/components/schemas/DiscountBase"},"discount_min":{"$ref":"#/components/schemas/DiscountBase"},"discount_type":{"enum":["percentage","fixed_amount"],"type":"string"},"eligibility":{"enum":["full","partial","none"],"type":"string"},"eligible_products":{"items":{"$ref":"#/components/schemas/EligibleProduct"},"type":"array"},"metadata":{"type":["object","null"]},"minimum_cart_value":{"oneOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}]},"name":{"type":"string"}},"required":["coupon_id","code","name","metadata","discount_type","minimum_cart_value","eligibility","discount_min","discount_max","eligible_products"],"type":"object"},"EligibleProduct":{"additionalProperties":false,"properties":{"discount":{"$ref":"#/components/schemas/DiscountBase"},"id":{"type":"string"}},"required":["id","discount"],"type":"object"},"EligibleRequest":{"additionalProperties":false,"properties":{"context":{"$ref":"#/components/schemas/EligibleContext"},"pagination":{"$ref":"#/components/schemas/PaginationInput"}},"type":"object"},"EligibleResponse":{"additionalProperties":false,"properties":{"coupons":{"items":{"$ref":"#/components/schemas/EligibleCoupon"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"},"policy":{"const":"single_coupon_per_cart","type":"string"}},"required":["policy","coupons","pagination"],"type":"object"},"ErrorResponse":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id","details"],"type":"object"}},"required":["error"],"type":"object"},"IssuanceResponse":{"properties":{"code":{"pattern":"^[A-Z0-9]{2,12}-[0-9A-HJKMNP-TV-Z]{8}$","type":"string"},"coupon_id":{"format":"uuid","type":"string"},"coupon_revision_id":{"format":"uuid","type":"string"},"external_reference":{"type":"string"},"id":{"format":"uuid","type":"string"},"items":{"items":{"required":["id","minimum_quantity","maximum_discount_quantity","unitary_price","reserved_discount"],"type":"object"},"type":"array"},"metadata":{"type":["object","null"]},"prefix":{"type":"string"},"replayed":{"type":"boolean"},"reserved_discount":{"$ref":"#/components/schemas/Money"},"status":{"enum":["ACTIVE","CONSUMED","REVOKED","EXPIRED"],"type":"string"},"subject":{"type":"object"},"valid_from":{"format":"date-time","type":"string"},"valid_until":{"format":"date-time","type":"string"}},"required":["id","coupon_id","coupon_revision_id","code","prefix","external_reference","subject","status","valid_from","valid_until","reserved_discount","items","replayed"],"type":"object"},"Money":{"description":"Valor em BRL. O motor calcula internamente em centavos.","minimum":0,"multipleOf":0.01,"type":"number"},"MultipleDiscountItem":{"additionalProperties":false,"properties":{"discount_total":{"$ref":"#/components/schemas/Money"},"discounts":{"items":{"$ref":"#/components/schemas/DiscountApplication"},"type":"array"},"id":{"type":"string"},"quantity":{"minimum":1,"type":"integer"},"total_with_discount":{"$ref":"#/components/schemas/Money"},"unitary_price":{"$ref":"#/components/schemas/Money"}},"required":["id","quantity","unitary_price","discounts","discount_total","total_with_discount"],"type":"object"},"MultipleDiscountRequest":{"additionalProperties":false,"properties":{"cart_id":{"maxLength":200,"minLength":1,"type":["string","null"]},"context":{"$ref":"#/components/schemas/QuoteContext"},"coupon_codes":{"items":{"minLength":1,"type":"string"},"maxItems":10,"minItems":2,"type":"array","uniqueItems":true},"selection":{"$ref":"#/components/schemas/CartDiscountSelection"}},"required":["coupon_codes","context"],"type":"object"},"MultipleDiscountResponse":{"additionalProperties":false,"properties":{"cart_id":{"type":["string","null"]},"coupons":{"$ref":"#/components/schemas/CouponCatalog"},"currency":{"const":"BRL","type":"string"},"expires_at":{"format":"date-time","type":"string"},"items":{"items":{"$ref":"#/components/schemas/MultipleDiscountItem"},"type":"array"},"policy":{"enum":["multiple_coupons_code_order","highest_discount_per_product"],"type":"string"},"quote_id":{"type":"string"},"status":{"const":"reserved"},"totals":{"$ref":"#/components/schemas/Totals"},"user_id":{"type":["string","null"]}},"required":["quote_id","status","expires_at","policy","currency","coupons","items","totals"],"type":"object"},"MultipleRedeemRequest":{"additionalProperties":false,"description":"O carrinho é obrigatório e deve conter de 1 a 120 produtos. A prioridade de correlação é cart_id, context.user.id e, por último, quote_id. O campo expected_total não é aceito.","properties":{"cart_id":{"maxLength":200,"minLength":1,"type":["string","null"]},"context":{"$ref":"#/components/schemas/QuoteContext"},"coupon_codes":{"items":{"minLength":1,"type":"string"},"maxItems":10,"minItems":2,"type":"array","uniqueItems":true},"order_id":{"description":"Referência opcional ao pedido do cliente; não é usada para localizar a cotação.","maxLength":200,"minLength":1,"type":["string","null"]},"payment":{"$ref":"#/components/schemas/PaymentRequest"},"quote_id":{"description":"Correlação explícita com a cotação. A prioridade de resolução é cart_id, context.user.id e, por último, quote_id.","type":["string","null"]},"selection":{"$ref":"#/components/schemas/CartDiscountSelection"}},"required":["coupon_codes","context"],"type":"object"},"MultipleUnit":{"additionalProperties":false,"properties":{"brand_id":{"type":"string"},"products":{"items":{"$ref":"#/components/schemas/MultipleUnitProduct"},"type":"array"},"unit_id":{"type":"string"}},"required":["unit_id","brand_id","products"],"type":"object"},"MultipleUnitDiscountRequest":{"additionalProperties":false,"properties":{"context":{"$ref":"#/components/schemas/EligibilityContext"},"selection":{"$ref":"#/components/schemas/MultipleUnitDiscountSelection"},"units":{"items":{"$ref":"#/components/schemas/UnitQuoteInput"},"maxItems":20,"minItems":1,"type":"array"}},"required":["units"],"type":"object"},"MultipleUnitDiscountResponse":{"additionalProperties":false,"properties":{"coupons":{"$ref":"#/components/schemas/CouponCatalog"},"currency":{"const":"BRL","type":"string"},"units":{"items":{"$ref":"#/components/schemas/MultipleUnit"},"type":"array"}},"required":["currency","coupons","units"],"type":"object"},"MultipleUnitDiscountSelection":{"additionalProperties":false,"properties":{"max_coupons_per_unit":{"default":2,"maximum":10,"minimum":2,"type":"integer"},"priority":{"default":"total_discount","enum":["coverage","total_discount"],"type":"string"}},"type":"object"},"MultipleUnitProduct":{"additionalProperties":false,"properties":{"discount_total":{"$ref":"#/components/schemas/Money"},"discounts":{"items":{"$ref":"#/components/schemas/DiscountApplication"},"type":"array"},"product_id":{"type":"string"},"total_with_discount":{"$ref":"#/components/schemas/Money"},"unitary_price":{"$ref":"#/components/schemas/Money"}},"required":["product_id","unitary_price","discounts","discount_total","total_with_discount"],"type":"object"},"OperationReversalResult":{"additionalProperties":false,"properties":{"operation_id":{"type":"string"},"operation_status":{"enum":["cancelled","refunded"],"type":"string"},"replayed":{"type":"boolean"},"request_id":{"type":"string"},"requested_by":{"additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"description":"Prefixo não secreto da API key.","type":"string"},"type":{"const":"api_key"}},"required":["type","id","name","prefix"],"type":"object"},"reversal_id":{"type":"string"},"reversed_at":{"description":"Data e hora geradas pelo backend ao confirmar a reversão.","format":"date-time","type":"string"},"type":{"enum":["cancellation","refund"],"type":"string"}},"required":["operation_id","reversal_id","type","reversed_at","operation_status","requested_by","request_id","replayed"],"type":"object"},"PaginationInput":{"additionalProperties":false,"properties":{"page":{"default":1,"minimum":1,"type":"integer"},"per_page":{"default":20,"maximum":100,"minimum":1,"type":"integer"}},"type":"object"},"PaginationResponse":{"additionalProperties":false,"properties":{"page":{"minimum":1,"type":"integer"},"per_page":{"minimum":1,"type":"integer"},"total_items":{"minimum":0,"type":"integer"},"total_pages":{"minimum":0,"type":"integer"}},"required":["page","per_page","total_items","total_pages"],"type":"object"},"PaymentRequest":{"additionalProperties":false,"properties":{"amount":{"minimum":0,"multipleOf":0.01,"type":"number"},"currency":{"const":"BRL"},"external_id":{"maxLength":200,"minLength":1,"type":"string"},"method":{"enum":["pix","credit_card"]},"paid_at":{"format":"date-time","type":"string"}},"required":["external_id","method","amount","currency","paid_at"],"type":"object"},"PaymentResult":{"properties":{"amount":{"type":"number"},"operation_id":{"type":"string"},"payment_id":{"type":"string"},"payment_status":{"const":"paid"},"replayed":{"type":"boolean"}},"type":"object"},"QuoteContext":{"additionalProperties":false,"properties":{"attributes":{"default":{},"type":"object"},"brand_id":{"type":["string","null"]},"cart":{"items":{"$ref":"#/components/schemas/CartItem"},"minItems":1,"type":"array"},"location":{"additionalProperties":false,"properties":{"city":{"type":["string","null"]},"country":{"type":["string","null"]},"state":{"type":["string","null"]}},"type":["object","null"]},"payment_method":{"enum":["pix","credit_card",null],"type":["string","null"]},"unit_id":{"type":["string","null"]},"user":{"additionalProperties":false,"properties":{"age":{"maximum":150,"minimum":0,"type":["integer","null"]},"id":{"type":["string","null"]},"sex":{"enum":["male","female","other",null],"type":["string","null"]}},"type":["object","null"]}},"required":["cart"],"type":"object"},"RedemptionResult":{"properties":{"cart_id":{"type":["string","null"]},"currency":{"const":"BRL"},"operation_id":{"description":"Identificador interno da operação gerado pela API.","type":"string"},"order_id":{"type":["string","null"]},"payment_status":{"enum":["pending","paid"]},"quote_id":{"type":"string"},"quote_renewed":{"type":"boolean"},"redeemed_at":{"format":"date-time","type":"string"},"redemption_status":{"const":"redeemed"},"redemptions":{"items":{"properties":{"coupon_id":{"type":"string"},"coupon_revision_id":{"type":"string"},"receipt":{"description":"Comprovante versionado. Os campos monetários *_amount e unit_price usam centavos inteiros; a configuração percentual usa pontos-base.","type":"object"},"receipt_hash":{"type":"string"},"redemption_id":{"type":"string"}},"type":"object"},"type":"array"},"replayed":{"type":"boolean"},"totals":{"properties":{"discount":{"type":"number"},"subtotal":{"type":"number"},"total":{"type":"number"}},"type":"object"}},"required":["operation_id","quote_id","quote_renewed","redemption_status","payment_status","currency","totals","redemptions","replayed"],"type":"object"},"SingleCoupon":{"additionalProperties":false,"properties":{"code":{"type":"string"},"discount_type":{"enum":["percentage","fixed_amount"],"type":"string"},"id":{"type":"string"},"name":{"type":"string"}},"required":["id","code","name","discount_type"],"type":"object"},"SingleDiscountItem":{"additionalProperties":false,"properties":{"coupon":{"description":"ID do objeto coupon da resposta ou null quando o item não recebeu desconto.","type":["string","null"]},"discount_base":{"$ref":"#/components/schemas/DiscountBase"},"discount_total":{"$ref":"#/components/schemas/Money"},"discount_unitary":{"$ref":"#/components/schemas/Money"},"discounted_quantity":{"minimum":0,"type":"integer"},"id":{"type":"string"},"quantity":{"minimum":1,"type":"integer"},"total_with_discount":{"$ref":"#/components/schemas/Money"},"unitary_price":{"$ref":"#/components/schemas/Money"}},"required":["id","quantity","discounted_quantity","unitary_price","coupon","discount_base","discount_unitary","discount_total","total_with_discount"],"type":"object"},"SingleDiscountRequest":{"additionalProperties":false,"properties":{"cart_id":{"maxLength":200,"minLength":1,"type":["string","null"]},"context":{"$ref":"#/components/schemas/QuoteContext"},"coupon_code":{"minLength":1,"type":"string"}},"required":["coupon_code","context"],"type":"object"},"SingleDiscountResponse":{"additionalProperties":false,"properties":{"cart_id":{"type":["string","null"]},"coupon":{"$ref":"#/components/schemas/SingleCoupon"},"currency":{"const":"BRL","type":"string"},"expires_at":{"format":"date-time","type":"string"},"items":{"items":{"$ref":"#/components/schemas/SingleDiscountItem"},"type":"array"},"quote_id":{"type":"string"},"status":{"const":"reserved"},"totals":{"$ref":"#/components/schemas/Totals"},"user_id":{"type":["string","null"]}},"required":["quote_id","status","expires_at","currency","coupon","items","totals"],"type":"object"},"SingleRedeemRequest":{"additionalProperties":false,"description":"O carrinho é obrigatório e deve conter de 1 a 120 produtos. A prioridade de correlação é cart_id, context.user.id e, por último, quote_id. O campo expected_total não é aceito.","properties":{"cart_id":{"maxLength":200,"minLength":1,"type":["string","null"]},"context":{"$ref":"#/components/schemas/QuoteContext"},"coupon_code":{"minLength":1,"type":"string"},"order_id":{"description":"Referência opcional ao pedido do cliente; não é usada para localizar a cotação.","maxLength":200,"minLength":1,"type":["string","null"]},"payment":{"$ref":"#/components/schemas/PaymentRequest"},"quote_id":{"description":"Correlação explícita com a cotação. A prioridade de resolução é cart_id, context.user.id e, por último, quote_id.","type":["string","null"]}},"required":["coupon_code","context"],"type":"object"},"SingleUnit":{"additionalProperties":false,"properties":{"brand_id":{"type":"string"},"products":{"items":{"$ref":"#/components/schemas/SingleUnitProduct"},"type":"array"},"unit_id":{"type":"string"}},"required":["unit_id","brand_id","products"],"type":"object"},"SingleUnitDiscountRequest":{"additionalProperties":false,"properties":{"context":{"$ref":"#/components/schemas/EligibilityContext"},"selection":{"$ref":"#/components/schemas/SingleUnitDiscountSelection"},"units":{"items":{"$ref":"#/components/schemas/UnitQuoteInput"},"maxItems":20,"minItems":1,"type":"array"}},"required":["units"],"type":"object"},"SingleUnitDiscountResponse":{"additionalProperties":false,"properties":{"coupons":{"$ref":"#/components/schemas/CouponCatalog"},"currency":{"const":"BRL","type":"string"},"units":{"items":{"$ref":"#/components/schemas/SingleUnit"},"type":"array"}},"required":["currency","coupons","units"],"type":"object"},"SingleUnitDiscountSelection":{"additionalProperties":false,"properties":{"priority":{"default":"total_discount","enum":["coverage","total_discount"],"type":"string"}},"type":"object"},"SingleUnitProduct":{"additionalProperties":false,"properties":{"coupon":{"description":"Chave no catálogo coupons ou null quando o produto não recebeu desconto.","type":["string","null"]},"discount_base":{"$ref":"#/components/schemas/DiscountBase"},"discount_total":{"$ref":"#/components/schemas/Money"},"discount_unitary":{"$ref":"#/components/schemas/Money"},"discounted_quantity":{"maximum":1,"minimum":0,"type":"integer"},"product_id":{"type":"string"},"total_with_discount":{"$ref":"#/components/schemas/Money"},"unitary_price":{"$ref":"#/components/schemas/Money"}},"required":["product_id","unitary_price","coupon","discounted_quantity","discount_base","discount_unitary","discount_total","total_with_discount"],"type":"object"},"Totals":{"additionalProperties":false,"properties":{"discount":{"$ref":"#/components/schemas/Money"},"subtotal":{"$ref":"#/components/schemas/Money"},"total":{"$ref":"#/components/schemas/Money"}},"required":["subtotal","discount","total"],"type":"object"},"UnitProductInput":{"additionalProperties":false,"properties":{"product_id":{"minLength":1,"type":"string"},"unitary_price":{"description":"Preço unitário em BRL, com no máximo duas casas decimais.","minimum":0,"multipleOf":0.01,"type":"number"}},"required":["product_id","unitary_price"],"type":"object"},"UnitQuoteInput":{"additionalProperties":false,"properties":{"brand_id":{"minLength":1,"type":"string"},"products":{"items":{"$ref":"#/components/schemas/UnitProductInput"},"maxItems":120,"minItems":1,"type":"array"},"unit_id":{"minLength":1,"type":"string"}},"required":["unit_id","brand_id","products"],"type":"object"}},"securitySchemes":{"apiKey":{"description":"Chave exclusiva de uma organização, ambiente e projeto. O ambiente é resolvido pela chave.","scheme":"bearer","type":"http"}}},"info":{"title":"Cupom Center REST API","version":"0.1.0"},"openapi":"3.2.0","paths":{"/v1/coupon/discount/multiple":{"post":{"operationId":"multipleCartDiscounts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipleDiscountRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipleDiscountResponse"}}},"description":"Quote reservada","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chave de API inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Sem acesso"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Cupom não encontrado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de uso ou orçamento indisponível para reserva"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Content-Type não suportado"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Contexto ou regra insuficiente para calcular"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Calcula e reserva vários cupons no carrinho"}},"/v1/coupon/discount/single":{"post":{"operationId":"singleCartDiscount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleDiscountRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleDiscountResponse"}}},"description":"Quote reservada","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chave de API inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Sem acesso"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Cupom não encontrado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de uso ou orçamento indisponível para reserva"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Content-Type não suportado"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Contexto ou regra insuficiente para calcular"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Calcula e reserva um cupom no carrinho"}},"/v1/coupon/eligibility":{"additionalOperations":{"QUERY":{"operationId":"eligibleCoupons","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibleRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibleResponse"}}},"description":"Cupons elegíveis","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chave de API inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Sem acesso"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Cupom não encontrado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de uso ou orçamento indisponível para reserva"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Content-Type não suportado"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Contexto ou regra insuficiente para calcular"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Consulta cupons elegíveis"}}},"/v1/coupon/eligibility/units/multiple":{"additionalOperations":{"QUERY":{"operationId":"multipleUnitDiscounts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipleUnitDiscountRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipleUnitDiscountResponse"}}},"description":"Unidades com múltiplos cupons selecionados","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chave de API inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Sem acesso"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Cupom não encontrado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de uso ou orçamento indisponível para reserva"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Content-Type não suportado"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Contexto ou regra insuficiente para calcular"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Seleciona vários cupons públicos por unidade"}}},"/v1/coupon/eligibility/units/single":{"additionalOperations":{"QUERY":{"operationId":"singleUnitDiscount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleUnitDiscountRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleUnitDiscountResponse"}}},"description":"Unidades com um cupom selecionado","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chave de API inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Sem acesso"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Cupom não encontrado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de uso ou orçamento indisponível para reserva"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Content-Type não suportado"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Contexto ou regra insuficiente para calcular"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Seleciona um cupom público por unidade"}}},"/v1/coupon/issuances":{"post":{"operationId":"createCouponIssuance","parameters":[{"description":"Identificador estável da tentativa no escopo da API key.","in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":200,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIssuanceRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuanceResponse"}}},"description":"Resultado original da repetição idêntica (replayed=true)","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuanceResponse"}}},"description":"Nova emissão criada"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chave de API inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Sem acesso"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Cupom não encontrado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de uso ou orçamento indisponível para reserva"},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Content-Type não suportado"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Contexto ou regra insuficiente para calcular"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Emite um código individual para uma oferta dinâmica"}},"/v1/coupon/issuances/{issuance_id}":{"get":{"operationId":"getCouponIssuance","parameters":[{"in":"path","name":"issuance_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuanceResponse"}}},"description":"Emissão"}},"security":[{"apiKey":[]}],"summary":"Consulta uma emissão"}},"/v1/coupon/issuances/{issuance_id}/revocations":{"post":{"operationId":"revokeCouponIssuance","parameters":[{"in":"path","name":"issuance_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuanceResponse"}}},"description":"Emissão revogada"}},"security":[{"apiKey":[]}],"summary":"Revoga uma emissão de forma idempotente"}},"/v1/coupon/operations/{operation_id}":{"get":{"operationId":"getRedemptionOperation","parameters":[{"description":"Identificador da operação de resgate.","in":"path","name":"operation_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operação atual com comprovantes imutáveis, registro da entrada e pagamento mais recente"},"404":{"description":"Operação não encontrada no projeto autorizado"}},"security":[{"apiKey":[]}],"summary":"Consulta uma operação de resgate"}},"/v1/coupon/operations/{operation_id}/payments":{"post":{"description":"Comando transacional. Retorna 201 para um novo efeito e 200 para a repetição idêntica, não faturável. A permissão coupon:redeem é exigida para resgates; payment:write é exigida para pagamentos, inclusive quando informados no resgate.","operationId":"recordOperationPayment","parameters":[{"description":"Identificador da operação de resgate.","in":"path","name":"operation_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}},"required":true},"responses":{"200":{"description":"Resultado original do comando (replayed=true), sem unidades de faturamento"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResult"}}},"description":"Operação confirmada"},"400":{"description":"Requisição inválida"},"403":{"description":"Permissão ausente"},"404":{"description":"Recurso não encontrado no escopo autorizado"},"409":{"description":"Conflito na operação ou no pagamento, total alterado ou limite de orçamento ou uso esgotado"},"422":{"description":"Cupom inelegível ou não aplicado"},"429":{"description":"Limite de requisições da organização excedido"},"503":{"description":"Repita a requisição com o mesmo identificador de operação"}},"security":[{"apiKey":[]}],"summary":"Registra o pagamento de uma operação"}},"/v1/coupon/operations/{operation_id}/refunds":{"post":{"description":"Comando sem corpo que requer coupon:redeem. O backend classifica o resultado como cancellation quando a operação não possui pagamento e refund quando existe pagamento confirmado. A API não movimenta dinheiro. O backend gera reversal_id e reversed_at e registra a API key autenticada, request_id, IP confiável e user-agent. A operação original identifica a idempotência do comando; nenhum external_id ou reason é recebido. Resgates, pagamentos e comprovantes anteriores são preservados, e a reversão aparece no histórico de auditoria. Reversões parciais não fazem parte deste contrato inicial.","operationId":"refundOperation","parameters":[{"description":"Identificador da operação de resgate.","in":"path","name":"operation_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationReversalResult"}}},"description":"Resultado original da repetição idêntica para a mesma operação, com replayed=true"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationReversalResult"}}},"description":"Reversão registrada"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Requisição inválida"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Permissão coupon:redeem ausente"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Operação não encontrada no projeto autorizado"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Não foi possível restaurar os contadores da operação"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Limite de requisições da organização excedido"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Serviço temporariamente indisponível"}},"security":[{"apiKey":[]}],"summary":"Libera os usos e budgets consumidos por uma operação"}},"/v1/coupon/redeem/multiple":{"post":{"description":"Comando transacional. Retorna 201 para um novo efeito e 200 para a repetição idêntica, não faturável. A permissão coupon:redeem é exigida para resgates; payment:write é exigida para pagamentos, inclusive quando informados no resgate.","operationId":"redeemMultiple","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultipleRedeemRequest"}}},"required":true},"responses":{"200":{"description":"Resultado original do comando (replayed=true), sem unidades de faturamento"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedemptionResult"}}},"description":"Operação confirmada"},"400":{"description":"Requisição inválida"},"403":{"description":"Permissão ausente"},"404":{"description":"Recurso não encontrado no escopo autorizado"},"409":{"description":"Conflito na operação ou no pagamento, total alterado ou limite de orçamento ou uso esgotado"},"422":{"description":"Cupom inelegível ou não aplicado"},"429":{"description":"Limite de requisições da organização excedido"},"503":{"description":"Repita a requisição com o mesmo identificador de operação"}},"security":[{"apiKey":[]}],"summary":"Resgata vários cupons"}},"/v1/coupon/redeem/single":{"post":{"description":"Comando transacional. Retorna 201 para um novo efeito e 200 para a repetição idêntica, não faturável. A permissão coupon:redeem é exigida para resgates; payment:write é exigida para pagamentos, inclusive quando informados no resgate.","operationId":"redeemSingle","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleRedeemRequest"}}},"required":true},"responses":{"200":{"description":"Resultado original do comando (replayed=true), sem unidades de faturamento"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedemptionResult"}}},"description":"Operação confirmada"},"400":{"description":"Requisição inválida"},"403":{"description":"Permissão ausente"},"404":{"description":"Recurso não encontrado no escopo autorizado"},"409":{"description":"Conflito na operação ou no pagamento, total alterado ou limite de orçamento ou uso esgotado"},"422":{"description":"Cupom inelegível ou não aplicado"},"429":{"description":"Limite de requisições da organização excedido"},"503":{"description":"Repita a requisição com o mesmo identificador de operação"}},"security":[{"apiKey":[]}],"summary":"Resgata um cupom"}}}}