> ## 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. # Get a deal > Returns one deal of your organization, with its customer, totals and invoices. `customer` is the payer as a customer of your organization, found by the payer's document — `null` when none has it, or when it could not be looked up in time; the deal is answered either way. `financialValues` adds up the deal's invoices so far, and `invoices` lists them by due date, each with the status the Portão 3 app shows (`displayStatus`). Any member of the organization, or an admin of the realm, can read it. ## OpenAPI ````yaml /api-reference/billing.openapi.json get /realms/{realmId}/organizations/{organizationId}/deals/{dealId} 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/{dealId}: get: tags: - Deals summary: Get a deal description: >- Returns one deal of your organization, with its customer, totals and invoices. operationId: getRealmsByRealmIdOrganizationsByOrganizationIdDealsByDealId 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 that issues the deal. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: dealId in: path required: true description: |- ID of the deal. Format: `UUID` schema: type: string format: uuid example: 9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d responses: '200': description: Successful response content: application/json: schema: 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 customer: description: >- The payer as a customer of your organization, found by the payer's document. `null` when no customer has that document, or when it could not be looked up in time. type: object properties: id: type: string description: ID of the customer. example: 2a4c6e8f-1b3d-4f5a-8c7e-9d0b1a2c3e4f format: uuid name: type: string description: Name of the customer. example: Maria da Silva required: - id - name nullable: true financialValues: type: object properties: total: type: integer description: >- Sum of the amounts of all the deal's invoices so far — canceled ones included — in centavos, rounded to a whole number. example: 45000 totalPaid: type: integer description: >- Sum of the amounts of the paid invoices, in centavos, rounded to a whole number. example: 30000 outstandingBalance: type: integer description: >- What is still to be paid: the unrounded total minus the unrounded paid amount, in centavos, rounded to a whole number — so it can differ by 1 from `total` minus `totalPaid`. example: 15000 required: - total - totalPaid - outstandingBalance description: The deal's totals. invoices: type: array items: type: object properties: id: type: string description: ID of the invoice. example: 0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a format: uuid name: type: string description: Name of the invoice. example: Mensalidade Plano Pro - 3/12 dueAt: type: string description: When the invoice is due. example: '2027-01-10T00:00:00.000Z' format: date-time status: type: string enum: - OPEN - CLOSED - PAID - CANCELED description: >- `OPEN`: gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`. example: CLOSED paymentStatus: type: string enum: - NONE - PENDING - PROCESSING - PROCESSED - FAILED description: Progress of the invoice's payment. example: PENDING amount: type: number description: Amount of the invoice, in centavos. example: 15000 displayStatus: type: string enum: - OPEN - READY_TO_PAYMENT - OVERDUE - PAID - CANCELED - READY_TO_SCHEDULE - SCHEDULED - PAYMENT_FAILED - REVOKED - EXPIRED description: >- The invoice's status as the Portão 3 app shows it, computed when you read it — the same rule as every invoice endpoint. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, less than a day past its due date. `OVERDUE`: issued and more than a day past its due date (PIX Automático: after the 5-day retry window). `PAID`. `CANCELED`. PIX Automático only: `READY_TO_SCHEDULE` (the payment is not scheduled with the payer's bank yet), `SCHEDULED` (it will be charged on the due date), `PAYMENT_FAILED` (the due-date charge failed and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization), `EXPIRED` (canceled because the payer never authorized it). example: READY_TO_PAYMENT required: - id - dueAt - status - amount - displayStatus description: An invoice of the deal. description: The deal's invoices so far, every status, by due date. required: - chargeType - closingAt - createdAt - createdBy - creditParties - customer - debitParties - dueAt - endAt - financialValues - firstChargeDate - id - invoices - organization - paymentMethods - products - realm - secondaryPaymentMethods - startAt - status - updatedAt - updatedBy description: A deal, with its customer, totals and invoices. '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 '404': description: '`DEAL_NOT_FOUND` — The organization has no deal with this ID.' 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: - DEAL_NOT_FOUND 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: DEAL_NOT_FOUND origin: BILLING message: deal not found '422': description: >- `BAD_REQUEST` — A path parameter is not a valid ID; `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: dealId message: Invalid UUID code: DEALID_UUID ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.