openapi: 3.1.0 info: title: API do Faturamento Automático version: 1.0.0 description: |- Hey dev, have fun! ✨ > **Documentation index** — fetch the full index at [https://docs.billing.kobana.com.br/llms.txt](https://docs.billing.kobana.com.br/llms.txt). Use this file to discover every available page before exploring further. > **Mind the API versions** — you are reading the **v1.0** documentation of the Automatic Billing API, which covers the **Subscriptions** endpoints (create, plan change, pause, cancel, manual invoicing, item sync) and related resources. Resources like **Payments, Transfers, Statements and Pix Receivables** live in other Kobana APIs — use the product picker in the top menu to switch. ## Format The API only accepts `JSON`. Every request must use `Content-Type: application/json`. All responses use `snake_case`. | Field type | Format | | :--- | :--- | | **DateTime** | [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format. Examples — Date: `2026-01-24`. Date and time: `2026-01-24T10:07Z` | | **Money (`_cents`)** | Integer in cents (÷100). E.g.: `10000` = R$ 100.00 | | **Money (`_subcents`)** | Integer in sub-cents (÷10000), used for pricing. E.g.: `1000000` = R$ 100.00 | | **UUID** | Resource identifiers as UUID v4 | ## Conventions Conventions used in this documentation: | Convention | Description | | :--- | :--- | | **`:variable`** | A variable name that must be replaced in the URL. | | **`#{variable}`** | A variable name that must be replaced with values from your account. | | **`...`** | Response content truncated for readability. | | **`$KOBANA_TOKEN`** | Access token. For command-line testing, export it: `export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx` then paste the docs commands into your terminal. | ## Return Codes The API returns standard HTTP status codes: | | Code | Description | | :--- | :--- | :--- | | ✅ | **200 OK** | Successful request with a response body. | | ✅ | **201 Created** | Resource created successfully. | | ✅ | **204 No Content** | Successful request without a response body. | | ❌ | **400 Bad Request** | Invalid request, usually malformed content. | | ❌ | **401 Unauthorized** | Missing or invalid access token. | | ❌ | **403 Forbidden** | API access blocked or user not authorized. | | ❌ | **404 Not Found** | Resource not found. | | ❌ | **422 Unprocessable Entity** | Valid request, but the data is not. | | ❌ | **429 Too Many Requests** | Rate limit reached. | | ❌ | **500 Internal Server Error** | Internal processing error. Check [server status](https://status.kobana.com.br). | ## Request ID Every request has an associated identifier in the `Request-Id` response header. This value helps with debugging and auditing — requests and their IDs are available in the system dashboard. Request logs are retained for **30 days**. When opening a support ticket about a specific request, provide the `Request-Id` to speed up the investigation. ## Security The Kobana API uses **2048-bit SSL** certificates. Every request must use **HTTPS** — calls on port 80 are redirected to 443. Clients must support `TLSv1.2` or `TLSv1.3` with one of the ciphers: `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, `TLS_CHACHA20_POLY1305_SHA256`, `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES128-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`, `ECDHE-RSA-AES256-SHA384`. `TLSv1` and `TLSv1.1` are not supported. ## HTTP Caching Use HTTP cache headers to reduce load and improve speed. Most responses include `ETag` and/or `Last-Modified` — store these values and send them back on follow-up requests via `If-None-Match` and `If-Modified-Since`. If the resource hasn't changed you'll get `304 Not Modified` — no body, no reprocessing. More info: [HTTP Cache Docs](http://www.mnot.net/cache_docs/). ## Error Handling 5xx errors mean a server failure: **500 Internal Server Error** (application unavailable), **502 Bad Gateway**, **503 Service Unavailable** and **504 Gateway Timeout** (point-in-time infrastructure failures). Your application must catch these and retry the request after a few minutes with backoff. Server status: [https://status.kobana.com.br](https://status.kobana.com.br). ## Monetary values Monetary values follow two conventions: fields with the `_cents` suffix (÷100) and pricing fields with the `_subcents` suffix (÷10000). Use these conventions to convert to BRL before displaying to the end user. license: name: Proprietário — Kobana url: https://kobana.com.br servers: - url: https://api.billing.kobana.com.br description: Production. Overridden at runtime when `API_V1_PUBLIC_URL` is set. - url: https://api.billing.sandbox.kobana.com.br description: Sandbox — isolated testing environment, separate from production. components: schemas: ApiV1Error: type: object properties: error: type: object properties: code: type: string description: Stable error code. Use this field to handle errors programmatically — never parse `message`. example: invalid_token message: type: string description: Human-readable message. Never includes user data verbatim. example: Cabeçalho Authorization ausente. details: description: "Optional error-specific payload (e.g.: `{ required, granted }` in `insufficient_scope`)." required: - code - message description: Error envelope. Present in every 4xx and 5xx response. required: - error PaginationMeta: type: object properties: total: type: integer description: Total items across all pages. page: type: integer description: Current page (starts at 1). per_page: type: integer description: Items per page. total_pages: type: integer description: Total pages. required: - total - page - per_page - total_pages DeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data SubscriptionV1: type: object properties: id: type: string format: uuid billing_account_id: type: string format: uuid company_id: type: - string - "null" format: uuid plan_id: type: - string - "null" format: uuid product_group_id: type: - string - "null" format: uuid status: type: string enum: - draft - confirmed - trialing - active - past_due - canceled - paused description: "Subscription state. Lifecycle: `draft` → `confirmed` → `trialing` → `active` ↔ `past_due` → `canceled`. Also accepts `paused`." billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual description: "Billing cycle: monthly, quarterly, semiannual or annual." billing_cycle_anchor: type: string format: date-time description: Anchor date used to compute billing periods. current_period_start: type: string format: date-time description: Start of the current billing period. current_period_end: type: string format: date-time description: End of the current billing period. trial_start: type: - string - "null" format: date-time trial_end: type: - string - "null" format: date-time activated_at: type: - string - "null" format: date-time confirmed_at: type: - string - "null" format: date-time cancel_at_period_end: type: boolean description: When `true`, the subscription is canceled at the end of the current period instead of immediately. canceled_at: type: - string - "null" format: date-time cancellation_reason: type: - string - "null" pause_collection: description: When paused, contains `{ behavior, resumes_at }`. `null` when active. paused_at: type: - string - "null" format: date-time resumes_at: type: - string - "null" format: date-time resumed_at: type: - string - "null" format: date-time discount_code_id: type: - string - "null" format: uuid discount_percent: type: - string - "null" description: 'Decimal as string (e.g.: `"10.00"` = 10%). Range: 0–100.' recurring_amount_cents: type: - integer - "null" description: Recurring amount in cents (÷100 → BRL). example: 9990 proration_behavior: type: string enum: - create_prorations - none - always_invoice description: "Proration behavior when switching plans. `create_prorations` (default): generates an adjustment; `none`: ignores; `always_invoice`: emits an immediate invoice." collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "`charge_automatically`: automatic invoicing and charging. `manual_charge`: automatic invoicing, manual charging. `manual_invoice`: both manual." nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment description: "NF-e issuance policy: `disabled`, `on_finalization`, `on_full_payment` or `per_installment`." renewal_settings: description: '`{ type: "auto_renew" | "cancel" | "downgrade_to_flexible", ... }`.' commitment: {} allow_pause: type: boolean allow_cancel: type: boolean proposal_id: type: - string - "null" format: uuid notes: type: - string - "null" custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - billing_account_id - company_id - plan_id - product_group_id - status - billing_cycle - billing_cycle_anchor - current_period_start - current_period_end - trial_start - trial_end - activated_at - confirmed_at - cancel_at_period_end - canceled_at - cancellation_reason - discount_code_id - discount_percent - recurring_amount_cents - proration_behavior - collection_method - nfe_issuance_policy - allow_pause - allow_cancel - proposal_id - notes - custom_metadata - created_at - updated_at SubscriptionListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/SubscriptionV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta SubscriptionResponse: type: object properties: data: $ref: "#/components/schemas/SubscriptionV1" required: - data SubscriptionCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that will receive this subscription. company_id: type: string format: uuid plan_id: type: string format: uuid description: Plan UUID. Required when `items` is not provided. product_group_id: type: string format: uuid billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice trial_end: type: string format: date-time description: Trial end date (ISO 8601). trial_period_days: type: integer minimum: 0 description: Alternative to `trial_end`. Trial days from creation. discount_code_id: type: string format: uuid proration_behavior: type: string enum: - create_prorations - none - always_invoice nfe_issuance_policy: type: string enum: - disabled - on_finalization - on_full_payment - per_installment items: type: array items: type: object properties: product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer minimum: 1 default: 1 unit_amount_subcents: type: integer minimum: 0 description: 4-decimal precision (÷10000 → BRL). Overrides the price amount. required: - product_id - price_id notes: type: - string - "null" custom_metadata: type: object additionalProperties: {} required: - billing_account_id SubscriptionUpdateRequest: type: object properties: plan_id: type: - string - "null" format: uuid billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice cancel_at_period_end: type: boolean discount_code_id: type: - string - "null" format: uuid discount_percent: type: - number - "null" minimum: 0 maximum: 100 proration_behavior: type: string enum: - create_prorations - none - always_invoice nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment allow_pause: type: boolean allow_cancel: type: boolean notes: type: - string - "null" custom_metadata: type: object additionalProperties: {} SubscriptionPauseRequest: type: object properties: behavior: type: string enum: - mark_uncollectible - keep_as_draft - void description: "How to treat invoices generated during the pause. Default: `mark_uncollectible`." resumes_at: type: string format: date-time description: Auto-resume date. Omit for manual resume. SubscriptionChangePlanRequest: type: object properties: plan_id: type: string format: uuid description: UUID of the new plan. timing: type: string enum: - immediate - end_of_period description: "When the plan change takes effect. Default: `immediate`." reason: type: string description: Change reason (optional, recorded in audit log). required: - plan_id SubscriptionCancelRequest: type: object properties: cancel_at_period_end: type: boolean description: "When `true`, schedules cancellation for end of current period. Default: `false` (cancels immediately)." reason: type: string BillingAccountCustomerV1: type: object properties: id: type: string format: uuid external_id: type: - string - "null" name: type: string nickname: type: - string - "null" legal_name: type: - string - "null" document_type: type: - string - "null" enum: - cpf - cnpj document_number: type: - string - "null" kind: type: - string - "null" enum: - individual - company birthday: type: - string - "null" notes: type: - string - "null" addresses: {} phones: {} emails: {} websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name BillingAccountV1: type: object properties: id: type: string format: uuid external_id: type: - string - "null" description: External identifier for the account in the client's system. currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL billing_email: type: - string - "null" format: email description: Email address invoices and notices are sent to. payment_terms_days: type: integer description: "Payment terms in days (default: 10)." example: 10 auto_collection: type: boolean description: When `true`, charges are collected automatically. balance_cents: type: integer description: Account balance in cents (÷100 → BRL). example: 0 status: type: string enum: - active - suspended - closed description: "Account status: `active`, `suspended` or `closed`." suspended_at: type: - string - "null" format: date-time suspension_reason: type: - string - "null" tax_exempt: type: boolean description: Whether the account is tax-exempt. tax_exemption_certificate: type: - string - "null" description: Tax exemption certificate number. customer_tax_type: type: - string - "null" enum: - individual - business - exempt description: "Customer tax type: individual, business or exempt." withhold_iss: type: boolean description: Withhold ISS. withhold_irrf: type: boolean description: Withhold IRRF. withhold_csrf: type: boolean description: Withhold CSRF (PIS/COFINS/CSLL). withhold_inss: type: boolean description: Withhold INSS. municipal_registration: type: - string - "null" description: Customer's municipal registration. created_at: type: string format: date-time updated_at: type: string format: date-time customer: allOf: - $ref: "#/components/schemas/BillingAccountCustomerV1" - description: Associated customer, present when the relation is loaded. required: - id - external_id - currency - billing_email - payment_terms_days - auto_collection - balance_cents - status - suspended_at - suspension_reason - tax_exempt - tax_exemption_certificate - customer_tax_type - withhold_iss - withhold_irrf - withhold_csrf - withhold_inss - municipal_registration - created_at - updated_at BillingAccountListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/BillingAccountV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta BillingAccountResponse: type: object properties: data: $ref: "#/components/schemas/BillingAccountV1" required: - data BillingAccountCustomerInput: type: object properties: id: type: string description: UUID or external_code of the existing customer. external_id: type: string description: External code to locate/create the customer. document_number: type: string description: CPF or CNPJ to locate/create the customer. name: type: string description: Required when creating a new customer. nickname: type: string legal_name: type: string kind: type: string enum: - individual - company birthday: type: string email: type: string format: email phone: type: string notes: type: string addresses: {} phones: {} emails: {} websites: {} tags: type: array items: type: string custom_metadata: type: object additionalProperties: {} BillingAccountCreateRequest: type: object properties: customer: allOf: - $ref: "#/components/schemas/BillingAccountCustomerInput" - description: Customer to associate — existing or new. external_id: type: string description: External identifier for the account in the client's system. billing_email: type: string format: email description: "Billing email. Default: `customer.email`." payment_terms_days: type: integer minimum: 1 maximum: 90 description: "Payment terms in days (1–90). Default: 10." auto_collection: type: boolean description: "Enables automatic collection. Default: `true`." required: - customer BillingAccountUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 email: type: string format: email phone: type: string address: type: object additionalProperties: {} billing_email: type: string format: email payment_terms_days: type: integer minimum: 1 maximum: 90 auto_collection: type: boolean custom_metadata: type: object additionalProperties: {} BillingAccountReasonRequest: type: object properties: reason: type: string description: Operation reason (recorded in the audit log). CustomerV1: type: object properties: id: type: string format: uuid external_id: type: - string - "null" description: External customer identifier (internal alias `external_code`). name: type: string nickname: type: - string - "null" legal_name: type: - string - "null" description: Legal name (for businesses). document_type: type: - string - "null" enum: - cpf - cnpj description: Primary document type. Inferred from `document_number`'s length. document_number: type: - string - "null" description: CPF (11 digits) or CNPJ (14 digits). May include a mask. kind: type: - string - "null" enum: - natural - juridical description: "`natural` for individuals; `juridical` for businesses." birthday: type: - string - "null" description: Birth date (ISO 8601). notes: type: - string - "null" addresses: type: - array - "null" items: type: object properties: kind: type: string description: "Address kind (e.g.: `billing`, `shipping`)." street: type: string number: type: string complement: type: - string - "null" neighborhood: type: string city: type: string state: type: string postal_code: type: string country: type: string description: "ISO country code (e.g.: `BR`)." phones: type: - array - "null" items: type: object properties: kind: type: string value: type: string required: - value emails: type: - array - "null" items: type: object properties: kind: type: string value: type: string required: - value websites: type: - array - "null" items: type: object properties: kind: type: string value: type: string required: - value tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata defined by the organization. created_at: type: string format: date-time updated_at: type: string format: date-time billing_accounts: type: array items: $ref: "#/components/schemas/BillingAccountV1" description: Included only when the customer is loaded with billing accounts. required: - id - external_id - name - nickname - legal_name - document_type - document_number - kind - birthday - notes - addresses - phones - emails - websites - tags - custom_metadata - created_at - updated_at CustomerListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomerV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CustomerResponse: type: object properties: data: $ref: "#/components/schemas/CustomerV1" required: - data CustomerCreateResponse: type: object properties: data: type: object properties: customer: $ref: "#/components/schemas/CustomerV1" billing_account: allOf: - $ref: "#/components/schemas/BillingAccountV1" - type: - object - "null" required: - customer - billing_account required: - data CustomerCreateRequest: type: object properties: name: type: string description: Customer name (required). external_id: type: string description: External customer identifier in the source system. nickname: type: string legal_name: type: string description: Legal name (for businesses). document_number: type: string description: CPF or CNPJ. The `document_type` is inferred from the length (≤11 → cpf, otherwise cnpj). kind: type: string enum: - natural - juridical birthday: type: string description: Birth date (ISO 8601). email: type: string description: Primary contact email. phone: type: string notes: type: string addresses: type: array items: type: object properties: kind: type: string description: "Address kind (e.g.: `billing`, `shipping`)." street: type: string number: type: string complement: type: - string - "null" neighborhood: type: string city: type: string state: type: string postal_code: type: string country: type: string description: "ISO country code (e.g.: `BR`)." phones: type: array items: type: object properties: kind: type: string value: type: string required: - value emails: type: array items: type: object properties: kind: type: string value: type: string required: - value websites: type: array items: type: object properties: kind: type: string value: type: string required: - value tags: type: array items: type: string custom_metadata: type: object additionalProperties: {} create_billing_account: type: boolean description: "When `false`, doesn't automatically create a billing account. Default: `true`." billing_email: type: string description: "Email for sending invoices. Default: uses `email` when omitted." payment_terms_days: type: integer minimum: 0 description: "Payment terms in days. Default: `10`." auto_collection: type: boolean description: "Automatic collection on the created account. Default: `true`." required: - name CustomerUpdateRequest: type: object properties: name: type: string external_id: type: string nickname: type: string legal_name: type: string document_number: type: string kind: type: string enum: - natural - juridical birthday: type: string email: type: string phone: type: string notes: type: string addresses: type: array items: type: object properties: kind: type: string description: "Address kind (e.g.: `billing`, `shipping`)." street: type: string number: type: string complement: type: - string - "null" neighborhood: type: string city: type: string state: type: string postal_code: type: string country: type: string description: "ISO country code (e.g.: `BR`)." phones: type: array items: type: object properties: kind: type: string value: type: string required: - value emails: type: array items: type: object properties: kind: type: string value: type: string required: - value websites: type: array items: type: object properties: kind: type: string value: type: string required: - value tags: type: array items: type: string custom_metadata: type: object additionalProperties: {} CustomerStatementItem: type: object properties: id: type: string format: uuid billing_account_id: type: string format: uuid kind: type: string description: "Entry kind (e.g.: `invoice`, `payment`, `credit_application`)." occurred_at: type: string format: date-time description: type: - string - "null" amount_cents: type: integer description: Entry amount in cents (÷100 → BRL). Can be negative. parent_id: type: - string - "null" parent_type: type: - string - "null" created_at: type: string format: date-time required: - id - billing_account_id - kind - occurred_at - description - amount_cents - parent_id - parent_type - created_at CustomerStatementListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomerStatementItem" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CustomerStatementSyncResponse: type: object properties: data: type: object properties: customer_id: type: string format: uuid billing_account_id: type: string format: uuid invoices_created: type: integer payments_created: type: integer credit_applications_created: type: integer total_created: type: integer required: - customer_id - billing_account_id - invoices_created - payments_created - credit_applications_created - total_created required: - data CustomerStatementSyncRequest: type: object properties: billing_account_id: type: string format: uuid description: Required when the customer has multiple billing accounts. CustomerRecalculateMrrResponse: type: object properties: data: type: object properties: customer_id: type: string format: uuid total_mrr_cents: type: integer description: Consolidated MRR across all accounts, in cents (÷100 → BRL). billing_accounts: type: array items: type: object properties: billing_account_id: type: string format: uuid mrr_amount_cents: type: integer required: - billing_account_id - mrr_amount_cents required: - customer_id - total_mrr_cents - billing_accounts required: - data CustomerPortalUserV1: type: object properties: id: type: string format: uuid email: type: string status: type: string enum: - active - pending_verification - pending_invitation - suspended - locked sso_only: type: boolean external_id: type: - string - "null" email_verified_at: type: - string - "null" format: date-time last_login_at: type: - string - "null" format: date-time custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time name: type: - string - "null" description: Linked `Person` name, when loaded. required: - id - email - status - sso_only - external_id - email_verified_at - last_login_at - custom_metadata - created_at - updated_at CustomerPortalUserListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomerPortalUserV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CustomerPortalUserResponse: type: object properties: data: $ref: "#/components/schemas/CustomerPortalUserV1" required: - data CustomerPortalUserInviteRequest: type: object properties: email: type: string description: Invitee's email (required). required: - email CustomerPortalUserUpdateRequest: type: object properties: email: type: string external_id: type: - string - "null" sso_only: type: boolean status: type: string enum: - active - suspended description: "Allowed transitions: `active` ↔ `suspended`." CustomerPortalUserEmailPreviewResponse: type: object properties: data: type: object properties: type: type: string enum: - invitation - verification from: type: string to: type: string subject: type: string message: type: string required: - type - from - to - subject - message required: - data CustomerPortalUserResendResponse: type: object properties: data: type: object properties: resent: type: boolean type: type: string enum: - invitation - verification required: - resent - type required: - data PlanItemV1: type: object properties: id: type: string format: uuid plan_id: type: string format: uuid product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer description: Quantity of the product included in the plan. example: 1 included: type: boolean description: When `true`, the item is included in the plan's price. When `false`, it's an add-on charged separately. created_at: type: string format: date-time required: - id - plan_id - product_id - price_id - quantity - included - created_at PlanV1: type: object properties: id: type: string format: uuid organization_id: type: - string - "null" format: uuid company_id: type: - string - "null" format: uuid plan_group_id: type: - string - "null" format: uuid billing_account_id: type: - string - "null" format: uuid description: When set, the plan is specific to one billing account (custom plan). name: type: string slug: type: string description: Unique identifier per organization. Only `[a-z0-9-]`. description: type: - string - "null" status: type: string enum: - draft - active - archived description: "Plan state: `draft`, `active` or `archived`." plan_type: type: string enum: - standard - custom - promotional description: "`standard`: standard public plan. `custom`: customer-specific plan. `promotional`: temporary promotional plan." visibility: type: string enum: - public - private description: "`public`: visible in the catalog. `private`: hidden." features: type: array items: type: string description: List of plan features (free-form strings). limits: type: object properties: users: type: integer subaccounts: type: integer operationsPerMonth: type: integer apiRequestsPerDay: type: integer description: Plan limits (users, subaccounts, operations, etc.). trial_period_days: type: - integer - "null" description: Trial days granted when creating a subscription for this plan. default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual description: Default billing cycle. available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual description: Billing cycles allowed for this plan. custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time items: type: array items: $ref: "#/components/schemas/PlanItemV1" description: Plan items. Present when included via relations. required: - id - organization_id - company_id - plan_group_id - billing_account_id - name - slug - description - status - plan_type - visibility - features - limits - trial_period_days - default_billing_cycle - available_billing_cycles - custom_metadata - created_at - updated_at PlanListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PlanResponse: type: object properties: data: $ref: "#/components/schemas/PlanV1" required: - data PlanItemListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanItemV1" required: - data PlanItemInput: type: object properties: product_id: type: string format: uuid price_id: type: string format: uuid quantity: type: integer minimum: 1 default: 1 included: type: boolean default: true required: - product_id - price_id PlanCreateRequest: type: object properties: company_id: type: string format: uuid plan_group_id: type: - string - "null" format: uuid name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9-]+$ description: Lowercase letters, digits and hyphens only. description: type: - string - "null" status: type: string enum: - draft - active - archived plan_type: type: string enum: - standard - custom - promotional description: "Default: `standard`." billing_account_id: type: - string - "null" format: uuid visibility: type: string enum: - public - private description: "Default: `public`." features: type: array items: type: string limits: type: object properties: users: type: integer subaccounts: type: integer operationsPerMonth: type: integer apiRequestsPerDay: type: integer trial_period_days: type: integer minimum: 0 maximum: 90 default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual items: type: array items: $ref: "#/components/schemas/PlanItemInput" custom_metadata: type: object additionalProperties: {} required: - name - slug PlanUpdateRequest: type: object properties: company_id: type: - string - "null" format: uuid plan_group_id: type: - string - "null" format: uuid name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9-]+$ description: Lowercase letters, digits and hyphens only. description: type: - string - "null" status: type: string enum: - draft - active - archived plan_type: type: string enum: - standard - custom - promotional description: "Default: `standard`." billing_account_id: type: - string - "null" format: uuid visibility: type: string enum: - public - private description: "Default: `public`." features: type: array items: type: string limits: type: object properties: users: type: integer subaccounts: type: integer operationsPerMonth: type: integer apiRequestsPerDay: type: integer trial_period_days: type: integer minimum: 0 maximum: 90 default_billing_cycle: type: string enum: - monthly - quarterly - semiannual - annual available_billing_cycles: type: array items: type: string enum: - monthly - quarterly - semiannual - annual items: type: array items: $ref: "#/components/schemas/PlanItemInput" custom_metadata: type: object additionalProperties: {} PlanItemsReplaceRequest: type: object properties: items: type: array items: $ref: "#/components/schemas/PlanItemInput" required: - items PlanItemsReplaceResponse: type: array items: $ref: "#/components/schemas/PlanItemV1" PlanBulkIdsRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 description: List of plan UUIDs. Minimum 1. required: - ids PlanBulkMoveGroupRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 plan_group_id: type: - string - "null" format: uuid description: Target group UUID. Use `null` to remove the grouping. required: - ids - plan_group_id PlanBulkArchiveResponse: type: object properties: data: type: object properties: archived_count: type: integer skipped_count: type: integer skipped_ids: type: array items: type: string format: uuid required: - archived_count - skipped_count - skipped_ids required: - data PlanBulkDeleteResponse: type: object properties: data: type: object properties: deleted_count: type: integer skipped_count: type: integer skipped_ids: type: array items: type: string format: uuid required: - deleted_count - skipped_count - skipped_ids required: - data PlanBulkMoveGroupResponse: type: object properties: data: type: object properties: moved_count: type: integer required: - moved_count required: - data PlanGroupV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid company_id: type: - string - "null" format: uuid name: type: string description: Plan group name. slug: type: - string - "null" description: Readable identifier used in public URLs. display_order: type: integer description: Display position (lower value shown first). archived_at: type: - string - "null" format: date-time description: Archive date. `null` when active. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - company_id - name - slug - display_order - archived_at - created_at - updated_at PlanGroupListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanGroupV1" required: - data PlanGroupResponse: type: object properties: data: $ref: "#/components/schemas/PlanGroupV1" required: - data PlanGroupCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Plan group name. slug: type: string minLength: 1 maxLength: 100 description: Readable identifier (optional). Auto-generated when omitted. required: - name PlanGroupUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 PlanGroupReorderRequest: type: object properties: group_ids: type: array items: type: string format: uuid minItems: 1 description: List of group UUIDs in the new display order. All must belong to the current organization. required: - group_ids PlanGroupReorderResponse: type: object properties: data: type: object properties: success: type: boolean example: true required: - success required: - data ProductV1: type: object properties: id: type: string format: uuid organization_id: type: - string - "null" format: uuid company_id: type: - string - "null" format: uuid parent_product_id: type: - string - "null" format: uuid product_group_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid name: type: string description: Product display name. slug: type: string description: Readable identifier unique within the product group. Accepts only `[a-z0-9_-]+`. description: type: - string - "null" status: type: string enum: - draft - active - archived description: "Product state: `draft`, `active` or `archived`." visibility: type: string enum: - public - private description: "Visibility in the customer portal. `public`: visible to customers; `private`: operators only." product_type: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity description: "Product type. `base`: main plan; `addon_quantity`/`addon_fixed`: add-ons; `metered`: usage-based charging; `one_time_fixed`/`one_time_quantity`: one-time charging." unit_label: type: - string - "null" description: 'Unit label (e.g.: "user", "GB"). Used in invoices and the portal.' increment: type: integer description: Minimum quantity increment when changing the item. website_url: type: - string - "null" display_order: type: integer description: Display order (smaller first). is_required: type: boolean description: When `true`, the product is required in any plan it is included in. custom_metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - company_id - parent_product_id - product_group_id - service_item_id - name - slug - description - status - visibility - product_type - unit_label - increment - website_url - display_order - is_required - custom_metadata - created_at - updated_at ProductListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProductV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProductResponse: type: object properties: data: $ref: "#/components/schemas/ProductV1" required: - data ProductCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Product name. slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9_-]+$ description: Unique slug within the group. Accepts only `[a-z0-9_-]+`. description: type: string productType: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity description: "Product type. Default: `base`." visibility: type: string enum: - public - private description: "Portal visibility. Default: `public`." unitLabel: type: string increment: type: integer exclusiveMinimum: 0 description: "Minimum increment. Default: `1`." websiteUrl: type: string format: uri isRequired: type: boolean parentProductId: type: string format: uuid productGroupId: type: string format: uuid companyId: type: string format: uuid customMetadata: type: object additionalProperties: {} required: - name - slug ProductUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 slug: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9_-]+$ description: type: string status: type: string enum: - draft - active - archived productType: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity visibility: type: string enum: - public - private unitLabel: type: string increment: type: integer exclusiveMinimum: 0 websiteUrl: type: string format: uri isRequired: type: boolean parentProductId: type: - string - "null" format: uuid productGroupId: type: - string - "null" format: uuid companyId: type: - string - "null" format: uuid customMetadata: type: object additionalProperties: {} ProductReorderRequest: type: object properties: product_ids: type: array items: type: string format: uuid minItems: 1 description: Product IDs in the new desired order. Index 0 becomes the first in the list. required: - product_ids ProductBulkArchiveRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 description: IDs of products to archive. required: - ids ProductBulkDeleteRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 description: IDs of products to permanently delete. required: - ids ProductBulkVisibilityRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 visibility: type: string enum: - public - private description: New visibility to apply to all products. required: - ids - visibility ProductBulkMoveGroupRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 product_group_id: type: - string - "null" format: uuid description: Target group. Use `null` to remove from the current group. required: - ids - product_group_id ProductBulkChangeCompanyRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 company_id: type: - string - "null" format: uuid description: Target company. Use `null` to clear the link. required: - ids - company_id ProductBulkResultResponse: type: object properties: data: {} ProductGroupV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid company_id: type: - string - "null" format: uuid description: UUID of the issuing company associated with the group (optional). proposal_template_id: type: - string - "null" format: uuid description: UUID of the group's default proposal template (optional). service_item_id: type: - string - "null" format: uuid description: UUID of the group's default fiscal service item (optional). name: type: string description: Product group name. slug: type: string description: Readable identifier used in public URLs. Unique per organization. display_order: type: integer description: Group display order (smaller first). archived_at: type: - string - "null" format: date-time description: Archive date. `null` when active. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - company_id - proposal_template_id - service_item_id - name - slug - display_order - archived_at - created_at - updated_at ProductGroupListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProductGroupV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProductGroupResponse: type: object properties: data: $ref: "#/components/schemas/ProductGroupV1" required: - data ProductGroupCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Group name. slug: type: string description: Group slug. Generated from the name when omitted. company_id: type: - string - "null" format: uuid proposal_template_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid required: - name ProductGroupUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 slug: type: string company_id: type: - string - "null" format: uuid proposal_template_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid ProductGroupReorderRequest: type: object properties: group_ids: type: array items: type: string format: uuid minItems: 1 description: List of UUIDs in the new desired order. All IDs must belong to the organization. required: - group_ids ProductGroupReorderResponse: type: object properties: data: type: object properties: success: type: boolean example: true required: - success required: - data ProductGroupDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data OrganizationPersonV1: type: object properties: id: type: string format: uuid external_code: type: - string - "null" name: type: string description: Legal name or display name. nickname: type: - string - "null" legal_name: type: - string - "null" document_type: type: - string - "null" enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: - string - "null" description: Document number (digits only). kind: type: - string - "null" enum: - individual - company birthday: type: - string - "null" notes: type: - string - "null" addresses: description: List of addresses. phones: description: List of contact phones. emails: description: List of contact emails. websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} metadata: type: - object - "null" additionalProperties: {} type: type: string parent_id: type: - string - "null" format: uuid external_id: type: - string - "null" created_at: type: string format: date-time updated_at: type: string format: date-time required: - name OrganizationV1: type: object properties: id: type: string format: uuid external_id: type: - string - "null" description: External identifier for the organization in Kobana's system. status: type: string description: "Organization status (e.g.: `active`)." created_at: type: string format: date-time updated_at: type: string format: date-time metadata: type: - object - "null" additionalProperties: {} description: Arbitrary metadata. Internal keys (`apiKeys`, `encryptionKey`, `secrets`) are stripped before the response. person: allOf: - $ref: "#/components/schemas/OrganizationPersonV1" - description: Organization registration data (name, document, contacts, addresses). Always included. required: - id - external_id - status - created_at - updated_at - person OrganizationResponse: type: object properties: data: $ref: "#/components/schemas/OrganizationV1" required: - data OrganizationUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Display name of the organization. email: type: string format: email description: Primary contact email of the organization. phone: type: string description: Primary contact phone of the organization. addresses: type: array items: {} description: List of organization addresses. CompanyPersonV1: type: object properties: id: type: string format: uuid external_code: type: - string - "null" description: External code of the `Person` record in the client's system. name: type: string nickname: type: - string - "null" legal_name: type: - string - "null" description: Legal name. document_type: type: - string - "null" enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: - string - "null" description: Document number (CPF or CNPJ), stored as digits only. kind: type: - string - "null" birthday: type: - string - "null" notes: type: - string - "null" addresses: {} phones: {} emails: {} websites: {} tags: type: - array - "null" items: type: string custom_metadata: type: - object - "null" additionalProperties: {} metadata: type: - object - "null" additionalProperties: {} type: type: string parent_id: type: - string - "null" external_id: type: - string - "null" created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name CompanyV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" description: Short public identifier of the company (stable and safe to display). organization_id: type: string format: uuid description: UUID of the owning organization (tenant). person_id: type: string format: uuid description: UUID of the associated `Person` record (legal identity) for this company. parent_company_id: type: - string - "null" format: uuid description: Head office UUID when this company is a branch; `null` for head offices. is_default: type: boolean description: Whether this is the default company for the organization. Only head offices can be default. status: type: string enum: - active - inactive description: "Company status: `active` or `inactive`." metadata: type: - object - "null" additionalProperties: {} description: Internal company metadata (free-form key/value). custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata defined by the client (free-form key/value). created_at: type: string format: date-time updated_at: type: string format: date-time person: allOf: - $ref: "#/components/schemas/CompanyPersonV1" - description: Company's legal identity (name, legal name, document, contacts). required: - id - public_id - organization_id - person_id - parent_company_id - is_default - status - metadata - custom_metadata - created_at - updated_at CompanyListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CompanyV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CompanyResponse: type: object properties: data: $ref: "#/components/schemas/CompanyV1" required: - data CompanyMatrizListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CompanyV1" required: - data CompanyDeleteResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data CompanyCreateRequest: type: object properties: parent_company_id: type: string format: uuid description: Head office UUID when creating a branch. Omit to create a head office. name: type: string minLength: 1 maxLength: 255 description: Trade name of the company. legal_name: type: string maxLength: 255 description: Legal name. document_type: type: string enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`. Only `cnpj` can have branches." document_number: type: string minLength: 11 maxLength: 18 description: CPF or CNPJ (with or without mask — will be normalized to digits only). email: type: string format: email description: Primary company email. phone: type: string description: Primary company phone. When provided, it is added to the `phones` array. addresses: type: array items: type: object additionalProperties: {} description: List of company addresses. emails: type: array items: type: object additionalProperties: {} description: List of additional emails. If omitted, the primary `email` is used. phones: type: array items: type: object additionalProperties: {} description: List of company phones. websites: type: array items: type: object additionalProperties: {} description: List of company websites. is_default: type: boolean description: When `true`, sets this company as the organization default. Only head offices can be default. custom_metadata: type: object additionalProperties: {} description: Custom metadata (free-form key/value). required: - name - document_type - document_number - email CompanyUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: New trade name. legal_name: type: string maxLength: 255 description: New legal name. email: type: string format: email description: New primary email. Updates the first entry of the `emails` array. phone: type: string description: New primary phone. Updates the first entry of the `phones` array. addresses: type: array items: type: object additionalProperties: {} description: Replaces the addresses list. emails: type: array items: type: object additionalProperties: {} description: Replaces the emails list. phones: type: array items: type: object additionalProperties: {} description: Replaces the phones list. websites: type: array items: type: object additionalProperties: {} description: Replaces the websites list. is_default: type: boolean description: When `true`, marks this company as default. Use the `set-default` endpoint for the dedicated operation. custom_metadata: type: object additionalProperties: {} description: Replaces the custom metadata. CompanyFiscalProfileUpsertRequest: type: object properties: taxation_regime: type: string enum: - simple_national - presumed_profit - real_profit - mei description: "Taxation regime: `simple_national`, `presumed_profit`, `real_profit` or `mei`." simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." rbt12_cents: type: - integer - "null" minimum: 0 description: Gross revenue accumulated over the last 12 months, in cents (÷100 → BRL). factor_r: type: - number - "null" description: Factor R (payroll ÷ revenue), used for Simples Nacional bracket classification. cpp_inside_das: type: boolean description: Whether CPP (employer social security contribution) is bundled into DAS. presumption_rate: type: - number - "null" description: "Presumption rate (presumed profit), as decimal (e.g.: 0.32)." iss_municipality: type: - string - "null" description: Municipality where ISS is levied. iss_rate: type: - number - "null" description: ISS rate, as decimal. pis_rate: type: - number - "null" description: PIS rate, as decimal. cofins_rate: type: - number - "null" description: COFINS rate, as decimal. csll_rate: type: - number - "null" description: CSLL rate, as decimal. irpj_rate: type: - number - "null" description: IRPJ rate, as decimal. cbs_ibs_enabled: type: boolean description: Enables the CBS/IBS fields (Brazilian tax reform). cbs_rate: type: - number - "null" description: CBS rate, as decimal. ibs_rate: type: - number - "null" description: IBS rate, as decimal. cbs_ibs_mode: type: string enum: - informative - compositive description: "CBS/IBS calculation mode: `informative` (display only) or `compositive` (composes the price)." required: - taxation_regime CompanyFiscalProfileResponse: type: object properties: data: {} CertificatePersonV1: type: object properties: id: type: string format: uuid description: Person UUID. name: type: string description: Person name. document_number: type: - string - "null" description: Person CPF or CNPJ. required: - id - name - document_number CertificateV1: type: object properties: id: type: string format: uuid person_id: type: - string - "null" format: uuid description: UUID of the associated `person` (when the document matches an existing record). name: type: string description: Friendly name for the certificate. status: type: string enum: - active - expired - revoked description: "Certificate status: `active`, `expired` or `revoked`." format: type: string enum: - pfx - pem description: "Stored certificate format: `pfx` or `pem`." document: type: - string - "null" description: CPF or CNPJ extracted from the certificate (digits only). common_name: type: - string - "null" description: Subject common name (`CN`) of the certificate. organization_name: type: - string - "null" description: Subject organization name (`O`). organizational_unit: type: - string - "null" description: Subject organizational unit (`OU`). issuer_common_name: type: - string - "null" description: Issuer (CA) common name (`CN`). issuer_organization: type: - string - "null" description: Issuer (CA) organization (`O`). serial_number: type: - string - "null" description: Certificate serial number. thumbprint: type: - string - "null" description: Certificate SHA-1 thumbprint (uppercase hex). Unique per certificate. not_before: type: - string - "null" format: date-time description: Certificate validity start (UTC). not_after: type: - string - "null" format: date-time description: Certificate validity end (UTC). metadata: type: object additionalProperties: {} description: Internal certificate metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata. created_at: type: string format: date-time updated_at: type: string format: date-time person: allOf: - $ref: "#/components/schemas/CertificatePersonV1" - type: - object - "null" description: Summary of the associated `person` (id, name, document_number), when loaded. required: - id - person_id - name - status - format - document - common_name - organization_name - organizational_unit - issuer_common_name - issuer_organization - serial_number - thumbprint - not_before - not_after - created_at - updated_at CertificateListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CertificateV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CertificateResponse: type: object properties: data: $ref: "#/components/schemas/CertificateV1" required: - data CertificateUploadRequest: type: object properties: type: type: string enum: - pfx - cert_key - combined_pem - cert_key_password description: "Upload format: `pfx`, `cert_key`, `combined_pem` or `cert_key_password`." name: type: string description: Friendly certificate name. When omitted, it is derived from `common_name` or the document. file: type: string description: Binary file (PFX/P12) when `type=pfx`, or combined PEM when `type=combined_pem`. format: binary cert_file: type: string description: Certificate PEM file (only for `type=cert_key` or `type=cert_key_password`). format: binary key_file: type: string description: Private key PEM file (only for `type=cert_key` or `type=cert_key_password`). format: binary password: type: string description: PFX password (`type=pfx`) or private key password (`type=cert_key_password`). Stored encrypted and never returned. required: - type CouponTargetV1: type: object properties: planIds: type: array items: type: string format: uuid description: List of plan UUIDs. productIds: type: array items: type: string format: uuid description: List of product UUIDs. CouponV1: type: object properties: id: type: string format: uuid code: type: string description: Public coupon code — used by customers when applying the discount. Unique per organization. name: type: string description: Internal coupon name (shown in the dashboard). description: type: - string - "null" description: Optional coupon description. discount_type: type: string enum: - percentage - fixed_amount description: "Discount type: `percentage` (in percentage points) or `fixed_amount` (in cents, ÷100 → BRL)." discount_value: type: integer description: Discount value. When `discount_type=percentage`, an integer between `0` and `100`. When `discount_type=fixed_amount`, the amount in cents (÷100 → BRL). example: 10 currency: type: string description: "ISO 4217 currency. Default: `BRL`." example: BRL min_purchase_cents: type: - integer - "null" description: Minimum invoice amount (in cents, ÷100 → BRL) for the coupon to be applicable. max_discount_cents: type: - integer - "null" description: Absolute discount cap (in cents, ÷100 → BRL). Mainly used with percentage coupons. usage_limit: type: - integer - "null" description: Total number of times the coupon can be redeemed across the organization. `null` = unlimited. usage_limit_per_user: type: - integer - "null" description: Maximum number of redemptions per billing account. `null` = unlimited. usage_count: type: integer description: Number of redemptions already recorded for the coupon. example: 0 valid_from: type: - string - "null" format: date-time description: Start of the validity window (ISO 8601). `null` = no defined start. valid_until: type: - string - "null" format: date-time description: End of the validity window (ISO 8601). `null` = no expiration. applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: Restricts the coupon to specific plans and/or products. When `null`, applies to any item. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: List of plans and/or products where the coupon **cannot** be applied. is_active: type: boolean description: When `false`, the coupon no longer accepts new redemptions. custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - code - name - description - discount_type - discount_value - currency - min_purchase_cents - max_discount_cents - usage_limit - usage_limit_per_user - usage_count - valid_from - valid_until - applies_to - excludes - is_active - custom_metadata - created_at - updated_at CouponListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CouponV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CouponResponse: type: object properties: data: $ref: "#/components/schemas/CouponV1" required: - data CouponCreateRequest: type: object properties: code: type: string minLength: 1 description: Public coupon code — unique per organization. name: type: string minLength: 1 description: Internal coupon name. description: type: string description: Optional description. discount_type: type: string enum: - percentage - fixed_amount description: "Discount type: `percentage` or `fixed_amount`." discount_value: type: integer minimum: 0 description: Discount value. For `percentage`, integer between `0` and `100`. For `fixed_amount`, amount in cents (÷100 → BRL). currency: type: string description: "ISO 4217 currency. Default: `BRL`." min_purchase_cents: type: integer minimum: 0 description: Minimum invoice amount, in cents (÷100 → BRL), for the coupon to be applicable. max_discount_cents: type: integer minimum: 0 description: Absolute discount cap, in cents (÷100 → BRL). usage_limit: type: integer exclusiveMinimum: 0 description: Maximum total redemptions across the organization. Omit for unlimited. usage_limit_per_user: type: integer exclusiveMinimum: 0 description: Maximum redemptions per billing account. Omit for unlimited. valid_from: type: string description: Start of the validity window (ISO 8601 — date or date-time). valid_until: type: string description: End of the validity window (ISO 8601 — date or date-time). applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - description: Restricts the coupon to plans and/or products. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - description: List of plans and/or products where the coupon cannot be applied. custom_metadata: type: object additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - code - name - discount_type - discount_value CouponUpdateRequest: type: object properties: name: type: string minLength: 1 description: New internal coupon name. description: type: - string - "null" description: New description. Send `null` to clear. usage_limit: type: - integer - "null" exclusiveMinimum: 0 description: New total redemption limit. `null` = unlimited. usage_limit_per_user: type: - integer - "null" exclusiveMinimum: 0 description: New per-billing-account limit. `null` = unlimited. valid_from: type: - string - "null" description: New validity start (ISO 8601). `null` = removes the restriction. valid_until: type: - string - "null" description: New validity end (ISO 8601). `null` = removes the expiration. applies_to: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: New plan/product restriction. `null` = removes the restriction. excludes: allOf: - $ref: "#/components/schemas/CouponTargetV1" - type: - object - "null" description: New exclusion list. `null` = removes the exclusions. custom_metadata: type: object additionalProperties: {} description: Arbitrary client-defined metadata (key/value). CouponRedemptionV1: type: object properties: id: type: string format: uuid coupon_id: type: string format: uuid description: UUID of the redeemed coupon. billing_account_id: type: string format: uuid description: UUID of the billing account that applied the coupon. invoice_id: type: - string - "null" format: uuid description: UUID of the invoice the discount was applied to, when applicable. discount_cents: type: integer description: Discount actually applied in this redemption, in cents (÷100 → BRL). created_at: type: string format: date-time required: - id - coupon_id - billing_account_id - invoice_id - discount_cents - created_at CouponRedemptionListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CouponRedemptionV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CreditV1: type: object properties: id: type: string format: uuid billing_account_id: type: string format: uuid description: UUID of the billing account that owns the credit. organization_id: type: string format: uuid description: Organization (tenant) UUID. company_id: type: - string - "null" format: uuid description: Optional UUID of the linked `company`. When set, the credit can only be applied to invoices from the same `company`. type: type: string enum: - promotional - adjustment - refund - manual description: "Credit type: `promotional`, `adjustment`, `refund` or `manual`." amount_cents: type: integer description: Original credit amount in cents (÷100 → BRL). example: 10000 amount_remaining_cents: type: integer description: Remaining credit balance in cents (÷100 → BRL). example: 10000 currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL description: type: - string - "null" description: Free-form description — shown in the statement and audit log. expires_at: type: - string - "null" format: date-time description: Expiration date and time (ISO8601). `null` when the credit does not expire. metadata: type: - object - "null" additionalProperties: {} description: Internal credit metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom metadata validated against the organization schema. created_at: type: string format: date-time updated_at: type: string format: date-time applications: type: array items: {} description: Applications of this credit to invoices, when the relation is loaded. required: - id - billing_account_id - organization_id - company_id - type - amount_cents - amount_remaining_cents - currency - description - expires_at - metadata - custom_metadata - created_at - updated_at CreditListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/CreditV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta CreditResponse: type: object properties: data: $ref: "#/components/schemas/CreditV1" required: - data CreditCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: UUID of the billing account that will receive the credit. company_id: type: string format: uuid description: Optional UUID of the `company` the credit is tied to. When set, restricts credit application to invoices from the same `company`. type: type: string enum: - promotional - adjustment - refund - manual description: "Credit type: `promotional`, `adjustment`, `refund` or `manual`." amount_cents: type: integer exclusiveMinimum: 0 description: Credit amount in cents (÷100 → BRL). Must be a positive integer. example: 10000 description: type: string maxLength: 500 description: Free-form description (up to 500 characters) — shown in the statement and audit log. expires_at: type: string format: date-time description: Expiration date and time (ISO8601). After this date the remaining balance is discarded. custom_metadata: type: object additionalProperties: {} description: Custom metadata validated against the organization schema. required: - billing_account_id - type - amount_cents CreditUpdateRequest: type: object properties: type: type: string enum: - promotional - adjustment - refund - manual description: "New credit type: `promotional`, `adjustment`, `refund` or `manual`." amount_cents: type: integer exclusiveMinimum: 0 description: New amount in cents (÷100 → BRL). Positive integer. Can only change if the credit has not been used yet. description: type: - string - "null" maxLength: 500 description: New description. Send `null` to clear. expires_at: type: - string - "null" format: date-time description: New expiration date (ISO8601). Send `null` to remove the expiration. custom_metadata: type: object additionalProperties: {} description: Custom metadata validated against the organization schema. CreditDeleteResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data InvoiceLineItemV1: type: object properties: id: type: string format: uuid invoice_id: type: string format: uuid subscription_item_id: type: - string - "null" format: uuid product_id: type: - string - "null" format: uuid price_id: type: - string - "null" format: uuid service_item_id: type: - string - "null" format: uuid type: type: - string - "null" description: type: - string - "null" description: Item description. quantity: type: number description: Quantity. unit_amount_subcents: type: integer description: Unit amount in sub-cents (÷10000 → BRL). amount_cents: type: integer description: Item subtotal in cents (÷100 → BRL). discount_cents: type: - integer - "null" tax_cents: type: - integer - "null" period_start: type: - string - "null" format: date-time period_end: type: - string - "null" format: date-time proration: type: - boolean - "null" proration_details: {} metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time required: - id - invoice_id - quantity - unit_amount_subcents - amount_cents - created_at InvoiceInstallmentV1: type: object properties: id: type: string format: uuid public_id: type: - string - "null" invoice_id: type: string format: uuid number: type: integer description: Sequential installment number (starts at 1). amount_cents: type: integer description: Installment amount in cents (÷100 → BRL). due_date: type: string format: date-time description: Installment due date. status: type: string enum: - pending - paid - canceled description: "Installment status: `pending`, `paid` or `canceled`." payment_id: type: - string - "null" format: uuid paid_at: type: - string - "null" format: date-time metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - invoice_id - number - amount_cents - due_date - status - created_at - updated_at InvoiceV1: type: object properties: id: type: string format: uuid number: type: - string - "null" description: Human-readable invoice number (generated on finalization). billing_account_id: type: string format: uuid description: Target billing account UUID. company_id: type: - string - "null" format: uuid description: Issuing company UUID (optional — defaults to the organization's `default_company`). subscription_id: type: - string - "null" format: uuid description: Originating subscription UUID, when the invoice comes from a subscription. product_group_id: type: - string - "null" format: uuid description: Product group UUID, when the invoice is scoped to a group. status: type: string enum: - draft - open - paid - void - uncollectible description: "Status: `draft`, `open`, `paid`, `void` or `uncollectible`." collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "Collection method: `charge_automatically`, `manual_charge` or `manual_invoice`." currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL subtotal_cents: type: integer description: Sum of line items in cents (÷100 → BRL). discount_cents: type: integer description: Discount applied in cents (÷100 → BRL). tax_cents: type: integer description: Computed taxes in cents (÷100 → BRL). total_withheld_cents: type: integer description: Total tax withholdings (IRRF/ISS/INSS/CSRF) in cents. net_value_cents: type: - integer - "null" description: Net value after withholdings, in cents. total_cents: type: integer description: Invoice total in cents (÷100 → BRL). amount_due_cents: type: integer description: Amount due (charged) in cents. amount_paid_cents: type: integer description: Amount already paid in cents. amount_remaining_cents: type: integer description: Amount remaining to pay in cents. period_start: type: - string - "null" format: date-time description: Start of the billing period (subscription invoices). period_end: type: - string - "null" format: date-time description: End of the billing period (subscription invoices). due_date: type: - string - "null" format: date-time description: Due date. paid_at: type: - string - "null" format: date-time description: Date and time the invoice was settled. voided_at: type: - string - "null" format: date-time description: Date and time the invoice was voided. finalized_at: type: - string - "null" format: date-time description: Date and time the invoice left draft (`draft` → `open`). billing_reason: type: - string - "null" description: "Generation reason: `subscription_cycle`, `subscription_create`, `manual`, etc." description: type: - string - "null" description: Free-form description shown at the top of the invoice. footer: type: - string - "null" description: Free-form footer shown at the bottom of the invoice. hosted_invoice_url: type: - string - "null" description: Public hosted invoice URL. invoice_pdf_url: type: - string - "null" description: Direct URL to the invoice PDF. next_payment_attempt: type: - string - "null" format: date-time description: Next automatic charge attempt (dunning). payment_attempts: type: integer description: Number of charge attempts made. installment_count: type: - integer - "null" description: Number of installments (when the invoice is split). nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment description: "NF-e issuance policy: `disabled`, `on_finalization`, `on_full_payment` or `per_installment`." custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields defined by the organization. created_at: type: string format: date-time updated_at: type: string format: date-time line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemV1" description: Line items — present when included via `include=line_items`. installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentV1" description: Installments — present when included via `include=installments`. required: - id - number - billing_account_id - company_id - subscription_id - product_group_id - status - collection_method - currency - subtotal_cents - discount_cents - tax_cents - total_withheld_cents - net_value_cents - total_cents - amount_due_cents - amount_paid_cents - amount_remaining_cents - period_start - period_end - due_date - paid_at - voided_at - finalized_at - billing_reason - description - footer - hosted_invoice_url - invoice_pdf_url - next_payment_attempt - payment_attempts - installment_count - nfe_issuance_policy - created_at - updated_at InvoiceListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/InvoiceV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta InvoiceResponse: type: object properties: data: $ref: "#/components/schemas/InvoiceV1" required: - data InvoiceLineItemCreateInput: type: object properties: description: type: string minLength: 1 description: Item description. **Required**. quantity: type: number minimum: 1 description: "Quantity. Default: 1." unit_amount_cents: type: number minimum: 0 description: Unit amount in cents. product_id: type: string format: uuid description: Product UUID (optional). price_id: type: string format: uuid description: Price UUID (optional). service_item_id: type: string format: uuid description: Service item UUID (optional). required: - description - unit_amount_cents InvoiceInstallmentCreateInput: type: object properties: amount_cents: type: integer minimum: 1 description: Installment amount in cents. due_date: type: string description: Installment due date. required: - amount_cents - due_date InvoiceCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: Target billing account UUID. **Required**. company_id: type: string format: uuid description: "Issuing company UUID. Default: organization's default company." subscription_id: type: string format: uuid description: Originating subscription UUID. product_group_id: type: string format: uuid description: Product group UUID. collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: "Collection method. Default: `manual_invoice`." due_date: type: string description: "Due date. Default: today + the account's `payment_terms_days`." description: type: string description: Free-form description shown at the top of the invoice. footer: type: string description: Free-form footer shown at the bottom of the invoice. line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemCreateInput" minItems: 1 description: Line items. Minimum 1. discount_cents: type: integer minimum: 0 description: Fixed discount in cents. discount_description: type: string description: 'Discount description (e.g.: "20% annual payment discount").' installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentCreateInput" minItems: 2 description: Installment schedule (minimum 2). Each item has `amount_cents` and `due_date`. nfe_issuance_policy: type: string enum: - disabled - on_finalization - on_full_payment - per_installment description: NF-e issuance policy for installment invoices. period_start: type: string description: Start of the billing period (auto-set for subscription invoices). period_end: type: string description: End of the billing period (auto-set for subscription invoices). custom_metadata: type: object additionalProperties: {} description: Custom fields (validated against the organization's schema). required: - billing_account_id - line_items InvoiceLineItemUpdateInput: type: object properties: id: type: string format: uuid description: type: string minLength: 1 quantity: type: number minimum: 1 unit_amount_cents: type: number minimum: 0 required: - description - unit_amount_cents InvoiceUpdateRequest: type: object properties: company_id: type: - string - "null" format: uuid description: Update the issuing company. Use `null` to clear. collection_method: type: string enum: - charge_automatically - manual_charge - manual_invoice description: Update the collection method. due_date: type: string description: Update the due date. description: type: string footer: type: string line_items: type: array items: $ref: "#/components/schemas/InvoiceLineItemUpdateInput" description: Replaces line items. To preserve an item, pass its `id`. nfe_issuance_policy: type: - string - "null" enum: - disabled - on_finalization - on_full_payment - per_installment description: Update the NF-e policy. Use `null` to clear. custom_metadata: type: object additionalProperties: {} InvoiceVoidRequest: type: object properties: reason: type: string description: Void reason (recorded in the audit log). InvoiceUndoPaymentRequest: type: object properties: reason: type: string description: Reversal reason (recorded in the audit log). InvoicePayRequest: type: object properties: payment_method: type: string enum: - pix - bank_slip - card description: "When provided, triggers the gateway: `pix`, `bank_slip` or `card`. Omit to mark as paid manually." payment_method_id: type: string format: uuid description: "UUID of a saved payment method (e.g.: tokenized card)." card: type: object properties: card_token: type: string minLength: 1 description: Card token obtained on the front-end via the gateway SDK. holder_name: type: string minLength: 3 description: Name printed on the card (minimum 3 characters). required: - card_token - holder_name description: Card data when `payment_method = card` and no `payment_method_id` is provided. amount_cents: type: integer exclusiveMinimum: 0 description: "Amount to charge in cents. Default: invoice remaining amount." installment_ids: type: array items: type: string format: uuid description: UUIDs of the installments the payment covers (split invoices). InvoicePayResponse: type: object properties: data: type: object additionalProperties: {} required: - data InvoiceApplyCreditsRequest: type: object properties: credit_ids: type: array items: type: string format: uuid minItems: 1 description: UUIDs of the credits to apply (minimum 1). amount_cents: type: integer exclusiveMinimum: 0 description: "Amount to apply in cents. Default: covers the entire invoice." required: - credit_ids InvoiceCreditsResponse: type: object properties: data: type: object additionalProperties: {} required: - data InvoiceNfeResponse: type: object properties: data: type: object additionalProperties: {} required: - data InvoicePaymentMethodsResponse: type: object properties: data: type: object properties: invoice_id: type: string format: uuid methods: type: array items: type: string enum: - card - bank_slip - pix - bank_transfer details: type: array items: type: object properties: type: type: string enum: - card - bank_slip - pix - bank_transfer gateway_id: type: string format: uuid gateway_name: type: string is_default: type: boolean required: - type - gateway_id - gateway_name - is_default pagarme_public_key: type: string required: - invoice_id - methods - details required: - data InvoiceInstallmentsListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/InvoiceInstallmentV1" required: - data InvoiceInstallmentsCreateRequest: type: object properties: installments: type: array items: $ref: "#/components/schemas/InvoiceInstallmentCreateInput" minItems: 2 description: Installment list. Minimum 2. required: - installments InvoiceInstallmentResponse: type: object properties: data: allOf: - $ref: "#/components/schemas/InvoiceInstallmentV1" - type: - object - "null" required: - data InvoiceInstallmentPayRequest: type: object properties: payment_method: type: string enum: - pix - bank_slip - card description: "When provided, triggers the gateway: `pix`, `bank_slip` or `card`. Omit to mark as paid manually." payment_method_id: type: string format: uuid description: "UUID of a saved payment method (e.g.: tokenized card)." card: type: object properties: card_token: type: string minLength: 1 description: Card token obtained on the front-end via the gateway SDK. holder_name: type: string minLength: 3 description: Name printed on the card (minimum 3 characters). required: - card_token - holder_name description: Card data when `payment_method = card` and no `payment_method_id` is provided. required: - payment_method InvoiceDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data PaymentV1: type: object properties: id: type: string format: uuid invoice_id: type: - string - "null" format: uuid description: UUID of the associated invoice, when present. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID. company_id: type: - string - "null" format: uuid description: Issuing company UUID. payment_method_id: type: - string - "null" format: uuid description: UUID of the payment method used. gateway_id: type: - string - "null" format: uuid description: UUID of the gateway that processed the payment. payment_method_type: type: - string - "null" enum: - card - bank_slip - pix - bank_transfer description: "Payment method type: `card`, `bank_slip`, `pix` or `bank_transfer`." amount_cents: type: integer description: Charged amount in cents (÷100 → BRL). example: 10000 paid_amount_cents: type: - integer - "null" description: Amount actually received in cents (÷100 → BRL). currency: type: string description: "ISO 4217 currency (e.g.: `BRL`)." example: BRL status: type: string enum: - pending - processing - succeeded - failed - canceled - partial - refunded - partially_refunded description: "Status: `pending`, `processing`, `succeeded`, `failed`, `canceled`, `partial`, `refunded` or `partially_refunded`." payment_gateway: type: - string - "null" description: "Upstream gateway name (e.g.: `KOBANA`, `PAGARME`)." gateway_payment_id: type: - string - "null" description: Payment identifier at the upstream gateway. failure_code: type: - string - "null" description: Failure code returned by the gateway. failure_message: type: - string - "null" description: Failure message returned by the gateway. idempotency_key: type: - string - "null" description: Idempotency key provided when creating the payment. paid_at: type: - string - "null" format: date-time description: Date/time the payment was confirmed. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - invoice_id - billing_account_id - company_id - payment_method_id - gateway_id - payment_method_type - amount_cents - paid_amount_cents - currency - status - payment_gateway - gateway_payment_id - failure_code - failure_message - idempotency_key - paid_at - custom_metadata - created_at - updated_at PaymentListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PaymentV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PaymentResponse: type: object properties: data: $ref: "#/components/schemas/PaymentV1" required: - data PaymentCreateCard: type: object properties: cardToken: type: string minLength: 1 description: Card token issued by the gateway (preferred). number: type: string minLength: 13 maxLength: 19 description: Card number (PAN). Use the token whenever possible. expMonth: type: integer minimum: 1 maximum: 12 description: Expiration month (1–12). expYear: type: integer description: Expiration year (≥ current year). cvv: type: string minLength: 3 maxLength: 4 description: Card CVV/CVC (3 to 4 digits). holderName: type: string minLength: 1 description: Cardholder name as printed on the card. required: - holderName PaymentCreatePaymentMethod: type: object properties: type: type: string enum: - card - bank_slip - pix description: "Payment method type: `card`, `bank_slip` or `pix`." card: allOf: - $ref: "#/components/schemas/PaymentCreateCard" - description: Card data — token (preferred) **or** PAN/expiry/CVV. required: - type PaymentCreateRequest: type: object properties: invoiceId: type: string format: uuid description: UUID of the invoice to be paid. paymentMethodId: type: string format: uuid description: UUID of a payment method previously registered for the account. paymentMethod: allOf: - $ref: "#/components/schemas/PaymentCreatePaymentMethod" - description: Block with payment method data — used when no `payment_method_id` is provided. amountCents: type: integer minimum: 1 description: "Amount to charge in cents (÷100 → BRL). Default: invoice open balance." customMetadata: type: object additionalProperties: {} description: Free-form metadata defined by the client for internal correlation. required: - invoiceId PaymentCancelRequest: type: object properties: reason: type: string description: Cancellation reason (recorded in the audit log). cancel_on_gateway: type: boolean description: When `true` (default), also cancels at the upstream gateway. PaymentRetryCard: type: object properties: cardToken: type: string minLength: 1 description: Card token issued by the gateway. holderName: type: string minLength: 3 description: Cardholder name as printed on the card. required: - cardToken - holderName PaymentRetryRequest: type: object properties: card: allOf: - $ref: "#/components/schemas/PaymentRetryCard" - description: Alternative card (token and holder) for the retry attempt. payment_method_id: type: string format: uuid description: UUID of a saved payment method to use in the retry. PaymentChangeCardRequest: type: object properties: credit_card_id: type: string format: uuid description: UUID of the billing account's active credit card. required: - credit_card_id PaymentChangeDueDateRequest: type: object properties: due_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: New due date in `YYYY-MM-DD` format. example: 2026-08-15 required: - due_date PaymentChangeDueDateResponse: type: object properties: data: type: object properties: due_date: type: string updated: type: boolean required: - due_date - updated required: - data PaymentSendEmailRequest: type: object properties: email: type: string format: email description: Recipient's email address. message: type: string description: Optional message included in the email body. required: - email PaymentSendEmailResponse: type: object properties: data: type: object properties: sent: type: boolean email: type: string format: email required: - sent - email required: - data PaymentRefundRequest: type: object properties: amount_cents: type: integer minimum: 1 description: "Amount to refund in cents (÷100 → BRL). Default: full payment amount." reason: type: string description: Refund reason (recorded in the audit log). PaymentBulkUpdateInvoiceRequest: type: object properties: payment_ids: type: array items: type: string format: uuid minItems: 1 description: List of UUIDs of the payments to update. invoice_id: type: string format: uuid description: UUID of the target invoice. required: - payment_ids - invoice_id PaymentBulkUpdateInvoiceResponse: type: object properties: data: type: object properties: updated_count: type: integer required: - updated_count required: - data PaymentDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data PaymentMethodCreditCardV1: type: object properties: id: type: string format: uuid description: Card record UUID. status: type: string enum: - active - expired - removed description: "Card status: `active`, `expired`, `removed`." brand: type: - string - "null" description: "Card brand (e.g.: `visa`, `mastercard`)." example: visa last_four_digits: type: - string - "null" description: Last four digits of the card. example: "4242" holder_name: type: - string - "null" description: Cardholder name as printed on the card. expiration_month: type: - integer - "null" description: Expiration month (1–12). example: 12 expiration_year: type: - integer - "null" description: Expiration year (4 digits). example: 2030 required: - id - status - brand - last_four_digits - holder_name - expiration_month - expiration_year PaymentMethodBankAccountV1: type: object properties: bank_code: type: - string - "null" description: Bank clearing code (FEBRABAN, 3 digits). example: "341" bank_name: type: - string - "null" description: Bank name, resolved from `bank_code`. example: Itaú agency: type: - string - "null" description: Bank branch / agency. account: type: - string - "null" description: Bank account number. account_type: type: - string - "null" enum: - checking - savings description: "Account type: `checking` or `savings`." holder_name: type: - string - "null" description: Account holder name. required: - bank_code - bank_name - agency - account - account_type - holder_name PaymentMethodV1: type: object properties: id: type: string format: uuid billing_account_id: type: string format: uuid description: UUID of the owner billing account. credit_card_id: type: - string - "null" format: uuid description: UUID of the associated `credit_card`, when `type=card`. type: type: string enum: - card - bank_slip - pix - bank_transfer description: "Method type: `card`, `bank_slip`, `pix` or `bank_transfer`." status: type: string enum: - active - expired - failed - removed description: "Method status: `active`, `expired`, `failed` or `removed`." is_default: type: boolean description: Whether this is the default method for the billing account. is_backup: type: boolean description: Whether the method is used as a backup for the default. billing_details: type: - object - "null" additionalProperties: {} description: Optional billing details (name, email, phone, address) sent to the gateway. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form custom metadata (`object`). created_at: type: string format: date-time updated_at: type: string format: date-time bank_account: allOf: - $ref: "#/components/schemas/PaymentMethodBankAccountV1" - description: Public preview of the bank account, present when `type=bank_transfer`. Holder document is omitted. credit_card: allOf: - $ref: "#/components/schemas/PaymentMethodCreditCardV1" - description: Public preview of the card, present when `type=card`. Gateway tokens and fingerprint are omitted. required: - id - billing_account_id - credit_card_id - type - status - is_default - is_backup - created_at - updated_at PaymentMethodListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PaymentMethodV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PaymentMethodResponse: type: object properties: data: $ref: "#/components/schemas/PaymentMethodV1" required: - data PaymentMethodCardInput: type: object properties: cardToken: type: string minLength: 1 description: Card token produced by the gateway client-side tokenization. holderName: type: string minLength: 1 description: Cardholder name as printed on the card. required: - cardToken - holderName PaymentMethodBankAccountInput: type: object properties: bankCode: type: string minLength: 3 maxLength: 3 description: Bank clearing code (FEBRABAN, 3 digits). example: "341" agency: type: string minLength: 1 description: Bank branch / agency. account: type: string minLength: 1 description: Bank account number. accountType: type: string enum: - checking - savings description: "Account type: `checking` or `savings`." holderName: type: string minLength: 1 description: Account holder name. holderDocument: type: string minLength: 11 maxLength: 14 description: Holder's CPF or CNPJ (11–14 digits). required: - bankCode - agency - account - accountType - holderName - holderDocument PaymentMethodBillingAddress: type: object properties: street: type: string number: type: string complement: type: string neighborhood: type: string city: type: string state: type: string minLength: 2 maxLength: 2 zipCode: type: string country: type: string required: - street - number - neighborhood - city - state - zipCode PaymentMethodBillingDetailsInput: type: object properties: name: type: string description: Name for the billing details. email: type: string format: email description: Email for the billing details. phone: type: string description: Phone for the billing details. address: allOf: - $ref: "#/components/schemas/PaymentMethodBillingAddress" - description: Billing address. PaymentMethodCreateRequest: type: object properties: billingAccountId: type: string format: uuid description: UUID of the billing account that owns the payment method. type: type: string enum: - card - bank_slip - pix - bank_transfer description: "Method type: `card`, `bank_slip`, `pix` or `bank_transfer`." isDefault: type: boolean description: When `true`, marks this method as the account default (unsets previous defaults). The first method created for an account also becomes the default automatically. card: allOf: - $ref: "#/components/schemas/PaymentMethodCardInput" - description: Card block. Required when `type=card`. bankAccount: allOf: - $ref: "#/components/schemas/PaymentMethodBankAccountInput" - description: Bank account block. Required when `type=bank_transfer`. billingDetails: allOf: - $ref: "#/components/schemas/PaymentMethodBillingDetailsInput" - description: Optional billing details (name, email, phone, address) used by the gateway. required: - billingAccountId - type PaymentMethodUpdateRequest: type: object properties: exp_month: type: integer minimum: 1 maximum: 12 description: Card expiration month (1–12). exp_year: type: integer description: Card expiration year (>= current year). required: - exp_month - exp_year NfeV1: type: object properties: id: type: string format: uuid invoice_id: type: - string - "null" format: uuid description: Linked invoice UUID (when the NF-e was issued for an invoice). transaction_id: type: - string - "null" format: uuid description: Originating transaction UUID, when applicable. billing_account_id: type: string format: uuid description: NF-e billing account (taker) UUID. organization_id: type: string format: uuid description: Issuing organization UUID. company_id: type: - string - "null" format: uuid description: Issuing company (provider) UUID. Optional when the organization has a default company. person_id: type: - string - "null" format: uuid description: Person (taker) UUID associated with the NF-e. status: type: string enum: - draft - pending - processing - issued - pending_cancel - canceling - canceled - error description: "Status: `draft`, `pending`, `processing`, `issued`, `pending_cancel`, `canceling`, `canceled` or `error`." nfe_number: type: - integer - "null" description: NF-e number assigned by the municipality (set after issuance). nfe_series: type: - string - "null" description: NF-e series. nfe_key: type: - string - "null" description: Unique NF-e access key (44 or 50 digits, depending on the municipality). verification_code: type: - string - "null" description: Verification/authenticity code printed on the DANFSE. issue_date: type: - string - "null" format: date-time description: Date and time of issuance by the municipality. cancelled_at: type: - string - "null" format: date-time description: Cancellation date and time (when applicable). amount_cents: type: integer description: NF-e amount in cents (÷100 → BRL). service_code: type: - string - "null" description: Service code per the municipal table. service_description: type: - string - "null" description: Free-form description of the service provided. lc116_code: type: - string - "null" description: LC 116 code (national service list). cnae_code: type: - string - "null" description: Activity CNAE code. nbs_code: type: - string - "null" description: NBS code (Brazilian Service Nomenclature). ncm_code: type: - string - "null" description: NCM code (Mercosur Common Nomenclature), when applicable. customer_snapshot: type: object additionalProperties: {} description: Snapshot of taker data at issuance time (name, document, address). taxes: type: object additionalProperties: {} description: Tax rates and amounts (ISS, PIS, COFINS, CSLL, IR, INSS). xml_url: type: - string - "null" description: Public URL for the XML hosted by the provider. pdf_url: type: - string - "null" description: Public URL for the PDF (DANFE/DANFSE) hosted by the provider. provider_company_id: type: - string - "null" description: Company identifier on the external provider. rps_number: type: - integer - "null" description: RPS (Provisional Service Receipt) number. rps_serial_number: type: - string - "null" description: RPS series. issue_attempts: type: integer description: Number of issuance attempts made. cancel_attempts: type: integer description: Number of cancellation attempts made. next_retry_at: type: - string - "null" format: date-time description: Date and time of the next automatic retry (issuance or cancellation). error_message: type: - string - "null" description: Error message returned by the provider on the last attempt. custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields defined by the organization. pdf_downloaded_at: type: - string - "null" format: date-time description: Date the PDF was downloaded and stored in the database. xml_downloaded_at: type: - string - "null" format: date-time description: Date the XML was downloaded and stored in the database. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - invoice_id - transaction_id - billing_account_id - organization_id - company_id - person_id - status - nfe_number - nfe_series - nfe_key - verification_code - issue_date - cancelled_at - amount_cents - service_code - service_description - lc116_code - cnae_code - nbs_code - ncm_code - customer_snapshot - taxes - xml_url - pdf_url - provider_company_id - rps_number - rps_serial_number - issue_attempts - cancel_attempts - next_retry_at - error_message - pdf_downloaded_at - xml_downloaded_at - created_at - updated_at NfeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NfeResponse: type: object properties: data: $ref: "#/components/schemas/NfeV1" required: - data NfeCustomerAddressInput: type: object properties: street: type: string description: Street. number: type: string description: Address number. complement: type: string description: Complement (optional). neighborhood: type: string description: Neighborhood. city: type: string description: City. city_code: type: string description: IBGE city code (optional). state: type: string description: State (two-letter code). zip_code: type: string description: ZIP code. country: type: string description: Country (optional, defaults to `BR`). required: - street - number - neighborhood - city - state - zip_code description: Taker's address. NfeCustomerInput: type: object properties: name: type: string minLength: 1 description: Taker's name or legal name. email: type: string format: email description: Taker's email. document_type: type: string enum: - cpf - cnpj description: "Document type: `cpf` or `cnpj`." document_number: type: string minLength: 1 description: Document number (digits only or formatted). phone: type: string description: Taker's phone. address: $ref: "#/components/schemas/NfeCustomerAddressInput" required: - name - email - document_type - document_number description: Taker data at issuance time. **Required**. NfeTaxesInput: type: object properties: iss_rate: type: number description: ISS rate (decimal). pis_rate: type: number description: PIS rate (decimal). cofins_rate: type: number description: COFINS rate (decimal). csll_rate: type: number description: CSLL rate (decimal). ir_rate: type: number description: IR (income tax) rate (decimal). inss_rate: type: number description: INSS rate (decimal). description: "Tax rates (as decimals, e.g.: `0.05` for 5%). Falls back to company defaults when omitted." NfeCreateRequest: type: object properties: billing_account_id: type: string format: uuid description: Billing account (taker) UUID. **Required**. company_id: type: string format: uuid description: "Issuing company (provider) UUID. Default: organization's default company." invoice_id: type: string format: uuid description: Linked invoice UUID (optional). transaction_id: type: string format: uuid description: Originating transaction UUID (optional). amount_cents: type: integer exclusiveMinimum: 0 description: NF-e amount in cents (÷100 → BRL). **Required**, must be positive. service_code: type: string description: Service code per the municipal table. service_description: type: string description: Free-form description of the service provided. lc116_code: type: string description: LC 116 code. cnae_code: type: string description: CNAE code. nbs_code: type: string description: NBS code. rps_number: type: integer description: RPS number (when numbering is managed by the application). rps_serial_number: type: string description: RPS series. customer: $ref: "#/components/schemas/NfeCustomerInput" taxes: $ref: "#/components/schemas/NfeTaxesInput" custom_metadata: type: object additionalProperties: {} description: Custom fields (validated against the organization's schema). required: - billing_account_id - amount_cents - customer NfeUpdateRequest: type: object properties: service_code: type: string description: Update the service code. service_description: type: string description: Update the service description. amount_cents: type: integer exclusiveMinimum: 0 description: Update the NF-e amount in cents. lc116_code: type: - string - "null" description: Update the LC 116 code. Use `null` to clear. cnae_code: type: - string - "null" description: Update the CNAE code. Use `null` to clear. nbs_code: type: - string - "null" description: Update the NBS code. Use `null` to clear. ncm_code: type: - string - "null" description: Update the NCM code. Use `null` to clear. rps_number: type: - integer - "null" description: Update the RPS number. Use `null` to clear. rps_serial_number: type: - string - "null" description: Update the RPS series. Use `null` to clear. customer_snapshot: type: object additionalProperties: {} description: Replace the taker snapshot. taxes: type: object additionalProperties: {} description: Replace the tax rates and amounts. custom_metadata: type: object additionalProperties: {} description: Update custom fields. NfeCancelRequest: type: object properties: reason: type: string minLength: 15 description: Cancellation reason. **Minimum 15 characters**. Recorded in the audit log and sent to the provider. required: - reason NfeDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data NfeBulkUpdateRequest: type: object properties: nfe_ids: type: array items: type: string format: uuid minItems: 1 description: UUIDs of the NF-e to update. Minimum 1. invoice_id: type: - string - "null" format: uuid description: UUID of the invoice to link. Send `null` to unlink. required: - nfe_ids - invoice_id NfeBulkUpdateResponse: type: object properties: data: type: object properties: updated: type: integer required: - updated required: - data NfeBulkDeleteRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 maxItems: 100 description: UUIDs of the NF-e to delete. Minimum 1, maximum 100. required: - ids NfeBulkDeleteResponse: type: object properties: data: type: object properties: deleted_count: type: integer required: - deleted_count required: - data NfeSyncOrgResponse: type: object properties: data: type: object properties: job_id: type: string status: type: string required: - job_id - status required: - data NfeRequestTryV1: type: object properties: id: type: string format: uuid nfe_id: type: string format: uuid action: type: string description: "Attempted action: `issue`, `cancel` or `query`." endpoint: type: string description: Provider endpoint called. request_body: type: - string - "null" response_body: type: - string - "null" http_status: type: - string - "null" description: HTTP status returned by the provider. success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" description: Request duration in milliseconds. created_at: type: string format: date-time required: - id - nfe_id - action - endpoint - request_body - response_body - http_status - success - error_message - duration_ms - created_at NfeRequestTryListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeRequestTryV1" required: - data NfeRequestTryPaginatedResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeRequestTryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NfeExternalRequestSummaryV1: type: object properties: id: type: string format: uuid nfe_id: type: - string - "null" format: uuid invoice_id: type: - string - "null" format: uuid direction: type: string enum: - outbound - inbound description: "Request direction: `outbound` (outgoing call) or `inbound` (incoming webhook)." service: type: - string - "null" description: "External provider/service (e.g.: `nfeio`, `barueri`)." method: type: string endpoint: type: string http_status: type: - integer - "null" success: type: boolean error_message: type: - string - "null" duration_ms: type: - integer - "null" created_at: type: string format: date-time required: - id - nfe_id - invoice_id - direction - service - method - endpoint - http_status - success - error_message - duration_ms - created_at NfeExternalRequestV1: allOf: - $ref: "#/components/schemas/NfeExternalRequestSummaryV1" - type: object properties: request_headers: type: - object - "null" additionalProperties: {} request_body: type: - string - "null" response_headers: type: - object - "null" additionalProperties: {} response_body: type: - string - "null" metadata: type: - object - "null" additionalProperties: {} required: - request_headers - request_body - response_headers - response_body - metadata NfeExternalRequestListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/NfeExternalRequestSummaryV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta NfeExternalRequestResponse: type: object properties: data: $ref: "#/components/schemas/NfeExternalRequestV1" required: - data NfeFetchBarueriRequest: type: object properties: codigo_autenticidade: type: string minLength: 1 description: Authenticity code printed on the NFS-e DANFSE. cnpj_tomador: type: string minLength: 1 description: Taker's CPF or CNPJ (digits only or formatted). ambiente: type: string enum: - production - homologation description: "Municipal environment: `production` or `homologation`. Default: `production`." required: - codigo_autenticidade - cnpj_tomador NfeFetchBarueriResponse: type: object properties: data: type: object additionalProperties: {} required: - data NfeImportBarueriRequest: type: object properties: xml: type: string description: Raw XML returned by `POST /nfes/fetch-barueri`. Optional — when omitted, the NFS-e is re-fetched with `codigo_autenticidade` + `cnpj_tomador`. codigo_autenticidade: type: string minLength: 1 description: Authenticity code printed on the NFS-e DANFSE. cnpj_tomador: type: string minLength: 1 description: Taker's CPF or CNPJ (digits only or formatted). ambiente: type: string enum: - production - homologation description: "Municipal environment: `production` or `homologation`. Default: `production`." required: - codigo_autenticidade - cnpj_tomador NfeImportBarueriResponse: type: object properties: data: type: object additionalProperties: {} required: - data NfeValidateBarueriResponse: type: object properties: data: type: object additionalProperties: {} required: - data NfeFetchFromSefazRequest: type: object properties: access_key: type: string minLength: 1 description: NFS-e access key (50 digits). certificate_id: type: string minLength: 1 description: UUID of the digital certificate registered in the organization (used for mTLS authentication). ambiente: anyOf: - type: number enum: - 1 - type: number enum: - 2 description: "SEFAZ environment: `1` (production) or `2` (homologation). Default: `2`." required: - access_key - certificate_id NfeFetchFromSefazResponse: type: object properties: data: type: object additionalProperties: {} required: - data ProposalItemV1: type: object properties: id: type: string format: uuid proposal_id: type: string format: uuid product_id: type: - string - "null" format: uuid description: Product UUID. price_id: type: - string - "null" format: uuid description: Price UUID. quantity: type: number description: Quantity. unit_amount_subcents: type: integer description: Unit amount in sub-cents (÷10000 → BRL). setup_amount_subcents: type: - integer - "null" description: Unit setup amount in sub-cents (÷10000 → BRL). excess_amount_subcents: type: - integer - "null" description: Excess (overage) amount in sub-cents (÷10000 → BRL). metadata: type: - object - "null" additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - proposal_id - product_id - price_id - quantity - unit_amount_subcents - created_at - updated_at ProposalV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Public UUID — exposed in portal URLs (`/p/{code}`). company_id: type: - string - "null" format: uuid description: Issuing company UUID (optional). code: type: string description: "Short code, unique per organization (e.g.: `PROP-0001`)." title: type: string description: 'Proposal title (default: "Proposta Comercial").' description: type: - string - "null" description: Free-form description shown on the proposal. billing_account_id: type: - string - "null" format: uuid description: Target billing account UUID, when the proposal targets an existing customer. prospect_id: type: - string - "null" format: uuid description: Prospect UUID (juridical person being prospected), when no `billing_account_id` exists yet. contact_id: type: - string - "null" format: uuid description: Contact UUID (natural person responsible inside the prospect). coupon_id: type: - string - "null" format: uuid description: Coupon UUID applied to the proposal. template_id: type: - string - "null" format: uuid description: Template UUID used to generate the PDF. document_google_id: type: - string - "null" description: Google Doc ID generated by the App Script. document_url: type: - string - "null" description: Google Doc URL. pdf_url: type: - string - "null" description: Public proposal PDF URL. generated_at: type: - string - "null" format: date-time description: Date and time of the last PDF generation. pdf_outdated_at: type: - string - "null" format: date-time description: Marks when the PDF became stale compared to current items/prices. expires_at: type: - string - "null" format: date-time description: Proposal expiration date. status: type: string enum: - draft - sent - viewed - accepted - rejected - expired - canceled description: "Status: `draft`, `sent`, `viewed`, `accepted`, `rejected`, `expired` or `canceled`." rejection_reason: type: - string - "null" description: Rejection reason provided by the prospect. setup_amount_cents: type: integer description: Setup (one-time) amount in cents (÷100 → BRL). monthly_amount_cents: type: integer description: Recurring monthly amount in cents (÷100 → BRL). notes: type: - string - "null" description: Internal notes (not shown to the customer). custom_metadata: type: - object - "null" additionalProperties: {} description: Custom fields defined by the organization. created_at: type: string format: date-time updated_at: type: string format: date-time sent_at: type: - string - "null" format: date-time description: Date and time the proposal was sent. viewed_at: type: - string - "null" format: date-time description: Date and time of the first view by the recipient. accepted_at: type: - string - "null" format: date-time description: Date and time of acceptance. rejected_at: type: - string - "null" format: date-time description: Date and time of rejection. items: type: array items: $ref: "#/components/schemas/ProposalItemV1" description: Proposal items — present when included via `include=items`. required: - id - public_id - company_id - code - title - description - billing_account_id - prospect_id - contact_id - coupon_id - template_id - document_google_id - document_url - pdf_url - generated_at - pdf_outdated_at - expires_at - status - rejection_reason - setup_amount_cents - monthly_amount_cents - notes - created_at - updated_at - sent_at - viewed_at - accepted_at - rejected_at ProposalListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProposalV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProposalResponse: type: object properties: data: $ref: "#/components/schemas/ProposalV1" required: - data ProposalItemInput: type: object properties: product_id: type: string format: uuid description: Product UUID. **Required**. price_id: type: string format: uuid description: Price UUID. **Required**. quantity: type: number minimum: 1 description: "Quantity. Default: 1." unit_amount_subcents: type: number minimum: 0 description: Unit amount in sub-cents (÷10000 → BRL). custom_metadata: type: object additionalProperties: {} description: Item custom fields. required: - product_id - price_id - unit_amount_subcents ProspectDataInput: type: object properties: document: type: string description: Prospect CNPJ (digits only or formatted). name: type: string minLength: 1 description: Prospect legal/company name. legal_name: type: string description: Alternate legal name. nickname: type: string description: Trade name. email: type: string format: email description: Primary prospect email. phone: type: string description: Primary prospect phone. required: - name description: Data to create a prospect inline (juridical person). Alternative to `prospect_id`/`billing_account_id`. ContactDataInput: type: object properties: name: type: string minLength: 1 description: Contact name (person in charge). email: type: string format: email description: Contact email. phone: type: string description: Contact phone. required: - name description: Data to create a contact inline (natural person in charge). ProposalCreateRequest: type: object properties: company_id: type: - string - "null" format: uuid description: Issuing company UUID. Use `null` to clear. title: type: string minLength: 1 maxLength: 255 description: 'Proposal title. Default: "Proposta Comercial".' description: type: - string - "null" description: Free-form proposal description. billing_account_id: type: - string - "null" format: uuid description: Target billing account UUID (existing customer). Required if `prospect_id` and `prospect_data` are not provided. prospect_id: type: - string - "null" format: uuid description: UUID of an existing prospect. Alternative to `billing_account_id`/`prospect_data`. contact_id: type: - string - "null" format: uuid description: UUID of an existing contact linked to the prospect. prospect_data: $ref: "#/components/schemas/ProspectDataInput" contact_data: $ref: "#/components/schemas/ContactDataInput" coupon_id: type: - string - "null" format: uuid description: Coupon UUID to apply. template_id: type: - string - "null" format: uuid description: Template UUID for PDF generation. expires_at: type: string description: Expiration date. notes: type: - string - "null" description: Internal notes. items: type: array items: $ref: "#/components/schemas/ProposalItemInput" minItems: 1 description: Proposal items. Minimum 1. custom_metadata: type: object additionalProperties: {} description: Custom fields (validated against the organization's schema). ProposalUpdateRequest: type: object properties: company_id: type: - string - "null" format: uuid title: type: string minLength: 1 maxLength: 255 description: Update the title. description: type: - string - "null" description: Update the description. Use `null` to clear. billing_account_id: type: - string - "null" format: uuid prospect_id: type: - string - "null" format: uuid contact_id: type: - string - "null" format: uuid prospect_data: $ref: "#/components/schemas/ProspectDataInput" contact_data: $ref: "#/components/schemas/ContactDataInput" coupon_id: type: - string - "null" format: uuid template_id: type: - string - "null" format: uuid expires_at: type: - string - "null" description: Update the expiration date. Use `null` to clear. notes: type: - string - "null" description: Update the notes. Use `null` to clear. items: type: array items: $ref: "#/components/schemas/ProposalItemInput" description: Replaces the proposal items list. custom_metadata: type: object additionalProperties: {} ProposalAcceptRequest: type: object properties: cycle: type: string enum: - monthly - quarterly - semiannual - annual description: "Billing cycle of the subscription created on acceptance: `monthly`, `quarterly`, `semiannual` or `annual`." required: - cycle ProposalAcceptResponse: type: object properties: data: type: object properties: proposal: $ref: "#/components/schemas/ProposalV1" subscription_id: type: - string - "null" format: uuid invoice_id: type: - string - "null" format: uuid required: - proposal - subscription_id - invoice_id required: - data ProposalSendRequest: type: object properties: subject: type: string description: "Custom email subject. Default: `Proposta {code}`." message: type: string description: Custom HTML message for the email body. ProposalGeneratePdfResponse: type: object properties: data: type: object properties: proposal: $ref: "#/components/schemas/ProposalV1" pdf: type: object properties: document_id: type: - string - "null" document_url: type: - string - "null" pdf_url: type: - string - "null" required: - document_id - document_url - pdf_url required: - proposal - pdf required: - data ProposalJsonResponse: type: object properties: data: type: object properties: template_data: {} proposal: type: object properties: id: type: string format: uuid code: type: string template_google_doc_id: type: - string - "null" document_google_id: type: - string - "null" required: - id - code - template_google_doc_id - document_google_id required: - proposal required: - data ProposalPricingResponse: type: object properties: data: type: object additionalProperties: {} required: - data ProposalItemsListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProposalItemV1" required: - data ProposalItemResponse: type: object properties: data: $ref: "#/components/schemas/ProposalItemV1" required: - data ProposalItemUpdateRequest: type: object properties: quantity: type: integer minimum: 1 description: Update quantity. unit_amount_subcents: type: number minimum: 0 description: Update unit amount in sub-cents (÷10000 → BRL). setup_amount_subcents: type: number minimum: 0 description: Update unit setup amount in sub-cents (÷10000 → BRL). custom_metadata: type: object additionalProperties: {} description: proposals.items.update.body.custom_metadata ProposalBulkRequest: type: object properties: ids: type: array items: type: string format: uuid minItems: 1 maxItems: 100 description: List of target proposal UUIDs. Minimum 1, maximum 100. required: - ids ProposalBulkResponse: type: object properties: data: type: object properties: success_count: type: integer failed_count: type: integer errors: type: array items: type: object additionalProperties: {} required: - success_count - failed_count - errors required: - data ProposalStatsResponse: type: object properties: data: type: object additionalProperties: type: integer required: - data ProposalDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data ProposalTemplateV1: type: object properties: id: type: string format: uuid public_id: type: string format: uuid description: Stable public identifier of the template. name: type: string description: Template name (unique per organization). description: type: - string - "null" description: Free-form template description. document_type: type: string enum: - google_doc - google_slides description: "Base document type: `google_doc` or `google_slides`." google_doc_id: type: string description: Google Doc/Slides ID used as the template base. app_script_url: type: - string - "null" description: URL of the Apps Script that renders the template, when configured. google_drive_folder_id: type: - string - "null" description: Google Drive folder ID where generated copies are saved. is_default: type: boolean description: Indicates whether this is the organization default template. is_active: type: boolean description: Indicates whether the template is available for use in new proposals. metadata: type: - object - "null" additionalProperties: {} description: Internal template metadata (free-form structure). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - public_id - name - description - document_type - google_doc_id - app_script_url - google_drive_folder_id - is_default - is_active - metadata - created_at - updated_at ProposalTemplateListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ProposalTemplateV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ProposalTemplateResponse: type: object properties: data: $ref: "#/components/schemas/ProposalTemplateV1" required: - data ProposalTemplateCreateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Template name (unique per organization). description: type: - string - "null" description: Optional template description. documentType: type: string enum: - google_doc - google_slides description: "Base document type: `google_doc` or `google_slides`. Default: `google_doc`." googleDocId: type: string minLength: 1 description: Google Doc/Slides ID used as the template (unique per organization). appScriptUrl: type: - string - "null" format: uri description: URL of the published Apps Script that renders the template, when applicable. googleDriveFolderId: type: - string - "null" description: Google Drive folder ID where generated copies will be saved. isDefault: type: boolean description: When `true`, marks this template as the organization default. isActive: type: boolean description: When `false`, creates the template already deactivated. customMetadata: type: object additionalProperties: {} description: Free-form metadata defined by the client for internal correlation. required: - name - googleDocId ProposalTemplateUpdateRequest: type: object properties: name: type: string minLength: 1 maxLength: 255 description: New template name. description: type: - string - "null" description: New template description. documentType: type: string enum: - google_doc - google_slides description: "New base document type: `google_doc` or `google_slides`." googleDocId: type: string minLength: 1 description: New Google Doc/Slides ID used as the template. appScriptUrl: type: - string - "null" format: uri description: New URL of the published Apps Script. googleDriveFolderId: type: - string - "null" description: New Google Drive folder ID. isDefault: type: boolean description: When `true`, marks this template as the default. isActive: type: boolean description: Enables or disables the template. customMetadata: type: object additionalProperties: {} description: New free-form metadata defined by the client. PlanChangeV1: type: object properties: id: type: string format: uuid subscription_id: type: string format: uuid description: UUID of the subscription targeted by the change. billing_account_id: type: string format: uuid description: Billing account UUID. organization_id: type: string format: uuid description: UUID of the organization that owns the resource. from_plan_id: type: string format: uuid description: UUID of the source plan. to_plan_id: type: string format: uuid description: UUID of the target plan. change_type: type: string enum: - upgrade - downgrade - lateral description: "Change type: `upgrade`, `downgrade` or `lateral`." status: type: string enum: - pending - scheduled - completed - canceled - failed description: "Status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." timing: type: string enum: - immediate - end_of_period description: "When the change is/was applied: `immediate` or `end_of_period`." proration_method: type: string enum: - full_proration - no_proration - partial_proration description: Proration method effectively used. effective_date: type: string format: date-time description: Date when the change becomes effective. scheduled_date: type: - string - "null" format: date-time description: Date scheduled for application (when `timing = end_of_period`). completed_at: type: - string - "null" format: date-time description: When the change was completed. canceled_at: type: - string - "null" format: date-time description: When the change was canceled. from_price_subcents: type: integer description: Source plan price in sub-cents (÷10000 → BRL). example: 1000000 to_price_subcents: type: integer description: Target plan price in sub-cents (÷10000 → BRL). example: 2000000 price_difference_subcents: type: integer description: Difference `to - from` in sub-cents (÷10000 → BRL). proration_credit_subcents: type: integer description: Credit generated by proration in sub-cents (÷10000 → BRL). proration_charge_subcents: type: integer description: Additional charge from proration in sub-cents (÷10000 → BRL). days_remaining: type: integer description: Days remaining in the current period at the moment of the change. total_days_in_period: type: integer description: Total days in the billing period. invoice_id: type: - string - "null" format: uuid description: UUID of the proration invoice issued (if any). credit_id: type: - string - "null" format: uuid description: UUID of the generated credit (if any). reason: type: - string - "null" description: Reason recorded by the change initiator. initiated_by: type: - string - "null" description: Initiator identifier (user email, API key name or `api`). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - subscription_id - billing_account_id - organization_id - from_plan_id - to_plan_id - change_type - status - timing - proration_method - effective_date - scheduled_date - completed_at - canceled_at - from_price_subcents - to_price_subcents - price_difference_subcents - proration_credit_subcents - proration_charge_subcents - days_remaining - total_days_in_period - invoice_id - credit_id - reason - initiated_by - created_at - updated_at PlanChangeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanChangeV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta PlanChangeResponse: type: object properties: data: $ref: "#/components/schemas/PlanChangeV1" required: - data PlanChangeExecuteRequest: type: object properties: subscription_id: type: string format: uuid description: UUID of the subscription that will have its plan changed. to_plan_id: type: string format: uuid description: UUID of the target plan. timing: type: string enum: - immediate - end_of_period description: "When to apply the change: `immediate` (default for upgrades) or `end_of_period` (default for downgrades)." reason: type: string description: Reason for the change (recorded in the audit log). required: - subscription_id - to_plan_id PlanChangeExecuteResponse: type: object properties: data: type: object properties: plan_change_id: type: string format: uuid description: UUID of the created plan change. invoice_id: type: - string - "null" format: uuid description: UUID of the proration invoice issued (if any). credit_id: type: - string - "null" format: uuid description: UUID of the generated credit (if any). required: - plan_change_id - invoice_id - credit_id required: - data PlanChangeStatsResponse: type: object properties: data: type: object properties: total: type: integer description: Total changes in the window. by_type: type: object additionalProperties: type: integer description: "Count by type (keys: `upgrade`, `downgrade`, `lateral`)." by_status: type: object additionalProperties: type: integer description: Count by status. upgrades: type: integer description: Number of upgrades in the window. downgrades: type: integer description: Number of downgrades in the window. total_proration_credits_subcents: type: integer description: Sum of proration credits issued in sub-cents (÷10000 → BRL). total_proration_charges_subcents: type: integer description: Sum of proration charges in sub-cents (÷10000 → BRL). required: - total - by_type - by_status - upgrades - downgrades - total_proration_credits_subcents - total_proration_charges_subcents required: - data PlanChangeConfigV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization that owns the configuration. allow_upgrade: type: boolean description: Upgrades are enabled. allow_downgrade: type: boolean description: Downgrades are enabled. upgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method for upgrades. downgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method for downgrades. upgrade_timing: type: string enum: - immediate - end_of_period description: When to apply upgrades by default. downgrade_timing: type: string enum: - immediate - end_of_period description: When to apply downgrades by default. refund_on_downgrade: type: boolean description: Refunds the difference when downgrading. credit_on_downgrade: type: boolean description: Generates credit when downgrading. apply_discount_on_change: type: boolean description: Keeps active discounts when changing plans. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - allow_upgrade - allow_downgrade - upgrade_proration - downgrade_proration - upgrade_timing - downgrade_timing - refund_on_downgrade - credit_on_downgrade - apply_discount_on_change - created_at - updated_at PlanChangeConfigResponse: type: object properties: data: $ref: "#/components/schemas/PlanChangeConfigV1" required: - data PlanChangeConfigUpdateRequest: type: object properties: allow_upgrade: type: boolean description: Enables plan upgrades for the organization. allow_downgrade: type: boolean description: Enables plan downgrades for the organization. upgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: "Default proration method for upgrades: `full_proration`, `no_proration` or `partial_proration`." downgrade_proration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method for downgrades. upgrade_timing: type: string enum: - immediate - end_of_period description: "When to apply upgrades: `immediate` or `end_of_period`." downgrade_timing: type: string enum: - immediate - end_of_period description: "When to apply downgrades: `immediate` or `end_of_period`." refund_on_downgrade: type: boolean description: Refunds the difference when downgrading. credit_on_downgrade: type: boolean description: Generates credit (instead of refund) when downgrading. apply_discount_on_change: type: boolean description: Keeps active discounts when changing plans. PlanChangeRuleV1: type: object properties: id: type: string format: uuid from_plan_id: type: - string - "null" format: uuid description: UUID of the source plan, or `null` for any. to_plan_id: type: - string - "null" format: uuid description: UUID of the target plan, or `null` for any. change_type: type: - string - "null" enum: - upgrade - downgrade - lateral description: "Change type covered: `upgrade`, `downgrade` or `lateral` (or `null` for any)." allowed: type: boolean description: When `false`, the transition is blocked. timing: type: - string - "null" enum: - immediate - end_of_period description: Timing overridden by this rule. proration_method: type: - string - "null" enum: - full_proration - no_proration - partial_proration description: Proration method overridden by this rule. discount_percent: type: - integer - "null" description: Percent discount (0–100) applied. bonus_days: type: - integer - "null" description: Bonus days granted. message: type: - string - "null" description: Message shown to the customer. is_active: type: boolean description: Whether the rule is active. priority: type: integer description: Priority for conflict resolution (higher wins). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - from_plan_id - to_plan_id - change_type - allowed - timing - proration_method - discount_percent - bonus_days - message - is_active - priority - created_at - updated_at PlanChangeRuleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/PlanChangeRuleV1" required: - data PlanChangeRuleResponse: type: object properties: data: $ref: "#/components/schemas/PlanChangeRuleV1" required: - data PlanChangeRuleCreateRequest: type: object properties: from_plan_id: type: string format: uuid description: UUID of the source plan. When omitted, the rule covers any source plan. to_plan_id: type: string format: uuid description: UUID of the target plan. When omitted, the rule covers any target plan. change_type: type: string enum: - upgrade - downgrade - lateral description: "Change type: `upgrade`, `downgrade` or `lateral`." allowed: type: boolean description: When `false`, explicitly blocks the transition. timing: type: string enum: - immediate - end_of_period description: "Overrides the change timing: `immediate` or `end_of_period`." proration_method: type: string enum: - full_proration - no_proration - partial_proration description: "Overrides the proration method: `full_proration`, `no_proration` or `partial_proration`." discount_percent: type: number minimum: 0 maximum: 100 description: Percent discount applied when this rule matches (0 to 100). bonus_days: type: integer minimum: 0 description: Bonus days added to the current period when this rule is applied. message: type: string description: "Free-form message shown in the portal/checkout (e.g.: block reason)." priority: type: integer description: Priority for conflict resolution when multiple rules match (higher wins). PlanChangeRuleUpdateRequest: type: object properties: allowed: type: boolean description: When `false`, explicitly blocks the transition. timing: type: string enum: - immediate - end_of_period description: "Overrides the change timing: `immediate` or `end_of_period`." proration_method: type: string enum: - full_proration - no_proration - partial_proration description: "Overrides the proration method: `full_proration`, `no_proration` or `partial_proration`." discount_percent: type: number minimum: 0 maximum: 100 description: Percent discount applied when this rule matches (0 to 100). bonus_days: type: integer minimum: 0 description: Bonus days added to the current period when this rule is applied. message: type: string description: "Free-form message shown in the portal/checkout (e.g.: block reason)." priority: type: integer description: Priority for conflict resolution when multiple rules match (higher wins). is_active: type: boolean description: Deactivates the rule without removing it. PlanChangeRuleDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data SubscriptionChangeConfigV1: type: object properties: id: type: string format: uuid organizationId: type: string format: uuid description: UUID of the organization that owns the settings. allowItemAdd: type: boolean description: When `true`, allows adding new items to the subscription. allowItemRemove: type: boolean description: When `true`, allows removing items from the subscription. allowQuantityChange: type: boolean description: When `true`, allows changing the quantity of existing items. allowPriceSwap: type: boolean description: When `true`, allows swapping an item price (variant) without removing it. addProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when adding items. removeProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when removing items. quantityUpProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when increasing quantity. quantityDownProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when decreasing quantity. addTiming: type: string enum: - immediate - end_of_period description: Default timing when adding items. removeTiming: type: string enum: - immediate - end_of_period description: Default timing when removing items. quantityUpTiming: type: string enum: - immediate - end_of_period description: Default timing when increasing quantity. quantityDownTiming: type: string enum: - immediate - end_of_period description: Default timing when decreasing quantity. refundOnRemove: type: boolean description: When `true`, issues a refund when items are removed. Requires `creditOnRemove`. creditOnRemove: type: boolean description: When `true`, issues a credit for the customer when items are removed. portalSelfService: type: boolean description: When `true`, enables customer self-service from the portal. portalRequireConfirmation: type: boolean description: When `true`, requires explicit customer confirmation in the portal. metadata: type: object additionalProperties: {} description: Free-form metadata attached to the settings. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organizationId - allowItemAdd - allowItemRemove - allowQuantityChange - allowPriceSwap - addProration - removeProration - quantityUpProration - quantityDownProration - addTiming - removeTiming - quantityUpTiming - quantityDownTiming - refundOnRemove - creditOnRemove - portalSelfService - portalRequireConfirmation - metadata - created_at - updated_at SubscriptionChangeConfigResponse: type: object properties: id: type: string format: uuid organizationId: type: string format: uuid description: UUID of the organization that owns the settings. allowItemAdd: type: boolean description: When `true`, allows adding new items to the subscription. allowItemRemove: type: boolean description: When `true`, allows removing items from the subscription. allowQuantityChange: type: boolean description: When `true`, allows changing the quantity of existing items. allowPriceSwap: type: boolean description: When `true`, allows swapping an item price (variant) without removing it. addProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when adding items. removeProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when removing items. quantityUpProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when increasing quantity. quantityDownProration: type: string enum: - full_proration - no_proration - partial_proration description: Default proration method when decreasing quantity. addTiming: type: string enum: - immediate - end_of_period description: Default timing when adding items. removeTiming: type: string enum: - immediate - end_of_period description: Default timing when removing items. quantityUpTiming: type: string enum: - immediate - end_of_period description: Default timing when increasing quantity. quantityDownTiming: type: string enum: - immediate - end_of_period description: Default timing when decreasing quantity. refundOnRemove: type: boolean description: When `true`, issues a refund when items are removed. Requires `creditOnRemove`. creditOnRemove: type: boolean description: When `true`, issues a credit for the customer when items are removed. portalSelfService: type: boolean description: When `true`, enables customer self-service from the portal. portalRequireConfirmation: type: boolean description: When `true`, requires explicit customer confirmation in the portal. metadata: type: object additionalProperties: {} description: Free-form metadata attached to the settings. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organizationId - allowItemAdd - allowItemRemove - allowQuantityChange - allowPriceSwap - addProration - removeProration - quantityUpProration - quantityDownProration - addTiming - removeTiming - quantityUpTiming - quantityDownTiming - refundOnRemove - creditOnRemove - portalSelfService - portalRequireConfirmation - metadata - created_at - updated_at SubscriptionChangeConfigUpdateRequest: type: object properties: allow_item_add: type: boolean description: Allows adding new items to an existing subscription. allow_item_remove: type: boolean description: Allows removing items from an existing subscription. allow_quantity_change: type: boolean description: Allows changing the quantity of items already on the subscription. allow_price_swap: type: boolean description: Allows swapping the price (variant) of an existing item without removing it. add_proration: type: string enum: - full_proration - no_proration - partial_proration description: "Proration method when adding items: `full_proration`, `no_proration` or `partial_proration`." remove_proration: type: string enum: - full_proration - no_proration - partial_proration description: "Proration method when removing items: `full_proration`, `no_proration` or `partial_proration`." quantity_up_proration: type: string enum: - full_proration - no_proration - partial_proration description: Proration method when increasing an item quantity. quantity_down_proration: type: string enum: - full_proration - no_proration - partial_proration description: Proration method when decreasing an item quantity. add_timing: type: string enum: - immediate - end_of_period description: "Timing when adding items: `immediate` or `end_of_period`." remove_timing: type: string enum: - immediate - end_of_period description: "Timing when removing items: `immediate` or `end_of_period`." quantity_up_timing: type: string enum: - immediate - end_of_period description: "Timing when increasing quantity: `immediate` or `end_of_period`." quantity_down_timing: type: string enum: - immediate - end_of_period description: "Timing when decreasing quantity: `immediate` or `end_of_period`." refund_on_remove: type: boolean description: When `true`, issues a refund to the customer when items are removed. Requires `credit_on_remove` to be enabled. credit_on_remove: type: boolean description: When `true`, issues a credit in favor of the customer when items are removed. portal_self_service: type: boolean description: When `true`, lets customers change their own subscription from the portal. portal_require_confirmation: type: boolean description: When `true`, requires explicit customer confirmation before applying the change in the portal. SubscriptionItemChangeV1: type: object properties: id: type: string format: uuid publicId: type: string format: uuid description: Public identifier (UUID) used for external integration. organizationId: type: string format: uuid description: UUID of the organization that owns the change. subscriptionId: type: string format: uuid description: UUID of the subscription targeted by the change. billingAccountId: type: string format: uuid description: UUID of the billing account of the subscription. status: type: string enum: - pending - scheduled - completed - canceled - failed description: "Status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." timing: type: string enum: - immediate - end_of_period description: "Timing: `immediate` or `end_of_period`." initiatedByRole: type: string description: "Origin of the change: `dashboard`, `portal` or `api`." initiatedBy: type: - string - "null" description: Identifier of the user/integration that initiated the change. prorationMethod: type: string enum: - full_proration - no_proration - partial_proration description: "Proration method actually applied: `full_proration`, `no_proration` or `partial_proration`." prorationCreditSubcents: type: integer description: Proration credit in subcents (÷10000 → BRL) issued to the customer. example: 1000000 prorationChargeSubcents: type: integer description: Proration charge in subcents (÷10000 → BRL) issued to the customer. example: 0 daysRemaining: type: integer description: Days remaining in the billing period when applied. totalDaysInPeriod: type: integer description: Total days in the billing period used for the proration calculation. changes: type: array items: type: object additionalProperties: {} description: 'Snapshot of the applied batch of operations. Each entry has the shape `{ op: "add"|"remove"|"update_qty"|"update_price", productId, priceId, quantity, prevQuantity?, prevPriceId?, prevUnitAmountSubcents?, unitAmountSubcents }`.' effectiveDate: type: string format: date-time description: Effective date of the change (when it takes effect). scheduledDate: type: - string - "null" format: date-time description: Date scheduled for application, when `timing = end_of_period`. completedAt: type: - string - "null" format: date-time description: Date/time the change was actually applied. canceledAt: type: - string - "null" format: date-time description: Date/time the change was canceled, when applicable. invoiceId: type: - string - "null" format: uuid description: UUID of the invoice generated by the change, when present. creditId: type: - string - "null" format: uuid description: UUID of the credit generated by the change, when present. reason: type: - string - "null" description: Free-form reason informed by the operator when registering the change. idempotencyKey: type: - string - "null" description: Per-organization idempotency key — safely allows retrying the same execution. metadata: type: object additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - publicId - organizationId - subscriptionId - billingAccountId - status - timing - initiatedByRole - initiatedBy - prorationMethod - prorationCreditSubcents - prorationChargeSubcents - daysRemaining - totalDaysInPeriod - changes - effectiveDate - scheduledDate - completedAt - canceledAt - invoiceId - creditId - reason - idempotencyKey - metadata - created_at - updated_at SubscriptionItemChangeListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/SubscriptionItemChangeV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta SubscriptionItemChangeResponse: type: object properties: data: $ref: "#/components/schemas/SubscriptionItemChangeV1" required: - data UsageRecordV1: type: object properties: id: type: string format: uuid subscription_item_id: type: string format: uuid description: UUID of the subscription item the usage belongs to. quantity: type: number description: Quantity reported in the record. example: 5 action: type: string enum: - increment - set description: "Action type: `increment` (adds) or `set` (replaces previous values in the period)." timestamp: type: string format: date-time description: Usage date/time (ISO 8601). idempotency_key: type: - string - "null" description: Idempotency key used at creation, if any. metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time required: - id - subscription_item_id - quantity - action - timestamp - idempotency_key - metadata - created_at UsageListMeta: type: object properties: total: type: integer limit: type: integer offset: type: integer total_quantity: type: number product_slug: type: string customer_id: type: string required: - total - limit - offset - total_quantity UsageListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/UsageRecordV1" meta: $ref: "#/components/schemas/UsageListMeta" required: - data - meta UsageRecordCreateInput: type: object properties: subscription_item_id: type: string format: uuid description: Subscription item UUID (option 1 — alternative to `product_slug` + `customer_id`). product_slug: type: string description: Product slug (option 2). Combine with `customer_id` to locate the active subscription. customer_id: type: string description: Customer external identifier (the billing account `external_id`). Combine with `product_slug`. quantity: type: number minimum: 0 description: "Quantity to record — non-negative number. E.g.: `5`, `0`, `1500`." example: 5 action: type: string enum: - increment - set description: "`increment` (default) adds to the period quantity; `set` replaces any previous value in the period up to now." timestamp: type: string format: date-time description: "Usage date/time in ISO 8601. Default: now." idempotency_key: type: string description: "Optional idempotency key. If a record with the same key already exists for the item, returns the existing one with `duplicate: true`." custom_metadata: type: object additionalProperties: {} description: usage.create.body.custom_metadata required: - quantity UsageRecordBatchCreateInput: type: object properties: records: type: array items: $ref: "#/components/schemas/UsageRecordCreateInput" minItems: 1 maxItems: 100 description: Batch of records (1 to 100). When present, processes the batch and ignores the top-level record. required: - records UsageRecordCreateRequest: anyOf: - $ref: "#/components/schemas/UsageRecordCreateInput" - $ref: "#/components/schemas/UsageRecordBatchCreateInput" UsageRecordBatchResult: type: object properties: id: type: string format: uuid description: UUID of the created or existing record. subscription_item_id: type: string format: uuid product_slug: type: string customer_id: type: string success: type: boolean description: Indicates whether the record was processed successfully. duplicate: type: boolean description: When `true`, indicates the record already existed with the same `idempotency_key`. error: type: string description: Error message when `success` is `false`. required: - success UsageRecordCreateResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/UsageRecordBatchResult" - type: array items: $ref: "#/components/schemas/UsageRecordBatchResult" required: - success - processed - results UsageSummaryProduct: type: object properties: id: type: string format: uuid description: UUID of the product associated with the subscription item. name: type: string description: Product name. slug: type: string description: Product slug. required: - id - name - slug UsageSummaryPeriod: type: object properties: start: type: string format: date-time description: Period start used by the aggregation (ISO 8601). end: type: string format: date-time description: Period end used by the aggregation (ISO 8601). required: - start - end UsageSummaryUsage: type: object properties: total_quantity: type: number description: Total quantity consolidated in the period. record_count: type: integer description: Number of records considered. first_record_at: type: - string - "null" format: date-time description: Date/time of the first record in the period (ISO 8601). last_record_at: type: - string - "null" format: date-time description: Date/time of the last record in the period (ISO 8601). required: - total_quantity - record_count - first_record_at - last_record_at UsageSummaryBilling: type: object properties: estimated_cost_cents: type: - integer - "null" description: Estimated cost in cents (÷100 → BRL). `null` when the price does not allow the calculation. price_id: type: - string - "null" format: uuid description: UUID of the price used for the estimate. usage_type: type: - string - "null" description: "Usage type configured on the price (e.g.: `metered`, `licensed`)." required: - estimated_cost_cents - price_id - usage_type UsageSummaryResponse: type: object properties: subscription_item_id: type: string format: uuid description: UUID of the subscription item the usage belongs to. subscription_id: type: string format: uuid description: Subscription UUID. subscription_status: type: string description: "Current subscription status (e.g.: `active`, `trialing`)." product: allOf: - $ref: "#/components/schemas/UsageSummaryProduct" - type: - object - "null" customer_id: type: string period: $ref: "#/components/schemas/UsageSummaryPeriod" usage: $ref: "#/components/schemas/UsageSummaryUsage" billing: $ref: "#/components/schemas/UsageSummaryBilling" required: - subscription_item_id - subscription_id - subscription_status - product - period - usage - billing UsageDailySnapshotV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization owning the snapshot. billing_account_id: type: string format: uuid description: UUID of the billing account associated with the snapshot. product_group_id: type: string format: uuid description: UUID of the product group. product_id: type: string format: uuid description: UUID of the product. snapshot_date: type: string format: date-time description: Snapshot date (ISO 8601, daily granularity). quantity: type: number description: Quantity reported in the record. idempotency_key: type: string description: Idempotency key used at creation, if any. calculated_at: type: string format: date-time description: Date/time when the snapshot was calculated (ISO 8601). metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - billing_account_id - product_group_id - product_id - snapshot_date - quantity - idempotency_key - calculated_at - metadata - created_at - updated_at UsageSnapshotListMeta: type: object properties: total: type: integer limit: type: integer offset: type: integer required: - total - limit - offset UsageDailySnapshotListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/UsageDailySnapshotV1" meta: $ref: "#/components/schemas/UsageSnapshotListMeta" required: - data - meta UsageDailySnapshotCreateInput: type: object properties: billing_account_id: type: string format: uuid description: Billing account UUID. Alternative to `billing_account_public_id`. billing_account_public_id: type: string description: Billing account public identifier. Alternative to `billing_account_id`. product_group_slug: type: string description: Product group slug — required. Scopes the `product_slug`/`product_id` lookup. product_slug: type: string description: Product slug within the group. Alternative to `product_id`. product_id: type: string format: uuid description: Product UUID within the group. Alternative to `product_slug`. snapshot_date: type: string description: Snapshot date in `YYYY-MM-DD` format (ISO 8601). example: 2026-03-15 quantity: type: number minimum: 0 description: Consolidated daily quantity — non-negative number. idempotency_key: type: string minLength: 1 description: Idempotency key **required**. Must be unique across snapshots. calculated_at: type: string format: date-time description: "Date/time when the quantity was calculated (ISO 8601). Default: now." custom_metadata: type: object additionalProperties: {} description: usage.daily_snapshots.create.body.custom_metadata required: - product_group_slug - snapshot_date - quantity - idempotency_key UsageDailySnapshotBatchCreateInput: type: object properties: records: type: array items: $ref: "#/components/schemas/UsageDailySnapshotCreateInput" minItems: 1 maxItems: 100 description: Daily snapshots batch (1 to 100). required: - records UsageDailySnapshotCreateRequest: anyOf: - $ref: "#/components/schemas/UsageDailySnapshotCreateInput" - $ref: "#/components/schemas/UsageDailySnapshotBatchCreateInput" UsageDailySnapshotBatchResult: type: object properties: id: type: string format: uuid description: UUID of the created or existing record. billing_account_id: type: string format: uuid product_id: type: string format: uuid success: type: boolean description: Indicates whether the record was processed successfully. overwritten: type: boolean description: When `true`, indicates a pre-existing snapshot was overwritten. error: type: string description: Error message when `success` is `false`. data: $ref: "#/components/schemas/UsageDailySnapshotV1" required: - success UsageDailySnapshotCreateResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/UsageDailySnapshotBatchResult" - type: array items: $ref: "#/components/schemas/UsageDailySnapshotBatchResult" required: - success - processed - results UsageMonthlySnapshotV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization owning the snapshot. billing_account_id: type: string format: uuid description: UUID of the billing account associated with the snapshot. product_group_id: type: string format: uuid description: UUID of the product group. product_id: type: string format: uuid description: UUID of the product. month: type: string format: date-time description: Reference month (ISO 8601 — first day of the month). total_quantity: type: number description: Total accumulated quantity for the month. avg_daily_quantity: type: number description: Average daily usage for the month. days_with_usage: type: integer description: Number of days with recorded usage in the month. plan_limit: type: - number - "null" description: Contracted plan limit for the period. `null` when unlimited. excess_quantity: type: number description: Excess quantity over the `plan_limit`. idempotency_key: type: string description: Idempotency key used at creation, if any. calculated_at: type: string format: date-time description: Date/time when the snapshot was calculated (ISO 8601). metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - billing_account_id - product_group_id - product_id - month - total_quantity - avg_daily_quantity - days_with_usage - plan_limit - excess_quantity - idempotency_key - calculated_at - metadata - created_at - updated_at UsageMonthlySnapshotListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/UsageMonthlySnapshotV1" meta: $ref: "#/components/schemas/UsageSnapshotListMeta" required: - data - meta UsageMonthlySnapshotCreateInput: type: object properties: billing_account_id: type: string format: uuid description: Billing account UUID. Alternative to `billing_account_public_id`. billing_account_public_id: type: string description: Billing account public identifier. Alternative to `billing_account_id`. product_group_slug: type: string description: Product group slug — required. product_slug: type: string description: Product slug within the group. Alternative to `product_id`. product_id: type: string format: uuid description: Product UUID within the group. Alternative to `product_slug`. month: type: string description: "Reference month in `YYYY-MM-DD` format (use the first day of the month, e.g.: `2026-03-01`)." example: 2026-03-01 total_quantity: type: number minimum: 0 description: Total accumulated quantity for the month — non-negative number. avg_daily_quantity: type: number minimum: 0 description: Average daily usage for the month — non-negative number. days_with_usage: type: integer minimum: 0 description: Number of days with recorded usage (non-negative integer). plan_limit: type: - number - "null" description: Contracted plan limit for the period (optional). Use `null` for unlimited. excess_quantity: type: number minimum: 0 description: Excess quantity over the `plan_limit` — non-negative number. idempotency_key: type: string minLength: 1 description: Idempotency key **required**. Must be unique across snapshots. calculated_at: type: string format: date-time description: "Date/time when the numbers were calculated (ISO 8601). Default: now." custom_metadata: type: object additionalProperties: {} description: usage.monthly_snapshots.create.body.custom_metadata required: - product_group_slug - month - total_quantity - avg_daily_quantity - days_with_usage - excess_quantity - idempotency_key UsageMonthlySnapshotBatchCreateInput: type: object properties: records: type: array items: $ref: "#/components/schemas/UsageMonthlySnapshotCreateInput" minItems: 1 maxItems: 100 description: Monthly snapshots batch (1 to 100). required: - records UsageMonthlySnapshotCreateRequest: anyOf: - $ref: "#/components/schemas/UsageMonthlySnapshotCreateInput" - $ref: "#/components/schemas/UsageMonthlySnapshotBatchCreateInput" UsageMonthlySnapshotBatchResult: type: object properties: id: type: string format: uuid description: UUID of the created or existing record. billing_account_id: type: string format: uuid product_id: type: string format: uuid success: type: boolean description: Indicates whether the record was processed successfully. overwritten: type: boolean description: When `true`, indicates a pre-existing snapshot was overwritten. error: type: string description: Error message when `success` is `false`. data: $ref: "#/components/schemas/UsageMonthlySnapshotV1" required: - success UsageMonthlySnapshotCreateResponse: type: object properties: success: type: boolean processed: type: integer failed: type: integer partial: type: boolean results: anyOf: - $ref: "#/components/schemas/UsageMonthlySnapshotBatchResult" - type: array items: $ref: "#/components/schemas/UsageMonthlySnapshotBatchResult" required: - success - processed - results TaxRuleItemV1: type: object properties: id: type: string format: uuid tax_rule_id: type: string format: uuid description: UUID of the rule the item belongs to. tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Tax: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." rate: type: number description: "Percentage rate (0–100), up to 2 decimals. E.g.: `5.00` = 5%." example: 5 is_withheld: type: boolean description: When `true`, the tax is withheld at source. base_type: type: string enum: - service_value - service_value_minus_iss - presumed_base description: "Calculation base: `service_value`, `service_value_minus_iss` or `presumed_base`." is_exempt: type: boolean description: When `true`, indicates tax exemption. exemption_reason: type: - string - "null" description: Exemption reason, when `is_exempt = true`. created_at: type: string format: date-time required: - id - tax_rule_id - tax_type - rate - is_withheld - base_type - is_exempt - exemption_reason - created_at TaxRuleV1: type: object properties: id: type: string format: uuid scope: type: string enum: - global - organization - company - service - customer - municipality description: "Rule scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." priority: type: integer description: Priority. Higher value overrides lower-priority rules. example: 0 company_id: type: - string - "null" format: uuid description: Company UUID when `scope = company`. service_item_id: type: - string - "null" format: uuid description: Service item UUID when `scope = service`. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID when `scope = customer`. customer_tax_type: type: - string - "null" enum: - pessoa_fisica - pessoa_juridica - mei - simples_optante - entidade_publica description: Customer tax type that the rule covers. municipality: type: - string - "null" description: IBGE municipality code (7 digits) when `scope = municipality`. operation_type: type: - string - "null" enum: - interno - externo description: "Operation type: `interno` or `externo`." name: type: string description: Human-readable rule name. description: type: - string - "null" description: Rule description. is_active: type: boolean description: Indicates whether the rule is active. effective_from: type: string format: date-time description: ISO 8601 date/time from which the rule is effective. effective_to: type: - string - "null" format: date-time description: ISO 8601 date/time when the rule stops being effective. `null` means open-ended. items: type: array items: $ref: "#/components/schemas/TaxRuleItemV1" description: Rule items list — one entry per tax. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - scope - priority - company_id - service_item_id - billing_account_id - customer_tax_type - municipality - operation_type - name - description - is_active - effective_from - effective_to - items - created_at - updated_at TaxRuleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TaxRuleV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TaxRuleResponse: type: object properties: data: $ref: "#/components/schemas/TaxRuleV1" required: - data TaxRuleItemInput: type: object properties: tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Tax: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." rate: type: number minimum: 0 maximum: 100 description: "Percentage rate (0–100), up to 2 decimals. E.g.: `5.00` = 5%." example: 5 is_withheld: type: boolean description: When `true`, the tax is withheld at source. base_type: type: string enum: - service_value - service_value_minus_iss - presumed_base description: "Calculation base: `service_value`, `service_value_minus_iss` or `presumed_base`." is_exempt: type: boolean description: When `true`, indicates tax exemption. exemption_reason: type: - string - "null" description: Exemption reason, when `is_exempt = true`. required: - tax_type - rate TaxRuleCreateRequest: type: object properties: name: type: string minLength: 1 description: Human-readable rule name. description: type: - string - "null" description: Optional rule description. scope: type: string enum: - global - organization - company - service - customer - municipality description: "Rule scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." priority: type: integer description: "Rule priority. Higher value overrides lower-priority rules. Default: `0`." example: 0 company_id: type: - string - "null" format: uuid description: Company UUID when `scope = company`. The company must belong to the current organization. service_item_id: type: - string - "null" format: uuid description: Service item UUID when `scope = service`. The item must belong to the current organization. billing_account_id: type: - string - "null" format: uuid description: Billing account UUID when `scope = customer`. The account must belong to the current organization. customer_tax_type: type: - string - "null" enum: - pessoa_fisica - pessoa_juridica - mei - simples_optante - entidade_publica description: "Customer tax type: `pessoa_fisica`, `pessoa_juridica`, `mei`, `simples_optante` or `entidade_publica`." municipality: type: - string - "null" description: IBGE municipality code (7 digits) when `scope = municipality`. operation_type: type: - string - "null" enum: - interno - externo description: "Operation type: `interno` (same municipality) or `externo` (different municipality)." effective_from: type: string format: date-time description: ISO 8601 date/time when the rule becomes effective. effective_to: type: - string - "null" format: date-time description: ISO 8601 date/time when the rule stops being effective. `null` means open-ended. items: type: array items: $ref: "#/components/schemas/TaxRuleItemInput" minItems: 1 description: List of items (per-tax rates). At least 1 item is required. required: - name - scope - items TaxRuleUpdateRequest: type: object properties: name: type: string minLength: 1 description: New rule name. description: type: - string - "null" description: New rule description. priority: type: integer description: New rule priority. is_active: type: boolean description: When `false`, deactivates the rule without removing it. effective_to: type: - string - "null" format: date-time description: New ISO 8601 end-of-effectiveness date/time (or `null` for open-ended). items: type: array items: $ref: "#/components/schemas/TaxRuleItemInput" description: When provided, fully replaces the rule items list. TaxRuleDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data TaxPeriodV1: type: object properties: id: type: string format: uuid company_id: type: string format: uuid description: Issuing company UUID. period_type: type: string enum: - monthly - quarterly description: "Period type: `monthly` or `quarterly`." year: type: integer description: Reference year. example: 2026 month: type: - integer - "null" minimum: 1 maximum: 12 description: Reference month (1 to 12) — only set on monthly periods. quarter: type: - integer - "null" minimum: 1 maximum: 4 description: Reference quarter (1 to 4) — only set on quarterly periods. status: type: string enum: - open - calculated - closed description: "Period status: `open`, `calculated` or `closed`." gross_revenue_cents: type: integer description: Gross revenue computed for the period, in cents (÷100 → BRL). example: 100000 taxable_revenue_cents: type: integer description: Taxable revenue for the period, in cents (÷100 → BRL). iss_due_cents: type: integer description: ISS due for the period, in cents (÷100 → BRL). pis_due_cents: type: integer description: PIS due for the period, in cents (÷100 → BRL). cofins_due_cents: type: integer description: COFINS due for the period, in cents (÷100 → BRL). irpj_due_cents: type: integer description: IRPJ due (monthly estimate), in cents (÷100 → BRL). csll_due_cents: type: integer description: CSLL due (monthly estimate), in cents (÷100 → BRL). irrf_to_compensate_cents: type: integer description: IRRF withheld pending compensation, in cents (÷100 → BRL). csrf_to_compensate_cents: type: integer description: CSRF (withheld PIS/COFINS/CSLL) pending compensation, in cents (÷100 → BRL). iss_to_compensate_cents: type: integer description: ISS withheld pending compensation, in cents (÷100 → BRL). das_estimated_cents: type: - integer - "null" description: Estimated DAS (Simples Nacional), in cents (÷100 → BRL). simples_effective_rate: type: - string - "null" description: Effective Simples Nacional rate applied in the period (percent). simples_annex: type: - string - "null" description: "Applicable Simples Nacional annex (e.g.: `annex_iii`, `annex_v`)." cbs_due_cents: type: integer description: CBS due (2026+ tax reform), in cents (÷100 → BRL). ibs_due_cents: type: integer description: IBS due (2026+ tax reform), in cents (÷100 → BRL). calculation_log: type: - object - "null" additionalProperties: {} description: JSON log of the calculation memory (regime, NFes considered, rates). closed_at: type: - string - "null" format: date-time description: Date/time when the period was closed. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - company_id - period_type - year - month - quarter - status - gross_revenue_cents - taxable_revenue_cents - iss_due_cents - pis_due_cents - cofins_due_cents - irpj_due_cents - csll_due_cents - irrf_to_compensate_cents - csrf_to_compensate_cents - iss_to_compensate_cents - das_estimated_cents - simples_effective_rate - simples_annex - cbs_due_cents - ibs_due_cents - calculation_log - closed_at - created_at - updated_at TaxPeriodListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TaxPeriodV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TaxPeriodResponse: type: object properties: data: $ref: "#/components/schemas/TaxPeriodV1" required: - data TaxPeriodCreateRequest: type: object properties: company_id: type: string format: uuid description: UUID of the issuing company. Omit to use the organization default company. year: type: integer minimum: 2020 maximum: 2100 description: "Reference year (e.g.: `2026`)." example: 2026 month: type: integer minimum: 1 maximum: 12 description: Reference month (1 to 12). example: 6 required: - year - month TaxPeriodUpdateRequest: type: object properties: action: type: string enum: - recalculate - close - reopen description: "Action to execute: `recalculate`, `close` or `reopen`." required: - action TaxPeriodDeletedResponse: type: object properties: data: type: object properties: deleted: type: boolean example: true required: - deleted required: - data WithholdingV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization that owns the withholding. invoice_id: type: - string - "null" format: uuid description: UUID of the associated invoice, when present. nfe_id: type: - string - "null" format: uuid description: UUID of the associated NF-e, when present. tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Withheld tax type: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." base_cents: type: integer description: Calculation base in cents (÷100 → BRL). example: 100000 rate: type: number description: "Applied rate as a percentage (e.g.: `1.5` for 1.5%)." example: 1.5 amount_cents: type: integer description: Withheld amount in cents (÷100 → BRL). example: 1500 withholder_id: type: string format: uuid description: UUID of the withholder's billing account (the entity that withheld the tax). status: type: string enum: - retained - compensated - partially_compensated description: "Withholding status: `retained`, `compensated` or `partially_compensated`." compensated_cents: type: integer description: Amount already compensated/converted into credit, in cents (÷100 → BRL). example: 0 competence_month: type: integer minimum: 1 maximum: 12 description: Competence month (1–12). competence_year: type: integer description: Competence year (2000–3000). metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata attached to the withholding. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - invoice_id - nfe_id - tax_type - base_cents - rate - amount_cents - withholder_id - status - compensated_cents - competence_month - competence_year - metadata - created_at - updated_at WithholdingListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WithholdingV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta WithholdingResponse: type: object properties: data: $ref: "#/components/schemas/WithholdingV1" required: - data WithholdingConvertToCreditRequest: type: object properties: amount_cents: type: integer exclusiveMinimum: 0 description: "Amount to convert in cents (÷100 → BRL). Default: pending balance of the withholding." WithholdingConvertToCreditResponse: type: object properties: credit: allOf: - $ref: "#/components/schemas/CreditV1" - description: Credit generated by converting the withholding. required: - credit WithholdingBulkConvertRequest: type: object properties: tax_type: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Restricts conversion to a specific tax type (e.g.: `irrf`, `pis`, `cofins`)." competence_year: type: integer minimum: 2000 maximum: 3000 description: Restricts conversion to the given competence year. competence_month: type: integer minimum: 1 maximum: 12 description: Restricts conversion to the given competence month (1–12). WithholdingBulkConvertResponse: type: object properties: credits: type: array items: $ref: "#/components/schemas/CreditV1" description: List of credits generated by the conversion. total_converted: type: integer description: Total number of withholdings converted into credits. total_amount_cents: type: integer description: Sum of converted amounts in cents (÷100 → BRL). required: - credits - total_converted - total_amount_cents ServiceItemV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid company_id: type: - string - "null" format: uuid description: UUID of the issuing company associated with the item. `null` when the item applies to all companies in the organization. name: type: string description: Service item name (shown on invoices and NFS-e). description: type: - string - "null" description: Optional service description. internal_code: type: string description: Internal item code — immutable after creation. lc116_code: type: string description: Service code per Complementary Law 116/2003 (e.g. `01.05`). example: "01.05" municipal_code: type: - string - "null" description: Municipal service code, when the municipality requires its own coding. nbs_code: type: - string - "null" description: NBS code — Brazilian Service Nomenclature. cnae_code: type: - string - "null" description: CNAE code related to the service provided. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Simples Nacional annex applicable to the service: `annex_iii`, `annex_iv` or `annex_v`." default_iss_rate: type: - string - "null" description: Default ISS rate in percentage points (e.g. `2.5` means 2.5%). Decimal with up to two places. example: "2.50" subject_to_irrf: type: boolean description: Indicates whether the item is subject to IRRF withholding by default. subject_to_csrf: type: boolean description: Indicates whether the item is subject to CSRF withholding (PIS/COFINS/CSLL) by default. subject_to_inss: type: boolean description: Indicates whether the item is subject to INSS withholding by default. subject_to_iss_withholding: type: boolean description: Indicates whether the item is subject to ISS withholding by default. c_class_trib: type: - string - "null" description: Tax classification (IBS/CBS CST) applicable to the item. cbs_ibs_category: type: - string - "null" description: CBS/IBS category for the item, per the tax reform. indop_code: type: - string - "null" description: Operation Indicator (`indOp`) used in SNNFSE NFS-e. is_active: type: boolean description: When `false`, the item cannot be selected on new invoices or NFS-e. metadata: type: - object - "null" additionalProperties: {} description: Internal item metadata (platform use). custom_metadata: type: - object - "null" additionalProperties: {} description: Arbitrary client-defined metadata (key/value). created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - organization_id - company_id - name - description - internal_code - lc116_code - municipal_code - nbs_code - cnae_code - simples_annex - default_iss_rate - subject_to_irrf - subject_to_csrf - subject_to_inss - subject_to_iss_withholding - c_class_trib - cbs_ibs_category - indop_code - is_active - metadata - custom_metadata - created_at - updated_at ServiceItemListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ServiceItemV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta ServiceItemResponse: type: object properties: data: $ref: "#/components/schemas/ServiceItemV1" required: - data ServiceItemCreateRequest: type: object properties: company_id: type: - string - "null" format: uuid description: UUID of the associated issuing company. Omit or send `null` for an item applicable to all companies. name: type: string minLength: 1 description: Service item name. description: type: - string - "null" description: Optional description. internal_code: type: string minLength: 1 description: Internal item code — immutable after creation. lc116_code: type: string minLength: 1 description: LC 116/2003 service code (e.g. `01.05`). example: "01.05" municipal_code: type: - string - "null" description: Municipal service code, when applicable. nbs_code: type: - string - "null" description: NBS code. cnae_code: type: - string - "null" description: Related CNAE code. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: "Applicable Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." default_iss_rate: type: - number - "null" description: Default ISS rate in percentage points (e.g. `2.5`). example: 2.5 subject_to_irrf: type: boolean description: "Indicates whether the item is subject to IRRF withholding. Default: `true`." subject_to_csrf: type: boolean description: "Indicates whether the item is subject to CSRF withholding. Default: `true`." subject_to_inss: type: boolean description: "Indicates whether the item is subject to INSS withholding. Default: `false`." subject_to_iss_withholding: type: boolean description: "Indicates whether the item is subject to ISS withholding. Default: `false`." c_class_trib: type: - string - "null" description: IBS/CBS CST tax classification. cbs_ibs_category: type: - string - "null" description: CBS/IBS category for the item. indop_code: type: - string - "null" description: SNNFSE NFS-e Operation Indicator (`indOp`). custom_metadata: type: object additionalProperties: {} description: Arbitrary client-defined metadata (key/value). required: - name - internal_code - lc116_code ServiceItemUpdateRequest: type: object properties: company_id: type: - string - "null" format: uuid description: New associated issuing company. Send `null` to disassociate. name: type: string minLength: 1 description: New item name. description: type: - string - "null" description: New description. Send `null` to clear. lc116_code: type: string minLength: 1 description: New LC 116/2003 code. municipal_code: type: - string - "null" description: New municipal code. Send `null` to clear. nbs_code: type: - string - "null" description: New NBS code. Send `null` to clear. cnae_code: type: - string - "null" description: New CNAE code. Send `null` to clear. simples_annex: type: - string - "null" enum: - annex_iii - annex_iv - annex_v description: New Simples Nacional annex. Send `null` to clear. default_iss_rate: type: - number - "null" description: New default ISS rate in percentage points. Send `null` to clear. subject_to_irrf: type: boolean description: Updates the IRRF withholding flag. subject_to_csrf: type: boolean description: Updates the CSRF withholding flag. subject_to_inss: type: boolean description: Updates the INSS withholding flag. subject_to_iss_withholding: type: boolean description: Updates the ISS withholding flag. c_class_trib: type: - string - "null" description: New IBS/CBS CST tax classification. Send `null` to clear. cbs_ibs_category: type: - string - "null" description: New CBS/IBS category. Send `null` to clear. indop_code: type: - string - "null" description: New Operation Indicator (`indOp`). Send `null` to clear. is_active: type: boolean description: Activates (`true`) or deactivates (`false`) the service item. custom_metadata: type: object additionalProperties: {} description: Arbitrary client-defined metadata (key/value). DashboardUserRoleSummary: type: object properties: id: type: string format: uuid description: Role UUID. name: type: string description: Role name. slug: type: string description: Role slug (stable identifier). required: - id - name - slug DashboardUserV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization the user belongs to. person_id: type: - string - "null" format: uuid description: UUID of the person (identity record) linked to the user, when present. external_id: type: string description: External user identifier in Kobana OAuth. email: type: string format: email description: User email. name: type: - string - "null" description: Display name. picture: type: - string - "null" description: URL of the user picture. status: type: string enum: - active - pending_invitation - suspended description: "Current user status: `active`, `pending_invitation` or `suspended`." permissions: type: array items: type: string description: Ad-hoc permissions assigned directly to the user (on top of those inherited from roles). last_login_at: type: - string - "null" format: date-time description: Date/time of the last login. login_count: type: integer description: Total number of logins performed. show_getting_started: type: boolean description: Indicates whether the "Getting started" panel should be shown to the user. email_signature: type: - string - "null" description: Email signature configured by the user. metadata: type: - object - "null" additionalProperties: {} description: Internal system metadata. custom_metadata: type: - object - "null" additionalProperties: {} description: Free-form metadata defined by the client. created_at: type: string format: date-time updated_at: type: string format: date-time roles: type: array items: $ref: "#/components/schemas/DashboardUserRoleSummary" description: Roles assigned to the user, expanded as `{ id, name, slug }`. required: - id - organization_id - person_id - external_id - email - name - picture - status - permissions - last_login_at - login_count - show_getting_started - email_signature - metadata - custom_metadata - created_at - updated_at DashboardUserListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DashboardUserV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta DashboardUserResponse: type: object properties: data: $ref: "#/components/schemas/DashboardUserV1" required: - data DashboardUserCreateRequest: type: object properties: email: type: string format: email description: Email of the user to invite. name: type: string description: User name (optional — may be filled in by the user on first login). external_id: type: string description: External user identifier in Kobana OAuth, when already known. role_ids: type: array items: type: string format: uuid minItems: 1 description: List of role UUIDs (`team_roles`) to assign to the user. Must contain at least one item. permissions: type: array items: type: string description: Additional ad-hoc permissions (on top of those inherited from roles). Accepts the same permission slugs. required: - email - role_ids DashboardUserUpdateRequest: type: object properties: name: type: string description: New display name. picture: type: string description: URL of the user picture. status: type: string enum: - active - pending_invitation - suspended description: "New status: `active`, `pending_invitation` or `suspended`." permissions: type: array items: type: string description: Full list of ad-hoc permissions (replaces the previous list). role_ids: type: array items: type: string format: uuid description: Full list of role UUIDs (replaces the current assignments). TeamRoleV1: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid description: UUID of the organization the role belongs to. name: type: string description: Role name. slug: type: string description: Stable role slug. description: type: - string - "null" description: Role description. permissions: type: array items: type: string description: Permission slugs granted by the role. is_system: type: boolean description: Indicates whether the role is system-managed (not editable/removable). is_active: type: boolean description: Indicates whether the role is active and available for assignment. display_order: type: integer description: Display order of the role in the UI. metadata: type: - object - "null" additionalProperties: {} description: Internal role metadata. created_at: type: string format: date-time updated_at: type: string format: date-time users_count: type: integer description: Number of users currently linked to the role. required: - id - organization_id - name - slug - description - permissions - is_system - is_active - display_order - metadata - created_at - updated_at TeamRoleListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/TeamRoleV1" meta: $ref: "#/components/schemas/PaginationMeta" required: - data - meta TeamRoleResponse: type: object properties: data: $ref: "#/components/schemas/TeamRoleV1" required: - data TeamRoleCreateRequest: type: object properties: name: type: string minLength: 1 description: Role name (shown in the UI). slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: "Stable slug used to reference the role (e.g.: `billing_manager`)." example: billing_manager description: type: string description: Optional description of what the role grants. permissions: type: array items: type: string description: List of permission slugs granted by the role. is_active: type: boolean description: Indicates whether the role is active and can be assigned. required: - name - slug - permissions TeamRoleUpdateRequest: type: object properties: name: type: string minLength: 1 description: New role name. slug: type: string pattern: ^[a-z][a-z0-9_]*$ description: New role slug (same rules as on creation). description: type: string description: New description. permissions: type: array items: type: string description: Full permission list (replaces the previous one). is_active: type: boolean description: Activates or deactivates the role. ProposalItemCreateRequest: type: object properties: product_id: type: string format: uuid description: Product UUID. **Required**. price_id: type: string format: uuid description: Price UUID. **Required**. quantity: type: number minimum: 1 description: "Quantity. Default: 1." unit_amount_subcents: type: number minimum: 0 description: Unit amount in sub-cents (÷10000 → BRL). metadata: type: object additionalProperties: {} description: Arbitrary item metadata. custom_metadata: type: object additionalProperties: {} description: Item custom fields. required: - product_id - price_id - unit_amount_subcents parameters: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: "Send the `Authorization: Bearer ` header. Token format: HS512." paths: /v1/subscriptions: get: tags: - Assinaturas summary: List subscriptions description: Returns a paginated list of the current organization's subscriptions. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - draft - trialing - active - past_due - canceled - paused description: Filter by subscription status. required: false name: status in: query - schema: type: string format: uuid description: Filter by plan. required: false name: plan_id in: query - schema: type: string enum: - monthly - quarterly - semiannual - annual description: Filter by billing cycle. required: false name: billing_cycle in: query - schema: type: string format: uuid description: Filter by billing account. required: false name: billing_account_id in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: string format: date-time description: Start date (ISO 8601). required: false name: date_from in: query - schema: type: string format: date-time description: End date (ISO 8601). required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of subscriptions. content: application/json: schema: $ref: "#/components/schemas/SubscriptionListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscriptions post: tags: - Assinaturas summary: Create subscription description: Creates a subscription. Either `plan_id` or `items` is required. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionCreateRequest" responses: "201": description: Subscription created. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/subscriptions/{id}: get: tags: - Assinaturas summary: Get subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Subscription detail. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscriptions-id patch: tags: - Assinaturas summary: Update subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionUpdateRequest" responses: "200": description: Subscription updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-subscriptions-id delete: tags: - Assinaturas summary: Cancel and remove subscription (soft delete) security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Soft delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-subscriptions-id /v1/subscriptions/{id}/pause: post: tags: - Assinaturas summary: Pause subscription description: Suspends charging while keeping the subscription open. `behavior` controls how invoices generated during the pause are handled. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionPauseRequest" responses: "200": description: Subscription paused. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-pause /v1/subscriptions/{id}/resume: post: tags: - Assinaturas summary: Resume paused subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Subscription resumed. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-resume /v1/subscriptions/{id}/cancel: post: tags: - Assinaturas summary: Cancel subscription description: Cancels immediately, or schedules for end of period when `cancel_at_period_end=true`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionCancelRequest" responses: "200": description: Subscription canceled. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-cancel /v1/subscriptions/{id}/activate: post: tags: - Assinaturas summary: Activate draft/confirmed subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Subscription activated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-activate /v1/subscriptions/{id}/change-plan: post: tags: - Assinaturas summary: Change subscription plan description: Upgrade or downgrade. Proration follows the subscription's `proration_behavior`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangePlanRequest" responses: "200": description: Subscription updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-change-plan /v1/subscriptions/{id}/revert-to-confirmed: post: tags: - Assinaturas summary: Revert subscription to confirmed state security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Subscription reverted. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-revert-to-confirmed /v1/subscriptions/{id}/create-invoice: post: tags: - Assinaturas summary: Generate an ad-hoc invoice for the subscription security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "201": description: Invoice generated. content: application/json: schema: type: object properties: data: {} "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-create-invoice /v1/subscriptions/{id}/items: get: tags: - Assinaturas summary: List subscription items security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: List of items. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscriptions-id-items /v1/subscriptions/{id}/sync-plan-items: post: tags: - Assinaturas summary: Resync items with the current plan description: Realigns subscription items with the plan-items template (manual reconciliation). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Subscription synced. content: application/json: schema: $ref: "#/components/schemas/SubscriptionResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-subscriptions-id-sync-plan-items /v1/billing_accounts: get: tags: - Contas de Cobrança summary: List billing accounts description: Returns a paginated list of the current organization's billing accounts. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - suspended - closed description: Filter by billing account status. required: false name: status in: query - schema: type: string description: Free-text search. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of billing accounts. content: application/json: schema: $ref: "#/components/schemas/BillingAccountListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts post: tags: - Contas de Cobrança summary: Create billing account description: Creates a billing account associated with a customer. The `customer` block locates an existing customer by `id`, `external_id` or `document_number`; when not found, creates a new one (requires `name` and `document_number`). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountCreateRequest" responses: "201": description: Billing account created. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/billing_accounts/{id}: get: tags: - Contas de Cobrança summary: Get billing account security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Billing account detail. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id patch: tags: - Contas de Cobrança summary: Update billing account security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountUpdateRequest" responses: "200": description: Billing account updated. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-billing-accounts-id delete: tags: - Contas de Cobrança summary: Close billing account description: Closes the billing account (equivalent to `POST /billing_accounts/{id}/close`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: string description: Closing reason (recorded in the audit log). required: false name: reason in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Billing account closed. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-billing-accounts-id /v1/billing_accounts/{id}/close: post: tags: - Contas de Cobrança summary: Close billing account (POST /close) description: Closes the billing account. The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountReasonRequest" responses: "200": description: Billing account closed. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts-id-close /v1/billing_accounts/{id}/suspend: post: tags: - Contas de Cobrança summary: Suspend billing account description: Suspends the account. The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/BillingAccountReasonRequest" responses: "200": description: Billing account suspended. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts-id-suspend /v1/billing_accounts/{id}/reactivate: post: tags: - Contas de Cobrança summary: Reactivate billing account description: Reactivates a suspended billing account. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Billing account reactivated. content: application/json: schema: $ref: "#/components/schemas/BillingAccountResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-billing-accounts-id-reactivate /v1/billing_accounts/{id}/invoices: get: tags: - Contas de Cobrança summary: List billing account invoices description: Returns a paginated list of the billing account's invoices. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of invoices. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-invoices /v1/billing_accounts/{id}/subscriptions: get: tags: - Contas de Cobrança summary: List billing account subscriptions description: Returns a paginated list of the billing account's subscriptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of subscriptions. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-subscriptions /v1/billing_accounts/{id}/credits: get: tags: - Contas de Cobrança summary: List billing account credits description: Returns a paginated list of the billing account's credits. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Billing account UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: Includes expired credits when `true`. required: false name: include_expired in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of credits. content: application/json: schema: type: object properties: data: type: array items: {} required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-billing-accounts-id-credits /v1/customers: get: tags: - Clientes summary: List customers description: Returns a paginated list of the current organization's customers. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Free-text search by name, document or email. required: false name: search in: query - schema: type: string enum: - natural - juridical description: "Filter by person kind: `natural` (individual) or `juridical` (business)." required: false name: kind in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of customers. content: application/json: schema: $ref: "#/components/schemas/CustomerListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers post: tags: - Clientes summary: Create customer description: Creates a customer and, by default, an associated billing account. Use `create_billing_account=false` to create only the customer. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerCreateRequest" responses: "201": description: Customer created. content: application/json: schema: $ref: "#/components/schemas/CustomerCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/customers/{id}: get: tags: - Clientes summary: Get customer description: The `{id}` parameter accepts the customer UUID or its `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Customer detail. content: application/json: schema: $ref: "#/components/schemas/CustomerResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id patch: tags: - Clientes summary: Update customer description: The `{id}` parameter accepts the customer UUID or its `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerUpdateRequest" responses: "200": description: Customer updated. content: application/json: schema: $ref: "#/components/schemas/CustomerResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-customers-id delete: tags: - Clientes summary: Remove customer (soft delete) description: Marks the customer as removed without deleting historical records. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Soft delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-customers-id /v1/customers/{id}/statement: get: tags: - Clientes summary: List customer financial statement description: Returns statement entries (invoices, payments, credit applications) for the customer's billing account. When the customer has multiple accounts, provide `billing_account_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Required when the customer has multiple billing accounts. required: false name: billing_account_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of statement items. content: application/json: schema: $ref: "#/components/schemas/CustomerStatementListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-statement /v1/customers/{id}/statement/sync: post: tags: - Clientes summary: Rebuild the statement from history description: Recreates statement items from existing invoices, payments and credit applications. Returns a summary of what was created. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerStatementSyncRequest" responses: "200": description: Statement rebuilt. content: application/json: schema: $ref: "#/components/schemas/CustomerStatementSyncResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-statement-sync /v1/customers/{id}/recalculate-mrr: post: tags: - Clientes summary: Recalculate customer MRR description: Recalculates the MRR (Monthly Recurring Revenue) of the customer's billing accounts from active subscriptions. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: MRR recalculated. content: application/json: schema: $ref: "#/components/schemas/CustomerRecalculateMrrResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-recalculate-mrr /v1/customers/{id}/users: get: tags: - Clientes summary: List customer portal users description: Returns portal users linked to the customer's billing account. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - pending_verification - pending_invitation - suspended - locked description: Filter portal users by status. required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of portal users. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-users post: tags: - Clientes summary: Invite portal user description: Creates a portal access invitation for the given email. The invitation expires in 7 days. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserInviteRequest" responses: "201": description: Invitation created and email queued for sending. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "409": description: A user or invitation already exists for this email. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-users /v1/customers/{id}/users/invite: post: tags: - Clientes summary: Invite portal user (verb) description: Equivalent to `POST /customers/{id}/users`. Available as a verb route for SDKs that prefer descriptive URLs. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserInviteRequest" responses: "201": description: Invitation created. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-users-invite /v1/customers/{id}/users/{user_id}: get: tags: - Clientes summary: Get portal user description: The `{user_id}` parameter accepts the user's UUID or `external_id`. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Portal user detail. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-users-user-id patch: tags: - Clientes summary: Update portal user description: "Updates `email`, `external_id`, `sso_only` and `status`. Allowed status transitions: `active` ↔ `suspended`." security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserUpdateRequest" responses: "200": description: User updated. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-customers-id-users-user-id delete: tags: - Clientes summary: Remove portal user description: Pending invitations are permanently removed; active users are suspended. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-customers-id-users-user-id /v1/customers/{id}/users/{user_id}/email-preview: get: tags: - Clientes summary: Preview portal user email description: Returns the subject and body of the invitation or verification email that would be sent to the user, without actually sending it. Available only for `pending_invitation` or `pending_verification` users. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Email preview. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserEmailPreviewResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-customers-id-users-user-id-email-preview /v1/customers/{id}/users/{user_id}/resend: post: tags: - Clientes summary: Resend invitation or verification email description: Resends the invitation email (for `pending_invitation`, rotating the token) or verification email (for `pending_verification`). Other statuses return 400. security: - bearerAuth: [] parameters: - schema: type: string description: Customer UUID or `external_id`. required: true name: id in: path - schema: type: string description: Portal user UUID or its `external_id`. required: true name: user_id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Email resent. content: application/json: schema: $ref: "#/components/schemas/CustomerPortalUserResendResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-customers-id-users-user-id-resend /v1/plans: get: tags: - Planos summary: List plans description: Returns a paginated list of the current organization's plans. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - draft - active - archived description: Filter by plan status. required: false name: status in: query - schema: type: string enum: - standard - custom - promotional description: Filter by plan type. required: false name: plan_type in: query - schema: type: string enum: - public - private description: Filter by visibility. required: false name: visibility in: query - schema: type: string format: uuid description: Filter by plan group. required: false name: plan_group_id in: query - schema: type: string format: uuid description: Filter by issuing company. required: false name: company_id in: query - schema: type: string format: uuid description: Filter custom plans associated with a billing account. required: false name: billing_account_id in: query - schema: type: string description: Free-text search. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of plans. content: application/json: schema: $ref: "#/components/schemas/PlanListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plans post: tags: - Planos summary: Create plan description: Creates a plan for the authenticated organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanCreateRequest" responses: "201": description: Plan created. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plans/{id}: get: tags: - Planos summary: Get plan security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Plan detail. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plans-id patch: tags: - Planos summary: Update plan security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanUpdateRequest" responses: "200": description: Plan updated. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plans-id delete: tags: - Planos summary: Archive or delete plan description: By default archives the plan (soft delete). Use `?hard=true` to permanently delete a draft plan. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - schema: type: - boolean - "null" description: When `true`, permanently deletes the plan (drafts only). required: false name: hard in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Archive or delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-plans-id /v1/plans/{id}/duplicate: post: tags: - Planos summary: Duplicate plan description: Creates a copy of the plan (including its items) in draft state. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "201": description: Plan duplicated. content: application/json: schema: $ref: "#/components/schemas/PlanResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-id-duplicate /v1/plans/{id}/items: get: tags: - Planos summary: List plan items security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: List of plan items. content: application/json: schema: $ref: "#/components/schemas/PlanItemListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plans-id-items put: tags: - Planos summary: Replace plan items description: Atomically replaces all plan items. Only root products are accepted and each `product_id` must be unique in the list. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanItemsReplaceRequest" responses: "200": description: Plan items replaced. content: application/json: schema: $ref: "#/components/schemas/PlanItemsReplaceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-plans-id-items /v1/plans/bulk-archive: post: tags: - Planos summary: Bulk archive plans security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanBulkIdsRequest" responses: "200": description: Bulk archive summary. content: application/json: schema: $ref: "#/components/schemas/PlanBulkArchiveResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-bulk-archive parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plans/bulk-delete: post: tags: - Planos summary: Bulk delete plans description: Permanently deletes the given plans. Plans with active subscriptions are skipped and returned in `skipped_ids`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanBulkIdsRequest" responses: "200": description: Bulk delete summary. content: application/json: schema: $ref: "#/components/schemas/PlanBulkDeleteResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plans/bulk-move-group: post: tags: - Planos summary: Bulk move plans to another group security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanBulkMoveGroupRequest" responses: "200": description: Bulk move summary. content: application/json: schema: $ref: "#/components/schemas/PlanBulkMoveGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plans-bulk-move-group parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plan_groups: get: tags: - Grupos de Plano summary: List plan groups description: Returns all of the current organization's plan groups ordered by `display_order`. security: - bearerAuth: [] parameters: - schema: type: string description: Free-text search by name or slug. required: false name: search in: query - schema: type: string enum: - "true" - "false" description: When `true`, includes archived groups in the list. required: false name: include_archived in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: List of plan groups. content: application/json: schema: $ref: "#/components/schemas/PlanGroupListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-groups post: tags: - Grupos de Plano summary: Create plan group security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupCreateRequest" responses: "201": description: Plan group created. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-groups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plan_groups/{id}: get: tags: - Grupos de Plano summary: Get plan group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Plan group detail. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-groups-id patch: tags: - Grupos de Plano summary: Update plan group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupUpdateRequest" responses: "200": description: Plan group updated. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plan-groups-id delete: tags: - Grupos de Plano summary: Remove plan group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-plan-groups-id /v1/plan_groups/reorder: post: tags: - Grupos de Plano summary: Reorder plan groups description: Updates each group `display_order` according to the order of the `group_ids` array. All groups must belong to the current organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanGroupReorderRequest" responses: "200": description: Order updated. content: application/json: schema: $ref: "#/components/schemas/PlanGroupReorderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-groups-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plan_groups/{id}/archive: post: tags: - Grupos de Plano summary: Archive plan group description: Marks the group as archived by setting `archived_at`. Archived groups are hidden from default listings. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Plan group archived. content: application/json: schema: $ref: "#/components/schemas/PlanGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-groups-id-archive /v1/products: get: tags: - Produtos summary: List products description: Returns a paginated list of the current organization's products. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - all - draft - active - archived description: Filter by product status. required: false name: status in: query - schema: type: string enum: - public - private description: Filter by visibility. required: false name: visibility in: query - schema: type: string enum: - base - addon_quantity - addon_fixed - metered - one_time_fixed - one_time_quantity description: Filter by product type. required: false name: productType in: query - schema: type: string format: uuid description: Filter by product group. required: false name: productGroupId in: query - schema: type: string format: uuid description: Filter by company. required: false name: companyId in: query - schema: type: string format: uuid description: Filter by parent product. required: false name: parentProductId in: query - schema: type: - boolean - "null" description: When `true`, returns only root products (with no parent). required: false name: rootOnly in: query - schema: type: string description: Free-text search (name, slug). required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of products. content: application/json: schema: $ref: "#/components/schemas/ProductListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-products post: tags: - Produtos summary: Create product security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductCreateRequest" responses: "201": description: Product created. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/products/{id}: get: tags: - Produtos summary: Get product security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product detail. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-products-id patch: tags: - Produtos summary: Update product security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductUpdateRequest" responses: "200": description: Product updated. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-products-id delete: tags: - Produtos summary: Archive product (soft delete) description: Archives the product. Returns 422 when the product is in use by active subscriptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Soft delete confirmation. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-products-id /v1/products/{id}/archive: post: tags: - Produtos summary: Archive product description: Archives the product. Returns 422 when the product is in use by active subscriptions or is already archived. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product archived. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-id-archive /v1/products/{id}/publish: post: tags: - Produtos summary: Publish product description: Promotes a draft product to active status. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product published. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-id-publish /v1/products/{id}/restore: post: tags: - Produtos summary: Restore archived product description: Restores an archived product back to active status. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product restored. content: application/json: schema: $ref: "#/components/schemas/ProductResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-id-restore /v1/products/reorder: post: tags: - Produtos summary: Reorder products description: Updates product display order. Array index 0 becomes the first item in the list. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductReorderRequest" responses: "200": description: Order updated. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid put: tags: - Produtos summary: Reorder products (PUT /reorder) description: Alias `PUT` for `/products/reorder`. Same behavior as the `POST` version. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductReorderRequest" responses: "200": description: Order updated. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-products-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/products/bulk-archive: post: tags: - Produtos summary: Bulk archive products description: Archives multiple products. IDs in use by active subscriptions or already archived are skipped and reported in the response. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkArchiveRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-archive parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/products/bulk-delete: post: tags: - Produtos summary: Bulk delete products description: Permanently deletes multiple products. IDs in use by active subscriptions are skipped and reported in the response. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkDeleteRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/products/bulk-visibility: post: tags: - Produtos summary: Bulk change visibility description: Updates the visibility (`public` or `private`) of multiple products. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkVisibilityRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-visibility parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/products/bulk-move-group: post: tags: - Produtos summary: Move products to another group description: "Moves multiple products to a product group. Send `product_group_id: null` to remove from the current group." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkMoveGroupRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-move-group parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/products/bulk-change-company: post: tags: - Produtos summary: Bulk change product company description: "Reassigns multiple products to another company. Send `company_id: null` to clear the link." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductBulkChangeCompanyRequest" responses: "200": description: Bulk operation result. content: application/json: schema: $ref: "#/components/schemas/ProductBulkResultResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-products-bulk-change-company parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/product_groups: get: tags: - Grupos de Produto summary: List product groups description: Returns a paginated list of the current organization's product groups. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Free-text search by group name. required: false name: search in: query - schema: type: string format: uuid description: Filter by associated issuing company. required: false name: company_id in: query - schema: type: - boolean - "null" description: "When `true`, includes archived groups in the listing. Default: `false`." required: false name: include_archived in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of product groups. content: application/json: schema: $ref: "#/components/schemas/ProductGroupListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-product-groups post: tags: - Grupos de Produto summary: Create product group security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupCreateRequest" responses: "201": description: Product group created. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-product-groups parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/product_groups/{id}: get: tags: - Grupos de Produto summary: Get product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product group detail. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-product-groups-id patch: tags: - Grupos de Produto summary: Update product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupUpdateRequest" responses: "200": description: Product group updated. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-product-groups-id delete: tags: - Grupos de Produto summary: Remove product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Removal confirmation. content: application/json: schema: $ref: "#/components/schemas/ProductGroupDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-product-groups-id /v1/product_groups/{id}/archive: post: tags: - Grupos de Produto summary: Archive product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product group archived. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-product-groups-id-archive delete: tags: - Grupos de Produto summary: Unarchive product group security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Product group UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Product group unarchived. content: application/json: schema: $ref: "#/components/schemas/ProductGroupResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-product-groups-id-archive /v1/product_groups/reorder: post: tags: - Grupos de Produto summary: Reorder product groups description: Updates the display order of product groups. The `group_ids` array defines the new order — index 0 becomes the first group. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderRequest" responses: "200": description: Order updated successfully. content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-product-groups-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid put: tags: - Grupos de Produto summary: Reorder product groups (PUT alias) description: Alias `PUT` for `POST /product_groups/reorder`. Same contract. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderRequest" responses: "200": description: Order updated successfully. content: application/json: schema: $ref: "#/components/schemas/ProductGroupReorderResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-product-groups-reorder parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/organization: get: tags: - Organização summary: Get current organization description: Returns the data of the organization the authenticated token belongs to. There is no `:id` parameter — the organization is always resolved from the API key. security: - bearerAuth: [] responses: "200": description: Current organization detail. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-organization parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid patch: tags: - Organização summary: Update current organization description: Updates the profile of the authenticated organization. Only the fields below can be modified — identity (`id`, `external_id`, `status`) is not changeable through this endpoint. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/OrganizationUpdateRequest" responses: "200": description: Organization updated. content: application/json: schema: $ref: "#/components/schemas/OrganizationResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-organization parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/companies: get: tags: - Empresas summary: List companies description: Returns a paginated list of the current organization's companies (head offices and branches). security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - inactive description: "Filter by status: `active` or `inactive`." required: false name: status in: query - schema: type: string description: Free-text search by name, legal name, email or document number. required: false name: search in: query - schema: type: string enum: - "true" - "false" description: Filter only the company flagged as the organization default. required: false name: is_default in: query - schema: type: string description: Filter branches by head office. Use the head office UUID to list its branches. required: false name: parent_company_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of companies. content: application/json: schema: $ref: "#/components/schemas/CompanyListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies post: tags: - Empresas summary: Create company description: Creates a company (head office or branch). To create a branch, provide `parent_company_id` — the CNPJ must share the same prefix as the head office. Only CNPJ companies can have branches. The first company created in the organization is flagged as `is_default` automatically. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyCreateRequest" responses: "201": description: Company created. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/companies/matriz: get: tags: - Empresas summary: List head office companies description: Lists the active head office companies (without `parent_company_id`) of the organization. Useful when selecting the parent company before creating a branch. Only CNPJ companies appear here. security: - bearerAuth: [] responses: "200": description: List of head office companies. content: application/json: schema: $ref: "#/components/schemas/CompanyMatrizListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-matriz parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/companies/{id}: get: tags: - Empresas summary: Get company security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company detail. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-id patch: tags: - Empresas summary: Update company security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyUpdateRequest" responses: "200": description: Company updated. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-companies-id delete: tags: - Empresas summary: Deactivate company description: Deactivates the company (soft delete — equivalent to `POST /companies/{id}/deactivate`). Cannot deactivate the only active company, nor a company that has active or trialing subscriptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company deactivated. content: application/json: schema: $ref: "#/components/schemas/CompanyDeleteResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-companies-id /v1/companies/{id}/set-default: post: tags: - Empresas summary: Set default company description: Marks the company as the organization's default. The previous default is unset in the same transaction. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company set as default. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies-id-set-default /v1/companies/{id}/deactivate: post: tags: - Empresas summary: Deactivate company (POST /deactivate) description: Deactivates the company. Cannot deactivate the only active company, nor a company that has active or trialing subscriptions. If the deactivated company was the default, another active company is promoted automatically. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company deactivated. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies-id-deactivate /v1/companies/{id}/reactivate: post: tags: - Empresas summary: Reactivate company description: Reactivates a previously deactivated company. Returns **422** when the company is already active. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company reactivated. content: application/json: schema: $ref: "#/components/schemas/CompanyResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-companies-id-reactivate /v1/companies/{id}/fiscal: get: tags: - Empresas summary: Get fiscal profile description: Returns the company's fiscal profile, or `null` when it has not been configured yet. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company fiscal profile (or `null`). content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-id-fiscal patch: tags: - Empresas summary: Update fiscal profile description: Creates or updates (upsert) the company fiscal profile. Includes taxation regime, rates (ISS, PIS, COFINS, CSLL, IRPJ) and CBS/IBS settings. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileUpsertRequest" responses: "200": description: Fiscal profile updated. content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-companies-id-fiscal /v1/companies/{id}/fiscal-profile: get: tags: - Empresas summary: Get fiscal profile (alias) description: Alias of `GET /companies/{id}/fiscal` — same representation and behaviour. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Company fiscal profile (or `null`). content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-companies-id-fiscal-profile patch: tags: - Empresas summary: Update fiscal profile (alias) description: Alias of `PATCH /companies/{id}/fiscal` — same representation and behaviour. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Company UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileUpsertRequest" responses: "200": description: Fiscal profile updated. content: application/json: schema: $ref: "#/components/schemas/CompanyFiscalProfileResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-companies-id-fiscal-profile /v1/certificates: get: tags: - Certificados summary: List digital certificates description: Returns a paginated list of the current organization’s digital (A1) certificates. For security reasons, the response **never** includes the private key nor the PFX password — only metadata extracted from the certificate. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - active - expired - revoked - expiring_soon description: Filter by certificate status. `expiring_soon` returns active certificates expiring within 30 days. required: false name: status in: query - schema: type: string description: Free-text search in `name`, `common_name`, `document` or `organization_name`. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of certificates. content: application/json: schema: $ref: "#/components/schemas/CertificateListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-certificates post: tags: - Certificados summary: Upload digital certificate description: |- Uploads an A1 digital certificate via `multipart/form-data`. The private key and password are encrypted at rest and are **never** returned by the API. The endpoint detects duplicates by `thumbprint` and automatically associates the certificate with a `person` based on the extracted CNPJ/CPF. Accepted `type` values: - `pfx` — send `file` (binary PFX/P12) and `password`. - `cert_key` — send `cert_file` (certificate PEM) and `key_file` (key PEM). - `combined_pem` — send `file` (PEM containing certificate + key). - `cert_key_password` — send `cert_file`, `key_file` and `password` (password-protected key). security: - bearerAuth: [] requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/CertificateUploadRequest" responses: "201": description: Certificate uploaded and stored successfully. content: application/json: schema: $ref: "#/components/schemas/CertificateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-certificates parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/certificates/{id}: get: tags: - Certificados summary: Get certificate security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Certificate UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Certificate detail (no sensitive data). content: application/json: schema: $ref: "#/components/schemas/CertificateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-certificates-id delete: tags: - Certificados summary: Delete certificate description: Removes the certificate via **soft delete**. Encrypted data remains in the database for audit purposes only. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Certificate UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Certificate deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-certificates-id /v1/coupons: get: tags: - Cupons summary: List coupons description: Returns a paginated list of the current organization's coupons. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - "true" - "false" description: "Filter by status: `true` returns only active coupons; `false`, only inactive." required: false name: is_active in: query - schema: type: string description: Free-text search across `code` and `name`. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of coupons. content: application/json: schema: $ref: "#/components/schemas/CouponListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-coupons post: tags: - Cupons summary: Create coupon description: Creates a discount coupon. The `code` must be unique per organization. Use `discount_type=percentage` with `discount_value` between `0` and `100`, or `discount_type=fixed_amount` with `discount_value` in cents (÷100 → BRL). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CouponCreateRequest" responses: "201": description: Coupon created. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-coupons parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/coupons/{id}: get: tags: - Cupons summary: Get coupon security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Coupon detail. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-coupons-id patch: tags: - Cupons summary: Update coupon description: Updates editable coupon fields. `code`, `discount_type`, `discount_value` and `currency` are immutable after creation. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CouponUpdateRequest" responses: "200": description: Coupon updated. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-coupons-id delete: tags: - Cupons summary: Delete coupon description: Deletes the coupon permanently. Allowed only while the coupon **has no recorded redemptions** — otherwise use `POST /coupons/{id}/deactivate` to preserve history. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Coupon deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-coupons-id /v1/coupons/{id}/deactivate: post: tags: - Cupons summary: Deactivate coupon description: "Deactivates the coupon: new redemptions are blocked, but previous redemptions are preserved." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Coupon deactivated. content: application/json: schema: $ref: "#/components/schemas/CouponResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-coupons-id-deactivate /v1/coupons/{id}/redemptions: get: tags: - Cupons summary: List coupon redemptions description: Returns a paginated list of the coupon's recorded redemptions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Coupon UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of coupon redemptions. content: application/json: schema: $ref: "#/components/schemas/CouponRedemptionListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-coupons-id-redemptions /v1/credits: get: tags: - Créditos summary: List credits description: Returns a paginated list of credits in the current organization. By default, expired credits are omitted — use `usage` or `include_expired` to include them. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter credits by billing account. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter credits by the linked `company`. required: false name: company_id in: query - schema: type: string enum: - promotional - adjustment - refund - manual description: "Filter by credit type: `promotional`, `adjustment`, `refund` or `manual`." required: false name: type in: query - schema: type: string enum: - available - used - expired description: Filter by usage state — `available` (remaining balance and not expired), `used` (fully consumed) or `expired` (past expiration). required: false name: usage in: query - schema: type: string enum: - "true" - "false" description: Includes expired credits when `true`. Ignored when `usage` is set. required: false name: include_expired in: query - schema: type: string format: date-time description: Lower bound for `created_at` (ISO8601, inclusive). required: false name: date_from in: query - schema: type: string format: date-time description: Upper bound for `created_at` (ISO8601, inclusive). required: false name: date_to in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of credits. content: application/json: schema: $ref: "#/components/schemas/CreditListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-credits post: tags: - Créditos summary: Add credit description: Adds a credit to a billing account. The amount is credited to the `BillingAccount` `balance_cents` and becomes available to settle future invoices. When `company_id` is provided, the credit can only be applied to invoices from the same `company`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditCreateRequest" responses: "201": description: Credit created. content: application/json: schema: $ref: "#/components/schemas/CreditResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-credits parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/credits/{id}: get: tags: - Créditos summary: Get credit security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Credit UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Credit detail. content: application/json: schema: $ref: "#/components/schemas/CreditResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-credits-id patch: tags: - Créditos summary: Update credit description: Adjusts the credit (type, amount, description or expiration). `amount_cents` can only change if the credit has not been partially used — otherwise the API responds with `400`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Credit UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/CreditUpdateRequest" responses: "200": description: Credit updated. content: application/json: schema: $ref: "#/components/schemas/CreditResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-credits-id delete: tags: - Créditos summary: Delete credit description: Removes the credit and reverses the matching balance on the billing account. Only allowed if no cents of the credit have been consumed — otherwise the API responds with `400`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Credit UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Credit deleted. content: application/json: schema: $ref: "#/components/schemas/CreditDeleteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-credits-id /v1/invoices: get: tags: - Faturas summary: List invoices description: Returns a paginated list of the current organization's invoices. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - draft - open - paid - void - uncollectible description: "Filter by status: `draft`, `open`, `paid`, `void` or `uncollectible`." required: false name: status in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by issuing `company_id`. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by originating `subscription_id`. required: false name: subscription_id in: query - schema: type: string description: Filter by start `due_date` (inclusive). required: false name: due_date_from in: query - schema: type: string description: Filter by end `due_date` (inclusive). required: false name: due_date_to in: query - schema: type: string description: Filter by start `created_at` (inclusive). required: false name: date_from in: query - schema: type: string description: Filter by end `created_at` (inclusive). required: false name: date_to in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: - integer - "null" description: Filter by exact total amount (in cents). required: false name: total_cents in: query - schema: type: string description: Filter by customer's CPF/CNPJ. required: false name: document_number in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only invoices without associated payments. required: false name: without_payments in: query - schema: type: string enum: - all - with_plan - without_plan description: "Filter by origin: `all`, `with_plan` (subscription) or `without_plan` (one-off)." required: false name: plan_filter in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of invoices. content: application/json: schema: $ref: "#/components/schemas/InvoiceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices post: tags: - Faturas summary: Create invoice description: Creates an invoice for a billing account. Accepts line items, optional installments (`installments`, minimum 2) and NF-e issuance policy. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceCreateRequest" responses: "201": description: Invoice created. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/invoices/pending-payment: get: tags: - Faturas summary: List invoices with pending payment description: Returns finalized invoices (`status = open`) past their `due_date`. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of invoices with pending payment. content: application/json: schema: $ref: "#/components/schemas/InvoiceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-pending-payment /v1/invoices/pending-nfe: get: tags: - Faturas summary: List invoices with pending NF-e description: Returns paid invoices that still need NF-e emission — no NF-e, or NF-e in `pending`, `processing` or `error` status. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billing_account_id in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of invoices with pending NF-e. content: application/json: schema: $ref: "#/components/schemas/InvoiceListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-pending-nfe /v1/invoices/{id}: get: tags: - Faturas summary: Get invoice security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Invoice detail. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id patch: tags: - Faturas summary: Update invoice security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceUpdateRequest" responses: "200": description: Invoice updated. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-invoices-id delete: tags: - Faturas summary: Delete invoice description: Deletes a draft (`draft`) invoice. Finalized invoices must be canceled via `POST /invoices/{id}/void`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Invoice deleted. content: application/json: schema: $ref: "#/components/schemas/InvoiceDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-invoices-id /v1/invoices/{id}/finalize: post: tags: - Faturas summary: Finalize invoice description: Finalizes a draft invoice (`draft` → `open`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Invoice finalized. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-finalize /v1/invoices/{id}/void: post: tags: - Faturas summary: Void invoice description: Voids an open invoice (`open` → `void`). The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceVoidRequest" responses: "200": description: Invoice voided. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-void /v1/invoices/{id}/undo-payment: post: tags: - Faturas summary: Undo invoice payment description: Reverts the invoice payment (`paid` → `open`). The `reason` is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceUndoPaymentRequest" responses: "200": description: Payment undone. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-undo-payment /v1/invoices/{id}/pay: post: tags: - Faturas summary: Pay invoice description: "Two modes: (a) when `payment_method` is provided, creates a gateway payment (`pix`, `bank_slip` or `card`) and returns the method artifacts (QR code, barcode or card status); (b) when omitted, marks the invoice as paid manually (reconciliation)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoicePayRequest" responses: "200": description: Payment result or invoice marked as paid. content: application/json: schema: $ref: "#/components/schemas/InvoicePayResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-pay /v1/invoices/{id}/send-reminder: post: tags: - Faturas summary: Send invoice reminder description: Sends an invoice payment reminder email to the billing account's `billing_email`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Reminder sent. content: application/json: schema: $ref: "#/components/schemas/InvoiceResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-send-reminder /v1/invoices/{id}/issue-nfe: post: tags: - Faturas summary: Issue NF-e for invoice description: Triggers issuance of the NF-e (Electronic Invoice) for the invoice. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: NF-e queued/issued. content: application/json: schema: $ref: "#/components/schemas/InvoiceNfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-issue-nfe /v1/invoices/{id}/apply-credits: post: tags: - Faturas summary: Apply credits to invoice description: Applies billing-account credits to an open (`status = open`) invoice. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceApplyCreditsRequest" responses: "200": description: Credits applied. content: application/json: schema: $ref: "#/components/schemas/InvoiceCreditsResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-apply-credits /v1/invoices/{id}/remove-credits: post: tags: - Faturas summary: Remove applied credits description: Removes all credits applied to the invoice, returning them to the billing account. Only works on open (`status = open`) invoices. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Credits removed. content: application/json: schema: $ref: "#/components/schemas/InvoiceCreditsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-remove-credits /v1/invoices/{id}/pdf: get: tags: - Faturas summary: Download invoice PDF description: Generates and downloads the invoice PDF as a binary attachment (`application/pdf`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Invoice PDF. content: application/pdf: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id-pdf /v1/invoices/{id}/payment-methods: get: tags: - Faturas summary: List available payment methods description: Lists the payment methods available to pay this invoice, based on the organization's active gateways and portal settings. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Available payment methods. content: application/json: schema: $ref: "#/components/schemas/InvoicePaymentMethodsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id-payment-methods /v1/invoices/{id}/installments: get: tags: - Faturas summary: List invoice installments security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: List of installments. content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentsListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-invoices-id-installments post: tags: - Faturas summary: Create/update installment schedule description: Creates or replaces the invoice installment schedule. Minimum of 2 installments. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentsCreateRequest" responses: "201": description: Installment schedule created. content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentsListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-installments /v1/invoices/{id}/installments/{installmentId}/mark-paid: post: tags: - Faturas summary: Mark installment as paid description: Manually marks an installment as paid (reconciliation, no gateway call). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - schema: type: string format: uuid description: Installment UUID. required: true name: installmentId in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Installment marked as paid. content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-installments-installmentid-mark-paid /v1/invoices/{id}/installments/{installmentId}/pay: post: tags: - Faturas summary: Pay installment description: Processes payment for a specific installment via the gateway. The previous installment must be paid. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Invoice UUID. required: true name: id in: path - schema: type: string format: uuid description: Installment UUID. required: true name: installmentId in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/InvoiceInstallmentPayRequest" responses: "200": description: Installment payment result. content: application/json: schema: $ref: "#/components/schemas/InvoicePayResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-invoices-id-installments-installmentid-pay /v1/payments: get: tags: - Pagamentos summary: List payments description: Returns a paginated list of the current organization's payments. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - pending - processing - succeeded - failed - canceled - partial - refunded - partially_refunded description: Filter by payment status. required: false name: status in: query - schema: type: string format: uuid description: Filter by payments of a specific invoice. required: false name: invoiceId in: query - schema: type: string format: uuid description: Filter by payments of a billing account. required: false name: billingAccountId in: query - schema: type: string description: Start date (creation) — ISO 8601 format. required: false name: dateFrom in: query - schema: type: string description: End date (creation) — ISO 8601 format. required: false name: dateTo in: query - schema: type: string description: Paid-at start date — ISO 8601 format. required: false name: paidDateFrom in: query - schema: type: string description: Paid-at end date — ISO 8601 format. required: false name: paidDateTo in: query - schema: type: string enum: - all - with_invoice - without_invoice description: "Filter by invoice presence: `all`, `with_invoice` or `without_invoice`." required: false name: invoiceFilter in: query - schema: type: string enum: - card - bank_slip - pix - bank_transfer description: "Filter by payment method: `card`, `bank_slip`, `pix` or `bank_transfer`." required: false name: paymentMethodType in: query - schema: type: - integer - "null" minimum: 0 description: Minimum amount in cents (÷100 → BRL). required: false name: amountMinCents in: query - schema: type: - integer - "null" minimum: 0 description: Maximum amount in cents (÷100 → BRL). required: false name: amountMaxCents in: query - schema: type: string description: Free-text search. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of payments. content: application/json: schema: $ref: "#/components/schemas/PaymentListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payments post: tags: - Pagamentos summary: Process payment description: Processes a payment for an existing invoice. Accepts a previously registered `payment_method_id` **or** a `payment_method` block with card/PIX/bank-slip data. When `amount_cents` is omitted, charges the invoice open balance. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentCreateRequest" responses: "201": description: Payment created. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/payments/bulk-update-invoice: post: tags: - Pagamentos summary: Reassign payments to another invoice description: Bulk-updates the invoice associated with the given payments. Useful for fixing links when payments arrived pointing to the wrong invoice. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentBulkUpdateInvoiceRequest" responses: "200": description: Payments reassigned. content: application/json: schema: $ref: "#/components/schemas/PaymentBulkUpdateInvoiceResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-bulk-update-invoice parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/payments/{id}: get: tags: - Pagamentos summary: Get payment security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Payment detail. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payments-id delete: tags: - Pagamentos summary: Delete payment description: Removes a payment. Confirmed payments cannot be deleted — use `cancel` or `refund` instead. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Payment removed. content: application/json: schema: $ref: "#/components/schemas/PaymentDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-payments-id /v1/payments/{id}/cancel: post: tags: - Pagamentos summary: Cancel payment description: Cancels an open payment. When `cancel_on_gateway` is `true` (default), the cancellation is propagated to the gateway. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentCancelRequest" responses: "200": description: Payment canceled. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-cancel /v1/payments/{id}/retry: post: tags: - Pagamentos summary: Retry payment description: Reprocesses a failed payment. Optionally switches to a new card (via `card`) or to a saved payment method (`payment_method_id`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentRetryRequest" responses: "200": description: Payment retried. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-retry /v1/payments/{id}/change-card: post: tags: - Pagamentos summary: Change payment card description: Replaces the credit card on a failed Pagar.me payment. The new card must be pre-registered in `payment_methods`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentChangeCardRequest" responses: "200": description: Card changed. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-change-card /v1/payments/{id}/change-due-date: post: tags: - Pagamentos summary: Change bank slip due date description: Changes the due date of a pending bank-slip payment issued via the Kobana gateway. The new date must be in the future. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentChangeDueDateRequest" responses: "200": description: Due date updated. content: application/json: schema: $ref: "#/components/schemas/PaymentChangeDueDateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-change-due-date /v1/payments/{id}/send-email: post: tags: - Pagamentos summary: Send bank slip by email description: Sends the bank-slip link by email to the given recipient. Only available for pending bank-slip payments. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentSendEmailRequest" responses: "200": description: Email sent. content: application/json: schema: $ref: "#/components/schemas/PaymentSendEmailResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-send-email /v1/payments/{id}/sync: post: tags: - Pagamentos summary: Sync payment with gateway description: Syncs the payment status with the upstream gateway (Kobana PIX/boleto or Pagar.me refund). Returns the refreshed payment. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Payment synced. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-sync /v1/payments/{id}/refund: post: tags: - Pagamentos summary: Refund payment description: Refunds a successful payment. Without `amount_cents`, refunds the full amount; with a partial amount, issues a partial refund. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentRefundRequest" responses: "200": description: Payment refunded. content: application/json: schema: $ref: "#/components/schemas/PaymentResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payments-id-refund /v1/payment_methods: get: tags: - Métodos de Pagamento summary: List payment methods description: "Returns a paginated list of the current organization's payment methods. Optional filters: `billing_account_id`, `type`, `status`." security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by billing account UUID. required: false name: billingAccountId in: query - schema: type: string enum: - card - bank_slip - pix - bank_transfer description: "Filter by type: `card`, `bank_slip`, `pix` or `bank_transfer`." required: false name: type in: query - schema: type: string enum: - active - expired - failed description: "Filter by status: `active`, `expired` or `failed`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of payment methods. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payment-methods post: tags: - Métodos de Pagamento summary: Create payment method description: Creates a payment method tied to a billing account. For `type=card`, send the `card` block with the `cardToken` produced by client-side tokenization. For `type=bank_transfer`, send the `bankAccount` block. For `bank_slip` and `pix`, only the `type` is required — the default gateway is resolved from the organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodCreateRequest" responses: "201": description: Payment method created. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payment-methods parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/payment_methods/{id}: get: tags: - Métodos de Pagamento summary: Get payment method security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Payment method detail. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-payment-methods-id patch: tags: - Métodos de Pagamento summary: Update card expiration description: Updates only the expiration month and year of the card tied to the method. Fails when `type` is not `card`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodUpdateRequest" responses: "200": description: Payment method updated. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-payment-methods-id delete: tags: - Métodos de Pagamento summary: Delete payment method description: Soft-deletes the payment method (marks it as `removed`). Fails when there are pending or processing payments. If it was the default, another active method is automatically promoted. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Payment method deleted. content: application/json: schema: type: object properties: data: type: object properties: deleted: type: boolean required: - deleted required: - data "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-payment-methods-id /v1/payment_methods/{id}/set-default: post: tags: - Métodos de Pagamento summary: Set payment method as default description: Marks the method as the billing account's default and unsets previous defaults. Fails when the method is not `active`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Payment method UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Payment method set as default. content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-payment-methods-id-set-default /v1/nfes: get: tags: - NF-e summary: List NF-e description: Returns a paginated list of the current organization's NF-e (electronic invoices). security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by `billing_account_id`. required: false name: billingAccountId in: query - schema: type: string format: uuid description: Filter by issuing `company_id`. required: false name: companyId in: query - schema: type: string format: uuid description: Filter by linked `invoice_id`. required: false name: invoiceId in: query - schema: type: string enum: - draft - pending - processing - issued - pending_cancel - canceling - canceled - error description: "Filter by status: `draft`, `pending`, `processing`, `issued`, `pending_cancel`, `canceling`, `canceled` or `error`." required: false name: status in: query - schema: type: string enum: - with - without description: "Filter by invoice presence: `with` (with invoice only) or `without` (one-off only)." required: false name: invoiceFilter in: query - schema: type: string description: Filter by start `created_at` (inclusive). required: false name: dateFrom in: query - schema: type: string description: Filter by end `created_at` (inclusive). required: false name: dateTo in: query - schema: type: string description: Filter by start `issue_date` (inclusive). required: false name: issueDateFrom in: query - schema: type: string description: Filter by end `issue_date` (inclusive). required: false name: issueDateTo in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of NF-e. content: application/json: schema: $ref: "#/components/schemas/NfeListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes post: tags: - NF-e summary: Create draft NF-e description: Creates a draft (`draft`) NF-e for later issuance via `POST /nfes/{id}/issue`. Accepts taker data (`customer`) and optional tax rates. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeCreateRequest" responses: "201": description: Draft NF-e created. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/sync: post: tags: - NF-e summary: Sync organization NF-e description: Triggers a background job to sync every organization NF-e with the provider (updates status, downloads pending PDFs/XMLs). Returns the `job_id` for polling. Refuses if a sync is already running. security: - bearerAuth: [] responses: "201": description: Sync queued. content: application/json: schema: $ref: "#/components/schemas/NfeSyncOrgResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-sync parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/bulk: post: tags: - NF-e summary: Bulk update NF-e description: Updates multiple NF-e at once. Currently supports linking or unlinking an invoice (`invoice_id`) on up to 100 NF-e per request. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeBulkUpdateRequest" responses: "200": description: Number of NF-e updated. content: application/json: schema: $ref: "#/components/schemas/NfeBulkUpdateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-bulk parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/bulk-delete: post: tags: - NF-e summary: Bulk delete NF-e description: Deletes up to 100 NF-e at once. All must be in `draft` status and belong to the current organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeBulkDeleteRequest" responses: "200": description: Number of NF-e deleted. content: application/json: schema: $ref: "#/components/schemas/NfeBulkDeleteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/request-tries: get: tags: - NF-e summary: List request retries (organization) description: Lists every NF-e provider request attempt for the organization, paginated and ordered by descending date. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of attempts. content: application/json: schema: $ref: "#/components/schemas/NfeRequestTryPaginatedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-request-tries /v1/nfes/fetch-from-sefaz: post: tags: - NF-e summary: Fetch NFS-e from ADN (SEFAZ) description: Fetches an NFS-e from the Ambiente de Dados Nacional (ADN) using a 50-digit access key and a previously registered digital certificate (mTLS authentication). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeFetchFromSefazRequest" responses: "200": description: ADN fetch result. content: application/json: schema: $ref: "#/components/schemas/NfeFetchFromSefazResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-fetch-from-sefaz parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/fetch-barueri: post: tags: - NF-e summary: Fetch NFS-e from Barueri description: Fetches an NFS-e from the Barueri municipal endpoint using the `codigo_autenticidade` printed on the DANFSE and the taker's CPF/CNPJ. Returns the raw XML and, when found, the NF-e already present in the organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeFetchBarueriRequest" responses: "200": description: Fetch result with XML and reference to the existing NF-e, when present. content: application/json: schema: $ref: "#/components/schemas/NfeFetchBarueriResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-fetch-barueri parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/import-barueri: post: tags: - NF-e summary: Import Barueri NFS-e description: Imports a Barueri NFS-e into the database. Accepts a raw XML (returned by `POST /nfes/fetch-barueri`) or the `codigo_autenticidade` + `cnpj_tomador` to re-fetch before importing. Creates the taker `BillingAccount` when it does not yet exist. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeImportBarueriRequest" responses: "200": description: Import result with `created`/`updated` flags and the persisted NF-e. content: application/json: schema: $ref: "#/components/schemas/NfeImportBarueriResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-import-barueri parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/nfes/{id}: get: tags: - NF-e summary: Get NF-e security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: NF-e detail. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id patch: tags: - NF-e summary: Update draft NF-e description: Updates NF-e fields. Only `draft` NF-e accept changes to amounts and fiscal codes. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeUpdateRequest" responses: "200": description: NF-e updated. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-nfes-id delete: tags: - NF-e summary: Delete NF-e description: Deletes an NF-e. Allowed only for `draft`, `pending`, `processing`, `error` or `canceled` statuses. `issued` NF-e must be canceled via `POST /nfes/{id}/cancel`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: NF-e deleted. content: application/json: schema: $ref: "#/components/schemas/NfeDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-nfes-id /v1/nfes/{id}/issue: post: tags: - NF-e summary: Issue NF-e description: Issues a draft (`draft`) NF-e or retries one in `pending`/`error`. Sends the request to the provider configured for the organization. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: NF-e queued/issued. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-issue /v1/nfes/{id}/cancel: post: tags: - NF-e summary: Cancel NF-e description: Cancels an issued NF-e. Enqueues the cancellation asynchronously with the provider. The `reason` must be at least 15 characters and is recorded in the audit log. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/NfeCancelRequest" responses: "200": description: Cancellation queued. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-cancel /v1/nfes/{id}/retry-cancel: post: tags: - NF-e summary: Retry NF-e cancellation description: Retries cancellation of an NF-e stuck in `pending_cancel`, `canceling` or `error`. Re-enqueues the cancellation job. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Cancellation retry queued. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-retry-cancel /v1/nfes/{id}/sync: post: tags: - NF-e summary: Sync NF-e PDF/XML description: Downloads the NF-e PDF and XML from the provider and stores them in the database. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: PDF/XML synced. content: application/json: schema: $ref: "#/components/schemas/NfeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-sync /v1/nfes/{id}/pdf: get: tags: - NF-e summary: Download NF-e PDF description: Downloads the NF-e PDF (DANFE) as a binary attachment (`application/pdf`). Served from the database when available; otherwise fetched from the provider. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: NF-e PDF. content: application/pdf: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-pdf /v1/nfes/{id}/xml: get: tags: - NF-e summary: Download NF-e XML description: Downloads the NF-e XML as a binary attachment (`application/xml`). Served from the database when available; otherwise fetched from the provider. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: NF-e XML. content: application/xml: schema: type: string format: binary "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-xml /v1/nfes/{id}/request-tries: get: tags: - NF-e summary: List NF-e request retries description: Lists the attempts (`NfeRequestTry`) made to the provider for this NF-e — one entry per call, with endpoint, HTTP status, duration and error messages. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: List of attempts. content: application/json: schema: $ref: "#/components/schemas/NfeRequestTryListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-request-tries /v1/nfes/{id}/requests: get: tags: - NF-e summary: List NF-e external requests description: Lists captured HTTP requests for this NF-e (provider calls and incoming webhooks), paginated. Use `direction` to filter between `outbound` and `inbound`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - outbound - inbound description: "Filter requests by direction: `outbound` (outgoing calls) or `inbound` (incoming webhooks)." required: false name: direction in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of requests. content: application/json: schema: $ref: "#/components/schemas/NfeExternalRequestListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-requests /v1/nfes/{id}/requests/{requestId}: get: tags: - NF-e summary: Get external request security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - schema: type: string format: uuid description: External request UUID. required: true name: requestId in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: External request detail, including headers and bodies. content: application/json: schema: $ref: "#/components/schemas/NfeExternalRequestResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-nfes-id-requests-requestid /v1/nfes/{id}/validate-barueri: post: tags: - NF-e summary: Validate Barueri NFS-e description: Re-fetches the NFS-e from the Barueri municipality and compares it to the local record, returning the diff list and the fresh XML for reapplication via `POST /nfes/import-barueri`. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: NF-e UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Validation result with differences and current XML. content: application/json: schema: $ref: "#/components/schemas/NfeValidateBarueriResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-nfes-id-validate-barueri /v1/proposals: get: tags: - Propostas summary: List proposals description: Returns a paginated list of the current organization's commercial proposals. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - draft - sent - viewed - accepted - rejected - expired - canceled description: "Filter by status: `draft`, `sent`, `viewed`, `accepted`, `rejected`, `expired` or `canceled`." required: false name: status in: query - schema: type: string format: uuid description: Filter by linked `billing_account_id`. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter by `prospect_id`. required: false name: prospect_id in: query - schema: type: string format: uuid description: Filter by issuing `company_id`. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by `template_id` used to generate the PDF. required: false name: template_id in: query - schema: type: string description: Free-text search. required: false name: search in: query - schema: type: string description: Filter proposals with `expires_at` ≥ value (ISO 8601). required: false name: expires_after in: query - schema: type: string description: Filter proposals with `expires_at` ≤ value (ISO 8601). required: false name: expires_before in: query - schema: type: string description: Filter by start `created_at` (inclusive). required: false name: date_from in: query - schema: type: string description: Filter by end `created_at` (inclusive). required: false name: date_to in: query - schema: type: string description: Filter by start `accepted_at`. required: false name: accepted_from in: query - schema: type: string description: Filter by end `accepted_at`. required: false name: accepted_to in: query - schema: type: - integer - "null" minimum: 0 description: Filter by minimum `setup_amount_cents` (in cents). required: false name: setup_amount_min in: query - schema: type: - integer - "null" minimum: 0 description: Filter by maximum `setup_amount_cents` (in cents). required: false name: setup_amount_max in: query - schema: type: - integer - "null" minimum: 0 description: Filter by minimum `monthly_amount_cents` (in cents). required: false name: monthly_amount_min in: query - schema: type: - integer - "null" minimum: 0 description: Filter by maximum `monthly_amount_cents` (in cents). required: false name: monthly_amount_max in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of proposals. content: application/json: schema: $ref: "#/components/schemas/ProposalListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals post: tags: - Propostas summary: Create proposal description: Creates a commercial proposal. You must provide `billing_account_id`, `prospect_id` or `prospect_data` (inline prospect creation). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalCreateRequest" responses: "201": description: Proposal created. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/proposals/stats: get: tags: - Propostas summary: Get proposal statistics description: Returns proposal counts by status (`draft`, `sent`, `viewed`, `accepted`, `rejected`, `expired`, `canceled`) for the current organization. security: - bearerAuth: [] responses: "200": description: Proposal statistics. content: application/json: schema: $ref: "#/components/schemas/ProposalStatsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-stats parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/proposals/bulk-cancel: post: tags: - Propostas summary: Bulk cancel proposals description: Cancels multiple proposals at once (up to 100). Returns success/failure counts and errors per id. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalBulkRequest" responses: "200": description: Bulk cancel result. content: application/json: schema: $ref: "#/components/schemas/ProposalBulkResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-bulk-cancel parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/proposals/bulk-delete: post: tags: - Propostas summary: Bulk delete proposals description: Deletes multiple proposals at once (up to 100). Returns success/failure counts and errors per id. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalBulkRequest" responses: "200": description: Bulk delete result. content: application/json: schema: $ref: "#/components/schemas/ProposalBulkResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-bulk-delete parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/proposals/bulk-send: post: tags: - Propostas summary: Bulk send proposals description: Sends multiple proposals at once (up to 100). Returns success/failure counts and errors per id. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalBulkRequest" responses: "200": description: Bulk send result. content: application/json: schema: $ref: "#/components/schemas/ProposalBulkResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-bulk-send parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/proposals/{id}: get: tags: - Propostas summary: Get proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal detail. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id patch: tags: - Propostas summary: Update proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalUpdateRequest" responses: "200": description: Proposal updated. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-proposals-id delete: tags: - Propostas summary: Delete proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal deleted. content: application/json: schema: $ref: "#/components/schemas/ProposalDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-proposals-id /v1/proposals/{id}/accept: post: tags: - Propostas summary: Accept proposal description: Accepts the proposal and creates (or confirms) the corresponding subscription using the given cycle. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalAcceptRequest" responses: "200": description: Proposal accepted — returns the proposal, `subscription_id` and `invoice_id` when applicable. content: application/json: schema: $ref: "#/components/schemas/ProposalAcceptResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-accept /v1/proposals/{id}/cancel: post: tags: - Propostas summary: Cancel proposal description: Cancels the proposal (`status → canceled`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal canceled. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-cancel /v1/proposals/{id}/duplicate: post: tags: - Propostas summary: Duplicate proposal description: Creates a new proposal from the original (as draft), preserving items and configuration. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "201": description: Proposal duplicated. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-duplicate /v1/proposals/{id}/send: post: tags: - Propostas summary: Send proposal email description: "Sends (or resends) the proposal email to the recipient. Allowed statuses: `draft`, `sent` or `viewed`. Optionally customize `subject` and `message` (HTML)." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalSendRequest" responses: "200": description: Proposal sent. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-send /v1/proposals/{id}/publish: post: tags: - Propostas summary: Publish proposal description: Publishes the proposal (`draft → sent`) without sending the email, making it available on the portal. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal published. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-publish /v1/proposals/{id}/unpublish: post: tags: - Propostas summary: Unpublish proposal description: Reverts the proposal to draft (`sent`/`viewed` → `draft`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal unpublished. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-unpublish /v1/proposals/{id}/undo-accept: post: tags: - Propostas summary: Undo proposal acceptance description: "Reverts the acceptance: removes the linked subscription and returns status to `sent`." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Acceptance undone. content: application/json: schema: $ref: "#/components/schemas/ProposalResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-undo-accept /v1/proposals/{id}/generate-pdf: post: tags: - Propostas summary: Generate proposal PDF description: Generates (or regenerates) the proposal PDF via Google App Scripts. Requires a `template` with `app_script_url` configured. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: PDF generated — returns the updated proposal and document/PDF URLs. content: application/json: schema: $ref: "#/components/schemas/ProposalGeneratePdfResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-generate-pdf /v1/proposals/{id}/json: get: tags: - Propostas summary: Get proposal JSON snapshot description: Returns the full data snapshot used to render the PDF template (mirrors what AppScript receives). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal JSON snapshot. content: application/json: schema: $ref: "#/components/schemas/ProposalJsonResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-json /v1/proposals/{id}/pricing: get: tags: - Propostas summary: Get proposal pricing breakdown description: Returns the pricing breakdown per billing cycle (monthly, quarterly, semiannual, annual), with setup and discounts applied. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Pricing breakdown. content: application/json: schema: $ref: "#/components/schemas/ProposalPricingResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-pricing /v1/proposals/{id}/items: get: tags: - Propostas summary: List proposal items security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: List of items. content: application/json: schema: $ref: "#/components/schemas/ProposalItemsListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-items post: tags: - Propostas summary: Add item to proposal security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalItemCreateRequest" responses: "201": description: Item created. content: application/json: schema: $ref: "#/components/schemas/ProposalItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposals-id-items /v1/proposals/{id}/items/{itemId}: get: tags: - Propostas summary: Get proposal item security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - schema: type: string format: uuid description: Proposal item UUID. required: true name: itemId in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Item detail. content: application/json: schema: $ref: "#/components/schemas/ProposalItemResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposals-id-items-itemid patch: tags: - Propostas summary: Update proposal item description: Updates an item. Only allowed on draft (`status = draft`) proposals. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - schema: type: string format: uuid description: Proposal item UUID. required: true name: itemId in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalItemUpdateRequest" responses: "200": description: Item updated. content: application/json: schema: $ref: "#/components/schemas/ProposalItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-proposals-id-items-itemid delete: tags: - Propostas summary: Delete proposal item description: Removes an item. Only allowed on draft (`status = draft`) proposals. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal UUID. required: true name: id in: path - schema: type: string format: uuid description: Proposal item UUID. required: true name: itemId in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Item deleted. content: application/json: schema: $ref: "#/components/schemas/ProposalDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-proposals-id-items-itemid /v1/proposal_templates: get: tags: - Templates de Proposta summary: List proposal templates description: Returns a paginated list of the current organization's proposal templates. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or description. required: false name: search in: query - schema: type: boolean description: Filter by active (`true`) or deactivated (`false`) templates. required: false name: isActive in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of proposal templates. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposal-templates post: tags: - Templates de Proposta summary: Create proposal template description: Creates a proposal template linked to a Google Doc or Google Slides. The `google_doc_id` must be unique per organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateCreateRequest" responses: "201": description: Proposal template created. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/proposal_templates/{id}: get: tags: - Templates de Proposta summary: Get proposal template security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal template detail. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-proposal-templates-id patch: tags: - Templates de Proposta summary: Update proposal template security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateUpdateRequest" responses: "200": description: Proposal template updated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-proposal-templates-id delete: tags: - Templates de Proposta summary: Delete proposal template security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal template removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-proposal-templates-id /v1/proposal_templates/{id}/activate: post: tags: - Templates de Proposta summary: Activate proposal template description: Activates a previously deactivated proposal template, making it available for use in new proposals. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal template activated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-activate /v1/proposal_templates/{id}/deactivate: post: tags: - Templates de Proposta summary: Deactivate proposal template description: Deactivates a proposal template. Deactivated templates cannot be used in new proposals, but proposals already created remain unchanged. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Proposal template deactivated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-deactivate /v1/proposal_templates/{id}/duplicate: post: tags: - Templates de Proposta summary: Duplicate proposal template description: Creates a copy of the given template, keeping configuration and metadata. The new template gets a derived name and never inherits the `is_default` flag. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "201": description: Proposal template duplicated. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-duplicate /v1/proposal_templates/{id}/set-default: post: tags: - Templates de Proposta summary: Set template as default description: Marks the given template as the organization default and removes the flag from the others. Only one template can be default at a time. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Proposal template UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Template set as default. content: application/json: schema: $ref: "#/components/schemas/ProposalTemplateResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-proposal-templates-id-set-default /v1/plan_changes: get: tags: - Mudanças de Plano summary: List plan changes description: Returns the paginated history of plan changes (upgrades, downgrades and lateral) for the current organization. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by changes of a subscription. required: false name: subscription_id in: query - schema: type: string enum: - upgrade - downgrade - lateral description: "Filter by type: `upgrade`, `downgrade` or `lateral`." required: false name: change_type in: query - schema: type: string enum: - pending - scheduled - completed - canceled - failed description: "Filter by status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of plan changes. content: application/json: schema: $ref: "#/components/schemas/PlanChangeListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes post: tags: - Mudanças de Plano summary: Execute plan change description: Executes a plan change for an existing subscription. `timing` controls whether the change applies immediately (with proration) or at the end of the current period. On success, returns the UUIDs of the `plan_change`, the proration invoice (if any) and the generated credit (if any). security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeExecuteRequest" responses: "201": description: Plan change executed. content: application/json: schema: $ref: "#/components/schemas/PlanChangeExecuteResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-changes parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plan_changes/stats: get: tags: - Mudanças de Plano summary: Plan change stats description: Returns plan change aggregates (totals by type, by status, proration credits and charges) for a window in days. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Window in days for the aggregates (default: `30`)." example: 30 required: false name: days in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Aggregated plan change stats. content: application/json: schema: $ref: "#/components/schemas/PlanChangeStatsResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-stats /v1/plan_changes/config: get: tags: - Mudanças de Plano summary: Get plan change config description: Returns the organization's default configuration for upgrades and downgrades — proration behavior, timing and credit/refund generation. security: - bearerAuth: [] responses: "200": description: Current configuration. content: application/json: schema: $ref: "#/components/schemas/PlanChangeConfigResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid patch: tags: - Mudanças de Plano summary: Update plan change config description: Partially updates (PATCH) the organization's plan change configuration. All fields are optional. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeConfigUpdateRequest" responses: "200": description: Configuration updated. content: application/json: schema: $ref: "#/components/schemas/PlanChangeConfigResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plan-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plan_changes/rules: get: tags: - Mudanças de Plano summary: List plan change rules description: Lists custom rules that override the default behavior for specific plan-to-plan transitions. security: - bearerAuth: [] responses: "200": description: List of plan change rules. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid post: tags: - Mudanças de Plano summary: Create plan change rule description: Creates a new rule for a plan-to-plan transition. Lets you block/allow the transition, set timing, proration, discounts and bonus days. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleCreateRequest" responses: "201": description: Rule created. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-plan-changes-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/plan_changes/rules/{id}: get: tags: - Mudanças de Plano summary: Get plan change rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Rule detail. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-rules-id patch: tags: - Mudanças de Plano summary: Update plan change rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleUpdateRequest" responses: "200": description: Rule updated. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-plan-changes-rules-id delete: tags: - Mudanças de Plano summary: Delete plan change rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Rule removed. content: application/json: schema: $ref: "#/components/schemas/PlanChangeRuleDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-plan-changes-rules-id /v1/plan_changes/{id}: get: tags: - Mudanças de Plano summary: Get plan change security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Plan change UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Plan change detail. content: application/json: schema: $ref: "#/components/schemas/PlanChangeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-plan-changes-id /v1/subscription_changes/config: get: tags: - Mudanças de Assinatura summary: Get subscription change settings description: Returns the organization settings for subscription item changes — allowed operations (add/remove/quantity change/price swap), proration method per operation, timing (`immediate` or `end_of_period`), refund/credit on remove and portal self-service. If not yet present, defaults are created on first read. security: - bearerAuth: [] responses: "200": description: Organization settings. content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeConfigResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscription-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid put: tags: - Mudanças de Assinatura summary: Update subscription change settings description: Partially updates the settings. Only supplied fields are changed. `refund_on_remove` requires `credit_on_remove` to also be enabled — refund is a variant of credit. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeConfigUpdateRequest" responses: "200": description: Settings updated. content: application/json: schema: $ref: "#/components/schemas/SubscriptionChangeConfigResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: put-subscription-changes-config parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/subscription_item_changes: get: tags: - Mudanças de Assinatura summary: List subscription item changes description: Returns a paginated list of changes applied (or scheduled) to the organization's subscription items — additions, removals, quantity changes and price swaps. Each record includes the operations snapshot, proration amounts in **subcents** (÷10000 → BRL) and pointers to the resulting invoice/credit. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by changes of a specific subscription. required: false name: subscription_id in: query - schema: type: string enum: - pending - scheduled - completed - canceled - failed description: "Filter by status: `pending`, `scheduled`, `completed`, `canceled` or `failed`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of item changes. content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemChangeListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscription-item-changes /v1/subscription_item_changes/{id}: get: tags: - Mudanças de Assinatura summary: Get subscription item change security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Item change UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Item change detail. content: application/json: schema: $ref: "#/components/schemas/SubscriptionItemChangeResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-subscription-item-changes-id /v1/usage: get: tags: - Uso (Metered) summary: List usage records description: Returns metered usage records for a subscription item. Identify the item by `subscription_item_id` **or** by the `product_slug` + `customer_id` combination. Supports date-range filtering and `limit`/`offset` windowing. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription item UUID. Alternative to `product_slug` + `customer_id`. required: false name: subscription_item_id in: query - schema: type: string description: Product slug. Combine with `customer_id`. required: false name: product_slug in: query - schema: type: string description: Customer external identifier. Combine with `product_slug`. required: false name: customer_id in: query - schema: type: string description: Filter start date/time — ISO 8601 format. required: false name: start_date in: query - schema: type: string description: Filter end date/time — ISO 8601 format. required: false name: end_date in: query - schema: type: integer minimum: 1 maximum: 1000 description: "Items per page. Default: `100`. Maximum: `1000`." required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 description: "Pagination offset. Default: `0`." required: false name: offset in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Usage records list with `total_quantity` aggregation in `meta`. content: application/json: schema: $ref: "#/components/schemas/UsageListResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage post: tags: - Uso (Metered) summary: Report usage (metered) description: "Reports usage for metered billing. Accepts a single record **or** a `{ records: [...] }` batch of up to **100** items. Each record must identify the subscription item by `subscription_item_id` **or** by `product_slug` + `customer_id` (recommended for external integrations). The price/product must be configured with `usage_type=metered` and the subscription must be `active` or `trialing`. Use `idempotency_key` to avoid duplicates — when a key was already seen the response is flagged with `duplicate: true`. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/UsageRecordCreateRequest" responses: "200": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageRecordCreateResponse" "207": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageRecordCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/usage/summary: get: tags: - Uso (Metered) summary: Usage summary for the period description: Returns the aggregated usage of a subscription item for the current billing period (or for an arbitrary period via `period_start`/`period_end`). Honors `set` records (which replace) and the sum of subsequent `increment` records. When the price is tiered or per-unit, computes an estimated cost in `estimated_cost_cents` (÷100 → BRL). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Subscription item UUID. Alternative to `product_slug` + `customer_id`. required: false name: subscription_item_id in: query - schema: type: string description: Product slug. Combine with `customer_id`. required: false name: product_slug in: query - schema: type: string description: Customer external identifier. Combine with `product_slug`. required: false name: customer_id in: query - schema: type: string description: "Period start (ISO 8601). Default: subscription `current_period_start`." required: false name: period_start in: query - schema: type: string description: "Period end (ISO 8601). Default: subscription `current_period_end`." required: false name: period_end in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Usage summary, period and estimated cost. content: application/json: schema: $ref: "#/components/schemas/UsageSummaryResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-summary /v1/usage/snapshots/daily: get: tags: - Uso (Metered) summary: List daily usage snapshots description: "Lists the organization's daily usage snapshots. Optional filters: `billing_account_id`, `product_id` and `start_date`/`end_date` window. Supports `limit`/`offset` pagination." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Filter snapshots by billing account UUID. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter snapshots by product UUID. required: false name: product_id in: query - schema: type: string description: Filter start date/time — ISO 8601 format. required: false name: start_date in: query - schema: type: string description: Filter end date/time — ISO 8601 format. required: false name: end_date in: query - schema: type: integer minimum: 1 maximum: 1000 description: "Items per page. Default: `100`. Maximum: `1000`." required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 description: "Pagination offset. Default: `0`." required: false name: offset in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Daily snapshots list with `meta` carrying `total`, `limit`, `offset`. content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-snapshots-daily post: tags: - Uso (Metered) summary: Create daily usage snapshots description: "Creates daily usage snapshots, single record **or** `{ records: [...] }` batch up to **100** items. The natural key (organization, billing account, product, date) is unique: when present, the snapshot is overwritten (`overwritten: true`). Resolve the account by `billing_account_id` **or** `billing_account_public_id` and the product by `product_slug` **or** `product_id` within the supplied `product_group_slug`. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotCreateRequest" responses: "200": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotCreateResponse" "207": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageDailySnapshotCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage-snapshots-daily parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/usage/snapshots/monthly: get: tags: - Uso (Metered) summary: List monthly usage snapshots description: "Lists the organization's monthly usage snapshots. Optional filters: `billing_account_id`, `product_id` and `start_month`/`end_month` window. Supports `limit`/`offset` pagination." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Filter snapshots by billing account UUID. required: false name: billing_account_id in: query - schema: type: string format: uuid description: Filter snapshots by product UUID. required: false name: product_id in: query - schema: type: string description: Filter start month in `YYYY-MM-DD` format (first day of the month). required: false name: start_month in: query - schema: type: string description: Filter end month in `YYYY-MM-DD` format (first day of the month). required: false name: end_month in: query - schema: type: integer minimum: 1 maximum: 1000 description: "Items per page. Default: `100`. Maximum: `1000`." required: false name: limit in: query - schema: type: - integer - "null" minimum: 0 description: "Pagination offset. Default: `0`." required: false name: offset in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Monthly snapshots list with `meta` carrying `total`, `limit`, `offset`. content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-usage-snapshots-monthly post: tags: - Uso (Metered) summary: Create monthly usage snapshots description: "Creates monthly usage snapshots, single record **or** `{ records: [...] }` batch up to **100** items. The natural key (organization, billing account, product, month) is unique: when present, the snapshot is overwritten (`overwritten: true`). Resolve the account by `billing_account_id` **or** `billing_account_public_id` and the product by `product_slug` **or** `product_id` within `product_group_slug`. Batches with partial failures return **207 Multi-Status**." security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotCreateRequest" responses: "200": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotCreateResponse" "207": description: Processing result (single record or batch). content: application/json: schema: $ref: "#/components/schemas/UsageMonthlySnapshotCreateResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-usage-snapshots-monthly parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/tax_rules: get: tags: - Regras Tributárias summary: List tax rules description: Returns a paginated list of the current organization's tax rules. Use the `scope`, `company_id`, `service_item_id`, `billing_account_id` and `is_active` filters to narrow the result. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - global - organization - company - service - customer - municipality description: "Filter by scope: `global`, `organization`, `company`, `service`, `customer` or `municipality`." required: false name: scope in: query - schema: type: string format: uuid description: Filter by rules of a specific company. required: false name: company_id in: query - schema: type: string format: uuid description: Filter by rules of a specific service item. required: false name: service_item_id in: query - schema: type: string format: uuid description: Filter by rules of a specific billing account. required: false name: billing_account_id in: query - schema: type: string enum: - "true" - "false" description: When `true`, returns only active rules; when `false`, only inactive ones. required: false name: is_active in: query - schema: type: string description: Text search across `name` and `description`. required: false name: search in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of tax rules. content: application/json: schema: $ref: "#/components/schemas/TaxRuleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-rules post: tags: - Regras Tributárias summary: Create tax rule description: Creates a new tax rule along with its items (per-tax rates). The `scope` defines the applicability level and `priority` defines precedence — higher priority overrides lower. At least one entry in `items` is required. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxRuleCreateRequest" responses: "201": description: Tax rule created. content: application/json: schema: $ref: "#/components/schemas/TaxRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-tax-rules parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/tax_rules/{id}: get: tags: - Regras Tributárias summary: Get tax rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Tax rule detail. content: application/json: schema: $ref: "#/components/schemas/TaxRuleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-rules-id patch: tags: - Regras Tributárias summary: Update tax rule description: Updates editable fields of the rule. When `items` is provided, it **fully replaces** the existing items list. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxRuleUpdateRequest" responses: "200": description: Tax rule updated. content: application/json: schema: $ref: "#/components/schemas/TaxRuleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-tax-rules-id delete: tags: - Regras Tributárias summary: Delete tax rule security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax rule UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Tax rule removed. content: application/json: schema: $ref: "#/components/schemas/TaxRuleDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-tax-rules-id /v1/tax_periods: get: tags: - Períodos Tributários summary: List tax periods description: Returns a paginated list of the organization tax periods (monthly or quarterly). Supports filtering by company, period type, year and status. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by issuing company. required: false name: company_id in: query - schema: type: string enum: - monthly - quarterly description: "Filter by period type: `monthly` or `quarterly`." required: false name: period_type in: query - schema: type: string pattern: ^\d+$ description: "Filter by reference year (e.g.: `2026`)." required: false name: year in: query - schema: type: string enum: - open - calculated - closed description: "Filter by status: `open`, `calculated` or `closed`." required: false name: status in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of tax periods. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-periods post: tags: - Períodos Tributários summary: Process monthly tax period description: Creates (or retrieves) the given monthly tax period and computes the taxes due (ISS, PIS, COFINS, IRPJ, CSLL, CBS, IBS) based on issued NFes and pending compensation. When `company_id` is omitted, uses the organization default company. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxPeriodCreateRequest" responses: "201": description: Tax period processed. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-tax-periods parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/tax_periods/{id}: get: tags: - Períodos Tributários summary: Get tax period security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax period UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Tax period detail. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-tax-periods-id patch: tags: - Períodos Tributários summary: Run action on tax period description: "Applies an action to the period: `recalculate` recomputes taxes (monthly periods only), `close` closes the period and `reopen` reopens it." security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax period UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/TaxPeriodUpdateRequest" responses: "200": description: Tax period updated. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-tax-periods-id delete: tags: - Períodos Tributários summary: Delete tax period description: Permanently removes the tax period. Use with caution — closed periods usually should not be deleted. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Tax period UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Tax period removed. content: application/json: schema: $ref: "#/components/schemas/TaxPeriodDeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-tax-periods-id /v1/withholdings: get: tags: - Retenções summary: List withholdings description: Returns a paginated list of the current organization's tax withholdings. Supports filters by tax type, status, withholder, invoice, NF-e and competence period. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string enum: - iss - pis - cofins - csll - irpj - irrf - csrf - inss - cbs - ibs description: "Filter by tax type: `iss`, `pis`, `cofins`, `csll`, `irpj`, `irrf`, `csrf`, `inss`, `cbs` or `ibs`." required: false name: taxType in: query - schema: type: string enum: - retained - compensated - partially_compensated description: "Filter by status: `retained`, `compensated` or `partially_compensated`." required: false name: status in: query - schema: type: string format: uuid description: Filter by withholdings of a specific withholder (billing account). required: false name: withholderId in: query - schema: type: string format: uuid description: Filter by withholdings associated with an invoice. required: false name: invoiceId in: query - schema: type: string format: uuid description: Filter by withholdings associated with an NF-e. required: false name: nfeId in: query - schema: type: integer minimum: 2000 maximum: 3000 description: Filter by competence year (2000–3000). required: false name: competenceYear in: query - schema: type: integer minimum: 1 maximum: 12 description: Filter by competence month (1–12). required: false name: competenceMonth in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of withholdings. content: application/json: schema: $ref: "#/components/schemas/WithholdingListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-withholdings /v1/withholdings/convert-to-credits: post: tags: - Retenções summary: Convert pending withholdings to credits (bulk) description: Converts all of the organization's pending withholdings — optionally narrowed by `tax_type` and/or competence period — into credits. Returns the list of generated credits, the total count converted and the total amount in cents. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingBulkConvertRequest" responses: "200": description: Batch of withholdings converted to credits. content: application/json: schema: $ref: "#/components/schemas/WithholdingBulkConvertResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-withholdings-convert-to-credits parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/withholdings/{id}: get: tags: - Retenções summary: Get withholding security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Withholding UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Withholding detail. content: application/json: schema: $ref: "#/components/schemas/WithholdingResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-withholdings-id /v1/withholdings/{id}/convert-to-credit: post: tags: - Retenções summary: Convert withholding to credit description: Converts a withholding (fully or partially) into a credit on the billing account derived from the associated invoice — or, when absent, from the withholder itself. When `amount_cents` is omitted, converts the withholding's pending balance. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Withholding UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/WithholdingConvertToCreditRequest" responses: "201": description: Credit generated from the withholding. content: application/json: schema: $ref: "#/components/schemas/WithholdingConvertToCreditResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-withholdings-id-convert-to-credit /v1/service_items: get: tags: - Itens de Serviço (LC 116) summary: List service items description: Returns a paginated list of the current organization's service items (LC 116/2003 catalog). Use the filters to narrow by company, LC 116 code, NBS, tax classification, operation indicator, or Simples annex. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string format: uuid description: Filter by UUID of the issuing company associated with the item. required: false name: company_id in: query - schema: type: string description: Free-text search across `name`, `internal_code` and `description`. required: false name: search in: query - schema: type: string enum: - "true" - "false" description: "Filter by status: `true` returns only active items; `false`, only inactive." required: false name: is_active in: query - schema: type: string description: Filter by LC 116/2003 code (e.g. `01.05`). required: false name: lc116_code in: query - schema: type: string description: Filter by NBS code (Brazilian Service Nomenclature). required: false name: nbs_code in: query - schema: type: string description: Filter by IBS/CBS tax classification (`c_class_trib`). required: false name: c_class_trib in: query - schema: type: string description: Filter by Operation Indicator (`indop_code`) used in SNNFSE NFS-e. required: false name: indop_code in: query - schema: type: string enum: - annex_iii - annex_iv - annex_v description: "Filter by applicable Simples Nacional annex: `annex_iii`, `annex_iv` or `annex_v`." required: false name: simples_annex in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of service items. content: application/json: schema: $ref: "#/components/schemas/ServiceItemListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-service-items post: tags: - Itens de Serviço (LC 116) summary: Create service item description: Creates a service item in the LC 116/2003 catalog. `internal_code` is the internal identifier and `lc116_code` must follow the Complementary Law 116/2003 catalog (e.g. `01.05`). When `company_id` is provided, the company must belong to the authenticated organization. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/ServiceItemCreateRequest" responses: "201": description: Service item created. content: application/json: schema: $ref: "#/components/schemas/ServiceItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-service-items parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/service_items/{id}: get: tags: - Itens de Serviço (LC 116) summary: Get service item security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Service item UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Service item detail. content: application/json: schema: $ref: "#/components/schemas/ServiceItemResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-service-items-id patch: tags: - Itens de Serviço (LC 116) summary: Update service item description: Updates editable fields of the service item. `internal_code` is immutable after creation. Use `is_active=false` to deactivate the item without deleting it. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Service item UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/ServiceItemUpdateRequest" responses: "200": description: Service item updated. content: application/json: schema: $ref: "#/components/schemas/ServiceItemResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-service-items-id delete: tags: - Itens de Serviço (LC 116) summary: Delete service item description: Deletes the service item permanently. To preserve history on already-issued invoices or NFS-e, prefer deactivating the item (`PATCH` with `is_active=false`). security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Service item UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Service item deleted. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-service-items-id /v1/dashboard_users: get: tags: - Administração da Conta summary: List dashboard users description: Returns a paginated list of dashboard users (team members) for the current organization. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or email. required: false name: search in: query - schema: type: string enum: - all - active - pending_invitation - suspended description: "Filter by status: `all` (default), `active`, `pending_invitation` or `suspended`." required: false name: status in: query - schema: type: string description: Filter by users that have the given role (role slug). required: false name: role in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of dashboard users. content: application/json: schema: $ref: "#/components/schemas/DashboardUserListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users post: tags: - Administração da Conta summary: Invite dashboard user description: Invites a new member to the organization team. `email` and at least one role in `role_ids` are required. The user receives an email invite and starts with `pending_invitation` status. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserCreateRequest" responses: "201": description: User invited. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-dashboard-users parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/dashboard_users/{id}: get: tags: - Administração da Conta summary: Get dashboard user security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Dashboard user detail. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-dashboard-users-id patch: tags: - Administração da Conta summary: Update dashboard user description: Updates the user’s name, picture, status, permissions and/or roles. Only the fields sent are changed. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/DashboardUserUpdateRequest" responses: "200": description: User updated. content: application/json: schema: $ref: "#/components/schemas/DashboardUserResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-dashboard-users-id delete: tags: - Administração da Conta summary: Remove dashboard user description: Removes the dashboard user from the organization. Irreversible — the user must be invited again to regain access. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Dashboard user UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: User removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-dashboard-users-id /v1/team_roles: get: tags: - Administração da Conta summary: List team roles description: Returns the paginated list of roles configured for the organization team. Includes both system roles (`is_system = true`) and custom roles. security: - bearerAuth: [] parameters: - schema: type: integer minimum: 1 description: "Page (starts at 1). Default: `1`." example: 1 required: false name: page in: query - schema: type: integer minimum: 1 maximum: 100 description: "Items per page. Default: `20`. Maximum: `100`." example: 20 required: false name: per_page in: query - schema: type: string description: Sort field. Default depends on the resource. required: false name: sort_by in: query - schema: type: string enum: - asc - desc description: "Sort direction. Default: `desc`." required: false name: sort_order in: query - schema: type: string description: Text search by name or slug. required: false name: search in: query - schema: type: - boolean - "null" description: Filter by active (`true`) or inactive (`false`) roles. required: false name: is_active in: query - schema: type: - boolean - "null" description: Filter by system (`true`) or custom (`false`) roles. required: false name: is_system in: query - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Paginated list of roles. content: application/json: schema: $ref: "#/components/schemas/TeamRoleListResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles post: tags: - Administração da Conta summary: Create custom role description: Creates a custom role. `slug` must start with a lowercase letter and contain only lowercase letters, digits and `_`. security: - bearerAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleCreateRequest" responses: "201": description: Role created. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: post-team-roles parameters: - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid /v1/team_roles/{id}: get: tags: - Administração da Conta summary: Get role security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Role detail. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: get-team-roles-id patch: tags: - Administração da Conta summary: Update role description: Updates the role fields. Only the fields sent are changed. System roles have additional restrictions. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid requestBody: content: application/json: schema: $ref: "#/components/schemas/TeamRoleUpdateRequest" responses: "200": description: Role updated. content: application/json: schema: $ref: "#/components/schemas/TeamRoleResponse" "400": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "422": description: Request body failed validation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: patch-team-roles-id delete: tags: - Administração da Conta summary: Remove role description: Soft-deletes the role. System roles (`is_system = true`) cannot be removed. security: - bearerAuth: [] parameters: - schema: type: string format: uuid description: Role UUID. required: true name: id in: path - name: User-Agent in: header required: true description: Integrator identification. Include a name and contact email — e.g. `Kevin Mitnick `. Used for support and audit. schema: type: string example: Kevin Mitnick example: Kevin Mitnick - name: X-Idempotency-Key in: header required: false description: Unique key (UUID v4 recommended) to safely retry the same request. Requests sharing the key within 24h return the original result. schema: type: string format: uuid responses: "200": description: Role removed. content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" "401": description: Missing or invalid bearer token. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "403": description: Token is valid but lacks permission for this operation. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "404": description: Resource not found in the current organization. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "429": description: Rate limit exceeded. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ApiV1Error" operationId: delete-team-roles-id webhooks: {}