> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # List deals > Lists the deals of your organization, newest first by default. Each deal comes with its progress: `installmentInfo` (paid invoices over installments), `nextDueDate` (the earliest invoice still to be paid) and `totalAmount` (what its invoices are expected to charge in total). Filter by status, payer document (`debitPartyDocuments`, several at once), payer organization (`debitPartyOrgIds`, several at once: it matches the organization of the payer's Portão 3 wallet, so a payer with no wallet is found by its document instead), charge type, number of installments, a text in the description, the start and end dates, and the creation date (`startDate`/`endDate`). Dates are read in UTC: a date without a time is its midnight. Sort with `order` and `orderBy`, and page with `limit` + `next`: pass the `next` of one page to get the following one — the last page answers `next: null`. Any member of the organization, or an admin of the realm, can list them. ## OpenAPI ````yaml /api-reference/billing.openapi.json get /realms/{realmId}/organizations/{organizationId}/deals openapi: 3.0.3 info: title: Billing version: 1.0.0 description: >- Portão 3 billing API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Full billing surface — contracts, deals, invoices, statements, payment links, checkout and NFSe orchestration. (The product/supplier catalog moved to registry.) Confidence tiers: generated:typed=74 copied:manual=0 unknown=5. servers: - url: https://api.billing.v2.portao3.com.br/ description: production - url: https://api.billing.dev.3pers.com.br/ description: development security: [] tags: - name: Contracts - name: Deals - name: Invoices - name: Invoice Entries - name: Invoice Statements - name: NFSe Configuration - name: Payment Links paths: /realms/{realmId}/organizations/{organizationId}/deals: get: tags: - Deals summary: List deals description: Lists the deals of your organization, newest first by default. operationId: getRealmsByRealmIdOrganizationsByOrganizationIdDeals parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of your organization: the one whose deals you list. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: status in: query required: false description: |- Only deals in these statuses. --- Example (comma-separated list): `?status=OPEN,TERMINATED` schema: type: array items: type: string enum: - OPEN - CANCELED - TERMINATED - EXPIRED - REVOKED style: form explode: false - name: debitPartyDocuments in: query required: false description: >- Only deals whose debit party has one of these documents (exact match). --- Example (comma-separated list): `?debitPartyDocuments=11144477735,39053344705` schema: type: array items: type: string style: form explode: false - name: debitPartyOrgIds in: query required: false description: >- Only deals whose payer (the debit party) pays from a Portão 3 wallet of one of these organizations. It matches the organization of the payer's wallet, so a payer with no wallet (a customer who pays by boleto or PIX, for example) is not found by it: filter by `debitPartyDocuments` instead. Format: `UUID` --- Example: `?debitPartyOrgIds=5e0a1c2b-3d4f-4a6b-8c9d-0e1f2a3b4c5d` schema: type: array items: type: string format: uuid style: form explode: false - name: chargeType in: query required: false description: Only deals with this charge type. schema: type: string enum: - SINGLE - RECURRENT - SUBSCRIPTION example: RECURRENT - name: numberOfInstallments in: query required: false description: Only deals with exactly this number of installments. schema: type: integer minimum: 1 example: 12 - name: description in: query required: false description: Only deals whose description contains this text (case-insensitive). schema: type: string maxLength: 250 example: Gold plan - name: startAt in: query required: false description: >- Only deals that start on or after this date (ISO 8601 date or date-time). schema: anyOf: - type: string format: date - type: string format: date-time example: '2026-01-01T00:00:00.000Z' - name: endAt in: query required: false description: >- Only deals that end on or before this date (ISO 8601 date or date-time). Combines with `endAtFrom` and `endAtTo`: every bound you send applies. schema: anyOf: - type: string format: date - type: string format: date-time example: '2026-12-31T00:00:00.000Z' - name: endAtFrom in: query required: false description: >- Only deals that end on or after this date, inclusive (ISO 8601 date or date-time). Send `endAtTo` as well for a closed range. schema: anyOf: - type: string format: date - type: string format: date-time example: '2026-02-01T00:00:00.000Z' - name: endAtTo in: query required: false description: >- Only deals that end on or before this date, inclusive (ISO 8601 date or date-time). Send `endAtFrom` as well for a closed range. schema: anyOf: - type: string format: date - type: string format: date-time example: '2026-03-01T00:00:00.000Z' - name: startDate in: query required: false description: >- Only deals created on or after this date, inclusive (ISO 8601 date or date-time). Send `endDate` as well for a closed window. schema: anyOf: - type: string format: date - type: string format: date-time example: '2026-04-01T00:00:00.000Z' - name: endDate in: query required: false description: >- Only deals created on or before this date, inclusive (ISO 8601 date or date-time). Send `startDate` as well for a closed window. schema: anyOf: - type: string format: date - type: string format: date-time example: '2026-05-01T00:00:00.000Z' - name: order in: query required: false description: Sort direction. Case-insensitive. schema: default: DESC type: string enum: - ASC - DESC example: DESC - name: orderBy in: query required: false description: Field to sort the deals by. schema: default: createdAt type: string enum: - createdAt - description - startAt example: createdAt - name: limit in: query required: false description: Page size. schema: default: 15 type: integer minimum: 1 maximum: 1000 example: 15 - name: next in: query required: false description: >- Cursor returned as `next` by the previous page; it must be valid base64. Omit it for the first page. Use it with the same filters and order: a cursor that no longer matches a deal returns the first page. schema: type: string maxLength: 128 pattern: ^[A-Za-z0-9+/]+={0,2}$ example: NjhkM2YxYTJjNGI1ZTZmN2E4YjljMGQx responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string description: ID of the deal. example: 9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d format: uuid description: type: string description: >- Description of the deal. It names the invoice of a `SINGLE` deal, and the invoices created at the start when `settings.invoiceNameType` is `DEAL_DESCRIPTION`. example: Mensalidade Plano Pro realm: type: string description: >- ID of the realm of the organization that issues the deal. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the organization that issues the deal. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid contract: type: string description: >- ID of the contract the deal belongs to. Absent on a deal created without a contract. example: 7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d format: uuid chargeType: type: string enum: - SINGLE - RECURRENT - SUBSCRIPTION description: >- `SINGLE`: one invoice. `RECURRENT`: monthly invoices up to `numberOfInstallments` months after `firstChargeDate`. `SUBSCRIPTION`: one invoice a month until the deal ends, is terminated or is canceled. After the first, each invoice is created when the previous one closes — unless the deal created them all at the start (`settings.createAllInvoicesOnStart`) — and only while the deal has a `RECURRENT` product. example: RECURRENT status: type: string enum: - OPEN - CANCELED - TERMINATED - EXPIRED - REVOKED description: >- `OPEN`: active — it creates invoices and can be changed or canceled. `CANCELED`: canceled through the API. `TERMINATED`: it reached its end date (checked daily), its end date was moved to today or earlier, or its contract was terminated. `EXPIRED`: a PIX Automático or recurring PIX deal whose payer never authorized the payment, a few days after the first due date. `REVOKED`: the payer revoked the PIX Automático authorization. example: OPEN firstChargeDate: type: string description: >- Due date of the first invoice. The later invoices are due on the same day of each following month. example: '2026-11-10T00:00:00.000Z' format: date-time numberOfInstallments: type: number description: >- With `settings.createAllInvoicesOnStart`, how many invoices were created at the start. Otherwise it sets when a `RECURRENT` deal ends: `numberOfInstallments` months after `firstChargeDate`. `1` unless it was sent. example: 12 settings: type: object properties: createAllInvoicesOnStart: type: boolean description: >- `true`: every invoice of the deal was created with the deal, each due one month after the previous one. Otherwise the deal creates its invoices one at a time, the next one when the previous one closes. example: false disableOpenStatus: type: boolean description: >- `true`: each invoice is closed — and its payment issued — as soon as it is created. Otherwise an invoice created one at a time stays open, gathering charges, until 5 days before its due date; of the invoices created at the start, the first stays open until its due date and the others were created closed. example: false invoiceNameType: type: string enum: - DEAL_DESCRIPTION description: >- `DEAL_DESCRIPTION`: the invoices created at the start are named after the deal's description — as ` - /` on a `RECURRENT` deal. Absent, and for invoices created one at a time: they are named after their month (`Nov/26`), except a `SINGLE` deal's invoice, which takes the description. example: DEAL_DESCRIPTION paymentLinkId: type: string description: >- ID of the payment link the deal was created from. Only on deals created by a payment-link checkout. example: 5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f format: uuid callBackUrlForPaymentProvider: type: object properties: success: type: string description: After a successful payment. example: >- https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/success pending: type: string description: While the payment is pending. example: >- https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/pending error: type: string description: After a failed payment. example: >- https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/error description: >- The pages the payer returns to. Only on deals created by a payment-link checkout. description: How the deal creates its invoices. startAt: type: string description: >- When the deal starts: when it was created, unless it was changed with `PUT`. example: '2026-10-26T13:00:00.000Z' format: date-time endAt: type: string nullable: true description: >- When the deal ends. `SINGLE`: when it was created. `RECURRENT`: `numberOfInstallments` months after `firstChargeDate`. `SUBSCRIPTION`: the end date you set, or `null` for no end. Once the end date has passed, a daily routine terminates an `OPEN` deal. example: '2027-11-10T00:00:00.000Z' format: date-time products: type: array items: type: object properties: id: type: string description: ID of the product inside the deal. example: 3c1d9a7e-2b4f-4e8a-9c6d-5f7e8a9b0c1d format: uuid identifier: type: string description: Your label for the product. example: PLANO-PRO description: type: string description: Description of the product. example: Plano Pro mensal price: type: number description: >- Price in centavos (`15000` is R$ 150,00), charged on each invoice the product appears on. example: 15000 type: type: string enum: - RECURRENT - ONE_TIME - ON_EVENT description: >- Which invoices charge the product. `RECURRENT`: every invoice of the deal. `ONE_TIME`: the first invoice only — or every invoice, when the deal creates all its invoices at the start (`settings.createAllInvoicesOnStart`). `ON_EVENT`: no invoice charges it automatically. example: RECURRENT chargeMethod: type: string enum: - INSTANT - LATER description: >- When the product is charged. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is debited from the payer's Portão 3 wallet as soon as it is added (only on `P2P` deals). example: LATER idProduct: type: string description: >- ID of the product in your product catalog, when the deal was created from one. example: 8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f required: - id - identifier - price - type - chargeMethod description: A product the deal charges for. description: What the deal charges for. paymentMethods: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX_AUTOMATIC - PIX - P2P example: BANK_SLIP description: >- How the invoices are paid: one of `BANK_SLIP` (boleto), `PIX` (a PIX charge), `P2P` (a debit from the payer's Portão 3 wallet), `PIX_AUTOMATIC` (PIX Automático) or `PIX_INITIATION` (recurring scheduled PIX). --- Example: `["BANK_SLIP"]` secondaryPaymentMethods: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX_AUTOMATIC - PIX - P2P description: >- Other ways the payer can pay the invoices: `PIX` and/or `BANK_SLIP`. Empty when there are none. --- Example: `[]` example: [] creditParties: type: array items: type: object properties: document: type: string description: >- CPF or CNPJ of the receiver, digits only (an alphanumeric CNPJ in upper case). example: '12345678000195' name: type: string description: Name of the receiver. example: Empresa Exemplo Ltda email: type: string description: E-mail of the receiver. example: financeiro@empresaexemplo.com.br unit: type: string enum: - PERCENTAGE description: 'Always `PERCENTAGE`: `amount` is a percentage.' example: PERCENTAGE amount: type: number description: >- The receiver's share of every payment, in percent. The shares of all receivers add up to 100; the deal's own organization keeps what is not transferred to the others. example: 100 account: type: object properties: bank: type: string enum: - P3 description: 'Always `P3`: a Portão 3 account.' example: P3 type: type: string enum: - WALLET description: Always `WALLET`. example: WALLET identifier: type: object properties: realm: type: string description: ID of the wallet owner's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the wallet owner's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the organization's account. example: 6711b4c0d8e1a30012b7c9f1 wallet: type: string description: >- ID of the wallet, or `default` for the account's default wallet. example: default required: - realm - organization - account - wallet description: Which wallet. required: - bank - type - identifier description: The wallet the share is paid into. required: - document - unit - amount - account description: >- Who receives the money the deal collects, and their share of it. description: Who receives the money and each one's share. debitParties: type: array items: type: object properties: document: type: string description: >- CPF or CNPJ of the payer, digits only (an alphanumeric CNPJ in upper case). example: '52998224725' name: type: string description: Name of the payer. example: Maria da Silva email: type: string description: E-mail of the payer. example: maria.silva@example.com phone: type: string description: >- Phone of the payer, in E.164 format (`+`, the country code and the number, digits only). Absent when the deal has none. example: '+5511987654321' unit: type: string enum: - PERCENTAGE description: 'Always `PERCENTAGE`: `amount` is a percentage.' example: PERCENTAGE amount: type: number description: >- The payer's share of each invoice, in percent: `100`, since a deal has one payer. example: 100 account: type: object properties: bank: type: string enum: - P3 description: 'Always `P3`: a Portão 3 account.' example: P3 type: type: string enum: - WALLET description: Always `WALLET`. example: WALLET identifier: type: object properties: realm: type: string description: ID of the wallet owner's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the wallet owner's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the organization's account. example: 6711b4c0d8e1a30012b7c9f1 wallet: type: string description: >- ID of the wallet, or `default` for the account's default wallet. example: default required: - realm - organization - account - wallet description: Which wallet. required: - bank - type - identifier description: >- The payer's Portão 3 wallet the invoices are debited from. Present on `P2P` deals. address: type: object properties: street: type: string description: Street. example: Avenida Paulista number: type: string description: Number. example: '1000' complement: type: string description: Complement. example: Sala 12 neighborhood: type: string description: Neighborhood. example: Bela Vista city: type: string description: City. example: São Paulo state: type: string description: State, as its two-letter code. example: SP postalCode: type: string description: Postal code (CEP), as `NNNNN-NNN`. example: 01310-100 required: - street - number - neighborhood - city - state - postalCode description: >- The payer's billing address. Present on boleto and PIX deals. required: - document - name - unit - amount description: Who pays the deal. description: Who pays. closingAt: type: string description: >- When each invoice created one at a time closes, as a cron expression `0 0 * *`: 5 days before `firstChargeDate`'s day, or that same day when `settings.disableOpenStatus` is `true`. Invoices created at the start close on their own due date. example: 0 0 5 * * dueAt: type: string description: >- When each invoice is due, as a cron expression `0 0 * *`: `firstChargeDate`'s day. example: 0 0 10 * * createdBy: type: string description: ID of who created the deal. example: 5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b updatedBy: type: string description: ID of who last changed the deal. example: 5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b fine: description: >- Fine for late payment. `null` when the deal has none. type: object properties: amountType: type: string enum: - FIXED_VALUE - PERCENT description: >- `PERCENT`: `amount` is a percentage of the invoice. `FIXED_VALUE`: `amount` is in centavos. example: PERCENT amount: type: number description: >- The fine: a percentage (`2` is 2%) or an amount in centavos, per `amountType`. example: 2 required: - amountType - amount nullable: true interest: description: >- Interest for late payment. `null` when the deal has none. type: object properties: amountType: type: string enum: - AMOUNT_CALENDAR_DAYS - AMOUNT_WORKING_DAYS - PERCENT_POINT_PER_DAY_CALENDAR_DAYS - PERCENT_POINT_PER_DAY_WORKING_DAYS description: >- `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS`: `amount` is a percentage — per calendar or working day on a PIX charge, but per MONTH on a boleto. `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS`: `amount` is in centavos per calendar or working day. example: PERCENT_POINT_PER_DAY_CALENDAR_DAYS amount: type: number description: >- The interest: a percentage or an amount in centavos, per `amountType`. example: 0.1 required: - amountType - amount nullable: true discount: description: >- Discount for early payment. `null` when the deal has none. type: object properties: amountType: type: string enum: - AMOUNT_PER_ANTECIPATION - PERCENT_PER_ANTECIPATION description: >- `PERCENT_PER_ANTECIPATION`: `amount` is a percentage of the invoice. `AMOUNT_PER_ANTECIPATION`: `amount` is in centavos. example: AMOUNT_PER_ANTECIPATION amount: type: number description: >- The discount: a percentage or an amount in centavos, per `amountType`. example: 500 required: - amountType - amount nullable: true createdAt: type: string description: When the deal was created. example: '2026-10-26T13:00:00.000Z' format: date-time updatedAt: type: string description: When the deal last changed. example: '2026-10-26T13:00:00.000Z' format: date-time paymentUrl: type: string description: >- Link where the payer authorizes the payments. Only on `PIX_AUTOMATIC` and `PIX_INITIATION` deals. example: https://pix.example.com/authorize/9b2f7c1e paymentLinkValidity: type: string nullable: true description: >- Until when `paymentUrl` can be used. Only on `PIX_AUTOMATIC` deals; `null` on `PIX_INITIATION` deals. example: '2026-11-09T23:59:59.000Z' format: date-time installmentInfo: type: string description: >- Paid invoices over installments, as `/`. example: 3/12 nextDueDate: type: string description: >- Due date of the earliest invoice that is neither paid nor canceled — it may be in the past. Absent when there is none. example: '2027-02-10T00:00:00.000Z' format: date-time totalAmount: type: number description: >- What the deal's invoices are expected to charge in total, in centavos: the `RECURRENT` products on every installment plus the `ONE_TIME` products once (on every installment when `settings.createAllInvoicesOnStart` is `true`). `ON_EVENT` products are not counted. example: 180000 required: - chargeType - closingAt - createdAt - createdBy - creditParties - debitParties - dueAt - endAt - firstChargeDate - id - installmentInfo - organization - paymentMethods - products - realm - secondaryPaymentMethods - startAt - status - totalAmount - updatedAt - updatedBy description: A deal of a list, with its progress. description: The deals of this page. next: type: string nullable: true description: >- Cursor for the next page: pass it as `next` to get it. `null` on the last page. example: NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy required: - items - next description: A page of deals. '403': description: >- `INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - INSUFFICIENT_PERMISSIONS description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: INSUFFICIENT_PERMISSIONS origin: BILLING message: insufficient permissions '422': description: >- `BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `status`, a `limit` out of range or a `next` that is not valid base64; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: BILLING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: chargeType message: >- Invalid option: expected one of "SINGLE"|"RECURRENT"|"SUBSCRIPTION" code: CHARGETYPE_ONE_OF ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.