{ "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" } ], "x-p3-surface": "public", "tags": [ { "name": "Contracts" }, { "name": "Deals" }, { "name": "Invoices" }, { "name": "Invoice Entries" }, { "name": "Invoice Statements" }, { "name": "NFSe Configuration" }, { "name": "Payment Links" } ], "components": {}, "paths": { "/realms/{realmId}/organizations/{organizationId}/contracts": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdContracts", "summary": "Deprecated — List contracts", "tags": [ "Contracts" ], "x-p3-sidebar-order": 1, "description": "Deprecated: use `GET .../deals`, filtering by `debitPartyOrgIds` or `debitPartyDocuments`; contracts are being removed.", "x-mint": { "content": "Lists the contracts of your organization. To find the deals of one payer, filter `GET .../deals` by `debitPartyOrgIds` (the organization of the payer's Portão 3 wallet) or, for a payer with no wallet, by `debitPartyDocuments` (its CPF or CNPJ)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Undocumented response (no code type, no existing spec)." } }, "x-p3-confidence": { "response": "unknown" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdContracts", "summary": "Deprecated — Create a contract", "tags": [ "Contracts" ], "x-p3-sidebar-order": 2, "description": "Deprecated: contracts are being removed; there is no replacement.", "x-mint": { "content": "Creates a contract: an agreement between your organization and its payers that groups deals. Creating deals does not need one — `POST .../deals` creates a deal for your organization alone." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Undocumented response (no code type, no existing spec)." } }, "x-p3-confidence": { "response": "unknown" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractId", "summary": "Deprecated — Get a contract", "tags": [ "Contracts" ], "x-p3-sidebar-order": 3, "description": "Deprecated: use `GET .../deals`, filtering by `debitPartyOrgIds` or `debitPartyDocuments`; contracts are being removed.", "x-mint": { "content": "Returns one contract of your organization, with its parties. A deal carries its payers: read one with `GET .../deals/{dealId}`, or find a payer's deals with `GET .../deals?debitPartyOrgIds=…` (a payer with a Portão 3 wallet) or `GET .../deals?debitPartyDocuments=…` (any payer)." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Undocumented response (no code type, no existing spec)." } }, "x-p3-confidence": { "response": "unknown" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractId", "summary": "Deprecated — Update a contract", "tags": [ "Contracts" ], "x-p3-sidebar-order": 4, "description": "Deprecated: contracts are being removed; there is no replacement.", "x-mint": { "content": "Changes a contract of your organization." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Undocumented response (no code type, no existing spec)." } }, "x-p3-confidence": { "response": "unknown" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/terminate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdTerminate", "summary": "Deprecated — Terminate a contract", "tags": [ "Contracts" ], "x-p3-sidebar-order": 5, "description": "Deprecated: contracts are being removed; there is no replacement.", "x-mint": { "content": "Terminates a contract of your organization. Cancelling a deal is a different action: it does not stand in for this one." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contractId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Undocumented response (no code type, no existing spec)." } }, "x-p3-confidence": { "response": "unknown" } } }, "/realms/{realmId}/organizations/{organizationId}/deals": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdDeals", "summary": "List deals", "tags": [ "Deals" ], "x-p3-sidebar-order": 1, "description": "Lists the deals of your organization, newest first by default.", "x-mint": { "content": "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).\n\nFilter 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`.\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "status", "in": "query", "required": false, "description": "Only deals in these statuses.\n\n---\n\nExample (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).\n\n---\n\nExample (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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:findDealsQuerySchema", "note": "`.refine(…)` constraint not represented (runtime-dependent value); root `z.preprocess(…)` step not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdDeals", "summary": "Create a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 4, "description": "Creates a deal: what your organization charges a payer for, how it is paid and when.", "x-mint": { "content": "The invoices follow from `chargeType` and `settings.createAllInvoicesOnStart`. With it, every invoice is created now — `numberOfInstallments` of them, each due one month after the previous one. Without it, a `SINGLE` or `SUBSCRIPTION` deal gets its first invoice now, and a `RECURRENT` deal none until you start it: send its `startAt` with `PUT .../deals/{dealId}` — today creates the first invoice at once, a later date (as `YYYY-MM-DD`) on that day. From then on, each invoice creates the next one when it closes, as long as the deal is open, has a `RECURRENT` product and its end date has not passed — `numberOfInstallments` months after `firstChargeDate` for a `RECURRENT` deal, `endAt` (or never) for a `SUBSCRIPTION` deal. The first invoice is due on `firstChargeDate`. An invoice closes — and its boleto or PIX charge is issued — as soon as it is created with `settings.disableOpenStatus`; otherwise an invoice created one at a time closes 5 days before its due date, and of the invoices created at the start the first closes on its due date and the others are created closed. The deal starts now, and its closing and due days are derived from `firstChargeDate` (see `closingAt` and `dueAt` in the response).\n\nThe deal belongs to your organization alone: no contract is involved, so nothing about the payer or the receivers is checked against one. Each receiver's wallet must be active, and one that names a Portão 3 organization must name an active organization of its realm, with the document registered for it. On a `P2P` deal the payer's wallet must be active or still pending activation — nothing is debited from a pending wallet until it is active. Deals paid by `PIX`, `PIX_AUTOMATIC` or `PIX_INITIATION` need an active PIX key in your organization's default wallet.\n\nThe payer's `name`, `email`, `phone` and `address` are what its fiscal documents and charges carry, and nothing else completes them: send what each document needs. `phone` is optional, in E.164 format (`+5511987654321`).\n\n`PIX_AUTOMATIC` (PIX Automático) and `PIX_INITIATION` (recurring scheduled PIX) are `RECURRENT` deals that create every invoice now and close them at once (`settings.createAllInvoicesOnStart` and `settings.disableOpenStatus` both `true`), from `RECURRENT` products charged `LATER`, with at least one secondary method. The payment authorization is requested from the bank as the deal is created: the response carries the `paymentUrl` where the payer authorizes it.\n\nThe `BILLING_DEAL_CREATED` webhook event is sent, and `BILLING_INVOICE_CREATED` for each invoice created (`BILLING_INVOICE_CLOSED` for each one closed at once). If creating the invoices fails after the deal was saved, the error is returned and the deal and what was already created for it are deleted — a best-effort cleanup that can itself fail; a PIX authorization the bank already created, and the webhook events already sent for its invoices, are not undone. A request sent twice creates two deals.\n\nAny member of the organization, or an admin of the realm, can create one; `createdBy` and `updatedBy` are set to the ID of the authenticated caller. Answers the deal it created." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "`SINGLE`: one invoice, created now. `RECURRENT`: monthly invoices up to `numberOfInstallments` months after `firstChargeDate`. `SUBSCRIPTION`: monthly invoices, the first created now, until `endAt` (or until the deal is canceled or terminated). Unless `settings.createAllInvoicesOnStart` creates them all now, each invoice after the first is created when the previous one closes, and only while the deal has a `RECURRENT` product (see the description above).", "example": "RECURRENT" }, "description": { "type": "string", "minLength": 1, "maxLength": 90, "description": "Description of the deal, up to 90 characters. 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" }, "products": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "description": "Your label for the product.", "example": "PLANO-PRO" }, "description": { "type": "string", "minLength": 1, "description": "Description of the product.", "example": "Plano Pro mensal" }, "price": { "type": "integer", "minimum": 1, "description": "Price in centavos, a whole number (`15000` is R$ 150,00), charged on each invoice the product appears on.", "example": 15000 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "`LATER`: added to the invoice and paid with it. `INSTANT`: debited from the payer's Portão 3 wallet as soon as it is added — only on `P2P` deals.", "example": "LATER" }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "`RECURRENT`: on every invoice. `ONE_TIME`: on the first invoice only — on every invoice when `settings.createAllInvoicesOnStart` is `true`. `ON_EVENT`: never charged automatically.", "example": "RECURRENT" }, "idProduct": { "description": "ID of the product in your product catalog, if it comes from one.", "example": "8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f", "type": "string" } }, "required": [ "identifier", "description", "price", "chargeMethod", "type" ] }, "description": "What the deal charges for. At least one." }, "paymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "BANK_SLIP" }, "description": "How the invoices are paid — exactly one: `BANK_SLIP` (boleto), `PIX` (a PIX charge), `P2P` (a debit from the payer's Portão 3 wallet), `PIX_AUTOMATIC` (PIX Automático: the payer authorizes the recurring payments once, through `paymentUrl` in the response) or `PIX_INITIATION` (recurring scheduled PIX, authorized the same way).\n\n---\n\nExample: `[\"BANK_SLIP\"]`" }, "secondaryPaymentMethods": { "description": "Other ways the payer can pay: `PIX` and/or `BANK_SLIP`. Required, with at least one, for `PIX_AUTOMATIC` and `PIX_INITIATION`. Only invoices created at the start (`settings.createAllInvoicesOnStart`) accept them.\n\n---\n\nExample: `[\"PIX\"]`", "type": "array", "items": { "type": "string", "enum": [ "PIX", "BANK_SLIP" ], "example": "PIX" } }, "settings": { "description": "How the deal creates its invoices.", "type": "object", "properties": { "createAllInvoicesOnStart": { "description": "`true`: create every invoice now, each due one month after the previous one. Required as `true` for `PIX_AUTOMATIC` and `PIX_INITIATION`.", "example": false, "type": "boolean" }, "disableOpenStatus": { "default": false, "description": "`true`: close each invoice — and issue its payment — as soon as it is created. `false` (the default): an invoice created one at a time stays open, gathering charges, until 5 days before it is due; of the invoices created at the start (`createAllInvoicesOnStart`), the first stays open until its due date and the others are created closed. Required as `true` for `PIX_AUTOMATIC` and `PIX_INITIATION`.", "example": false, "type": "boolean" }, "invoiceNameType": { "description": "`DEAL_DESCRIPTION`: name the invoices created at the start after the deal's description — as ` - /` on a `RECURRENT` deal, the description alone otherwise. Omitted, 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", "type": "string", "enum": [ "DEAL_DESCRIPTION" ] }, "paymentLinkId": { "description": "ID of the payment link the deal comes from. Set by the payment-link checkout: leave it out.", "example": "5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f", "type": "string" } } }, "numberOfInstallments": { "type": "integer", "description": "With `settings.createAllInvoicesOnStart`, how many invoices are created now, whatever the charge type. Otherwise it sets when a `RECURRENT` deal ends: `numberOfInstallments` months after `firstChargeDate`. Required for `RECURRENT`, a whole number of at least 2; defaults to 1 otherwise.", "example": 12 }, "firstChargeDate": { "description": "Due date of the first invoice (ISO 8601 date or date-time, read in UTC); the next ones are due on the same day of the following months. Today or later — strictly after today for `PIX_INITIATION`, today or later in Brasília time for `PIX_AUTOMATIC`.", "example": "2026-11-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "creditParties": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the receiver, without punctuation (a valid one). It must be the document registered for the organization that owns the wallet.", "example": "12345678000195" }, "name": { "description": "Name of the receiver.", "example": "Empresa Exemplo Ltda", "type": "string" }, "email": { "description": "E-mail of the receiver.", "example": "financeiro@empresaexemplo.com.br", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "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 must add up to 100; your organization keeps what is not transferred to the others.", "example": 100 }, "account": { "type": "object", "properties": { "bank": { "type": "string", "enum": [ "P3" ], "description": "Always `P3`.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Always `WALLET`.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "account": { "type": "string", "minLength": 1, "description": "ID of the organization's account.", "example": "6711b4c0d8e1a30012b7c9f1" }, "wallet": { "type": "string", "minLength": 1, "description": "ID of the wallet, or `default` for the account's default wallet. It must be active.", "example": "default" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "Which wallet." } }, "required": [ "bank", "type", "identifier" ], "description": "The Portão 3 wallet the share is paid into." } }, "required": [ "document", "unit", "amount", "account" ] }, "description": "Who receives the money, and each one's share. At least one." }, "debitParties": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the payer, without punctuation (a valid one).", "example": "52998224725" }, "name": { "type": "string", "minLength": 1, "description": "Name of the payer.", "example": "Maria da Silva" }, "email": { "description": "E-mail of the payer. It is the e-mail printed on the payer's fiscal documents.", "example": "maria.silva@example.com", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "phone": { "description": "Phone of the payer, in E.164 format: `+`, the country code and the number, digits only. A Brazilian number is `+55`, the 2-digit area code and 8 or 9 digits. It is the phone printed on the payer's fiscal documents; omitted (or blank), they carry none.", "example": "+5511987654321", "type": "string", "pattern": "^\\+(?:55[0-9]{10,11}|(?!55)[1-9]\\d{7,14})$" }, "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`.", "example": 100 }, "account": { "description": "The payer's Portão 3 wallet the invoices are debited from. Required, with every field, for `P2P` deals.", "type": "object", "properties": { "bank": { "description": "Always `P3`.", "example": "P3", "type": "string", "enum": [ "P3" ] }, "type": { "description": "Always `WALLET`.", "example": "WALLET", "type": "string", "enum": [ "WALLET" ] }, "identifier": { "description": "Which wallet.", "type": "object", "properties": { "realm": { "description": "ID of the payer's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "type": "string" }, "organization": { "description": "ID of the payer's organization.", "example": "1d3f5a7c-9e2b-4c6d-8f0a-2b4c6d8e0f1a", "type": "string" }, "account": { "description": "ID of the payer's account.", "example": "6711b4c0d8e1a30012b7c9f9", "type": "string" }, "wallet": { "description": "ID of the payer's wallet, or `default` for the account's default wallet. It must be active.", "example": "default", "type": "string" } } } } }, "address": { "description": "The payer's billing address, printed on its boletos and PIX charges. Required, with every field but `complement`, for `BANK_SLIP` and `PIX` deals — and for deals that create all their invoices at the start with `PIX` or `BANK_SLIP` among `secondaryPaymentMethods`. Otherwise it is optional, and printed on the payer's fiscal documents.", "type": "object", "properties": { "street": { "description": "Street.", "example": "Avenida Paulista", "type": "string" }, "number": { "description": "Number.", "example": "1000", "type": "string" }, "complement": { "description": "Complement, up to 50 characters.", "example": "Sala 12", "type": "string" }, "neighborhood": { "description": "Neighborhood.", "example": "Bela Vista", "type": "string" }, "city": { "description": "City.", "example": "São Paulo", "type": "string" }, "state": { "description": "State, as its two-letter code (`SP`, `RJ`, …).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } }, "required": [ "document", "name", "unit", "amount" ] }, "description": "Who pays: exactly one payer." }, "fine": { "default": null, "description": "Fine charged once on an invoice paid after its due date. `null` or omitted: none.", "type": "object", "properties": { "amountType": { "type": "string", "enum": [ "FIXED_VALUE", "PERCENT" ], "description": "`PERCENT`: `amount` is a percentage of the invoice, from 0.1 to 99.99. `FIXED_VALUE`: `amount` is a whole number of centavos, at least 1.", "example": "PERCENT" }, "amount": { "type": "number", "description": "The fine, per `amountType`.", "example": 2 } }, "required": [ "amountType", "amount" ], "nullable": true }, "interest": { "default": null, "description": "Interest charged on an invoice paid late, from the day after its due date. `null` or omitted: 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, from 0.1 to 99.99 — per day on a PIX charge, but per MONTH on a boleto. `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS`: `amount` is a whole number of centavos per calendar or working day, at least 1.", "example": "PERCENT_POINT_PER_DAY_CALENDAR_DAYS" }, "amount": { "type": "number", "description": "The interest, per `amountType`.", "example": 0.1 } }, "required": [ "amountType", "amount" ], "nullable": true }, "discount": { "default": null, "description": "Discount for an invoice paid before its due date. `null` or omitted: 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, from 0.1 to 99.99. `AMOUNT_PER_ANTECIPATION`: `amount` is a whole number of centavos, at least 1.", "example": "AMOUNT_PER_ANTECIPATION" }, "amount": { "type": "number", "description": "The discount, per `amountType`.", "example": 500 } }, "required": [ "amountType", "amount" ], "nullable": true }, "endAt": { "description": "End date of a `SUBSCRIPTION` deal (ISO 8601 date or date-time); omitted, it has no end. Ignored by `SINGLE` and `RECURRENT` deals, whose end follows from their invoices.", "example": "2027-12-31", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "chargeType", "description", "products", "paymentMethods", "firstChargeDate", "creditParties", "debitParties" ] } } } }, "responses": { "201": { "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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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" } }, "required": [ "id", "realm", "organization", "chargeType", "status", "firstChargeDate", "startAt", "endAt", "products", "paymentMethods", "secondaryPaymentMethods", "creditParties", "debitParties", "closingAt", "dueAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "A deal: what an organization charges a payer for, how and when." } } } }, "400": { "description": "`PARTY_REALM_ORG_NOT_FOUND` — A receiver's wallet organization does not exist, is not active, or has another document.\n\n`CREDIT_AMOUNT_MISMATCH` — The receivers' shares don't add up to 100.\n\n`DEBIT_AMOUNT_MISMATCH` — The payer's share is not 100.\n\n`INVALID_CHARGE_METHOD` — A product is charged `INSTANT` on a deal that is not paid by `P2P`.\n\n`WALLET_NOT_ACTIVE` — A receiver's wallet is not active, or — on a `P2P` deal — the payer's is neither active nor pending activation.\n\n`PIX_DICT_NOT_FOUND` — The deal is paid by `PIX`, `PIX_AUTOMATIC` or `PIX_INITIATION`, and your organization's default wallet has no active PIX key.\n\n`CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT` — On a `P2P` deal, the payer's wallet is also a receiver's.", "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": [ "PARTY_REALM_ORG_NOT_FOUND", "CREDIT_AMOUNT_MISMATCH", "DEBIT_AMOUNT_MISMATCH", "INVALID_CHARGE_METHOD", "WALLET_NOT_ACTIVE", "PIX_DICT_NOT_FOUND", "CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT" ], "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": "PARTY_REALM_ORG_NOT_FOUND", "origin": "BILLING", "message": "Party realm and organization not found to document: 12345678000195" } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm.\n\n`BILLING_P2P_NOT_ENABLED` — The deal is paid by `P2P`, and P2P is not enabled for your organization.", "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", "BILLING_P2P_NOT_ENABLED" ], "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": "`WALLET_NOT_FOUND` — A receiver's wallet — or, on a `P2P` deal, the payer's — does not exist.", "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": [ "WALLET_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": "WALLET_NOT_FOUND", "origin": "BILLING", "message": "Wallet not found" } } } }, "422": { "description": "`CREATE_INVOICE_ERROR` — The deal's first invoice could not be created; nothing was kept.\n\n`BAD_REQUEST` — The body is invalid — a missing field, more than one payment method, a `firstChargeDate` in the past, a PIX Automático deal that breaks its rules, a payer without the address or wallet the payment method needs, an invalid `phone` — or 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": [ "CREATE_INVOICE_ERROR", "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": "CREATE_INVOICE_ERROR", "origin": "BILLING", "message": "INVOICE_CREATION_ERROR" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.transform(…)` constraint not represented (runtime-dependent value); `.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/deals/export": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdDealsExport", "summary": "Export deals", "tags": [ "Deals" ], "x-p3-sidebar-order": 2, "description": "Exports the deals of your organization as a CSV or XLSX file.", "x-mint": { "content": "The file has every deal that matches the same filters and order as the deal list, one per row, with six columns whose headers are in Portuguese: `Descrição` (the description), `Cliente` (the payer's name), `Quantidade` (the number of installments), `Data de vencimento` (the deal's end date, as `DD/MM/YYYY`, UTC), `Status` (`Ativo`, `Cancelado`, `Terminado`, `Expirado` or `Revogado`) and `Valor` (what the invoices are expected to charge in total, in reais, as `1.234,56`). When no deal matches, the file has the header and one row with `Quantidade` `0` and `Valor` `0,00`.\n\n`?type=csv` answers a UTF-8 CSV file; `?type=xlsx` an Excel workbook, base64-encoded. An export is limited to 50,000 deals and 4 MiB: narrow the filters to export more. Any member of the organization, or an admin of the realm, can export them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 export.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "type", "in": "query", "required": true, "description": "Format of the exported file.", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "example": "csv" }, { "name": "encoding", "in": "query", "required": false, "description": "How an `xlsx` file is encoded in the response body: always `base64`, the default. A `csv` file is always sent as plain text.", "schema": { "default": "base64", "type": "string", "enum": [ "base64" ] }, "example": "base64" }, { "name": "status", "in": "query", "required": false, "description": "Only deals in these statuses.\n\n---\n\nExample (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).\n\n---\n\nExample (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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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" } ], "responses": { "200": { "description": "`application/csv` — The deals as a UTF-8 CSV file, when `type` is `csv`.\n\n`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — The Excel workbook, base64-encoded, when `type` is `xlsx`.", "content": { "application/csv": { "schema": { "type": "string", "description": "The deals as a UTF-8 CSV file, when `type` is `csv`." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "byte", "description": "The Excel workbook, base64-encoded, when `type` is `xlsx`." } } } }, "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": "`EXPORT_TOO_LARGE` — More than 50,000 deals match, or the file would exceed 4 MiB.\n\n`BAD_REQUEST` — A path or query parameter is invalid, such as a missing `type`; `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": [ "EXPORT_TOO_LARGE", "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": "EXPORT_TOO_LARGE", "origin": "BILLING", "message": "This export is too large to generate in a single request. Narrow the filters (for example a shorter date range) and try again." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:exportDealsQuerySchema", "note": "root `z.preprocess(…)` step not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/deals/{dealId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdDealsByDealId", "summary": "Get a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 3, "description": "Returns one deal of your organization, with its customer, totals and invoices.", "x-mint": { "content": "`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`).\n\nAny member of the organization, or an admin of the realm, can read it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal.\n\nFormat: `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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdDealsByDealId", "summary": "Update a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 5, "description": "Changes an open deal: its description, dates, payment method, closing and due days, or parties. Send only what changes.", "x-mint": { "content": "A new `description` renames every invoice of the deal. `startAt` can change only while the deal has no invoice; when it is today, the first invoice is created at once. `endAt` can't be before the deal's start; `null` removes it, and today or earlier terminates the deal at once — its open invoice is closed and issued, and the `BILLING_DEAL_TERMINATED` webhook event is sent. Parties are replaced as a whole and checked like on create: the wallets, the shares adding up to 100, and what the (new or current) payment method needs from the payer. A PIX Automático or recurring PIX deal can't change its payment method. The products, charge type, settings, fees and installments can't be changed.\n\nWhen the payer you send has the stored payer's `document`, the contact fields you leave out — `phone`, `name`, `email` and, field by field, the address — keep their stored values; a field you send replaces the stored one, and none can be cleared. A payer with another document gets only what you send.\n\nThe deal is found by its ID alone: it belongs to your organization, and no contract is involved. Any member of the organization, or an admin of the realm, can change it; `updatedBy` is set to the ID of the authenticated caller. Answers the deal as changed." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal to change.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "New description, up to 90 characters. It also renames every invoice of the deal. Omitted or empty: unchanged.", "example": "Mensalidade Plano Pro", "type": "string", "maxLength": 90 }, "startAt": { "description": "New start date (ISO 8601 date or date-time). Only while the deal has no invoice, and not before today. When it is today, the deal's first invoice is created at once.", "example": "2026-11-01", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "endAt": { "description": "New end date (ISO 8601 date or date-time), or `null` to remove it. It can't be before the deal's start date. Today or earlier terminates the deal at once. Omitted: unchanged.", "example": "2027-11-10", "anyOf": [ { "type": "string", "format": "date", "nullable": true }, { "type": "string", "format": "date-time", "nullable": true } ] }, "paymentMethods": { "description": "New payment method, exactly one: `BANK_SLIP`, `PIX` or `P2P`. A PIX Automático or recurring PIX deal can't change it. With `P2P` the payer needs its Portão 3 wallet, with `BANK_SLIP` or `PIX` its billing address (see `debitParties`). Omitted: unchanged.\n\n---\n\nExample: `[\"BANK_SLIP\"]`", "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX", "P2P" ], "example": "BANK_SLIP" } }, "closingAt": { "description": "New closing day of the invoices, as a cron expression `0 0 * *` with a day from 1 to 28. Omitted or empty: unchanged.", "example": "0 0 5 * *", "type": "string" }, "dueAt": { "description": "New due day of the invoices, as a cron expression `0 0 * *` with a day from 1 to 28. Omitted or empty: unchanged.", "example": "0 0 10 * *", "type": "string" }, "creditParties": { "description": "New receivers. Replaces the whole list; their shares must add up to 100. Omitted: unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the receiver, without punctuation (a valid one). It must be the document registered for the organization that owns the wallet.", "example": "12345678000195" }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "Always `PERCENTAGE`.", "example": "PERCENTAGE" }, "name": { "description": "Name of the receiver.", "example": "Empresa Exemplo Ltda", "type": "string" }, "email": { "description": "E-mail of the receiver.", "example": "financeiro@empresaexemplo.com.br", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "amount": { "type": "number", "description": "The receiver's share of every payment, in percent. The shares of all receivers must add up to 100.", "example": 100 }, "account": { "type": "object", "properties": { "bank": { "type": "string", "enum": [ "P3" ], "description": "Always `P3`.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Always `WALLET`.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "account": { "type": "string", "minLength": 1, "description": "ID of the organization's account.", "example": "6711b4c0d8e1a30012b7c9f1" }, "wallet": { "type": "string", "minLength": 1, "description": "ID of the wallet, or `default` for the account's default wallet. It must be active.", "example": "default" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "Which wallet." } }, "required": [ "bank", "type", "identifier" ], "description": "The Portão 3 wallet the share is paid into." } }, "required": [ "document", "unit", "amount", "account" ] } }, "debitParties": { "description": "New payer: exactly one. Replaces the stored one — send its wallet again when the deal needs it, and its address when the deal is paid by `BANK_SLIP` or `PIX`. When the payer's `document` is the stored payer's, the contact fields you leave out (`phone`, `name`, `email`, and the `address` unless you send a new one with its `postalCode` and `street`) keep their stored values; a field you send replaces the stored one, and none can be cleared. Omitted: unchanged.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the payer, without punctuation (a valid one).", "example": "52998224725" }, "name": { "description": "Name of the payer. Omitted (or blank), for the stored payer: the stored name is kept.", "example": "Maria da Silva", "type": "string" }, "email": { "description": "E-mail of the payer. Omitted (or blank), for the stored payer: the stored e-mail is kept.", "example": "maria.silva@example.com", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "phone": { "description": "Phone of the payer, in E.164 format: `+`, the country code and the number, digits only. A Brazilian number is `+55`, the 2-digit area code and 8 or 9 digits. It is the phone printed on the payer's fiscal documents. Omitted (or blank), for the stored payer: the stored phone is kept.", "example": "+5511987654321", "type": "string", "pattern": "^\\+(?:55[0-9]{10,11}|(?!55)[1-9]\\d{7,14})$" }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "Always `PERCENTAGE`.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share of each invoice, in percent: `100`.", "example": 100 }, "account": { "description": "The payer's Portão 3 wallet the invoices are debited from. Required, with every field, when the deal is paid by `P2P`.", "type": "object", "properties": { "bank": { "description": "Always `P3`.", "example": "P3", "type": "string", "enum": [ "P3" ] }, "type": { "description": "Always `WALLET`.", "example": "WALLET", "type": "string", "enum": [ "WALLET" ] }, "identifier": { "description": "Which wallet.", "type": "object", "properties": { "realm": { "description": "ID of the payer's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "type": "string" }, "organization": { "description": "ID of the payer's organization.", "example": "1d3f5a7c-9e2b-4c6d-8f0a-2b4c6d8e0f1a", "type": "string" }, "account": { "description": "ID of the payer's account.", "example": "6711b4c0d8e1a30012b7c9f9", "type": "string" }, "wallet": { "description": "ID of the payer's wallet, or `default` for the account's default wallet.", "example": "default", "type": "string" } } } } }, "address": { "description": "The payer's billing address. Required, with every field but `complement`, when the deal is paid by `BANK_SLIP` or `PIX`, or creates all its invoices at the start with `PIX` or `BANK_SLIP` as a secondary method. Otherwise, for the stored payer, an omitted address keeps the stored one; a sent address with its own `postalCode` and `street` replaces it as sent (nothing of the old one is kept); a partial one, without them, keeps the stored value of each field it omits (or leaves blank).", "type": "object", "properties": { "street": { "description": "Street.", "example": "Avenida Paulista", "type": "string" }, "number": { "description": "Number.", "example": "1000", "type": "string" }, "complement": { "description": "Complement, up to 50 characters.", "example": "Sala 12", "type": "string" }, "neighborhood": { "description": "Neighborhood.", "example": "Bela Vista", "type": "string" }, "city": { "description": "City.", "example": "São Paulo", "type": "string" }, "state": { "description": "State, as its two-letter code (`SP`, `RJ`, …).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } }, "required": [ "document", "unit", "amount" ] } } } } } } }, "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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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" } }, "required": [ "id", "realm", "organization", "chargeType", "status", "firstChargeDate", "startAt", "endAt", "products", "paymentMethods", "secondaryPaymentMethods", "creditParties", "debitParties", "closingAt", "dueAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "A deal: what an organization charges a payer for, how and when." } } } }, "400": { "description": "`DEAL_NOT_OPEN` — The deal was canceled, terminated, expired or revoked.\n\n`DEAL_END_AT_BEFORE_START_AT` — The deal would end before it starts.\n\n`DEAL_START_AT_LOCKED` — `startAt` was sent, and the deal already has invoices.\n\n`DEAL_PAYMENT_METHOD_LOCKED` — `paymentMethods` was sent for a PIX Automático or recurring PIX deal.\n\n`PARTY_REALM_ORG_NOT_FOUND` — A new receiver's wallet organization does not exist, is not active, or has another document.\n\n`CREDIT_AMOUNT_MISMATCH` — The new receivers' shares don't add up to 100.\n\n`DEBIT_AMOUNT_MISMATCH` — The new payer's share is not 100.\n\n`WALLET_NOT_ACTIVE` — A new receiver's wallet is not active, or a new payer's is neither active nor pending activation.", "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_OPEN", "DEAL_END_AT_BEFORE_START_AT", "DEAL_START_AT_LOCKED", "DEAL_PAYMENT_METHOD_LOCKED", "PARTY_REALM_ORG_NOT_FOUND", "CREDIT_AMOUNT_MISMATCH", "DEBIT_AMOUNT_MISMATCH", "WALLET_NOT_ACTIVE" ], "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_OPEN", "origin": "BILLING", "message": "Deal is not open" } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm.\n\n`BILLING_P2P_NOT_ENABLED` — The deal is, or would become, paid by `P2P`, and P2P is not enabled for your organization.", "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", "BILLING_P2P_NOT_ENABLED" ], "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.\n\n`WALLET_NOT_FOUND` — A new receiver's wallet does not exist.", "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", "WALLET_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": "`DEAL_START_AT_INVALID` — The new `startAt` is before today.\n\n`CREATE_INVOICE_ERROR` — The new `startAt` is today and the deal's first invoice could not be created.\n\n`BAD_REQUEST` — The body is invalid — a date that is not a date, a cron that is not `0 0 * *`, more than one payment method, a payer without the address or wallet the payment method needs, an invalid `phone` — or 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": [ "DEAL_START_AT_INVALID", "CREATE_INVOICE_ERROR", "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": "DEAL_START_AT_INVALID", "origin": "BILLING", "message": "Start date must be today or later" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/deals/{dealId}/cancel": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdDealsByDealIdCancel", "summary": "Cancel a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 6, "description": "Cancels an open deal: it stops creating invoices.", "x-mint": { "content": "For a PIX Automático or recurring PIX deal, the payer's authorization is canceled at the bank first; if that fails, the bank's error is returned (`origin` `BANKING`, with its own status and `code`) and nothing changes.\n\nThe body is optional: send `{}`, or no body and no `Content-Type`. With `cancelAllInvoices: true`, every invoice of the deal that is not paid or canceled yet is canceled. Otherwise the open invoice is closed — its boleto or PIX charge is issued and it stays payable — and only the closed invoices due more than a month from now are canceled. Paid invoices are never touched.\n\nThe deal is found by its ID alone: it belongs to your organization, and no contract is involved. The `BILLING_DEAL_CANCELED` webhook event is sent (and `BILLING_INVOICE_CLOSED` for the invoice it closed, or `BILLING_INVOICE_PAID` when that invoice was already paid in full). Any member of the organization, or an admin of the realm, can cancel one; `updatedBy` is set to the ID of the authenticated caller. Answers the canceled deal." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal to cancel.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelAllInvoices": { "description": "`true`: cancel every invoice of the deal that is not paid or canceled yet. `false` or omitted: close the open invoice — it is issued and stays payable — and cancel only the closed invoices due more than a month from now.", "example": true, "type": "boolean" } } } } } }, "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": "CANCELED" }, "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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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-28T09:15: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" } }, "required": [ "id", "realm", "organization", "chargeType", "status", "firstChargeDate", "startAt", "endAt", "products", "paymentMethods", "secondaryPaymentMethods", "creditParties", "debitParties", "closingAt", "dueAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "A deal: what an organization charges a payer for, how and when." } } } }, "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" } } } }, "409": { "description": "`DEAL_NOT_ACTIVE` — The deal is no longer open: it was already canceled, terminated, expired or revoked.", "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_ACTIVE" ], "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_ACTIVE", "origin": "BILLING", "message": "Deal is not active to perform this action" } } } }, "422": { "description": "`BAD_REQUEST` — `cancelAllInvoices` is not a boolean, or 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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/deals": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDeals", "summary": "Deprecated — List a contract's deals", "tags": [ "Deals" ], "x-p3-sidebar-order": 8, "description": "Deprecated: use `GET .../deals`, filtering by `debitPartyOrgIds` or `debitPartyDocuments`; contracts are being removed.", "x-mint": { "content": "Lists the deals of one contract, newest first by default. The same list, filters, sorting and paging as `GET .../deals`, narrowed to the contract. A contract ID that matches no contract of the organization answers an empty list.\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 deals.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the contract whose deals you list. An ID that matches no contract of the organization answers an empty list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "status", "in": "query", "required": false, "description": "Only deals in these statuses.\n\n---\n\nExample (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).\n\n---\n\nExample (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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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 a `contractId` that is not a valid ID or a `limit` out of range; `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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:findDealsQuerySchema", "note": "`.refine(…)` constraint not represented (runtime-dependent value); root `z.preprocess(…)` step not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDeals", "summary": "Deprecated — Create a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 9, "description": "Deprecated: use `POST .../deals`; contracts are being removed.", "x-mint": { "content": "Creates a deal under a contract: what your organization charges a payer for, how it is paid and when.\n\nThe invoices follow from `chargeType` and `settings.createAllInvoicesOnStart`. With it, every invoice is created now — `numberOfInstallments` of them, each due one month after the previous one. Without it, a `SINGLE` or `SUBSCRIPTION` deal gets its first invoice now, and a `RECURRENT` deal none until you start it: send its `startAt` with `PUT .../deals/{dealId}` — today creates the first invoice at once, a later date (as `YYYY-MM-DD`) on that day. From then on, each invoice creates the next one when it closes, as long as the deal is open, has a `RECURRENT` product and its end date has not passed — `numberOfInstallments` months after `firstChargeDate` for a `RECURRENT` deal, `endAt` (or never) for a `SUBSCRIPTION` deal. The first invoice is due on `firstChargeDate`. An invoice closes — and its boleto or PIX charge is issued — as soon as it is created with `settings.disableOpenStatus`; otherwise an invoice created one at a time closes 5 days before its due date, and of the invoices created at the start the first closes on its due date and the others are created closed. The deal starts now, and its closing and due days are derived from `firstChargeDate` (see `closingAt` and `dueAt` in the response).\n\nThe contract must be open, the payer must be one of its buyers and every receiver one of its vendors or intermediaries; each receiver's wallet must be active, and on a `P2P` deal the payer's must be active or still pending activation — nothing is debited from a pending wallet until it is active. Deals paid by `PIX`, `PIX_AUTOMATIC` or `PIX_INITIATION` need an active PIX key in your organization's default wallet.\n\n`PIX_AUTOMATIC` (PIX Automático) and `PIX_INITIATION` (recurring scheduled PIX) are `RECURRENT` deals that create every invoice now and close them at once (`settings.createAllInvoicesOnStart` and `settings.disableOpenStatus` both `true`), from `RECURRENT` products charged `LATER`, with at least one secondary method. The payment authorization is requested from the bank as the deal is created: the response carries the `paymentUrl` where the payer authorizes it.\n\nThe `BILLING_DEAL_CREATED` webhook event is sent, and `BILLING_INVOICE_CREATED` for each invoice created (`BILLING_INVOICE_CLOSED` for each one closed at once). If creating the invoices fails after the deal was saved, the error is returned and the deal and what was already created for it are deleted — a best-effort cleanup that can itself fail; a PIX authorization the bank already created, and the webhook events already sent for its invoices, are not undone. A request sent twice creates two deals.\n\nAny member of the organization, or an admin of the realm, can create one; `createdBy` and `updatedBy` are set to the ID of the authenticated caller. Answers the deal it created." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the contract the deal belongs to. It must be open, and the deal's parties must be parties of it.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "`SINGLE`: one invoice, created now. `RECURRENT`: monthly invoices up to `numberOfInstallments` months after `firstChargeDate`. `SUBSCRIPTION`: monthly invoices, the first created now, until `endAt` (or until the deal is canceled or terminated). Unless `settings.createAllInvoicesOnStart` creates them all now, each invoice after the first is created when the previous one closes, and only while the deal has a `RECURRENT` product (see the description above).", "example": "RECURRENT" }, "description": { "type": "string", "minLength": 1, "maxLength": 90, "description": "Description of the deal, up to 90 characters. 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" }, "products": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "description": "Your label for the product.", "example": "PLANO-PRO" }, "description": { "type": "string", "minLength": 1, "description": "Description of the product.", "example": "Plano Pro mensal" }, "price": { "type": "integer", "minimum": 1, "description": "Price in centavos, a whole number (`15000` is R$ 150,00), charged on each invoice the product appears on.", "example": 15000 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "`LATER`: added to the invoice and paid with it. `INSTANT`: debited from the payer's Portão 3 wallet as soon as it is added — only on `P2P` deals.", "example": "LATER" }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "`RECURRENT`: on every invoice. `ONE_TIME`: on the first invoice only — on every invoice when `settings.createAllInvoicesOnStart` is `true`. `ON_EVENT`: never charged automatically.", "example": "RECURRENT" }, "idProduct": { "description": "ID of the product in your product catalog, if it comes from one.", "example": "8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f", "type": "string" } }, "required": [ "identifier", "description", "price", "chargeMethod", "type" ] }, "description": "What the deal charges for. At least one." }, "paymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "BANK_SLIP" }, "description": "How the invoices are paid — exactly one: `BANK_SLIP` (boleto), `PIX` (a PIX charge), `P2P` (a debit from the payer's Portão 3 wallet), `PIX_AUTOMATIC` (PIX Automático: the payer authorizes the recurring payments once, through `paymentUrl` in the response) or `PIX_INITIATION` (recurring scheduled PIX, authorized the same way).\n\n---\n\nExample: `[\"BANK_SLIP\"]`" }, "secondaryPaymentMethods": { "description": "Other ways the payer can pay: `PIX` and/or `BANK_SLIP`. Required, with at least one, for `PIX_AUTOMATIC` and `PIX_INITIATION`. Only invoices created at the start (`settings.createAllInvoicesOnStart`) accept them.\n\n---\n\nExample: `[\"PIX\"]`", "type": "array", "items": { "type": "string", "enum": [ "PIX", "BANK_SLIP" ], "example": "PIX" } }, "settings": { "description": "How the deal creates its invoices.", "type": "object", "properties": { "createAllInvoicesOnStart": { "description": "`true`: create every invoice now, each due one month after the previous one. Required as `true` for `PIX_AUTOMATIC` and `PIX_INITIATION`.", "example": false, "type": "boolean" }, "disableOpenStatus": { "default": false, "description": "`true`: close each invoice — and issue its payment — as soon as it is created. `false` (the default): an invoice created one at a time stays open, gathering charges, until 5 days before it is due; of the invoices created at the start (`createAllInvoicesOnStart`), the first stays open until its due date and the others are created closed. Required as `true` for `PIX_AUTOMATIC` and `PIX_INITIATION`.", "example": false, "type": "boolean" }, "invoiceNameType": { "description": "`DEAL_DESCRIPTION`: name the invoices created at the start after the deal's description — as ` - /` on a `RECURRENT` deal, the description alone otherwise. Omitted, 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", "type": "string", "enum": [ "DEAL_DESCRIPTION" ] }, "paymentLinkId": { "description": "ID of the payment link the deal comes from. Set by the payment-link checkout: leave it out.", "example": "5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f", "type": "string" } } }, "numberOfInstallments": { "type": "integer", "description": "With `settings.createAllInvoicesOnStart`, how many invoices are created now, whatever the charge type. Otherwise it sets when a `RECURRENT` deal ends: `numberOfInstallments` months after `firstChargeDate`. Required for `RECURRENT`, a whole number of at least 2; defaults to 1 otherwise.", "example": 12 }, "firstChargeDate": { "description": "Due date of the first invoice (ISO 8601 date or date-time, read in UTC); the next ones are due on the same day of the following months. Today or later — strictly after today for `PIX_INITIATION`, today or later in Brasília time for `PIX_AUTOMATIC`.", "example": "2026-11-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "creditParties": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the receiver, without punctuation (a valid one). It must be a vendor or intermediary of the contract.", "example": "12345678000195" }, "name": { "description": "Name of the receiver.", "example": "Empresa Exemplo Ltda", "type": "string" }, "email": { "description": "E-mail of the receiver.", "example": "financeiro@empresaexemplo.com.br", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "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 must add up to 100; your organization keeps what is not transferred to the others.", "example": 100 }, "account": { "type": "object", "properties": { "bank": { "type": "string", "enum": [ "P3" ], "description": "Always `P3`.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Always `WALLET`.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "account": { "type": "string", "minLength": 1, "description": "ID of the organization's account.", "example": "6711b4c0d8e1a30012b7c9f1" }, "wallet": { "type": "string", "minLength": 1, "description": "ID of the wallet, or `default` for the account's default wallet. It must be active.", "example": "default" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "Which wallet." } }, "required": [ "bank", "type", "identifier" ], "description": "The Portão 3 wallet the share is paid into." } }, "required": [ "document", "unit", "amount", "account" ] }, "description": "Who receives the money, and each one's share. At least one." }, "debitParties": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the payer, without punctuation (a valid one). It must be a buyer of the contract.", "example": "52998224725" }, "name": { "type": "string", "minLength": 1, "description": "Name of the payer.", "example": "Maria da Silva" }, "email": { "description": "E-mail of the payer. Omitted: the contract buyer's e-mail is used.", "example": "maria.silva@example.com", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "phone": { "description": "Phone of the payer, in E.164 format: `+`, the country code and the number, digits only. A Brazilian number is `+55`, the 2-digit area code and 8 or 9 digits. It is the phone printed on the payer's fiscal documents. Omitted: the contract buyer's phone is used, when it is a valid one.", "example": "+5511987654321", "type": "string", "pattern": "^\\+(?:55[0-9]{10,11}|(?!55)[1-9]\\d{7,14})$" }, "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`.", "example": 100 }, "account": { "description": "The payer's Portão 3 wallet the invoices are debited from. Required, with every field, for `P2P` deals.", "type": "object", "properties": { "bank": { "description": "Always `P3`.", "example": "P3", "type": "string", "enum": [ "P3" ] }, "type": { "description": "Always `WALLET`.", "example": "WALLET", "type": "string", "enum": [ "WALLET" ] }, "identifier": { "description": "Which wallet.", "type": "object", "properties": { "realm": { "description": "ID of the payer's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "type": "string" }, "organization": { "description": "ID of the payer's organization.", "example": "1d3f5a7c-9e2b-4c6d-8f0a-2b4c6d8e0f1a", "type": "string" }, "account": { "description": "ID of the payer's account.", "example": "6711b4c0d8e1a30012b7c9f9", "type": "string" }, "wallet": { "description": "ID of the payer's wallet, or `default` for the account's default wallet. It must be active.", "example": "default", "type": "string" } } } } }, "address": { "description": "The payer's billing address, printed on its boletos and PIX charges. Required, with every field but `complement`, for `BANK_SLIP` and `PIX` deals — and for deals that create all their invoices at the start with `PIX` or `BANK_SLIP` among `secondaryPaymentMethods`. Otherwise, an omitted address is the contract buyer's.", "type": "object", "properties": { "street": { "description": "Street.", "example": "Avenida Paulista", "type": "string" }, "number": { "description": "Number.", "example": "1000", "type": "string" }, "complement": { "description": "Complement, up to 50 characters.", "example": "Sala 12", "type": "string" }, "neighborhood": { "description": "Neighborhood.", "example": "Bela Vista", "type": "string" }, "city": { "description": "City.", "example": "São Paulo", "type": "string" }, "state": { "description": "State, as its two-letter code (`SP`, `RJ`, …).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } }, "required": [ "document", "name", "unit", "amount" ] }, "description": "Who pays: exactly one payer." }, "fine": { "default": null, "description": "Fine charged once on an invoice paid after its due date. `null` or omitted: none.", "type": "object", "properties": { "amountType": { "type": "string", "enum": [ "FIXED_VALUE", "PERCENT" ], "description": "`PERCENT`: `amount` is a percentage of the invoice, from 0.1 to 99.99. `FIXED_VALUE`: `amount` is a whole number of centavos, at least 1.", "example": "PERCENT" }, "amount": { "type": "number", "description": "The fine, per `amountType`.", "example": 2 } }, "required": [ "amountType", "amount" ], "nullable": true }, "interest": { "default": null, "description": "Interest charged on an invoice paid late, from the day after its due date. `null` or omitted: 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, from 0.1 to 99.99 — per day on a PIX charge, but per MONTH on a boleto. `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS`: `amount` is a whole number of centavos per calendar or working day, at least 1.", "example": "PERCENT_POINT_PER_DAY_CALENDAR_DAYS" }, "amount": { "type": "number", "description": "The interest, per `amountType`.", "example": 0.1 } }, "required": [ "amountType", "amount" ], "nullable": true }, "discount": { "default": null, "description": "Discount for an invoice paid before its due date. `null` or omitted: 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, from 0.1 to 99.99. `AMOUNT_PER_ANTECIPATION`: `amount` is a whole number of centavos, at least 1.", "example": "AMOUNT_PER_ANTECIPATION" }, "amount": { "type": "number", "description": "The discount, per `amountType`.", "example": 500 } }, "required": [ "amountType", "amount" ], "nullable": true }, "endAt": { "description": "End date of a `SUBSCRIPTION` deal (ISO 8601 date or date-time); omitted, it has no end. Ignored by `SINGLE` and `RECURRENT` deals, whose end follows from their invoices. When the contract has an end date, the deal's end can't be after it — and a `SUBSCRIPTION` deal must then have one.", "example": "2027-12-31", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "chargeType", "description", "products", "paymentMethods", "firstChargeDate", "creditParties", "debitParties" ] } } } }, "responses": { "201": { "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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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" } }, "required": [ "id", "realm", "organization", "chargeType", "status", "firstChargeDate", "startAt", "endAt", "products", "paymentMethods", "secondaryPaymentMethods", "creditParties", "debitParties", "closingAt", "dueAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "A deal: what an organization charges a payer for, how and when." } } } }, "400": { "description": "`DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT` — The payer is not a buyer of the contract.\n\n`CREDIT_PARTY_DOCUMENT_MISMATCH_CONTRACT` — A receiver is not a vendor or intermediary of the contract.\n\n`INVALID_PARTY_REALM_ORG` — A receiver's wallet belongs to a realm and organization that don't match the contract's.\n\n`PARTY_REALM_ORG_NOT_FOUND` — A receiver's wallet organization does not exist, is not active, or has another document.\n\n`CREDIT_AMOUNT_MISMATCH` — The receivers' shares don't add up to 100.\n\n`DEBIT_AMOUNT_MISMATCH` — The payer's share is not 100.\n\n`INVALID_CHARGE_METHOD` — A product is charged `INSTANT` on a deal that is not paid by `P2P`.\n\n`WALLET_NOT_ACTIVE` — A receiver's wallet is not active, or — on a `P2P` deal — the payer's is neither active nor pending activation.\n\n`PIX_DICT_NOT_FOUND` — The deal is paid by `PIX`, `PIX_AUTOMATIC` or `PIX_INITIATION`, and your organization's default wallet has no active PIX key.\n\n`CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT` — On a `P2P` deal, the payer's wallet is also a receiver's.", "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": [ "DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT", "CREDIT_PARTY_DOCUMENT_MISMATCH_CONTRACT", "INVALID_PARTY_REALM_ORG", "PARTY_REALM_ORG_NOT_FOUND", "CREDIT_AMOUNT_MISMATCH", "DEBIT_AMOUNT_MISMATCH", "INVALID_CHARGE_METHOD", "WALLET_NOT_ACTIVE", "PIX_DICT_NOT_FOUND", "CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT" ], "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": "DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT", "origin": "BILLING", "message": "Debit party document 52998224725 must be in contract parties" } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm.\n\n`BILLING_P2P_NOT_ENABLED` — The deal is paid by `P2P`, and P2P is not enabled for your organization.", "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", "BILLING_P2P_NOT_ENABLED" ], "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": "`CONTRACT_NOT_FOUND` — The organization has no contract with this ID.\n\n`WALLET_NOT_FOUND` — A receiver's wallet — or, on a `P2P` deal, the payer's — does not exist.", "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": [ "CONTRACT_NOT_FOUND", "WALLET_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": "CONTRACT_NOT_FOUND", "origin": "BILLING", "message": "Contract not found" } } } }, "422": { "description": "`CONTRACT_NOT_OPEN` — The contract was terminated.\n\n`DEAL_START_AT_INVALID` — The contract only starts after today.\n\n`DEAL_END_AT_REQUIRED` — The contract has an end date and the `SUBSCRIPTION` deal has no `endAt`.\n\n`DEAL_END_AT_INVALID` — The deal would end after the contract.\n\n`CREATE_INVOICE_ERROR` — The deal's first invoice could not be created; nothing was kept.\n\n`BAD_REQUEST` — The body is invalid — a missing field, more than one payment method, a `firstChargeDate` in the past, a PIX Automático deal that breaks its rules, a payer without the address or wallet the payment method needs — or 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": [ "CONTRACT_NOT_OPEN", "DEAL_START_AT_INVALID", "DEAL_END_AT_REQUIRED", "DEAL_END_AT_INVALID", "CREATE_INVOICE_ERROR", "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": "CONTRACT_NOT_OPEN", "origin": "BILLING", "message": "Contract is not open" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.transform(…)` constraint not represented (runtime-dependent value); `.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/deals/{dealId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDealsByDealId", "summary": "Deprecated — Get a contract's deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 10, "description": "Deprecated: use `GET .../deals/{dealId}`; contracts are being removed.", "x-mint": { "content": "Returns one deal of a contract, with its customer, totals and invoices. The same deal, with the same fields, as `GET .../deals/{dealId}`, checked against the contract: a deal of another contract is not found.\n\nAny member of the organization, or an admin of the realm, can read it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the contract the deal belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal.\n\nFormat: `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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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 contract 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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDealsByDealId", "summary": "Deprecated — Update a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 11, "description": "Deprecated: use `PUT .../deals/{dealId}`; contracts are being removed.", "x-mint": { "content": "Changes an open deal: its description, dates, payment method, closing and due days, or parties. Send only what changes.\n\nA new `description` renames every invoice of the deal. `startAt` can change only while the deal has no invoice; when it is today, the first invoice is created at once. `endAt` can't be after the contract's end nor before the deal's start; `null` removes it when the contract has no end date, and today or earlier terminates the deal at once — its open invoice is closed and issued, and the `BILLING_DEAL_TERMINATED` webhook event is sent. Parties are replaced as a whole and checked like on create: against the contract, the wallets, the shares adding up to 100, and what the (new or current) payment method needs from the payer. A PIX Automático or recurring PIX deal can't change its payment method. The products, charge type, settings, fees and installments can't be changed.\n\nAny member of the organization, or an admin of the realm, can change it; `updatedBy` is set to the ID of the authenticated caller. Answers the deal as changed." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the contract the deal belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal to change.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "New description, up to 90 characters. It also renames every invoice of the deal. Omitted or empty: unchanged.", "example": "Mensalidade Plano Pro", "type": "string", "maxLength": 90 }, "startAt": { "description": "New start date (ISO 8601 date or date-time). Only while the deal has no invoice, and not before the contract starts nor before today. When it is today, the deal's first invoice is created at once.", "example": "2026-11-01", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "endAt": { "description": "New end date (ISO 8601 date or date-time), or `null` to remove it — unless the contract has an end date, which the deal's can't exceed. It can't be before the deal's start date. Today or earlier terminates the deal at once. Omitted: unchanged.", "example": "2027-11-10", "anyOf": [ { "type": "string", "format": "date", "nullable": true }, { "type": "string", "format": "date-time", "nullable": true } ] }, "paymentMethods": { "description": "New payment method, exactly one: `BANK_SLIP`, `PIX` or `P2P`. A PIX Automático or recurring PIX deal can't change it. With `P2P` the payer needs its Portão 3 wallet, with `BANK_SLIP` or `PIX` its billing address (see `debitParties`). Omitted: unchanged.\n\n---\n\nExample: `[\"BANK_SLIP\"]`", "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX", "P2P" ], "example": "BANK_SLIP" } }, "closingAt": { "description": "New closing day of the invoices, as a cron expression `0 0 * *` with a day from 1 to 28. Omitted or empty: unchanged.", "example": "0 0 5 * *", "type": "string" }, "dueAt": { "description": "New due day of the invoices, as a cron expression `0 0 * *` with a day from 1 to 28. Omitted or empty: unchanged.", "example": "0 0 10 * *", "type": "string" }, "creditParties": { "description": "New receivers. Replaces the whole list; their shares must add up to 100. Omitted: unchanged.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the receiver, without punctuation (a valid one). It must be a vendor or intermediary of the contract.", "example": "12345678000195" }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "Always `PERCENTAGE`.", "example": "PERCENTAGE" }, "name": { "description": "Name of the receiver.", "example": "Empresa Exemplo Ltda", "type": "string" }, "email": { "description": "E-mail of the receiver.", "example": "financeiro@empresaexemplo.com.br", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "amount": { "type": "number", "description": "The receiver's share of every payment, in percent. The shares of all receivers must add up to 100.", "example": 100 }, "account": { "type": "object", "properties": { "bank": { "type": "string", "enum": [ "P3" ], "description": "Always `P3`.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Always `WALLET`.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "description": "ID of the wallet owner's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "account": { "type": "string", "minLength": 1, "description": "ID of the organization's account.", "example": "6711b4c0d8e1a30012b7c9f1" }, "wallet": { "type": "string", "minLength": 1, "description": "ID of the wallet, or `default` for the account's default wallet. It must be active.", "example": "default" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "Which wallet." } }, "required": [ "bank", "type", "identifier" ], "description": "The Portão 3 wallet the share is paid into." } }, "required": [ "document", "unit", "amount", "account" ] } }, "debitParties": { "description": "New payer: exactly one. Replaces the stored one — send its wallet again when the deal needs it, and its address when the deal is paid by `BANK_SLIP` or `PIX`. When the payer's `document` is the stored payer's, the contact fields you leave out (`phone`, `name`, `email`, and the `address` unless you send a new one with its `postalCode` and `street`) keep their stored values; a field you send replaces the stored one, and none can be cleared. Omitted: unchanged.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string", "pattern": "^[A-Za-z0-9]+$", "description": "CPF or CNPJ of the payer, without punctuation (a valid one). It must be a buyer of the contract.", "example": "52998224725" }, "name": { "description": "Name of the payer. Omitted (or blank), for the stored payer: the stored name is kept.", "example": "Maria da Silva", "type": "string" }, "email": { "description": "E-mail of the payer. Omitted (or blank), for the stored payer: the stored e-mail is kept.", "example": "maria.silva@example.com", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "enum": [ "" ] } ] }, "phone": { "description": "Phone of the payer, in E.164 format: `+`, the country code and the number, digits only. A Brazilian number is `+55`, the 2-digit area code and 8 or 9 digits. It is the phone printed on the payer's fiscal documents. Omitted, for the stored payer: the stored phone is kept.", "example": "+5511987654321", "type": "string", "pattern": "^\\+(?:55[0-9]{10,11}|(?!55)[1-9]\\d{7,14})$" }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "Always `PERCENTAGE`.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share of each invoice, in percent: `100`.", "example": 100 }, "account": { "description": "The payer's Portão 3 wallet the invoices are debited from. Required, with every field, when the deal is paid by `P2P`.", "type": "object", "properties": { "bank": { "description": "Always `P3`.", "example": "P3", "type": "string", "enum": [ "P3" ] }, "type": { "description": "Always `WALLET`.", "example": "WALLET", "type": "string", "enum": [ "WALLET" ] }, "identifier": { "description": "Which wallet.", "type": "object", "properties": { "realm": { "description": "ID of the payer's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "type": "string" }, "organization": { "description": "ID of the payer's organization.", "example": "1d3f5a7c-9e2b-4c6d-8f0a-2b4c6d8e0f1a", "type": "string" }, "account": { "description": "ID of the payer's account.", "example": "6711b4c0d8e1a30012b7c9f9", "type": "string" }, "wallet": { "description": "ID of the payer's wallet, or `default` for the account's default wallet.", "example": "default", "type": "string" } } } } }, "address": { "description": "The payer's billing address. Required, with every field but `complement`, when the deal is paid by `BANK_SLIP` or `PIX`, or creates all its invoices at the start with `PIX` or `BANK_SLIP` as a secondary method. Otherwise, for the stored payer, an omitted address keeps the stored one; a sent address with its own `postalCode` and `street` replaces it as sent (nothing of the old one is kept); a partial one, without them, keeps the stored value of each field it omits (or leaves blank).", "type": "object", "properties": { "street": { "description": "Street.", "example": "Avenida Paulista", "type": "string" }, "number": { "description": "Number.", "example": "1000", "type": "string" }, "complement": { "description": "Complement, up to 50 characters.", "example": "Sala 12", "type": "string" }, "neighborhood": { "description": "Neighborhood.", "example": "Bela Vista", "type": "string" }, "city": { "description": "City.", "example": "São Paulo", "type": "string" }, "state": { "description": "State, as its two-letter code (`SP`, `RJ`, …).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } }, "required": [ "document", "unit", "amount" ] } } } } } } }, "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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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" } }, "required": [ "id", "realm", "organization", "chargeType", "status", "firstChargeDate", "startAt", "endAt", "products", "paymentMethods", "secondaryPaymentMethods", "creditParties", "debitParties", "closingAt", "dueAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "A deal: what an organization charges a payer for, how and when." } } } }, "400": { "description": "`DEAL_NOT_OPEN` — The deal was canceled, terminated, expired or revoked.\n\n`DEAL_END_AT_BEFORE_START_AT` — The deal would end before it starts.\n\n`DEAL_START_AT_LOCKED` — `startAt` was sent, and the deal already has invoices.\n\n`DEAL_PAYMENT_METHOD_LOCKED` — `paymentMethods` was sent for a PIX Automático or recurring PIX deal.\n\n`DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT` — The new payer is not a buyer of the contract.\n\n`CREDIT_PARTY_DOCUMENT_MISMATCH_CONTRACT` — A new receiver is not a vendor or intermediary of the contract.\n\n`INVALID_PARTY_REALM_ORG` — A new receiver's wallet belongs to a realm and organization that don't match the contract's.\n\n`PARTY_REALM_ORG_NOT_FOUND` — A new receiver's wallet organization does not exist, is not active, or has another document.\n\n`CREDIT_AMOUNT_MISMATCH` — The new receivers' shares don't add up to 100.\n\n`DEBIT_AMOUNT_MISMATCH` — The new payer's share is not 100.\n\n`WALLET_NOT_ACTIVE` — A new receiver's wallet is not active, or a new payer's is neither active nor pending activation.", "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_OPEN", "DEAL_END_AT_BEFORE_START_AT", "DEAL_START_AT_LOCKED", "DEAL_PAYMENT_METHOD_LOCKED", "DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT", "CREDIT_PARTY_DOCUMENT_MISMATCH_CONTRACT", "INVALID_PARTY_REALM_ORG", "PARTY_REALM_ORG_NOT_FOUND", "CREDIT_AMOUNT_MISMATCH", "DEBIT_AMOUNT_MISMATCH", "WALLET_NOT_ACTIVE" ], "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_OPEN", "origin": "BILLING", "message": "Deal is not open" } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm.\n\n`BILLING_P2P_NOT_ENABLED` — The deal is, or would become, paid by `P2P`, and P2P is not enabled for your organization.", "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", "BILLING_P2P_NOT_ENABLED" ], "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": "`CONTRACT_NOT_FOUND` — The organization has no contract with this ID.\n\n`DEAL_NOT_FOUND` — The contract has no deal with this ID.\n\n`WALLET_NOT_FOUND` — A new receiver's wallet does not exist.", "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": [ "CONTRACT_NOT_FOUND", "DEAL_NOT_FOUND", "WALLET_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": "CONTRACT_NOT_FOUND", "origin": "BILLING", "message": "Contract not found" } } } }, "422": { "description": "`DEAL_START_AT_INVALID` — The new `startAt` is before today or before the contract starts.\n\n`DEAL_END_AT_REQUIRED` — `endAt` was sent as `null`, and the contract has an end date.\n\n`DEAL_END_AT_INVALID` — The deal would end after the contract.\n\n`CREATE_INVOICE_ERROR` — The new `startAt` is today and the deal's first invoice could not be created.\n\n`BAD_REQUEST` — The body is invalid — a date that is not a date, a cron that is not `0 0 * *`, more than one payment method, a payer without the address or wallet the payment method needs — or 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": [ "DEAL_START_AT_INVALID", "DEAL_END_AT_REQUIRED", "DEAL_END_AT_INVALID", "CREATE_INVOICE_ERROR", "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": "DEAL_START_AT_INVALID", "origin": "BILLING", "message": "Start date is before contract start at or today" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/deals/{dealId}/cancel": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDealsByDealIdCancel", "summary": "Deprecated — Cancel a deal", "tags": [ "Deals" ], "x-p3-sidebar-order": 12, "description": "Deprecated: use `POST .../deals/{dealId}/cancel`; contracts are being removed.", "x-mint": { "content": "Cancels an open deal: it stops creating invoices.\n\nFor a PIX Automático or recurring PIX deal, the payer's authorization is canceled at the bank first; if that fails, the bank's error is returned (`origin` `BANKING`, with its own status and `code`) and nothing changes.\n\nThe body is optional: send `{}`, or no body and no `Content-Type`. With `cancelAllInvoices: true`, every invoice of the deal that is not paid or canceled yet is canceled. Otherwise the open invoice is closed — its boleto or PIX charge is issued and it stays payable — and only the closed invoices due more than a month from now are canceled. Paid invoices are never touched.\n\nThe `BILLING_DEAL_CANCELED` webhook event is sent (and `BILLING_INVOICE_CLOSED` for the invoice it closed, or `BILLING_INVOICE_PAID` when that invoice was already paid in full). Any member of the organization, or an admin of the realm, can cancel one; `updatedBy` is set to the ID of the authenticated caller. Answers the canceled deal." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the contract the deal belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal to cancel.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelAllInvoices": { "description": "`true`: cancel every invoice of the deal that is not paid or canceled yet. `false` or omitted: close the open invoice — it is issued and stays payable — and cancel only the closed invoices due more than a month from now.", "example": true, "type": "boolean" } } } } } }, "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": "CANCELED" }, "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).\n\n---\n\nExample: `[\"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.\n\n---\n\nExample: `[]`", "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-28T09:15: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" } }, "required": [ "id", "realm", "organization", "chargeType", "status", "firstChargeDate", "startAt", "endAt", "products", "paymentMethods", "secondaryPaymentMethods", "creditParties", "debitParties", "closingAt", "dueAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "A deal: what an organization charges a payer for, how and when." } } } }, "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 contract 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" } } } }, "409": { "description": "`DEAL_NOT_ACTIVE` — The deal is no longer open: it was already canceled, terminated, expired or revoked.", "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_ACTIVE" ], "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_ACTIVE", "origin": "BILLING", "message": "Deal is not active to perform this action" } } } }, "422": { "description": "`BAD_REQUEST` — `cancelAllInvoices` is not a boolean, or 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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoices", "summary": "List an organization's invoices", "tags": [ "Invoices" ], "x-p3-sidebar-order": 1, "description": "Lists the invoices of your organization, newest first by default.", "x-mint": { "content": "Read them as their issuer (`role=VENDOR`, the default) or as their payer (`role=BUYER`: the invoices other organizations issued to yours). Each invoice comes with the status the Portão 3 app shows (`displayStatus`), its deal's charge type and number of installments and, as the issuer, the payer as a customer of your organization (`customer`, `null` when none has the payer's document or it could not be looked up in time). As the payer, the issuer's receivers (`creditParties`) are not shown.\n\nFilter by status, payer document (`debitPartyDocuments`) or payer organization (`debitPartyOrgIds`: the organization of the payer's Portão 3 wallet, so a payer with no wallet is found by its document instead), the deal's charge type (`chargeType`), a text in the description and the due date (`startDueAt`/`endDueAt`); every list filter takes several values at once, repeated or comma-separated. 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`. To list one deal's invoices, use `GET .../deals/{dealId}/invoices`; to list one payer's, filter by `debitPartyOrgIds` (a payer with a Portão 3 wallet) or `debitPartyDocuments` (any payer).\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 invoices (or pays them, with `role=BUYER`).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "status", "in": "query", "required": false, "description": "Only invoices in these stored statuses (`OPEN`, `CLOSED`, `PAID`, `CANCELED`). Repeat the parameter or separate values with commas.\n\n---\n\nExample (comma-separated list): `?status=CLOSED,PAID`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ] } }, "style": "form", "explode": false }, { "name": "debitPartyDocuments", "in": "query", "required": false, "description": "Only invoices whose payer (the debit party) has one of these CPF/CNPJ documents, digits only (exact match).\n\n---\n\nExample (comma-separated list): `?debitPartyDocuments=11144477735,39053344705`", "schema": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "style": "form", "explode": false }, { "name": "debitPartyOrgIds", "in": "query", "required": false, "description": "Only invoices 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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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 invoices whose deal has one of these charge types (`SINGLE`, `RECURRENT`, `SUBSCRIPTION`).\n\n---\n\nExample: `?chargeType=SINGLE`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ] } }, "style": "form", "explode": false }, { "name": "description", "in": "query", "required": false, "description": "Only invoices whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 250 }, "example": "Mensalidade" }, { "name": "startDueAt", "in": "query", "required": false, "description": "Only invoices due on or after this moment, inclusive (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": "endDueAt", "in": "query", "required": false, "description": "Only invoices due on or before this moment, inclusive (ISO 8601 date or date-time).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-31T23:59:59.999Z" }, { "name": "role", "in": "query", "required": false, "description": "`VENDOR` (default): the invoices your organization issues. `BUYER`: the invoices your organization pays.", "schema": { "default": "VENDOR", "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" }, { "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 invoices by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "dueAt", "closingAt", "description", "status", "amount", "invoiceNumber" ] }, "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.", "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 invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "CLOSED" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "SCHEDULED" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "The deal's charge type: `SINGLE` (one invoice), `RECURRENT` (a fixed number of installments) or `SUBSCRIPTION` (renews until the deal ends).", "example": "RECURRENT" }, "totalInstallments": { "type": "integer", "description": "How many installments the deal has (`1` for a single charge). With `invoiceNumber`, it labels the installment (\"1/12\").", "example": 12 }, "customer": { "description": "The payer as a customer of your organization, found by the payer's document. `null` when no customer has that document, when it could not be looked up in time, and always when you read the invoice as its payer (`role=BUYER`).", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "format": "uuid" }, "name": { "type": "string", "example": "Maria Silva" } }, "required": [ "id", "name" ], "nullable": true }, "scheduled": { "type": "boolean", "description": "PIX Automático and recurring scheduled PIX only: `true` once the payment is scheduled with the payer's bank.", "example": true }, "pixInitiationStatement": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "`CREATED`: not scheduled with the payer's bank yet. `SCHEDULED`: will be charged on its date. `CANCELED`. `ERROR` / `SCHEDULE_ERROR`: the charge or the scheduling failed. `DONE`: paid.", "example": "SCHEDULED" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "description": "Why the charge failed, once a failure was recorded." } }, "required": [ "status" ], "description": "PIX Automático and recurring scheduled PIX only: where the payment stands." } }, "required": [ "allowedPaymentMethods", "amount", "chargeType", "closingAt", "createdAt", "createdBy", "customer", "deal", "dealName", "debitParties", "description", "displayStatus", "dueAt", "expiresAt", "external", "id", "invoiceNumber", "organization", "paymentStatus", "paymentsAttempts", "previousInvoiceId", "realm", "status", "totalInstallments", "updatedAt", "updatedBy" ], "description": "An invoice in a list." } }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of 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" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid — an unknown `status`, a `limit` out of range, a `next` that is not valid base64, or a removed parameter (`customerDocument`, `debitPartyDocument`, `debitPartyOrg`, `id`, `contractId`, `dealId`); `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": "description", "message": "Too big: expected string to have <=250 characters", "code": "DESCRIPTION_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:findInvoicesQuerySchema", "note": "`.refine(…)` constraint not represented (runtime-dependent value); root `z.preprocess(…)` step not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoices", "summary": "Create an invoice", "tags": [ "Invoices" ], "x-p3-sidebar-order": 4, "description": "Creates an invoice for a deal of your organization.", "x-mint": { "content": "The deal must be open. Its `RECURRENT` products become the invoice's entries — and its `ONE_TIME` products too when there is no `previousInvoiceId` — and the invoice amount is their sum. Without `invoiceNumber`, the invoice is the deal's next installment. When the deal closes its invoices on creation (`settings.disableOpenStatus`), or it is a `SUBSCRIPTION` deal whose `closingAt` is today or earlier, the invoice is closed at once and its boleto or PIX charge is issued. The `BILLING_INVOICE_CREATED` webhook event is sent (`BILLING_INVOICE_CLOSED` when it closes at once). A request sent twice creates two invoices.\n\nOnly the fields below are read; any other one is ignored — the status, the amount and the payment state always start fresh. Any member of the organization, or an admin of the realm, can create one; `createdBy` and `updatedBy` are set to the ID of the authenticated caller. Answers the invoice as stored." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal": { "type": "string", "format": "uuid", "description": "ID of the deal the invoice belongs to. The deal must be `OPEN`; its products become the invoice's entries.\n\nFormat: `UUID`", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "description": { "description": "The invoice's name. Up to 100 characters.", "example": "Mensalidade Plano Pro - 1/12", "type": "string", "maxLength": 100 }, "invoiceNumber": { "description": "The installment number. Omit it for the next number of the deal.", "example": 1, "type": "integer", "minimum": 1 }, "previousInvoiceId": { "description": "ID of the deal's previous invoice, for an installment after the first. Without it, the deal's one-time products are charged too. It is not kept: the invoice answers it empty.\n\nFormat: `UUID`", "example": "1c8d3b55-7a2f-4e4c-8b9f-6d3a2e1f0c8b", "type": "string", "format": "uuid" }, "allowedPaymentMethods": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "BANK_SLIP" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the main method.\n\n---\n\nExample: `[\"BANK_SLIP\",\"PIX\"]`" }, "closingAt": { "minLength": 1, "description": "When the invoice closes — stops gathering charges and issues its payment (ISO 8601 date or date-time).", "example": "2026-10-01T00:00:00.000Z", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "dueAt": { "minLength": 1, "description": "When the invoice is due (ISO 8601 date or date-time).", "example": "2026-10-10T00:00:00.000Z", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "minLength": 1, "description": "The last day the invoice's charge can be paid (ISO 8601 date or date-time).", "example": "2026-11-10T00:00:00.000Z", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "creditParties": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "description": "CPF or CNPJ, digits only.", "example": "12345678000195", "type": "string" }, "name": { "description": "Name of the receiver.", "example": "Empresa Exemplo Ltda", "type": "string" }, "email": { "description": "E-mail of the receiver.", "example": "financeiro@empresaexemplo.com.br", "type": "string" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the account is held: `P3`, a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account: `WALLET`, a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "description": "ID of the receiver's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "description": "ID of the receiver's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "account": { "type": "string", "minLength": 1, "description": "ID of the receiver's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d" }, "wallet": { "type": "string", "minLength": 1, "description": "ID of the wallet the money is paid into.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "bank", "type", "identifier" ] }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers must add up to exactly 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ] }, "description": "Who receives the money: one or more receivers." }, "debitParties": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "name": { "description": "Name of the payer. Required when the invoice is paid by boleto or PIX.", "example": "Maria Silva", "type": "string", "maxLength": 100 }, "document": { "description": "CPF or CNPJ of the payer, digits only. When sent, it must be valid.", "example": "11144477735", "type": "string" }, "email": { "description": "E-mail of the payer.", "example": "maria.silva@exemplo.com.br", "type": "string" }, "address": { "description": "Address of the payer. Required when the invoice is paid by boleto or PIX.", "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "description": "Up to 50 characters.", "example": "Sala 4", "type": "string" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "State abbreviation (UF).", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ] }, "bank": { "description": "`P3`: the payer pays from a Portão 3 account. Required when the invoice is paid by `P2P`.", "example": "P3", "type": "string", "enum": [ "P3" ] }, "type": { "description": "`WALLET`: the payer pays from a Portão 3 wallet. Required when the invoice is paid by `P2P`.", "example": "WALLET", "type": "string", "enum": [ "WALLET" ] }, "identifier": { "description": "The payer's Portão 3 account and wallet, the one a `P2P` charge debits. Required when the invoice is paid by `P2P`; it must not be the receiver's wallet.", "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "example": "5e0a1c2b-3d4f-4a6b-8c9d-0e1f2a3b4c5d" }, "account": { "type": "string", "minLength": 1, "example": "6b2c4d8e-1f3a-4b5c-9d7e-8f0a1b2c3d4e" }, "wallet": { "type": "string", "minLength": 1, "example": "9c3d5e7f-2a4b-4c6d-8e0f-1a2b3c4d5e6f" } }, "required": [ "realm", "organization", "account", "wallet" ] } } }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ] }, "description": "Who pays: exactly one payer." }, "fine": { "description": "Late fee charged after the due date.", "type": "object", "properties": { "amountType": { "type": "string", "enum": [ "FIXED_VALUE", "PERCENT" ], "description": "`FIXED_VALUE`: `amount` in centavos (at least 1). `PERCENT`: `amount` is a percentage of the invoice amount (0.0101 to 100).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives.", "example": 2 } }, "required": [ "amountType", "amount" ], "nullable": true }, "interest": { "description": "Interest charged after the due date.", "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": "`AMOUNT_*`: `amount` in centavos per day late (at least 1). `PERCENT_POINT_PER_DAY_*`: `amount` is a percentage per day late (0.0101 to 100). Calendar or working days.", "example": "PERCENT_POINT_PER_DAY_CALENDAR_DAYS" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives.", "example": 0.033 } }, "required": [ "amountType", "amount" ], "nullable": true }, "discount": { "description": "Discount for paying before the due date.", "type": "object", "properties": { "amountType": { "type": "string", "enum": [ "AMOUNT_PER_ANTECIPATION", "PERCENT_PER_ANTECIPATION" ], "description": "`AMOUNT_PER_ANTECIPATION`: `amount` in centavos (at least 1). `PERCENT_PER_ANTECIPATION`: `amount` is a percentage of the invoice amount (0.0101 to 100).", "example": "PERCENT_PER_ANTECIPATION" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives.", "example": 5 } }, "required": [ "amountType", "amount" ], "nullable": true } }, "required": [ "deal", "allowedPaymentMethods", "closingAt", "dueAt", "expiresAt", "creditParties", "debitParties" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "OPEN" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "OPEN" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "deal", "previousInvoiceId", "dealName", "description", "allowedPaymentMethods", "invoiceNumber", "closingAt", "dueAt", "expiresAt", "amount", "status", "displayStatus", "paymentStatus", "paymentsAttempts", "external", "debitParties", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "An invoice." } } } }, "400": { "description": "`DEAL_NOT_OPEN` — The deal was canceled, terminated, revoked or expired.\n\n`CREDIT_AMOUNT_MISMATCH` — The receivers' shares don't add up to 100.\n\n`DEBIT_AMOUNT_MISMATCH` — The payer's share is not 100.\n\n`CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT` — The payer's wallet is also a receiver's.", "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_OPEN", "CREDIT_AMOUNT_MISMATCH", "DEBIT_AMOUNT_MISMATCH", "CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT" ], "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_OPEN", "origin": "BILLING", "message": "Deal must be open to create an invoice" } } } }, "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` — The body is invalid — a missing field, a date that is not a date, a fine, interest or discount out of range, a payer without the name or address a boleto or PIX charge needs, an invalid payer document, or a payer without the wallet a `P2P` charge debits — or 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": "deal", "message": "Invalid input: expected string, received undefined", "code": "DEAL_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/deals/{dealId}/invoices": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdDealsByDealIdInvoices", "summary": "List a deal's invoices", "tags": [ "Invoices" ], "x-p3-sidebar-order": 2, "description": "Lists the invoices of one deal, newest first by default.", "x-mint": { "content": "The same list, filters, sorting and paging as `GET .../invoices`, narrowed to the deal of your organization — whether or not it has a contract. A deal ID that matches no deal of your organization answers an empty list.\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 invoices.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal whose invoices you list. An ID that matches no deal of the organization answers an empty list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, { "name": "status", "in": "query", "required": false, "description": "Only invoices in these stored statuses (`OPEN`, `CLOSED`, `PAID`, `CANCELED`). Repeat the parameter or separate values with commas.\n\n---\n\nExample (comma-separated list): `?status=CLOSED,PAID`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ] } }, "style": "form", "explode": false }, { "name": "debitPartyDocuments", "in": "query", "required": false, "description": "Only invoices whose payer (the debit party) has one of these CPF/CNPJ documents, digits only (exact match).\n\n---\n\nExample (comma-separated list): `?debitPartyDocuments=11144477735,39053344705`", "schema": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "style": "form", "explode": false }, { "name": "debitPartyOrgIds", "in": "query", "required": false, "description": "Only invoices 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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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 invoices whose deal has one of these charge types (`SINGLE`, `RECURRENT`, `SUBSCRIPTION`).\n\n---\n\nExample: `?chargeType=SINGLE`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ] } }, "style": "form", "explode": false }, { "name": "description", "in": "query", "required": false, "description": "Only invoices whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 250 }, "example": "Mensalidade" }, { "name": "startDueAt", "in": "query", "required": false, "description": "Only invoices due on or after this moment, inclusive (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": "endDueAt", "in": "query", "required": false, "description": "Only invoices due on or before this moment, inclusive (ISO 8601 date or date-time).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-31T23:59:59.999Z" }, { "name": "role", "in": "query", "required": false, "description": "`VENDOR` (default): the invoices your organization issues. `BUYER`: the invoices your organization pays.", "schema": { "default": "VENDOR", "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" }, { "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 invoices by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "dueAt", "closingAt", "description", "status", "amount", "invoiceNumber" ] }, "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.", "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 invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "CLOSED" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "SCHEDULED" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "The deal's charge type: `SINGLE` (one invoice), `RECURRENT` (a fixed number of installments) or `SUBSCRIPTION` (renews until the deal ends).", "example": "RECURRENT" }, "totalInstallments": { "type": "integer", "description": "How many installments the deal has (`1` for a single charge). With `invoiceNumber`, it labels the installment (\"1/12\").", "example": 12 }, "customer": { "description": "The payer as a customer of your organization, found by the payer's document. `null` when no customer has that document, when it could not be looked up in time, and always when you read the invoice as its payer (`role=BUYER`).", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "format": "uuid" }, "name": { "type": "string", "example": "Maria Silva" } }, "required": [ "id", "name" ], "nullable": true }, "scheduled": { "type": "boolean", "description": "PIX Automático and recurring scheduled PIX only: `true` once the payment is scheduled with the payer's bank.", "example": true }, "pixInitiationStatement": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "`CREATED`: not scheduled with the payer's bank yet. `SCHEDULED`: will be charged on its date. `CANCELED`. `ERROR` / `SCHEDULE_ERROR`: the charge or the scheduling failed. `DONE`: paid.", "example": "SCHEDULED" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "description": "Why the charge failed, once a failure was recorded." } }, "required": [ "status" ], "description": "PIX Automático and recurring scheduled PIX only: where the payment stands." } }, "required": [ "allowedPaymentMethods", "amount", "chargeType", "closingAt", "createdAt", "createdBy", "customer", "deal", "dealName", "debitParties", "description", "displayStatus", "dueAt", "expiresAt", "external", "id", "invoiceNumber", "organization", "paymentStatus", "paymentsAttempts", "previousInvoiceId", "realm", "status", "totalInstallments", "updatedAt", "updatedBy" ], "description": "An invoice in a list." } }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of 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" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as a `dealId` that is not a valid ID, a `limit` out of range or a removed parameter; `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": "description", "message": "Too big: expected string to have <=250 characters", "code": "DESCRIPTION_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:findInvoicesQuerySchema", "note": "`.refine(…)` constraint not represented (runtime-dependent value); root `z.preprocess(…)` step not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceId", "summary": "Get an invoice", "tags": [ "Invoices" ], "x-p3-sidebar-order": 5, "description": "Returns one invoice, with its customer, totals, statements and products.", "x-mint": { "content": "Read it as its issuer (`role=VENDOR`, the default) or as its payer (`role=BUYER`, when your organization is the invoice's payer — the issuer's `creditParties` are not shown then). `customer` is the payer as a customer of the issuing organization, with the link to its page in the customer portal — `null` as the payer, when no customer has the payer's document, or when it could not be looked up in time; the invoice is answered either way. `financialValues` adds up the invoice's statements, `statements` lists them, and `products` groups the invoice's open entries by product.\n\nAny member of the organization, or an admin of the realm, can read it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice (or pays it, with `role=BUYER`).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "role", "in": "query", "required": false, "description": "`VENDOR` (default): read an invoice your organization issued. `BUYER`: read an invoice your organization pays.", "schema": { "default": "VENDOR", "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "CLOSED" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "SCHEDULED" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "The deal's charge type: `SINGLE` (one invoice), `RECURRENT` (a fixed number of installments) or `SUBSCRIPTION` (renews until the deal ends).", "example": "RECURRENT" }, "totalInstallments": { "type": "integer", "description": "How many installments the deal has (`1` for a single charge).", "example": 12 }, "customer": { "description": "The payer as a customer of your organization, found by the payer's document, with their portal link. `null` when no customer has that document, when it could not be looked up in time, and always when you read the invoice as its payer (`role=BUYER`).", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "format": "uuid" }, "name": { "type": "string", "example": "Maria Silva" }, "url": { "type": "string", "nullable": true, "description": "Link to the customer's portal page, where they see and pay their invoices. `null` when the customer has none.", "example": "https://portal.example.com/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" } }, "required": [ "id", "name", "url" ], "nullable": true }, "financialValues": { "type": "object", "properties": { "total": { "type": "integer", "description": "The invoice amount.", "example": 15000 }, "totalPaid": { "type": "integer", "description": "The invoice amount once the invoice is `PAID`, `0` before. A partial payment does not count here: see `statements`.", "example": 0 }, "outstandingBalance": { "type": "integer", "description": "`total` minus `totalPaid`.", "example": 15000 } }, "required": [ "total", "totalPaid", "outstandingBalance" ], "description": "The invoice's totals." }, "statements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "BANK_SLIP_CREATED" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Boleto da fatura de outubro" }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "DONE" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." }, "description": "The invoice's ledger: what it owes, its payment instruments (with the PIX code or the boleto line) and its payments, in no particular order." }, "products": { "type": "array", "items": { "type": "object", "properties": { "productName": { "type": "string", "example": "Plano Pro" }, "unitPrice": { "type": "number", "description": "Price of one unit, in centavos.", "example": 15000 }, "quantity": { "type": "integer", "description": "How many units of it the invoice charges.", "example": 1 } }, "required": [ "productName", "unitPrice", "quantity" ], "description": "A product charged on the invoice, grouped by name and price." }, "description": "What the invoice charges: its own charges (not deleted), grouped by name and price." } }, "required": [ "allowedPaymentMethods", "amount", "chargeType", "closingAt", "createdAt", "createdBy", "customer", "deal", "dealName", "debitParties", "description", "displayStatus", "dueAt", "expiresAt", "external", "financialValues", "id", "invoiceNumber", "organization", "paymentStatus", "paymentsAttempts", "previousInvoiceId", "products", "realm", "statements", "status", "totalInstallments", "updatedAt", "updatedBy" ], "description": "An invoice, with its customer, totals, ledger and products." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization (or, with `role=BUYER`, is paid by it).", "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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID, or `role` is unknown; `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": "role", "message": "Invalid option: expected one of \"VENDOR\"|\"BUYER\"", "code": "ROLE_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceId", "summary": "Update an invoice", "tags": [ "Invoices" ], "x-p3-sidebar-order": 6, "description": "Changes an open invoice your organization issued.", "x-mint": { "content": "Send only what changes: every field is optional, and an omitted one keeps its value. `creditParties` and `debitParties` replace the whole side they describe, and each side's shares must add up to 100. When you send `allowedPaymentMethods`, the payer — the one sent with it, or else the current one — must have what those methods need. Only an `OPEN` invoice can be changed: once it closes, its boleto or PIX charge is already issued. The invoice amount and its entries don't change here — add or delete entries for that.\n\nAny member of the organization, or an admin of the realm, can change it; `updatedBy` is set to the ID of the authenticated caller. Answers the invoice as stored." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowedPaymentMethods": { "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the main method. Omit it to keep the current ones.\n\n---\n\nExample: `[\"BANK_SLIP\",\"PIX\"]`", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "BANK_SLIP" } }, "closingAt": { "description": "When the invoice closes (ISO 8601 date or date-time). Omit it to keep the current one.", "example": "2026-10-01T00:00:00.000Z", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "minLength": 1 }, "dueAt": { "description": "When the invoice is due (ISO 8601 date or date-time). Omit it to keep the current one.", "example": "2026-10-10T00:00:00.000Z", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "minLength": 1 }, "expiresAt": { "description": "The last day the invoice's charge can be paid (ISO 8601 date or date-time). Omit it to keep the current one.", "example": "2026-11-10T00:00:00.000Z", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "minLength": 1 }, "creditParties": { "description": "Who receives the money — replaces every receiver. Omit it to keep the current ones.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "description": "CPF or CNPJ, digits only.", "example": "12345678000195", "type": "string" }, "name": { "description": "Name of the receiver.", "example": "Empresa Exemplo Ltda", "type": "string" }, "email": { "description": "E-mail of the receiver.", "example": "financeiro@empresaexemplo.com.br", "type": "string" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the account is held: `P3`, a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account: `WALLET`, a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "description": "ID of the receiver's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "description": "ID of the receiver's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "account": { "type": "string", "minLength": 1, "description": "ID of the receiver's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d" }, "wallet": { "type": "string", "minLength": 1, "description": "ID of the wallet the money is paid into.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b" } }, "required": [ "realm", "organization", "account", "wallet" ] } }, "required": [ "bank", "type", "identifier" ] }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers must add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ] } }, "debitParties": { "description": "Who pays: exactly one payer — replaces the current one. Omit it to keep it.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "name": { "description": "Name of the payer. Required when the invoice is paid by boleto or PIX.", "example": "Maria Silva", "type": "string", "maxLength": 100 }, "document": { "description": "CPF or CNPJ of the payer, digits only. Required, and must be valid, when the invoice is paid by boleto or PIX.", "example": "11144477735", "type": "string" }, "email": { "description": "E-mail of the payer.", "example": "maria.silva@exemplo.com.br", "type": "string" }, "address": { "description": "Address of the payer. Required when the invoice is paid by boleto or PIX.", "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "example": "Sala 4", "type": "string" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ] }, "bank": { "description": "`P3`: the payer pays from a Portão 3 account. Required when the invoice is paid by `P2P`.", "example": "P3", "type": "string", "enum": [ "P3" ] }, "type": { "description": "`WALLET`: the payer pays from a Portão 3 wallet. Required when the invoice is paid by `P2P`.", "example": "WALLET", "type": "string", "enum": [ "WALLET" ] }, "identifier": { "description": "The payer's Portão 3 account and wallet, the one a `P2P` charge debits. Required when the payment methods sent include `P2P`.", "type": "object", "properties": { "realm": { "type": "string", "minLength": 1, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organization": { "type": "string", "minLength": 1, "example": "5e0a1c2b-3d4f-4a6b-8c9d-0e1f2a3b4c5d" }, "account": { "type": "string", "minLength": 1, "example": "6b2c4d8e-1f3a-4b5c-9d7e-8f0a1b2c3d4e" }, "wallet": { "type": "string", "minLength": 1, "example": "9c3d5e7f-2a4b-4c6d-8e0f-1a2b3c4d5e6f" } }, "required": [ "realm", "organization", "account", "wallet" ] } } }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "OPEN" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "OPEN" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "deal", "previousInvoiceId", "dealName", "description", "allowedPaymentMethods", "invoiceNumber", "closingAt", "dueAt", "expiresAt", "amount", "status", "displayStatus", "paymentStatus", "paymentsAttempts", "external", "debitParties", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "An invoice." } } } }, "400": { "description": "`CREDIT_AMOUNT_MISMATCH` — The receivers' shares don't add up to 100.\n\n`DEBIT_AMOUNT_MISMATCH` — The payer's share is not 100.", "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": [ "CREDIT_AMOUNT_MISMATCH", "DEBIT_AMOUNT_MISMATCH" ], "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": "CREDIT_AMOUNT_MISMATCH", "origin": "BILLING", "message": "Credit parties amount must be 100%" } } } }, "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": "`INVOICE_NOT_FOUND` — The organization issued no invoice 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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_NOT_OPEN` — The invoice is closed, paid or canceled.\n\n`BAD_REQUEST` — The body is invalid — an unknown payment method, a date that is not a date, more than one payer, a payer without what the payment methods sent need — or 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": [ "INVOICE_NOT_OPEN", "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": "INVOICE_NOT_OPEN", "origin": "BILLING", "message": "invoice is not open for changes" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.transform(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdCancel", "summary": "Cancel an invoice", "tags": [ "Invoices" ], "x-p3-sidebar-order": 7, "description": "Cancels a closed invoice your organization issued.", "x-mint": { "content": "Only a `CLOSED` invoice — issued and not paid yet — can be canceled. A scheduled PIX payment of the invoice is canceled with it; for PIX Automático, once no invoice of the deal is left to pay, the payer's authorization is released too. The first payment of a PIX Automático can only be canceled together with its authorization: cancel the deal instead. A boleto or PIX charge already issued for it is not canceled, and no webhook event is sent.\n\nAny member of the organization, or an admin of the realm, can cancel it. Answers the invoice as stored, now `CANCELED`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice to cancel.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "CANCELED" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "CANCELED" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "deal", "previousInvoiceId", "dealName", "description", "allowedPaymentMethods", "invoiceNumber", "closingAt", "dueAt", "expiresAt", "amount", "status", "displayStatus", "paymentStatus", "paymentsAttempts", "external", "debitParties", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "An invoice." } } } }, "400": { "description": "`INVOICE_NOT_CLOSED` — The invoice is open, paid or already canceled.", "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": [ "INVOICE_NOT_CLOSED" ], "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": "INVOICE_NOT_CLOSED", "origin": "BILLING", "message": "Only closed invoices can be canceled" } } } }, "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": "`INVOICE_NOT_FOUND` — The organization issued no invoice 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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE` — The invoice is the first payment of a PIX Automático whose authorization is still pending.\n\n`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": [ "PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE", "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": "PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE", "origin": "BILLING", "message": "The first payment of a PIX Automático can only be canceled together with its consent. Cancel the deal instead." } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/export": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesExport", "summary": "Export invoices", "tags": [ "Invoices" ], "x-p3-sidebar-order": 8, "description": "Exports the invoices your organization issued as a CSV or XLSX file.", "x-mint": { "content": "The file has every invoice that matches the same filters and order as the invoice list — plus `contractId` and `dealId`, to export one contract's or one deal's invoices — one per row, with six columns whose headers are in Portuguese: `Descrição` (the description, or the deal's), `Cliente` (the payer's name), `Quantidade` (the installment, as `1/12`, or `Única`), `Data de Vencimento` (the due date, as `DD/MM/YYYY`, UTC), `Status` (the `displayStatus`, in Portuguese) and `Valor` (the invoice amount, in centavos). When no invoice matches, the file has the header and one empty row.\n\n`?type=csv` answers a UTF-8 CSV file; `?type=xlsx` an Excel workbook, base64-encoded. An export is limited to 50,000 invoices and 4 MiB: narrow the filters to export more. Any member of the organization, or an admin of the realm, can export them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 invoices you export.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "type", "in": "query", "required": true, "description": "Format of the exported file.", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "example": "csv" }, { "name": "encoding", "in": "query", "required": false, "description": "How an `xlsx` file is encoded in the response body: always `base64`, the default. A `csv` file is always sent as plain text.", "schema": { "default": "base64", "type": "string", "enum": [ "base64" ] }, "example": "base64" }, { "name": "status", "in": "query", "required": false, "description": "Only invoices in these stored statuses (`OPEN`, `CLOSED`, `PAID`, `CANCELED`). Repeat the parameter or separate values with commas.\n\n---\n\nExample (comma-separated list): `?status=CLOSED,PAID`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ] } }, "style": "form", "explode": false }, { "name": "debitPartyDocuments", "in": "query", "required": false, "description": "Only invoices whose payer (the debit party) has one of these CPF/CNPJ documents, digits only (exact match).\n\n---\n\nExample (comma-separated list): `?debitPartyDocuments=11144477735,39053344705`", "schema": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "style": "form", "explode": false }, { "name": "debitPartyOrgIds", "in": "query", "required": false, "description": "Only invoices 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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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 invoices whose deal has one of these charge types (`SINGLE`, `RECURRENT`, `SUBSCRIPTION`).\n\n---\n\nExample: `?chargeType=SINGLE`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ] } }, "style": "form", "explode": false }, { "name": "contractId", "in": "query", "required": false, "description": "Only invoices of this contract.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "dealId", "in": "query", "required": false, "description": "Only invoices of this deal.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, { "name": "description", "in": "query", "required": false, "description": "Only invoices whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 250 }, "example": "Mensalidade" }, { "name": "startDueAt", "in": "query", "required": false, "description": "Only invoices due on or after this moment, inclusive (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": "endDueAt", "in": "query", "required": false, "description": "Only invoices due on or before this moment, inclusive (ISO 8601 date or date-time).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-31T23:59:59.999Z" }, { "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 invoices by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "dueAt", "closingAt", "description", "status", "amount", "invoiceNumber" ] }, "example": "createdAt" } ], "responses": { "200": { "description": "`application/csv` — The invoices as a UTF-8 CSV file, when `type` is `csv`.\n\n`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — The Excel workbook, base64-encoded, when `type` is `xlsx`.", "content": { "application/csv": { "schema": { "type": "string", "description": "The invoices as a UTF-8 CSV file, when `type` is `csv`." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "byte", "description": "The Excel workbook, base64-encoded, when `type` is `xlsx`." } } } }, "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": "`EXPORT_TOO_LARGE` — More than 50,000 invoices match, or the file would exceed 4 MiB.\n\n`BAD_REQUEST` — A path or query parameter is invalid, such as a missing `type` or a removed parameter; `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": [ "EXPORT_TOO_LARGE", "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": "EXPORT_TOO_LARGE", "origin": "BILLING", "message": "This export is too large to generate in a single request. Narrow the filters (for example a shorter date range) and try again." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:exportInvoicesQuerySchema", "note": "root `z.preprocess(…)` step not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/invoices": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdInvoices", "summary": "Deprecated — List a contract's invoices", "tags": [ "Invoices" ], "x-p3-sidebar-order": 9, "description": "Deprecated: use `GET .../invoices`, filtering by `debitPartyOrgIds` or `debitPartyDocuments`; contracts are being removed.", "x-mint": { "content": "Lists the invoices of one contract, newest first by default. The same list, filters, sorting and paging as `GET .../invoices`, narrowed to the contract. A contract ID that matches no contract of the organization answers an empty list.\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 invoices.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the contract whose invoices you list. An ID that matches no contract of the organization answers an empty list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "status", "in": "query", "required": false, "description": "Only invoices in these stored statuses (`OPEN`, `CLOSED`, `PAID`, `CANCELED`). Repeat the parameter or separate values with commas.\n\n---\n\nExample (comma-separated list): `?status=CLOSED,PAID`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ] } }, "style": "form", "explode": false }, { "name": "debitPartyDocuments", "in": "query", "required": false, "description": "Only invoices whose payer (the debit party) has one of these CPF/CNPJ documents, digits only (exact match).\n\n---\n\nExample (comma-separated list): `?debitPartyDocuments=11144477735,39053344705`", "schema": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "style": "form", "explode": false }, { "name": "debitPartyOrgIds", "in": "query", "required": false, "description": "Only invoices 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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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 invoices whose deal has one of these charge types (`SINGLE`, `RECURRENT`, `SUBSCRIPTION`).\n\n---\n\nExample: `?chargeType=SINGLE`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ] } }, "style": "form", "explode": false }, { "name": "description", "in": "query", "required": false, "description": "Only invoices whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 250 }, "example": "Mensalidade" }, { "name": "startDueAt", "in": "query", "required": false, "description": "Only invoices due on or after this moment, inclusive (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": "endDueAt", "in": "query", "required": false, "description": "Only invoices due on or before this moment, inclusive (ISO 8601 date or date-time).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-31T23:59:59.999Z" }, { "name": "role", "in": "query", "required": false, "description": "`VENDOR` (default): the invoices your organization issues. `BUYER`: the invoices your organization pays.", "schema": { "default": "VENDOR", "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" }, { "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 invoices by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "dueAt", "closingAt", "description", "status", "amount", "invoiceNumber" ] }, "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.", "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 invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "CLOSED" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "SCHEDULED" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "The deal's charge type: `SINGLE` (one invoice), `RECURRENT` (a fixed number of installments) or `SUBSCRIPTION` (renews until the deal ends).", "example": "RECURRENT" }, "totalInstallments": { "type": "integer", "description": "How many installments the deal has (`1` for a single charge). With `invoiceNumber`, it labels the installment (\"1/12\").", "example": 12 }, "customer": { "description": "The payer as a customer of your organization, found by the payer's document. `null` when no customer has that document, when it could not be looked up in time, and always when you read the invoice as its payer (`role=BUYER`).", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "format": "uuid" }, "name": { "type": "string", "example": "Maria Silva" } }, "required": [ "id", "name" ], "nullable": true }, "scheduled": { "type": "boolean", "description": "PIX Automático and recurring scheduled PIX only: `true` once the payment is scheduled with the payer's bank.", "example": true }, "pixInitiationStatement": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "`CREATED`: not scheduled with the payer's bank yet. `SCHEDULED`: will be charged on its date. `CANCELED`. `ERROR` / `SCHEDULE_ERROR`: the charge or the scheduling failed. `DONE`: paid.", "example": "SCHEDULED" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "description": "Why the charge failed, once a failure was recorded." } }, "required": [ "status" ], "description": "PIX Automático and recurring scheduled PIX only: where the payment stands." } }, "required": [ "allowedPaymentMethods", "amount", "chargeType", "closingAt", "createdAt", "createdBy", "customer", "deal", "dealName", "debitParties", "description", "displayStatus", "dueAt", "expiresAt", "external", "id", "invoiceNumber", "organization", "paymentStatus", "paymentsAttempts", "previousInvoiceId", "realm", "status", "totalInstallments", "updatedAt", "updatedBy" ], "description": "An invoice in a list." } }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of 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" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as a `contractId` that is not a valid ID, a `limit` out of range or a removed parameter; `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": "description", "message": "Too big: expected string to have <=250 characters", "code": "DESCRIPTION_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:findInvoicesQuerySchema", "note": "`.refine(…)` constraint not represented (runtime-dependent value); root `z.preprocess(…)` step not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/deals/{dealId}/invoices": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDealsByDealIdInvoices", "summary": "Deprecated — List a deal's invoices", "tags": [ "Invoices" ], "x-p3-sidebar-order": 10, "description": "Deprecated: use `GET .../deals/{dealId}/invoices`; contracts are being removed.", "x-mint": { "content": "Lists the invoices of one deal, newest first by default. The same list, filters, sorting and paging as `GET .../invoices`, narrowed to the deal. A deal ID that matches no deal of the contract answers an empty list.\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 invoices.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "contractId", "in": "path", "required": true, "description": "ID of the deal's contract.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d" }, { "name": "dealId", "in": "path", "required": true, "description": "ID of the deal whose invoices you list. An ID that matches no deal of the contract answers an empty list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, { "name": "status", "in": "query", "required": false, "description": "Only invoices in these stored statuses (`OPEN`, `CLOSED`, `PAID`, `CANCELED`). Repeat the parameter or separate values with commas.\n\n---\n\nExample (comma-separated list): `?status=CLOSED,PAID`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ] } }, "style": "form", "explode": false }, { "name": "debitPartyDocuments", "in": "query", "required": false, "description": "Only invoices whose payer (the debit party) has one of these CPF/CNPJ documents, digits only (exact match).\n\n---\n\nExample (comma-separated list): `?debitPartyDocuments=11144477735,39053344705`", "schema": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "style": "form", "explode": false }, { "name": "debitPartyOrgIds", "in": "query", "required": false, "description": "Only invoices 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.\n\nFormat: `UUID`\n\n---\n\nExample: `?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 invoices whose deal has one of these charge types (`SINGLE`, `RECURRENT`, `SUBSCRIPTION`).\n\n---\n\nExample: `?chargeType=SINGLE`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ] } }, "style": "form", "explode": false }, { "name": "description", "in": "query", "required": false, "description": "Only invoices whose name contains this text (case-insensitive).", "schema": { "type": "string", "maxLength": 250 }, "example": "Mensalidade" }, { "name": "startDueAt", "in": "query", "required": false, "description": "Only invoices due on or after this moment, inclusive (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": "endDueAt", "in": "query", "required": false, "description": "Only invoices due on or before this moment, inclusive (ISO 8601 date or date-time).", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-31T23:59:59.999Z" }, { "name": "role", "in": "query", "required": false, "description": "`VENDOR` (default): the invoices your organization issues. `BUYER`: the invoices your organization pays.", "schema": { "default": "VENDOR", "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" }, { "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 invoices by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "dueAt", "closingAt", "description", "status", "amount", "invoiceNumber" ] }, "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.", "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 invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "contract": { "type": "string", "description": "ID of the invoice's contract. Absent on an invoice of a deal created without a contract.", "example": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d", "format": "uuid" }, "deal": { "type": "string", "description": "ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`.", "example": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f", "format": "uuid" }, "previousInvoiceId": { "type": "string", "description": "Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.", "example": "" }, "dealName": { "type": "string", "description": "The deal's description. Empty when the invoice has none.", "example": "Mensalidade Plano Pro" }, "description": { "type": "string", "description": "The invoice's name. Empty when it has none (show `dealName` instead).", "example": "Mensalidade Plano Pro - 1/12" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX_AUTOMATIC", "PIX", "P2P" ], "example": "PIX_AUTOMATIC" }, "description": "How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method.\n\n---\n\nExample: `[\"PIX_AUTOMATIC\",\"PIX\"]`" }, "invoiceNumber": { "type": "integer", "description": "The installment number, from 1.", "example": 1 }, "closingAt": { "type": "string", "description": "When the invoice closes: it stops gathering charges and its payment is issued.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "dueAt": { "type": "string", "description": "When the invoice is due.", "example": "2026-10-10T00:00:00.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "The last day the invoice's charge can be paid.", "example": "2026-11-10T00:00:00.000Z", "format": "date-time" }, "paidAt": { "type": "string", "description": "When the invoice was paid. Absent until it is.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "amount": { "type": "integer", "description": "Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges.", "example": 15000 }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED", "PAID", "CANCELED" ], "description": "The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`.", "example": "CLOSED" }, "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 on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `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 did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it).", "example": "SCHEDULED" }, "paymentStatus": { "type": "string", "enum": [ "NONE", "PENDING", "PROCESSING", "PROCESSED", "FAILED" ], "description": "Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice.", "example": "NONE" }, "paymentsAttempts": { "type": "integer", "description": "How many times the automatic P2P charge was attempted.", "example": 0 }, "fine": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Late fee charged after the due date, when the deal has one." }, "interest": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Interest charged after the due date, when the deal has it." }, "discount": { "type": "object", "properties": { "amountType": { "type": "string", "description": "How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount).", "example": "PERCENT" }, "amount": { "type": "number", "description": "The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others.", "example": 2 } }, "required": [ "amountType", "amount" ], "description": "Discount for paying early, when the deal has one." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto created for the invoice.", "example": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge created for the invoice.", "example": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d" } }, "description": "IDs of the invoice's boleto and PIX charge, once created." }, "creditParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "12345678000195" }, "name": { "type": "string", "example": "Empresa Exemplo Ltda" }, "email": { "type": "string", "example": "financeiro@empresaexemplo.com.br" }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the party's account is held. `P3`: a Portão 3 account.", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of account. `WALLET`: a Portão 3 wallet.", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The account and wallet the money is paid into." } }, "required": [ "name", "bank", "type", "identifier" ], "description": "Who receives the invoice's money." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The receiver's share. The shares of all receivers add up to 100.", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "A share of the invoice that goes to one receiver." }, "description": "Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`)." }, "debitParties": { "type": "array", "items": { "type": "object", "properties": { "partyAccount": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF or CNPJ, digits only.", "example": "11144477735" }, "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria.silva@exemplo.com.br" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Rua das Flores" }, "number": { "type": "string", "example": "123" }, "complement": { "type": "string", "example": "Sala 4" }, "neighborhood": { "type": "string", "example": "Centro" }, "city": { "type": "string", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter state 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 address. Present when the invoice is paid by boleto or PIX charge." }, "bank": { "type": "string", "enum": [ "P3" ], "description": "Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`).", "example": "P3" }, "type": { "type": "string", "enum": [ "WALLET" ], "description": "Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`).", "example": "WALLET" }, "identifier": { "type": "object", "properties": { "realm": { "type": "string", "description": "ID of the party's realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the party's organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "account": { "type": "string", "description": "ID of the party's account.", "example": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d", "format": "uuid" }, "wallet": { "type": "string", "description": "ID of the party's wallet.", "example": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b", "format": "uuid" } }, "required": [ "realm", "organization", "account", "wallet" ], "description": "The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P)." } }, "required": [ "name" ], "description": "Who pays the invoice." }, "unit": { "type": "string", "enum": [ "PERCENTAGE" ], "description": "`PERCENTAGE`: `amount` is a share of the invoice amount, in percent.", "example": "PERCENTAGE" }, "amount": { "type": "number", "description": "The payer's share: always 100 (an invoice has one payer).", "example": 100 } }, "required": [ "partyAccount", "unit", "amount" ], "description": "The invoice's payer and its share." }, "description": "Who pays: one payer." }, "createdBy": { "type": "string", "description": "Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "updatedBy": { "type": "string", "description": "Who last changed the invoice.", "example": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f" }, "createdAt": { "type": "string", "description": "When the invoice was created.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the invoice was created. It does not move when the invoice changes.", "example": "2026-09-01T00:00:00.000Z", "format": "date-time" }, "chargeType": { "type": "string", "enum": [ "SINGLE", "RECURRENT", "SUBSCRIPTION" ], "description": "The deal's charge type: `SINGLE` (one invoice), `RECURRENT` (a fixed number of installments) or `SUBSCRIPTION` (renews until the deal ends).", "example": "RECURRENT" }, "totalInstallments": { "type": "integer", "description": "How many installments the deal has (`1` for a single charge). With `invoiceNumber`, it labels the installment (\"1/12\").", "example": 12 }, "customer": { "description": "The payer as a customer of your organization, found by the payer's document. `null` when no customer has that document, when it could not be looked up in time, and always when you read the invoice as its payer (`role=BUYER`).", "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "format": "uuid" }, "name": { "type": "string", "example": "Maria Silva" } }, "required": [ "id", "name" ], "nullable": true }, "scheduled": { "type": "boolean", "description": "PIX Automático and recurring scheduled PIX only: `true` once the payment is scheduled with the payer's bank.", "example": true }, "pixInitiationStatement": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "`CREATED`: not scheduled with the payer's bank yet. `SCHEDULED`: will be charged on its date. `CANCELED`. `ERROR` / `SCHEDULE_ERROR`: the charge or the scheduling failed. `DONE`: paid.", "example": "SCHEDULED" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "description": "Why the charge failed, once a failure was recorded." } }, "required": [ "status" ], "description": "PIX Automático and recurring scheduled PIX only: where the payment stands." } }, "required": [ "allowedPaymentMethods", "amount", "chargeType", "closingAt", "createdAt", "createdBy", "customer", "deal", "dealName", "debitParties", "description", "displayStatus", "dueAt", "expiresAt", "external", "id", "invoiceNumber", "organization", "paymentStatus", "paymentsAttempts", "previousInvoiceId", "realm", "status", "totalInstallments", "updatedAt", "updatedBy" ], "description": "An invoice in a list." } }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of 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" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as a `dealId` that is not a valid ID, a `limit` out of range or a removed parameter; `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": "description", "message": "Too big: expected string to have <=250 characters", "code": "DESCRIPTION_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "querySource": "route:findInvoicesQuerySchema", "note": "`.refine(…)` constraint not represented (runtime-dependent value); root `z.preprocess(…)` step not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdEntries", "summary": "List an invoice's entries", "tags": [ "Invoice Entries" ], "x-p3-sidebar-order": 1, "description": "Lists the entries of an invoice, newest first: the products and services the payer purchased, which add up to the invoice amount.", "x-mint": { "content": "An invoice entry is one line item of the invoice — a product or service the payer purchased, with its amount — and the invoice amount is the sum of its `OPEN` entries. Entries are created automatically from the products of the deal when the invoice is created, and `POST .../entries` adds more: an on-demand charge for that invoice's period. Deleted entries stay in the list with `status` `DELETED` and no longer count; filter with `status`.\n\nRead the invoice as its issuer (`role=VENDOR`, the default) or as its payer (`role=BUYER`, when your organization is the invoice's payer). Any member of the organization, or an admin of the realm, can list them. Page with `limit` + `next`. With `details=true` the entries are grouped by identifier instead of listed one by one: see that parameter." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice, or the one that pays it when `role` is `BUYER`.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice whose entries you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "status", "in": "query", "required": false, "description": "Only the entries in this status. `OPEN`: the ones that count toward the invoice amount. `DELETED`: the ones that were deleted. Omit it to list both.", "schema": { "type": "string", "enum": [ "OPEN", "DELETED" ] }, "example": "OPEN" }, { "name": "details", "in": "query", "required": false, "description": "Send `true` (or the bare `?details`) to group the entries by `identifier`, ignoring case, instead of listing each one. Each item then stands for one identifier: its `amount` is the sum of that identifier's `OPEN` entries and its `createdAt` the creation time of one of them. The other fields of a grouped item are placeholders, not the values of its entries, so don't read them.", "schema": { "type": "string" }, "example": "true" }, { "name": "role", "in": "query", "required": false, "description": "Your side of the invoice. `VENDOR` (the default): your organization issued it. `BUYER`: your organization is the invoice's payer.", "schema": { "default": "VENDOR", "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–1000. Defaults to 15.", "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.", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9+/]+={0,2}$" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } ], "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 entry.", "example": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90", "format": "uuid" }, "identifier": { "type": "string", "description": "What the charge is for: the identifier of the deal product that generated the entry, or the label sent when it was added through the API. Free text.", "example": "MONTHLY_PLAN" }, "invoice": { "type": "string", "description": "ID of the invoice the entry belongs to.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "amount": { "type": "integer", "description": "Amount of the charge in centavos (`15000` is R$ 150,00). It counts toward the invoice amount while the entry is `OPEN`.", "example": 15000 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "When the charge is collected. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is also debited from the payer's Portão 3 account as soon as it is added.", "example": "LATER" }, "productType": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "When the charge's product is billed. `RECURRENT`: on every invoice of the deal. `ONE_TIME`: on the first invoice only. `ON_EVENT`: never automatically; such an entry is added through the API, when the event happens.", "example": "RECURRENT" }, "effectiveAt": { "type": "string", "description": "When the entry took effect: the moment it was created.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "external": { "type": "object", "properties": { "transaction": { "type": "string", "description": "ID of the payment transaction linked to the entry, when there is one. Entries created through this API don't carry one.", "example": "6711b4c0d8e1a30012b7c9f2" } }, "description": "References of the entry outside the invoice." }, "description": { "type": "string", "description": "Free text describing the charge. Empty when there is none.", "example": "Mensalidade do plano Pro" }, "status": { "type": "string", "enum": [ "OPEN", "DELETED" ], "description": "`OPEN`: the entry counts toward the invoice amount. `DELETED`: the entry was deleted and no longer counts.", "example": "OPEN" }, "createdBy": { "type": "string", "description": "ID of who created the entry: the authenticated caller of the API that added it, or the Portão 3 service that generated it from the deal.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "ID of who last changed the entry: who created it, until someone deletes it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the entry was created. Entries added in the same request are one minute apart, in the order they were sent, so that a listing keeps that order.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the entry was last changed. Deleting an entry does not refresh it.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" } }, "required": [ "id", "identifier", "invoice", "amount", "chargeMethod", "productType", "effectiveAt", "external", "description", "status", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One charge (line item) of an invoice. The invoice amount is the sum of the amounts of its `OPEN` entries." }, "description": "Entries, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of an invoice's entries, newest first." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization (or, with `role=BUYER`, is paid by it).", "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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `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": "status", "message": "Invalid option: expected one of \"OPEN\"|\"DELETED\"", "code": "STATUS_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdEntries", "summary": "Add entries to an invoice", "tags": [ "Invoice Entries" ], "x-p3-sidebar-order": 2, "description": "Adds charges (line items) to an open invoice your organization issued: an on-demand charge for the invoice's period, on top of the entries generated from the deal's products.", "x-mint": { "content": "Each entry's `amount` is added to the invoice amount, so the invoice must be `OPEN`: a closed, paid or canceled invoice refuses the request with `INVOICE_NOT_OPEN`. Send from 1 to 50 entries; they are created together, in the order sent. A field that is not documented is ignored and never stored. `createdBy` and `updatedBy` are set to the ID of the authenticated caller; they can't be sent in the body.\n\nAn entry whose `chargeMethod` is `INSTANT` is also charged to the payer's Portão 3 account right away, as a P2P payment of its amount, when P2P is enabled for your organization. That charge is attempted after the entries are saved and its outcome is not reported: a `201` does not mean the payer was charged. When the charge fails the entry stays on the invoice; check the invoice's statements to see which payments were created.\n\nAny member of the organization, or an admin of the realm, can add entries. Answers the entries it created." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization that issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice the entries are added to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "maxLength": 100, "description": "What the charge is for, such as `SETUP_FEE`. Free text, 1–100 characters; a number is read as its text. Entries with the same identifier (ignoring case) are grouped when you list with `details`.", "example": "SETUP_FEE" }, "description": { "description": "Free text describing the charge, up to 100 characters.", "example": "Taxa de instalação", "type": "string", "maxLength": 100 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "When the charge is collected. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is also debited from the payer's Portão 3 account right away.", "example": "LATER" }, "productType": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "How the charge is classified, with the values a deal's products use: `RECURRENT`, `ONE_TIME` or `ON_EVENT` (a charge made when something happens, which is what an entry added here usually is). It is stored as a label: it does not change how the entry is charged.", "example": "ON_EVENT" }, "amount": { "type": "integer", "minimum": 1, "description": "Amount of the charge in centavos (`15000` is R$ 150,00). A whole number, `1` or more; a string of digits is also accepted.", "example": 15000 } }, "required": [ "identifier", "chargeMethod", "productType", "amount" ] }, "description": "The charges to add, from 1 to 50 per request." } }, "required": [ "entries" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the entry.", "example": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90", "format": "uuid" }, "identifier": { "type": "string", "description": "What the charge is for: the identifier of the deal product that generated the entry, or the label sent when it was added through the API. Free text.", "example": "SETUP_FEE" }, "invoice": { "type": "string", "description": "ID of the invoice the entry belongs to.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "amount": { "type": "integer", "description": "Amount of the charge in centavos (`15000` is R$ 150,00). It counts toward the invoice amount while the entry is `OPEN`.", "example": 15000 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "When the charge is collected. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is also debited from the payer's Portão 3 account as soon as it is added.", "example": "LATER" }, "productType": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "When the charge's product is billed. `RECURRENT`: on every invoice of the deal. `ONE_TIME`: on the first invoice only. `ON_EVENT`: never automatically; such an entry is added through the API, when the event happens.", "example": "ON_EVENT" }, "effectiveAt": { "type": "string", "description": "When the entry took effect: the moment it was created.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "external": { "type": "object", "properties": { "transaction": { "type": "string", "description": "ID of the payment transaction linked to the entry, when there is one. Entries created through this API don't carry one.", "example": "6711b4c0d8e1a30012b7c9f2" } }, "description": "References of the entry outside the invoice." }, "description": { "type": "string", "description": "Free text describing the charge. Empty when there is none.", "example": "Taxa de instalação" }, "status": { "type": "string", "enum": [ "OPEN", "DELETED" ], "description": "`OPEN`: the entry counts toward the invoice amount. `DELETED`: the entry was deleted and no longer counts.", "example": "OPEN" }, "createdBy": { "type": "string", "description": "ID of who created the entry: the authenticated caller of the API that added it, or the Portão 3 service that generated it from the deal.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "ID of who last changed the entry: who created it, until someone deletes it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the entry was created. Entries added in the same request are one minute apart, in the order they were sent, so that a listing keeps that order.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the entry was last changed. Deleting an entry does not refresh it.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" } }, "required": [ "id", "identifier", "invoice", "amount", "chargeMethod", "productType", "effectiveAt", "external", "description", "status", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One charge (line item) of an invoice. The invoice amount is the sum of the amounts of its `OPEN` entries." } } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization.", "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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_NOT_OPEN` — The invoice is closed, paid or canceled.\n\n`BAD_REQUEST` — The body is invalid, such as a missing or empty `entries`, an unknown `chargeMethod` or `productType`, an `amount` that is not a whole number of centavos, or a path parameter that 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": [ "INVOICE_NOT_OPEN", "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": "INVOICE_NOT_OPEN", "origin": "BILLING", "message": "invoice is not open for changes" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries/{invoiceEntryId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdEntriesByInvoiceEntryId", "summary": "Get an entry", "tags": [ "Invoice Entries" ], "x-p3-sidebar-order": 3, "description": "Returns one entry of an invoice your organization issued.", "x-mint": { "content": "The entry is a charge (line item) of the invoice: it counts toward the invoice amount while its `status` is `OPEN`. Any member of the organization, or an admin of the realm, can read it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization that issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice the entry belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "invoiceEntryId", "in": "path", "required": true, "description": "ID of the entry, as returned by `GET .../invoices/{invoiceId}/entries`.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the entry.", "example": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90", "format": "uuid" }, "identifier": { "type": "string", "description": "What the charge is for: the identifier of the deal product that generated the entry, or the label sent when it was added through the API. Free text.", "example": "MONTHLY_PLAN" }, "invoice": { "type": "string", "description": "ID of the invoice the entry belongs to.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "amount": { "type": "integer", "description": "Amount of the charge in centavos (`15000` is R$ 150,00). It counts toward the invoice amount while the entry is `OPEN`.", "example": 15000 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "When the charge is collected. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is also debited from the payer's Portão 3 account as soon as it is added.", "example": "LATER" }, "productType": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "When the charge's product is billed. `RECURRENT`: on every invoice of the deal. `ONE_TIME`: on the first invoice only. `ON_EVENT`: never automatically; such an entry is added through the API, when the event happens.", "example": "RECURRENT" }, "effectiveAt": { "type": "string", "description": "When the entry took effect: the moment it was created.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "external": { "type": "object", "properties": { "transaction": { "type": "string", "description": "ID of the payment transaction linked to the entry, when there is one. Entries created through this API don't carry one.", "example": "6711b4c0d8e1a30012b7c9f2" } }, "description": "References of the entry outside the invoice." }, "description": { "type": "string", "description": "Free text describing the charge. Empty when there is none.", "example": "Mensalidade do plano Pro" }, "status": { "type": "string", "enum": [ "OPEN", "DELETED" ], "description": "`OPEN`: the entry counts toward the invoice amount. `DELETED`: the entry was deleted and no longer counts.", "example": "OPEN" }, "createdBy": { "type": "string", "description": "ID of who created the entry: the authenticated caller of the API that added it, or the Portão 3 service that generated it from the deal.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "ID of who last changed the entry: who created it, until someone deletes it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the entry was created. Entries added in the same request are one minute apart, in the order they were sent, so that a listing keeps that order.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the entry was last changed. Deleting an entry does not refresh it.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" } }, "required": [ "id", "identifier", "invoice", "amount", "chargeMethod", "productType", "effectiveAt", "external", "description", "status", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One charge (line item) of an invoice. The invoice amount is the sum of the amounts of its `OPEN` entries." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization.\n\n`INVOICEENTRY_NOT_FOUND` — The invoice has no entry 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": [ "INVOICE_NOT_FOUND", "INVOICEENTRY_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice 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": "invoiceEntryId", "message": "Invalid UUID", "code": "INVOICEENTRYID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries/{invoiceEntryId}/delete": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdEntriesByInvoiceEntryIdDelete", "summary": "Delete an entry", "tags": [ "Invoice Entries" ], "x-p3-sidebar-order": 4, "description": "Deletes an entry of an open invoice your organization issued, and takes its amount off the invoice amount.", "x-mint": { "content": "The entry is not removed: it is kept with `status` `DELETED` and no longer counts toward the invoice amount. The invoice must be `OPEN`; a closed, paid or canceled invoice refuses the request with `INVOICE_NOT_OPEN`. Only an admin of the organization, or an admin of the realm, can delete an entry. When taking the amount off would leave the invoice amount negative, the request is refused with `NEGATIVE_INVOICE_AMOUNT` and nothing changes.\n\nDelete each entry once: the entry's status is not checked, so repeating the call takes its amount off the invoice again.\n\nAnswers the entry, with `status` `DELETED` and `updatedBy` set to the ID of the authenticated caller; its `updatedAt` is not refreshed." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization that issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice the entry belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "invoiceEntryId", "in": "path", "required": true, "description": "ID of the entry to delete, as returned by `GET .../invoices/{invoiceId}/entries`.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the entry.", "example": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90", "format": "uuid" }, "identifier": { "type": "string", "description": "What the charge is for: the identifier of the deal product that generated the entry, or the label sent when it was added through the API. Free text.", "example": "MONTHLY_PLAN" }, "invoice": { "type": "string", "description": "ID of the invoice the entry belongs to.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "amount": { "type": "integer", "description": "Amount of the charge in centavos (`15000` is R$ 150,00). It counts toward the invoice amount while the entry is `OPEN`.", "example": 15000 }, "chargeMethod": { "type": "string", "enum": [ "INSTANT", "LATER" ], "description": "When the charge is collected. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is also debited from the payer's Portão 3 account as soon as it is added.", "example": "LATER" }, "productType": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME", "ON_EVENT" ], "description": "When the charge's product is billed. `RECURRENT`: on every invoice of the deal. `ONE_TIME`: on the first invoice only. `ON_EVENT`: never automatically; such an entry is added through the API, when the event happens.", "example": "RECURRENT" }, "effectiveAt": { "type": "string", "description": "When the entry took effect: the moment it was created.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "external": { "type": "object", "properties": { "transaction": { "type": "string", "description": "ID of the payment transaction linked to the entry, when there is one. Entries created through this API don't carry one.", "example": "6711b4c0d8e1a30012b7c9f2" } }, "description": "References of the entry outside the invoice." }, "description": { "type": "string", "description": "Free text describing the charge. Empty when there is none.", "example": "Mensalidade do plano Pro" }, "status": { "type": "string", "enum": [ "OPEN", "DELETED" ], "description": "`OPEN`: the entry counts toward the invoice amount. `DELETED`: the entry was deleted and no longer counts.", "example": "DELETED" }, "createdBy": { "type": "string", "description": "ID of who created the entry: the authenticated caller of the API that added it, or the Portão 3 service that generated it from the deal.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "ID of who last changed the entry: who created it, until someone deletes it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the entry was created. Entries added in the same request are one minute apart, in the order they were sent, so that a listing keeps that order.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the entry was last changed. Deleting an entry does not refresh it.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" } }, "required": [ "id", "identifier", "invoice", "amount", "chargeMethod", "productType", "effectiveAt", "external", "description", "status", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One charge (line item) of an invoice. The invoice amount is the sum of the amounts of its `OPEN` entries." } } } }, "400": { "description": "`NEGATIVE_INVOICE_AMOUNT` — Taking the entry's amount off would leave the invoice amount below zero.", "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": [ "NEGATIVE_INVOICE_AMOUNT" ], "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": "NEGATIVE_INVOICE_AMOUNT", "origin": "BILLING", "message": "Invoice amount can't be less than credit parties amount" } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not an admin of the organization nor 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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization.\n\n`INVOICEENTRY_NOT_FOUND` — The invoice has no entry 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": [ "INVOICE_NOT_FOUND", "INVOICEENTRY_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_NOT_OPEN` — The invoice is closed, paid or canceled.\n\n`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": [ "INVOICE_NOT_OPEN", "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": "INVOICE_NOT_OPEN", "origin": "BILLING", "message": "invoice is not open for changes" } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdStatements", "summary": "List statements", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 1, "description": "Lists the statements of an invoice, newest first: the amount owed, each payment instrument created for it (boleto, PIX, PIX Automático), the payments received, adjustments and manual settlements.", "x-mint": { "content": "Statements are the invoice's financial record: the charges generated for it and the payments made against it. An invoice can be paid with more than one payment method — part by PIX, part by boleto, or a payment received outside Portão 3 — so its statements carry the full list of everything that moved on the invoice, and the invoice's balance is computed from them.\n\nThe balance of the invoice comes from its `DONE` statements: what is owed is the sum of `billingAmount` over the `DEBIT` ones, and what was paid is the sum over the `CREDIT` ones. Statements in any other status are listed but do not count yet.\n\nRead the invoice as its issuer (`role=VENDOR`, the default) or as its payer (`role=BUYER`, when your organization is the invoice's payer). Any member of the organization, or an admin of the realm, can list them. Page with `limit` + `next`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice, or the one that pays it when `role` is `BUYER`.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice whose statements you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, { "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. A valid cursor that no longer matches a statement also returns the first page.", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9+/]+={0,2}$" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" }, { "name": "role", "in": "query", "required": false, "description": "Your side of the invoice. `VENDOR` (the default): your organization issued it. `BUYER`: your organization is the invoice's payer.", "schema": { "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" } ], "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 statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "BANK_SLIP_CREATED" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Boleto da fatura de outubro" }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "DONE" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." }, "description": "Statements, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of an invoice's statements." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization (or, with `role=BUYER`, is paid by it).", "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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `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": "limit", "message": "Too big: expected number to be <=100", "code": "LIMIT_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdStatements", "summary": "Create a statement", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 3, "description": "Records a statement on an invoice your organization issued: an adjustment such as a discount or a fee, or a payment received outside Portão 3.", "x-mint": { "content": "The statement is recorded as `DONE`, so it counts toward the balance at once: a `CREDIT` reduces what is still owed, a `DEBIT` adds to it, and `NONE` is kept for reference only. When the invoice is closed and a `CREDIT` covers everything still owed, the invoice becomes paid: the `BILLING_INVOICE_PAID` webhook event is sent and, when your NFSe configuration issues on paid invoices (`INVOICE_PAID`), its NFSe is issued. On an invoice that is not closed yet, the statement is recorded and the invoice is unchanged.\n\nA statement can't be edited or deleted: to undo one, record another with the opposite effect. Any member of the organization, or an admin of the realm, can record one. `createdBy` and `updatedBy` are set to the ID of the authenticated caller; they can't be sent in the body.\n\nAnswers the statement it recorded." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization that issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice the statement is recorded on.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "description": "Label for the kind of movement, such as `DISCOUNT` or `INCREASE`. Free text, stored without leading and trailing spaces; how the statement affects the balance comes from `financialImpactType`, not from the label. Don't use a label that contains `PIX` or `BANK_SLIP`, or that is `P2P_CREATED` or `INVOICE_CLOSED`: Portão 3 reads such a statement as a payment instrument or as the invoice's closing.", "example": "DISCOUNT" }, "description": { "description": "Free text describing the movement.", "example": "Desconto concedido por pagamento antecipado.", "type": "string" }, "billingAmount": { "type": "integer", "minimum": 0, "description": "Amount in centavos (`1500` is R$ 15,00) that counts toward the invoice balance: as paid with `CREDIT`, as owed with `DEBIT`, and not at all with `NONE`. A whole number, `0` or more; a string of digits is also accepted.", "example": 1500 }, "originalAmount": { "type": "integer", "minimum": 0, "description": "Reference amount in centavos, such as the amount the movement was calculated from. Stored and returned for display; it does not change the balance. A whole number, `0` or more; a string of digits is also accepted.", "example": 15000 }, "financialImpactType": { "description": "How `billingAmount` affects the invoice balance. `CREDIT`: it reduces what is still owed, like a payment or a discount. `DEBIT`: it adds to what is owed, like a fee. `NONE` (the default): it is recorded for reference only.", "example": "CREDIT", "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ] }, "effectiveAt": { "type": "string", "minLength": 1, "description": "When the movement took effect: a date (`YYYY-MM-DD`, read as midnight UTC) or a date-time with its offset (`2026-10-01T14:30:00-03:00`).", "example": "2026-10-01" } }, "required": [ "identifier", "billingAmount", "originalAmount", "effectiveAt" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "DISCOUNT" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Desconto concedido por pagamento antecipado." }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 1500 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "DONE" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T00:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-25T12:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-25T12:00:00.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization.", "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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`BAD_REQUEST` — The body is invalid, such as a missing `identifier`, an amount that is not a whole number of centavos, an unknown `financialImpactType` or an `effectiveAt` that is not a date, or 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": "identifier", "message": "Invalid input: expected string, received undefined", "code": "IDENTIFIER_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/{statementId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdStatementsByStatementId", "summary": "Get a statement", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 2, "description": "Returns one statement of an invoice.", "x-mint": { "content": "Read the invoice as its issuer (`role=VENDOR`, the default) or as its payer (`role=BUYER`). Any member of the organization, or an admin of the realm, can read it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice, or the one that pays it when `role` is `BUYER`.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice the statement belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "statementId", "in": "path", "required": true, "description": "ID of the statement, as returned by `GET .../invoices/{invoiceId}/statements`.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f" }, { "name": "role", "in": "query", "required": false, "description": "Your side of the invoice. `VENDOR` (the default): your organization issued it. `BUYER`: your organization is the invoice's payer.", "schema": { "type": "string", "enum": [ "VENDOR", "BUYER" ] }, "example": "VENDOR" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "BANK_SLIP_CREATED" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Boleto da fatura de outubro" }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "DONE" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization (or, with `role=BUYER`, is paid by it).\n\n`INVOICE_STATEMENT_NOT_FOUND` — The invoice has no statement 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": [ "INVOICE_NOT_FOUND", "INVOICE_STATEMENT_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `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": "role", "message": "Invalid option: expected one of \"VENDOR\"|\"BUYER\"", "code": "ROLE_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdStatementsSettlement", "summary": "Mark an invoice as paid", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 4, "description": "Marks an invoice your organization issued as paid, for a payment received outside Portão 3, by recording a `MANUAL_SETTLEMENT` statement for everything still owed.", "x-mint": { "content": "The settlement is a `CREDIT`, `DONE` statement whose `billingAmount` is computed from the ledger when you call it — the `DONE` debits minus the `DONE` credits — and whose `originalAmount` is the invoice amount. It is not checked against the invoice's status: before the invoice closes its amount is usually not owed yet, so the settlement can record `0` or less. The invoice becomes paid, the `BILLING_INVOICE_PAID` webhook event is sent and, when your NFSe configuration issues on paid invoices (`INVOICE_PAID`), its NFSe is issued.\n\nWhen the invoice has a PIX Automático or recurring PIX installment in `SCHEDULED` status, its charge is canceled first. An installment that is not scheduled yet (`CREATED`) is left as it is, and a PIX Automático charge is only canceled while it is still pending. If canceling a recurring PIX charge fails, or the PIX Automático charge can't be read, the Banking service's error is returned (`origin` `BANKING`, with its own status and `code`) and nothing is recorded. If canceling a PIX Automático charge fails, the error is returned the same way unless the charge was already attempted or its date is before today; then the invoice is marked as paid anyway, and the payer may still be charged.\n\nThe invoice's status is not checked: use it on an unpaid invoice, since marking a paid or a canceled invoice records another settlement and leaves the invoice paid. Any member of the organization, or an admin of the realm, can mark one as paid; `createdBy` is set to the ID of the authenticated caller.\n\nAnswers the settlement statement it recorded." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization that issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice to mark as paid.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "description": "Why the invoice is being marked as paid, such as how the payment was received. Stored on the settlement statement.", "example": "Pagamento recebido em dinheiro na loja." } }, "required": [ "description" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "MANUAL_SETTLEMENT" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Pagamento recebido em dinheiro na loja." }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "DONE" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-25T12:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-25T12:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-25T12:00:00.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." } } } }, "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": "`INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization.\n\n`DEAL_NOT_FOUND` — The invoice has a scheduled PIX payment to cancel, but its deal no longer exists.", "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": [ "INVOICE_NOT_FOUND", "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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`BAD_REQUEST` — `description` is missing or empty, or 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": "description", "message": "Invalid input: expected string, received undefined", "code": "DESCRIPTION_REQUIRED" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/bank-slip": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdBankSlip", "summary": "Create a boleto", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 5, "description": "Issues a boleto for an invoice your organization issued.", "x-mint": { "content": "The boleto charges `txnAmount` or, without it, what the invoice still owes, with the invoice's late fee, interest and discount. It is due on `dueAt` and can be paid until `expiresAt`. `customer` replaces the payer data printed on it. The invoice must accept `BANK_SLIP` (in its `allowedPaymentMethods` or as a secondary payment method of its deal), must not be paid or canceled, and the amount must be at least 1 centavo. The `BILLING_INVOICE_PAYMENT_CREATED` webhook event is sent. A request sent twice issues two boletos.\n\nAny member of the organization, or an admin of the realm, can issue one. Answers the `BANK_SLIP_CREATED` statement, with the boleto's digitable line and barcode in `paymentData.bankSlip`. Get its PDF with `GET .../invoices/{invoiceId}/download-pdf`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice to charge.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dueAt": { "minLength": 1, "description": "When the charge is due: today or later (ISO 8601 date or date-time).", "example": "2026-11-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "minLength": 1, "description": "The last day the charge can be paid: at least one day after `dueAt` (ISO 8601 date or date-time).", "example": "2026-12-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "txnAmount": { "description": "The amount to charge, in centavos (at least 1). Omit it to charge what the invoice still owes.", "example": 15000, "type": "integer", "minimum": 1 }, "customer": { "description": "The payer printed on the boleto or the PIX charge. Each field sent replaces the invoice's payer data; the ones omitted keep it. Not used by `p2p-billing`.", "type": "object", "properties": { "name": { "description": "Name of the payer.", "example": "Maria Silva", "type": "string" }, "email": { "description": "E-mail of the payer.", "example": "maria.silva@exemplo.com.br", "type": "string" }, "document": { "description": "CPF or CNPJ of the payer, digits only.", "example": "11144477735", "type": "string" }, "address": { "description": "Address of the payer. When sent, it replaces the whole stored address.", "type": "object", "properties": { "street": { "example": "Rua das Flores", "type": "string" }, "number": { "example": "123", "type": "string" }, "complement": { "example": "Sala 4", "type": "string" }, "neighborhood": { "example": "Centro", "type": "string" }, "city": { "example": "São Paulo", "type": "string" }, "state": { "description": "State abbreviation (UF).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } } } }, "required": [ "dueAt", "expiresAt" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "BANK_SLIP_CREATED" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Boleto da fatura de outubro" }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "PROCESSING" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." } } } }, "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": "`INVOICE_NOT_FOUND` — The organization issued no invoice 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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_NOT_PAYABLE` — The invoice is paid or canceled.\n\n`INVOICE_PAYMENT_METHOD_NOT_ALLOWED` — `BANK_SLIP` is neither one of the invoice's `allowedPaymentMethods` nor one of its deal's secondary payment methods.\n\n`INVOICE_NOTHING_TO_CHARGE` — No `txnAmount` was sent and the invoice owes nothing.\n\n`BAD_REQUEST` — The body is invalid — a `dueAt` in the past, an `expiresAt` not after `dueAt`, a `txnAmount` that is not a whole number of centavos of at least 1 — or 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": [ "INVOICE_NOT_PAYABLE", "INVOICE_PAYMENT_METHOD_NOT_ALLOWED", "INVOICE_NOTHING_TO_CHARGE", "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": "INVOICE_NOT_PAYABLE", "origin": "BILLING", "message": "invoice is already paid or canceled" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/download-pdf": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdDownloadPdf", "summary": "Download a boleto PDF", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 6, "description": "Downloads the PDF of a boleto of an invoice your organization issued.", "x-mint": { "content": "Pass the boleto's statement (`statement`, the ID of a `BANK_SLIP_CREATED` statement) or omit it for the invoice's latest boleto that is not paid. The PDF comes base64-encoded, as text: decode it to get the file. The invoice must accept `BANK_SLIP`.\n\nAny member of the organization, or an admin of the realm, can download it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" }, { "name": "statement", "in": "query", "required": false, "description": "ID of the boleto's statement (`BANK_SLIP_CREATED`). Omit it for the invoice's latest unpaid boleto.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f" } ], "responses": { "200": { "description": "The boleto's PDF, base64-encoded.", "content": { "text/plain": { "schema": { "type": "string", "format": "byte", "description": "The boleto's PDF, base64-encoded." } } } }, "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": "`INVOICE_NOT_FOUND` — The organization issued no invoice with this ID.\n\n`INVOICE_STATEMENT_NOT_FOUND` — The invoice has no such boleto statement, or — without `statement` — no boleto that is not paid.", "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": [ "INVOICE_NOT_FOUND", "INVOICE_STATEMENT_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_INVALID_PAYMENT_METHOD` — `BANK_SLIP` is not one of the invoice's `allowedPaymentMethods`.\n\n`BAD_REQUEST` — A path parameter or `statement` 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": [ "INVOICE_INVALID_PAYMENT_METHOD", "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": "INVOICE_INVALID_PAYMENT_METHOD", "origin": "BILLING", "message": "Invoice does not have a bank slip payment method" } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/pix-billing": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdPixBilling", "summary": "Create a PIX charge", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 7, "description": "Issues a PIX charge for an invoice your organization issued.", "x-mint": { "content": "The charge is for `txnAmount` or, without it, what the invoice still owes, with the invoice's late fee, interest and discount, into your organization's default wallet. It is due on `dueAt` and can be paid until `expiresAt`. `customer` replaces the payer data on the charge. The invoice must accept `PIX` (in its `allowedPaymentMethods` or as a secondary payment method of its deal), must not be paid or canceled, and the amount must be at least 1 centavo. The `BILLING_INVOICE_PAYMENT_CREATED` webhook event is sent. A request sent twice issues two charges.\n\nAny member of the organization, or an admin of the realm, can issue one. Answers the `PIX_CREATED` statement, with the PIX copy-and-paste code in `paymentData.pix.emv`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice to charge.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dueAt": { "minLength": 1, "description": "When the charge is due: today or later (ISO 8601 date or date-time).", "example": "2026-11-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "minLength": 1, "description": "The last day the charge can be paid: at least one day after `dueAt` (ISO 8601 date or date-time).", "example": "2026-12-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "txnAmount": { "description": "The amount to charge, in centavos (at least 1). Omit it to charge what the invoice still owes.", "example": 15000, "type": "integer", "minimum": 1 }, "customer": { "description": "The payer printed on the boleto or the PIX charge. Each field sent replaces the invoice's payer data; the ones omitted keep it. Not used by `p2p-billing`.", "type": "object", "properties": { "name": { "description": "Name of the payer.", "example": "Maria Silva", "type": "string" }, "email": { "description": "E-mail of the payer.", "example": "maria.silva@exemplo.com.br", "type": "string" }, "document": { "description": "CPF or CNPJ of the payer, digits only.", "example": "11144477735", "type": "string" }, "address": { "description": "Address of the payer. When sent, it replaces the whole stored address.", "type": "object", "properties": { "street": { "example": "Rua das Flores", "type": "string" }, "number": { "example": "123", "type": "string" }, "complement": { "example": "Sala 4", "type": "string" }, "neighborhood": { "example": "Centro", "type": "string" }, "city": { "example": "São Paulo", "type": "string" }, "state": { "description": "State abbreviation (UF).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } } } }, "required": [ "dueAt", "expiresAt" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "PIX_CREATED" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Boleto da fatura de outubro" }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "CREATED" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." } } } }, "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": "`INVOICE_NOT_FOUND` — The organization issued no invoice 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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_NOT_PAYABLE` — The invoice is paid or canceled.\n\n`INVOICE_PAYMENT_METHOD_NOT_ALLOWED` — `PIX` is neither one of the invoice's `allowedPaymentMethods` nor one of its deal's secondary payment methods.\n\n`INVOICE_NOTHING_TO_CHARGE` — No `txnAmount` was sent and the invoice owes nothing.\n\n`BAD_REQUEST` — The body is invalid — a `dueAt` in the past, an `expiresAt` not after `dueAt`, a `txnAmount` that is not a whole number of centavos of at least 1 — or 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": [ "INVOICE_NOT_PAYABLE", "INVOICE_PAYMENT_METHOD_NOT_ALLOWED", "INVOICE_NOTHING_TO_CHARGE", "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": "INVOICE_NOT_PAYABLE", "origin": "BILLING", "message": "invoice is already paid or canceled" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/p2p-billing": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdP2pBilling", "summary": "Charge the payer's wallet", "tags": [ "Invoice Statements" ], "x-p3-sidebar-order": 8, "description": "Charges an invoice your organization issued from the payer's Portão 3 wallet.", "x-mint": { "content": "P2P must be enabled for your organization. The payer's wallet (in `debitParties`) is debited `txnAmount` or, without it, what the invoice still owes, and the money goes to your organization's account. The invoice must accept `P2P` (in its `allowedPaymentMethods` or as a secondary payment method of its deal), must not be paid or canceled, and the amount must be at least 1 centavo. One statement is recorded per payer: `PROCESSING` while the debit settles, `ERROR` when it is refused — the request then answers the error. The `BILLING_INVOICE_PAYMENT_CREATED` webhook event is sent. A request sent twice charges twice.\n\nAny member of the organization, or an admin of the realm, can charge it. `customer` is not used. Answers the `P2P_CREATED` statements." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 issued the invoice.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "invoiceId", "in": "path", "required": true, "description": "ID of the invoice to charge.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dueAt": { "minLength": 1, "description": "When the charge is due: today or later (ISO 8601 date or date-time).", "example": "2026-11-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "minLength": 1, "description": "The last day the charge can be paid: at least one day after `dueAt` (ISO 8601 date or date-time).", "example": "2026-12-10", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "txnAmount": { "description": "The amount to charge, in centavos (at least 1). Omit it to charge what the invoice still owes.", "example": 15000, "type": "integer", "minimum": 1 }, "customer": { "description": "The payer printed on the boleto or the PIX charge. Each field sent replaces the invoice's payer data; the ones omitted keep it. Not used by `p2p-billing`.", "type": "object", "properties": { "name": { "description": "Name of the payer.", "example": "Maria Silva", "type": "string" }, "email": { "description": "E-mail of the payer.", "example": "maria.silva@exemplo.com.br", "type": "string" }, "document": { "description": "CPF or CNPJ of the payer, digits only.", "example": "11144477735", "type": "string" }, "address": { "description": "Address of the payer. When sent, it replaces the whole stored address.", "type": "object", "properties": { "street": { "example": "Rua das Flores", "type": "string" }, "number": { "example": "123", "type": "string" }, "complement": { "example": "Sala 4", "type": "string" }, "neighborhood": { "example": "Centro", "type": "string" }, "city": { "example": "São Paulo", "type": "string" }, "state": { "description": "State abbreviation (UF).", "example": "SP", "type": "string" }, "postalCode": { "description": "Postal code (CEP), as `NNNNN-NNN`.", "example": "01310-100", "type": "string" } } } } } }, "required": [ "dueAt", "expiresAt" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the statement.", "example": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f", "format": "uuid" }, "realm": { "type": "string", "description": "ID of the realm of the organization that issued the invoice.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization that issued the invoice.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "invoice": { "type": "string", "description": "ID of the invoice.", "example": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a", "format": "uuid" }, "identifier": { "type": "string", "description": "The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with.", "example": "P2P_CREATED" }, "description": { "type": "string", "description": "Free text describing the movement. Empty when there is none.", "example": "Boleto da fatura de outubro" }, "billingAmount": { "type": "integer", "description": "Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid.", "example": 15000 }, "originalAmount": { "type": "integer", "description": "Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance.", "example": 15000 }, "financialImpactType": { "type": "string", "enum": [ "CREDIT", "DEBIT", "NONE" ], "description": "`CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance.", "example": "CREDIT" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "SCHEDULED", "PAID", "CANCELED", "DONE", "ERROR", "SCHEDULE_ERROR" ], "description": "Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used.", "example": "PROCESSING" }, "effectiveAt": { "type": "string", "description": "When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "createdBy": { "type": "string", "description": "ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "updatedBy": { "type": "string", "description": "Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`.", "example": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b" }, "createdAt": { "type": "string", "description": "When the statement was recorded.", "example": "2026-10-01T09:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the statement last changed, such as its status.", "example": "2026-10-08T14:32:11.000Z", "format": "date-time" }, "paymentData": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "The PIX copy-and-paste code (EMV) the payer pays.", "example": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD" }, "dueAt": { "type": "string", "description": "When the PIX charge is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" } }, "required": [ "emv" ], "description": "The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "bankSlip": { "type": "object", "properties": { "digitableLine": { "type": "string", "description": "The boleto's typeable line (linha digitável). Empty until the boleto is registered.", "example": "34191790010104351004791020150008291070026000" }, "barcode": { "type": "string", "description": "The boleto's barcode. Empty until the boleto is registered.", "example": "34192910700260001790001043510047902015000829" }, "dueAt": { "type": "string", "description": "When the boleto is due.", "example": "2026-10-10T23:59:59.000Z", "format": "date-time" }, "expiresAt": { "type": "string", "description": "After this date the boleto can no longer be paid.", "example": "2026-11-09T23:59:59.000Z", "format": "date-time" } }, "required": [ "digitableLine", "barcode" ], "description": "The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment)." }, "pixInitiation": { "type": "object", "properties": { "paymentUrl": { "type": "string", "description": "Link where the payer authorizes the payment.", "example": "https://pix.example.com/authorize/9d4e1f6a" }, "scheduledTo": { "type": "string", "description": "When the payment is scheduled to be charged: the invoice's due date.", "example": "2026-10-10T12:00:00.000Z", "format": "date-time" } }, "required": [ "paymentUrl" ], "description": "The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement." } }, "description": "The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment." }, "external": { "type": "object", "properties": { "b3BankSlip": { "type": "string", "description": "ID of the boleto.", "example": "6711b4c0d8e1a30012b7c9f2" }, "b3Pix": { "type": "string", "description": "ID of the PIX charge.", "example": "6711b4c0d8e1a30012b7c9f3" }, "b3PixBillingInitiationRequest": { "type": "string", "description": "ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it.", "example": "6711b4c0d8e1a30012b7c9f4" }, "b3PixBillingInitiationRequestItem": { "type": "string", "description": "ID of this installment's scheduled charge. Empty until the charge is scheduled.", "example": "6711b4c0d8e1a30012b7c9f5" } }, "description": "IDs of the charge in the Banking service: on the same statements as `paymentData`." }, "error": { "description": "Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code, or `UNKNOWN_ERROR`.", "example": "PAYMENT_REJECTED" }, "detail": { "type": "string", "description": "Detail of the failure, or `Desconhecido`.", "example": "Saldo insuficiente na conta do pagador." }, "description": { "type": "string", "description": "Description of the failure, or `Erro desconhecido`.", "example": "O pagamento foi recusado pela instituição do pagador." } }, "nullable": true } }, "required": [ "id", "realm", "organization", "invoice", "identifier", "description", "billingAmount", "originalAmount", "financialImpactType", "status", "effectiveAt", "createdBy", "updatedBy", "createdAt", "updatedAt" ], "description": "One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement." } } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm.\n\n`BILLING_P2P_NOT_ENABLED` — P2P is not enabled for your organization.", "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", "BILLING_P2P_NOT_ENABLED" ], "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": "`INVOICE_NOT_FOUND` — The organization issued no invoice 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": [ "INVOICE_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": "INVOICE_NOT_FOUND", "origin": "BILLING", "message": "invoice not found" } } } }, "422": { "description": "`INVOICE_NOT_PAYABLE` — The invoice is paid or canceled.\n\n`INVOICE_PAYMENT_METHOD_NOT_ALLOWED` — `P2P` is neither one of the invoice's `allowedPaymentMethods` nor one of its deal's secondary payment methods.\n\n`INVOICE_NOTHING_TO_CHARGE` — No `txnAmount` was sent and the invoice owes nothing.\n\n`INVOICE_PAYER_WALLET_MISSING` — The invoice's payer has no Portão 3 wallet (`debitParties[].partyAccount.identifier`).\n\n`BAD_REQUEST` — The body is invalid — a `dueAt` in the past, an `expiresAt` not after `dueAt`, a `txnAmount` that is not a whole number of centavos of at least 1 — or 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": [ "INVOICE_NOT_PAYABLE", "INVOICE_PAYMENT_METHOD_NOT_ALLOWED", "INVOICE_NOTHING_TO_CHARGE", "INVOICE_PAYER_WALLET_MISSING", "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": "INVOICE_NOT_PAYABLE", "origin": "BILLING", "message": "invoice is already paid or canceled" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/nfse-configs": { "delete": { "operationId": "deleteRealmsByRealmIdOrganizationsByOrganizationIdNfseConfigs", "summary": "Delete the NFSe configuration", "tags": [ "NFSe Configuration" ], "x-p3-sidebar-order": 3, "description": "Turns off automatic NFSe issuance for the organization by deleting its NFSe configuration.", "x-mint": { "content": "Only admins of the organization or of the realm can delete it. Deleting is permanent: the configuration is read when each event is processed, so an event processed while the organization has no configuration issues no NFSe, and it is not issued later if you create a new one. NFSe already issued and your tax issuer are not affected." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the NFSe configuration belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "responses": { "204": { "description": "No Content. The operation succeeded and the response has no body." }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not an admin of the organization or 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": "`NFSE_CONFIG_NOT_FOUND` — The organization has no NFSe configuration.", "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": [ "NFSE_CONFIG_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": "NFSE_CONFIG_NOT_FOUND", "origin": "BILLING", "message": "NFSE_CONFIG 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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdNfseConfigs", "summary": "Get the NFSe configuration", "tags": [ "NFSe Configuration" ], "x-p3-sidebar-order": 1, "description": "Returns the organization's NFSe configuration: which billing event issues its service invoices (NFSe) automatically, and how they are filled in.", "x-mint": { "content": "Only admins of the organization or of the realm can read it. An organization has at most one NFSe configuration; without one, no NFSe is issued automatically." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the NFSe configuration belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "INVOICE_PAID", "INVOICE_CLOSED", "PAYMENT_RECEIVED" ], "description": "Which billing event issues an NFSe: `INVOICE_CLOSED` (one per invoice, when it closes), `INVOICE_PAID` (one per invoice, when it is paid) or `PAYMENT_RECEIVED` (one per payment settled on an invoice).", "example": "INVOICE_PAID" }, "issWithheldAtSource": { "type": "boolean", "description": "Whether the customer withholds the ISS at source.", "example": false }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ], "description": "`LIVE` for real NFSe, `TEST` for homologation documents with no fiscal value.", "example": "LIVE" }, "competence": { "type": "string", "enum": [ "EVENT_DATE", "CREATED_AT", "CLOSED_AT", "DUE_AT", "PAID_AT", "EFFECTIVE_AT" ], "description": "Which date becomes the competence date of each NFSe: `EVENT_DATE`, `CREATED_AT`, `CLOSED_AT`, `DUE_AT`, `PAID_AT` or `EFFECTIVE_AT`. Absent on a configuration created before this field existed: its NFSe take the day the invoice was last updated.", "example": "PAID_AT" }, "observation": { "type": "string", "description": "Free text printed on every NFSe. Absent on a configuration created before this field existed, which prints none.", "example": "Serviços prestados conforme contrato." }, "operationNature": { "type": "string", "description": "Nature of the operation, stored with every NFSe but not printed on it. Absent on a configuration created before this field existed, which stores `Prestação de Serviços`.", "example": "Prestação de Serviços" }, "createdAt": { "type": "string", "description": "When the configuration was created.", "example": "2026-08-07T19:45:17.204Z", "format": "date-time" } }, "required": [ "event", "issWithheldAtSource", "environment", "createdAt" ], "description": "The organization's NFSe configuration." } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not an admin of the organization or 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": "`NFSE_CONFIG_NOT_FOUND` — The organization has no NFSe configuration.", "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": [ "NFSE_CONFIG_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": "NFSE_CONFIG_NOT_FOUND", "origin": "BILLING", "message": "NFSE_CONFIG 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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdNfseConfigs", "summary": "Create the NFSe configuration", "tags": [ "NFSe Configuration" ], "x-p3-sidebar-order": 2, "description": "Turns on automatic NFSe issuance for the organization: from now on, each `event` you choose issues a service invoice (NFSe) through your tax issuer.", "x-mint": { "content": "Only admins of the organization or of the realm can create it. The organization needs an active tax issuer in the Accounting service first (`POST /realms/{realmId}/organizations/{organizationId}/tax-issuer`, with its test and live configurations), and it has at most one NFSe configuration: to change it, delete it and create a new one. The configuration is read when each event is processed, shortly after it happens, so an event processed while the organization has no configuration issues no NFSe, and it is not issued later.\n\nEach NFSe is issued in the background, after its event, and appears in the Accounting service's tax document list (`GET /realms/{realmId}/organizations/{organizationId}/tax-document`). It is issued to the invoice's payer: the CPF or CNPJ comes from the invoice, and the name, e-mail and address from the contract's buyer when it has them. An invoice whose payer has no CPF or CNPJ issues none. The service data (city, ISS rate, municipal service code, LC 116 item, CNAE) comes from your tax issuer's live configuration, also when `environment` is `TEST`, and the service description is the invoice's description.\n\nWith `PAYMENT_RECEIVED`, each payment settled on an invoice issues its own NFSe, for the amount of that payment. Payments you record by hand (`POST .../invoices/{invoiceId}/statements` and `POST .../invoices/{invoiceId}/statements/settlement`) issue none.\n\nAnswers the configuration it created." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization that issues the NFSe. It needs an active tax issuer.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "INVOICE_PAID", "INVOICE_CLOSED", "PAYMENT_RECEIVED" ], "description": "Which billing event issues an NFSe. `INVOICE_CLOSED`: one NFSe for the whole invoice, for its amount, when the invoice closes. `INVOICE_PAID`: one NFSe for the whole invoice, for its amount, when the invoice is paid. `PAYMENT_RECEIVED`: one NFSe for each payment settled on an invoice, for the amount of that payment.", "example": "INVOICE_PAID" }, "issWithheldAtSource": { "type": "boolean", "description": "Whether the customer withholds the ISS at source. Sent on every NFSe this configuration issues.", "example": false }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ], "description": "`LIVE` issues real NFSe. `TEST` issues homologation documents, which have no fiscal value; they carry the same service data, from your tax issuer's live configuration.", "example": "LIVE" }, "competence": { "type": "string", "enum": [ "EVENT_DATE", "CREATED_AT", "CLOSED_AT", "DUE_AT", "PAID_AT", "EFFECTIVE_AT" ], "description": "Which date becomes the competence date of each NFSe (the date the service refers to), as a UTC calendar day. `EVENT_DATE`: the day the event happened. `CREATED_AT`: the day the invoice was created, or, with `PAYMENT_RECEIVED`, the day the payment was recorded. `CLOSED_AT`, `DUE_AT`, `PAID_AT`: the invoice's closing, due and payment dates (an invoice with no payment date uses the event date). `EFFECTIVE_AT`: the day the payment took effect. `INVOICE_CLOSED` and `INVOICE_PAID` accept `EVENT_DATE`, `CREATED_AT`, `CLOSED_AT`, `DUE_AT` and `PAID_AT`; `PAYMENT_RECEIVED` accepts `EVENT_DATE`, `CREATED_AT` and `EFFECTIVE_AT`. Any other combination is rejected.", "example": "PAID_AT" }, "observation": { "type": "string", "description": "Free text printed on every NFSe this configuration issues. Send an empty string to print none.", "example": "Serviços prestados conforme contrato." }, "operationNature": { "type": "string", "description": "Nature of the operation, stored with every NFSe this configuration issues but not printed on it. An empty string is accepted.", "example": "Prestação de Serviços" } }, "required": [ "event", "issWithheldAtSource", "environment", "competence", "observation", "operationNature" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "INVOICE_PAID", "INVOICE_CLOSED", "PAYMENT_RECEIVED" ], "description": "Which billing event issues an NFSe: `INVOICE_CLOSED` (one per invoice, when it closes), `INVOICE_PAID` (one per invoice, when it is paid) or `PAYMENT_RECEIVED` (one per payment settled on an invoice).", "example": "INVOICE_PAID" }, "issWithheldAtSource": { "type": "boolean", "description": "Whether the customer withholds the ISS at source.", "example": false }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ], "description": "`LIVE` for real NFSe, `TEST` for homologation documents with no fiscal value.", "example": "LIVE" }, "competence": { "type": "string", "enum": [ "EVENT_DATE", "CREATED_AT", "CLOSED_AT", "DUE_AT", "PAID_AT", "EFFECTIVE_AT" ], "description": "Which date becomes the competence date of each NFSe: `EVENT_DATE`, `CREATED_AT`, `CLOSED_AT`, `DUE_AT`, `PAID_AT` or `EFFECTIVE_AT`. Absent on a configuration created before this field existed: its NFSe take the day the invoice was last updated.", "example": "PAID_AT" }, "observation": { "type": "string", "description": "Free text printed on every NFSe. Absent on a configuration created before this field existed, which prints none.", "example": "Serviços prestados conforme contrato." }, "operationNature": { "type": "string", "description": "Nature of the operation, stored with every NFSe but not printed on it. Absent on a configuration created before this field existed, which stores `Prestação de Serviços`.", "example": "Prestação de Serviços" }, "createdAt": { "type": "string", "description": "When the configuration was created.", "example": "2026-08-07T19:45:17.204Z", "format": "date-time" } }, "required": [ "event", "issWithheldAtSource", "environment", "createdAt" ], "description": "The organization's NFSe configuration." } } } }, "403": { "description": "`INSUFFICIENT_PERMISSIONS` — You are not an admin of the organization or 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": "`TAX_ISSUER_NOT_FOUND` — The organization has no active tax issuer, its tax issuer is missing its test or its live configuration, or the organization does not exist in your 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": [ "TAX_ISSUER_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": "TAX_ISSUER_NOT_FOUND", "origin": "BILLING", "message": "Tax issuer not found" } } } }, "409": { "description": "`RESOURCE_CONFLICT` — The organization already has an NFSe configuration. Delete it first to replace it.", "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": [ "RESOURCE_CONFLICT" ], "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": "RESOURCE_CONFLICT", "origin": "BILLING", "message": "NFSE_CONFIG already exist" } } } }, "422": { "description": "`BAD_REQUEST` — The body is invalid, such as a missing field, an unknown `event`, `environment` or `competence`, or a `competence` the `event` does not accept, or 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": "event", "message": "Invalid option: expected one of \"INVOICE_PAID\"|\"INVOICE_CLOSED\"|\"PAYMENT_RECEIVED\"", "code": "EVENT_ONE_OF", "values": [ "INVOICE_PAID", "INVOICE_CLOSED", "PAYMENT_RECEIVED" ] } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/payment-links": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinks", "summary": "List payment links", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 1, "description": "Lists the payment links of your organization, newest first by default.", "x-mint": { "content": "Each link comes with `totalProductsPrice`: the current catalog price of its products times their quantities.\n\nFilter by a text in the name, by status and by the creation date (`startAt`/`endAt`, each on its own or both). Sort with `order` and `orderBy`, and page with `limit` + `next`: pass the `next` of one page to get the following one — the last page has no `next`.\n\nAny member of the organization, or an admin of the realm, can list them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the links.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "name", "in": "query", "required": false, "description": "Only links whose name contains this text, ignoring case.", "schema": { "type": "string", "minLength": 1, "maxLength": 56 }, "example": "anual" }, { "name": "status", "in": "query", "required": false, "description": "Only links in these statuses. Omit it for every status.\n\n---\n\nExample (comma-separated list): `?status=ACTIVE,DEACTIVATED`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ] } }, "style": "form", "explode": false }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "default": 15, "type": "integer", "minimum": 1, "maximum": 100 }, "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 link returns the first page.", "schema": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9+/]+={0,2}$" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction.", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "name", "createdAt" ] }, "example": "createdAt" }, { "name": "startAt", "in": "query", "required": false, "description": "Only links created on or after this moment: an ISO 8601 date (read as midnight UTC) or a date-time with an offset.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-01" }, { "name": "endAt", "in": "query", "required": false, "description": "Only links created on or before this moment: an ISO 8601 date (read as midnight UTC) or a date-time with an offset.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-12-31T23:59:59.999Z" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "next": { "type": "string", "description": "Cursor of the next page: pass it as `next` to get it. Absent on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the payment link.", "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" }, "name": { "type": "string", "description": "Name of the link.", "example": "Plano anual" }, "description": { "type": "string", "description": "What the link sells. Absent when it has none.", "example": "Acesso completo por 12 meses." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ], "description": "`ACTIVE`, `DEACTIVATED` or `EXPIRED`.", "example": "ACTIVE" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "ID of the product in your organization's catalog.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ], "description": "A product the link sells." }, "description": "What the link sells." }, "totalProductsPrice": { "type": "number", "description": "The current catalog price of every product times its quantity, in centavos. A product the catalog no longer has counts as zero.", "example": 15000 }, "expirationDate": { "description": "Last day the link can be paid (midnight UTC of that day), or `null` when it never expires.", "example": "2026-12-31T00:00:00.000Z", "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME` or `RECURRENT`.", "example": "ONE_TIME" }, "paymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "Other ways each invoice can also be paid. Empty when there are none.\n\n---\n\nExample: `[\"PIX\"]`" }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY" }, "bankSlip": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS" }, "pixAutomatic": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS" } }, "description": "When the first payment of a checkout is due, per payment method." }, "numberOfInstallments": { "type": "integer", "description": "How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1).", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the link was created.", "example": "2026-10-26T14:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the link was last changed.", "example": "2026-10-26T14:30:00.000Z" } }, "required": [ "id", "name", "status", "products", "totalProductsPrice", "expirationDate", "type", "paymentMethod", "secondaryPaymentMethod" ], "description": "A payment link in a list, with the price of what it sells." }, "description": "The links of this page." } }, "required": [ "items" ], "description": "One page of payment links." } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `status`, a `limit` out of range or a `startAt` after `endAt`; `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": "name", "message": "Too big: expected string to have <=56 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinks", "summary": "Create a payment link", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 2, "description": "Creates a payment link: a checkout page where payers buy the products you choose.", "x-mint": { "content": "The link is created `ACTIVE` — `status` is not accepted in the body. So it must be sellable right away: every product must be an active product of your organization's catalog with a price above zero, and `expirationDate`, when sent, must be today or later.\n\nEach checkout of the link creates a contract and a deal for the payer, charging the products' prices at that moment. Any member of the organization, or an admin of the realm, can create one; `createdBy` and `updatedBy` are set to the ID of the authenticated caller." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 56, "description": "Name of the link. The checkout page shows it to the payer, and it becomes the description of the deal each checkout creates.", "example": "Plano anual" }, "description": { "description": "What the link sells, shown on the checkout page.", "example": "Acesso completo por 12 meses.", "type": "string", "maxLength": 250 }, "products": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1, "description": "ID of a product of your organization's catalog. It must be active and have a price above zero.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "minimum": 1, "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ] }, "description": "What the link sells. At least one. The amount charged is the products' current prices times their quantities, read at each checkout." }, "expirationDate": { "description": "Last day the link can be paid: an ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or a date-time with an offset. Today or later. The link can be paid through that day: the daily expiry run, at 03:01 UTC (00:01 in Brasília) of the following day, turns it `EXPIRED`, which is final. Omit it for a link that never expires.", "example": "2026-12-31", "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: each checkout charges `numberOfInstallments` times, monthly.", "example": "ONE_TIME" }, "paymentMethod": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout: `BANK_SLIP` (boleto), `PIX` (a PIX charge), `PIX_AUTOMATIC` (PIX Automático: the payer authorizes the recurring payments once) or `PIX_INITIATION` (recurring scheduled PIX, authorized the same way). A `RECURRENT` link with `PIX_AUTOMATIC` needs `numberOfInstallments` above 1 and `firstPaymentDate.pixAutomatic`.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "description": "Other ways each invoice can also be paid, whatever the payer chose — typically `PIX` and/or `BANK_SLIP` alongside `PIX_AUTOMATIC` or `PIX_INITIATION`.\n\n---\n\nExample: `[\"PIX\"]`", "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" } }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY", "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ] }, "bankSlip": { "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS", "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ] }, "pixAutomatic": { "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS", "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ] } }, "description": "When the first payment of a checkout is due, counted from the checkout day: `SAME_DAY`, `ONE_DAY`, `FIVE_DAYS`, `TEN_DAYS`, `THIRTY_DAYS`, `SIXTY_DAYS`, or `EXPIRATION_DATE` (the link's `expirationDate`; the checkout day when it has none). At least one key. One value applies to every checkout, whatever method the payer picks: `pixAutomatic` when set, otherwise `bankSlip`, otherwise `pix`." }, "numberOfInstallments": { "description": "How many monthly payments a checkout of a `RECURRENT` link creates. Above 1 for a `RECURRENT` link with `PIX_AUTOMATIC`. Omitted or `null`: 1.", "example": 12, "type": "integer", "minimum": 1, "nullable": true } }, "required": [ "name", "products", "type", "paymentMethod", "firstPaymentDate" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the payment link. The checkout page of the link is addressed by it.", "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" }, "name": { "type": "string", "description": "Name of the link.", "example": "Plano anual" }, "description": { "type": "string", "description": "What the link sells. Absent when it has none.", "example": "Acesso completo por 12 meses." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ], "description": "`ACTIVE`: payers can check out. `DEACTIVATED`: switched off; it can be activated again. `EXPIRED`: its `expirationDate` passed; final.", "example": "ACTIVE" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "ID of the product in your organization's catalog.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ], "description": "A product the link sells." }, "description": "What the link sells." }, "expirationDate": { "description": "Last day the link can be paid (midnight UTC of that day), or `null` when it never expires.", "example": "2026-12-31T00:00:00.000Z", "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: monthly, `numberOfInstallments` times.", "example": "ONE_TIME" }, "paymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "Other ways each invoice can also be paid. Empty when there are none.\n\n---\n\nExample: `[\"PIX\"]`" }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY" }, "bankSlip": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS" }, "pixAutomatic": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS" } }, "description": "When the first payment of a checkout is due, per payment method." }, "numberOfInstallments": { "type": "integer", "description": "How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1).", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the link was created.", "example": "2026-10-26T14:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the link was last changed.", "example": "2026-10-26T14:30:00.000Z" } }, "required": [ "id", "name", "status", "products", "expirationDate", "type", "paymentMethod", "secondaryPaymentMethod" ], "description": "A payment link." } } } }, "422": { "description": "`PAYMENT_LINK_INVALID_PRODUCT_STATUS` — A product is not in your organization's catalog, is not active, or has no price above zero.\n\n`PAYMENT_LINK_INVALID_EXPIRATION_DATE` — `expirationDate` is before today (UTC).\n\n`BAD_REQUEST` — The body is invalid — a missing field, an unknown payment method, no first payment date, a `RECURRENT` PIX Automático link without more than one installment, or a `status` (not accepted: `STATUS_REMOVED`) — or 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": [ "PAYMENT_LINK_INVALID_PRODUCT_STATUS", "PAYMENT_LINK_INVALID_EXPIRATION_DATE", "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": "PAYMENT_LINK_INVALID_PRODUCT_STATUS", "origin": "BILLING", "message": "Payment link products are not active" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/payment-links/report": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinksReport", "summary": "Export payment links", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 3, "description": "Exports the payment links of your organization as a CSV or XLSX file.", "x-mint": { "content": "The file has every link that matches the same filters and order as the payment-link list, one per row, with eleven columns whose headers are in Portuguese: `Identificador` (the ID), `Nome`, `Descrição`, `Status` (`Ativo`, `Desativado` or `Expirado`), `Produtos` (each product as `{\"produto\": , \"quantidadae\": }`, comma-separated), `Data de expiração`, `Método de pagamento`, `Métodos de pagamento secundários`, `Primeiro pagamento`, `Numero de parcelas` and `Criado em`. Dates are written as `DD/MM/YYYY HH:mm` in Brasília time. A link with no expiration date or no secondary payment methods reads `Não disponível` there, one with no description an empty `Descrição`, and one with no number of installments `0`. When no link matches, the file has the header and one placeholder row: empty `Identificador`, `Nome` and `Descrição`, `Numero de parcelas` `0`, and `Não disponível` in every other column.\n\n`?type=csv` answers a UTF-8 CSV file; `?type=xlsx` an Excel workbook, base64-encoded. An export is limited to 50,000 links and 4 MiB (a little less for a CSV with many quotes or line breaks): narrow the filters to export more. Only an admin of the organization, or of the realm, can export them." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the links.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "type", "in": "query", "required": true, "description": "File format: `csv` or `xlsx`.", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "example": "csv" }, { "name": "name", "in": "query", "required": false, "description": "Only links whose name contains this text, ignoring case.", "schema": { "type": "string", "minLength": 1, "maxLength": 56 }, "example": "anual" }, { "name": "status", "in": "query", "required": false, "description": "Only links in these statuses. Omit it for every status.\n\n---\n\nExample (comma-separated list): `?status=ACTIVE,DEACTIVATED`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ] } }, "style": "form", "explode": false }, { "name": "order", "in": "query", "required": false, "description": "Sort direction of the rows.", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field the rows are sorted by.", "schema": { "default": "createdAt", "type": "string", "enum": [ "name", "createdAt" ] }, "example": "createdAt" }, { "name": "startAt", "in": "query", "required": false, "description": "Only links created on or after this moment: an ISO 8601 date (read as midnight UTC) or a date-time with an offset.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-01-01" }, { "name": "endAt", "in": "query", "required": false, "description": "Only links created on or before this moment: an ISO 8601 date (read as midnight UTC) or a date-time with an offset.", "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] }, "example": "2026-12-31T23:59:59.999Z" } ], "responses": { "200": { "description": "`application/csv` — The payment links as a UTF-8 CSV file, when `type` is `csv`.\n\n`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — The Excel workbook, base64-encoded, when `type` is `xlsx`.", "content": { "application/csv": { "schema": { "type": "string", "description": "The payment links as a UTF-8 CSV file, when `type` is `csv`." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "byte", "description": "The Excel workbook, base64-encoded, when `type` is `xlsx`." } } } }, "403": { "description": "`FORBIDDEN_PAYMENT_LINK` — You are not an admin of the organization nor 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": [ "FORBIDDEN_PAYMENT_LINK" ], "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": "FORBIDDEN_PAYMENT_LINK", "origin": "BILLING", "message": "Forbidden" } } } }, "422": { "description": "`EXPORT_TOO_LARGE` — More than 50,000 links match, or the file would be too large to send.\n\n`BAD_REQUEST` — A path or query parameter is invalid, such as a missing `type`; `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": [ "EXPORT_TOO_LARGE", "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": "EXPORT_TOO_LARGE", "origin": "BILLING", "message": "This export is too large to generate in a single request. Narrow the filters (for example a shorter date range) and try again." } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/payment-links/{paymentLinkId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinksByPaymentLinkId", "summary": "Get a payment link", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 4, "description": "Returns one payment link of your organization, with its products' current names and prices.", "x-mint": { "content": "`products` carries each product's current `name` and `price` (in centavos) from your organization's catalog — both absent for a product the catalog no longer has. Any member of the organization, or an admin of the realm, can read it." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "paymentLinkId", "in": "path", "required": true, "description": "ID of the payment link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the payment link. The checkout page of the link is addressed by it.", "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" }, "realmId": { "type": "string", "description": "ID of your realm.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, "organizationId": { "type": "string", "description": "ID of your organization.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "name": { "type": "string", "description": "Name of the link.", "example": "Plano anual" }, "description": { "type": "string", "description": "What the link sells. Absent when it has none.", "example": "Acesso completo por 12 meses." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ], "description": "`ACTIVE`: payers can check out. `DEACTIVATED`: switched off; it can be activated again. `EXPIRED`: its `expirationDate` passed; final.", "example": "ACTIVE" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "ID of the product in your organization's catalog.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "name": { "type": "string", "description": "Current name of the product in the catalog. Absent when the catalog no longer has it.", "example": "Plano anual" }, "quantity": { "type": "integer", "description": "How many units of the product each checkout sells.", "example": 1 }, "price": { "type": "number", "description": "Current price of one unit in the catalog, in centavos (`15000` is R$ 150,00). Absent when the catalog no longer has the product.", "example": 15000 } }, "required": [ "product", "quantity" ], "description": "A product the link sells, with its current name and price in the catalog." }, "description": "What the link sells, with each product's current name and price." }, "expirationDate": { "description": "Last day the link can be paid (midnight UTC of that day), or `null` when it never expires.", "example": "2026-12-31T00:00:00.000Z", "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: monthly, `numberOfInstallments` times.", "example": "ONE_TIME" }, "paymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "Other ways each invoice can also be paid. Empty when there are none.\n\n---\n\nExample: `[\"PIX\"]`" }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY" }, "bankSlip": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS" }, "pixAutomatic": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS" } }, "description": "When the first payment of a checkout is due, per payment method." }, "numberOfInstallments": { "type": "integer", "description": "How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1).", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the link was created.", "example": "2026-10-26T14:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the link was last changed.", "example": "2026-10-26T14:30:00.000Z" }, "createdBy": { "type": "string", "description": "ID of the user who created the link. Absent on links created before it was recorded.", "example": "60242bfd-228e-43e2-8c18-6dc40746eb69" }, "updatedBy": { "type": "string", "description": "ID of the user who last changed the link. Absent on links never changed since it was recorded.", "example": "60242bfd-228e-43e2-8c18-6dc40746eb69" } }, "required": [ "id", "realmId", "organizationId", "name", "status", "products", "expirationDate", "type", "paymentMethod", "secondaryPaymentMethod" ], "description": "A payment link, with its products' current names and prices." } } } }, "404": { "description": "`PAYMENT_LINK_NOT_FOUND` — The organization has no payment link 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": [ "PAYMENT_LINK_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": "PAYMENT_LINK_NOT_FOUND", "origin": "BILLING", "message": "Payment link 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": "paymentLinkId", "message": "Invalid UUID", "code": "PAYMENTLINKID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinksByPaymentLinkId", "summary": "Update a payment link", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 5, "description": "Replaces an active payment link with the body sent.", "x-mint": { "content": "Only an `ACTIVE` link can be edited, and it stays `ACTIVE` — `status` is not accepted in the body: use the activate and deactivate routes. It is a full replace: an optional field left out (`description`, `expirationDate`, `secondaryPaymentMethod`, `numberOfInstallments`) is cleared. Like a new link, it must stay sellable: every product active in your organization's catalog with a price above zero, and `expirationDate` today or later.\n\nCheckouts already made are not affected. Any member of the organization, or an admin of the realm, can update one; `updatedBy` is set to the ID of the authenticated caller." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "paymentLinkId", "in": "path", "required": true, "description": "ID of the payment link to update.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 56, "description": "Name of the link. The checkout page shows it to the payer, and it becomes the description of the deal each checkout creates.", "example": "Plano anual" }, "description": { "description": "What the link sells, shown on the checkout page.", "example": "Acesso completo por 12 meses.", "type": "string", "maxLength": 250 }, "products": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "minLength": 1, "description": "ID of a product of your organization's catalog. It must be active and have a price above zero.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "minimum": 1, "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ] }, "description": "What the link sells. At least one. The amount charged is the products' current prices times their quantities, read at each checkout." }, "expirationDate": { "description": "Last day the link can be paid: an ISO 8601 date (`YYYY-MM-DD`, read as midnight UTC) or a date-time with an offset. Today or later. The link can be paid through that day: the daily expiry run, at 03:01 UTC (00:01 in Brasília) of the following day, turns it `EXPIRED`, which is final. Omitted or `null`: the link never expires.", "example": "2026-12-31", "anyOf": [ { "type": "string", "format": "date", "nullable": true }, { "type": "string", "format": "date-time", "nullable": true } ] }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: each checkout charges `numberOfInstallments` times, monthly.", "example": "ONE_TIME" }, "paymentMethod": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout: `BANK_SLIP` (boleto), `PIX` (a PIX charge), `PIX_AUTOMATIC` (PIX Automático: the payer authorizes the recurring payments once) or `PIX_INITIATION` (recurring scheduled PIX, authorized the same way). A `RECURRENT` link with `PIX_AUTOMATIC` needs `numberOfInstallments` above 1 and `firstPaymentDate.pixAutomatic`.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "description": "Other ways each invoice can also be paid, whatever the payer chose — typically `PIX` and/or `BANK_SLIP` alongside `PIX_AUTOMATIC` or `PIX_INITIATION`.\n\n---\n\nExample: `[\"PIX\"]`", "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" } }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY", "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ] }, "bankSlip": { "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS", "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ] }, "pixAutomatic": { "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS", "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ] } }, "description": "When the first payment of a checkout is due, counted from the checkout day: `SAME_DAY`, `ONE_DAY`, `FIVE_DAYS`, `TEN_DAYS`, `THIRTY_DAYS`, `SIXTY_DAYS`, or `EXPIRATION_DATE` (the link's `expirationDate`; the checkout day when it has none). At least one key. One value applies to every checkout, whatever method the payer picks: `pixAutomatic` when set, otherwise `bankSlip`, otherwise `pix`." }, "numberOfInstallments": { "description": "How many monthly payments a checkout of a `RECURRENT` link creates. Above 1 for a `RECURRENT` link with `PIX_AUTOMATIC`. Omitted or `null`: 1.", "example": 12, "type": "integer", "minimum": 1, "nullable": true } }, "required": [ "name", "products", "type", "paymentMethod", "firstPaymentDate" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the payment link. The checkout page of the link is addressed by it.", "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" }, "name": { "type": "string", "description": "Name of the link.", "example": "Plano anual" }, "description": { "type": "string", "description": "What the link sells. Absent when it has none.", "example": "Acesso completo por 12 meses." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ], "description": "`ACTIVE`: payers can check out. `DEACTIVATED`: switched off; it can be activated again. `EXPIRED`: its `expirationDate` passed; final.", "example": "ACTIVE" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "ID of the product in your organization's catalog.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ], "description": "A product the link sells." }, "description": "What the link sells." }, "expirationDate": { "description": "Last day the link can be paid (midnight UTC of that day), or `null` when it never expires.", "example": "2026-12-31T00:00:00.000Z", "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: monthly, `numberOfInstallments` times.", "example": "ONE_TIME" }, "paymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "Other ways each invoice can also be paid. Empty when there are none.\n\n---\n\nExample: `[\"PIX\"]`" }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY" }, "bankSlip": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS" }, "pixAutomatic": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS" } }, "description": "When the first payment of a checkout is due, per payment method." }, "numberOfInstallments": { "type": "integer", "description": "How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1).", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the link was created.", "example": "2026-10-26T14:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the link was last changed.", "example": "2026-10-26T14:30:00.000Z" } }, "required": [ "id", "name", "status", "products", "expirationDate", "type", "paymentMethod", "secondaryPaymentMethod" ], "description": "A payment link." } } } }, "404": { "description": "`PAYMENT_LINK_NOT_FOUND` — The organization has no payment link 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": [ "PAYMENT_LINK_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": "PAYMENT_LINK_NOT_FOUND", "origin": "BILLING", "message": "Payment link not found" } } } }, "422": { "description": "`PAYMENT_LINK_NOT_ACTIVE` — The link is `DEACTIVATED` (activate it first) or `EXPIRED`.\n\n`PAYMENT_LINK_INVALID_PRODUCT_STATUS` — A product is not in your organization's catalog, is not active, or has no price above zero.\n\n`PAYMENT_LINK_INVALID_EXPIRATION_DATE` — `expirationDate` is before today (UTC).\n\n`BAD_REQUEST` — The body is invalid — a missing field, an unknown payment method, no first payment date, a `RECURRENT` PIX Automático link without more than one installment, or a `status` (not accepted: `STATUS_REMOVED`) — or 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": [ "PAYMENT_LINK_NOT_ACTIVE", "PAYMENT_LINK_INVALID_PRODUCT_STATUS", "PAYMENT_LINK_INVALID_EXPIRATION_DATE", "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": "PAYMENT_LINK_NOT_ACTIVE", "origin": "BILLING", "message": "Payment link is not active" } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/payment-links/{paymentLinkId}/activate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinksByPaymentLinkIdActivate", "summary": "Activate a payment link", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 6, "description": "Activates a deactivated payment link: payers can check out again.", "x-mint": { "content": "Send no body and no `Content-Type` (or the body `{}`). The link must still be sellable: every product active in your organization's catalog with a price above zero, and its `expirationDate`, if any, today or later. Activating a link that is already `ACTIVE` changes nothing and answers it as it is; an `EXPIRED` link can't be activated.\n\nAny member of the organization, or an admin of the realm, can activate one; `updatedBy` is set to the ID of the authenticated caller. Answers the link." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "paymentLinkId", "in": "path", "required": true, "description": "ID of the payment link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the payment link. The checkout page of the link is addressed by it.", "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" }, "name": { "type": "string", "description": "Name of the link.", "example": "Plano anual" }, "description": { "type": "string", "description": "What the link sells. Absent when it has none.", "example": "Acesso completo por 12 meses." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ], "description": "`ACTIVE`: payers can check out. `DEACTIVATED`: switched off; it can be activated again. `EXPIRED`: its `expirationDate` passed; final.", "example": "ACTIVE" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "ID of the product in your organization's catalog.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ], "description": "A product the link sells." }, "description": "What the link sells." }, "expirationDate": { "description": "Last day the link can be paid (midnight UTC of that day), or `null` when it never expires.", "example": "2026-12-31T00:00:00.000Z", "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: monthly, `numberOfInstallments` times.", "example": "ONE_TIME" }, "paymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "Other ways each invoice can also be paid. Empty when there are none.\n\n---\n\nExample: `[\"PIX\"]`" }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY" }, "bankSlip": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS" }, "pixAutomatic": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS" } }, "description": "When the first payment of a checkout is due, per payment method." }, "numberOfInstallments": { "type": "integer", "description": "How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1).", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the link was created.", "example": "2026-10-26T14:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the link was last changed.", "example": "2026-10-26T14:30:00.000Z" } }, "required": [ "id", "name", "status", "products", "expirationDate", "type", "paymentMethod", "secondaryPaymentMethod" ], "description": "A payment link." } } } }, "404": { "description": "`PAYMENT_LINK_NOT_FOUND` — The organization has no payment link 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": [ "PAYMENT_LINK_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": "PAYMENT_LINK_NOT_FOUND", "origin": "BILLING", "message": "Payment link not found" } } } }, "409": { "description": "`PAYMENT_LINK_CONCURRENT_UPDATE` — The link's status kept changing while it was being activated; retrying is safe.", "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": [ "PAYMENT_LINK_CONCURRENT_UPDATE" ], "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": "PAYMENT_LINK_CONCURRENT_UPDATE", "origin": "BILLING", "message": "Payment link was changed concurrently, try again" } } } }, "422": { "description": "`PAYMENT_LINK_EXPIRED` — The link is `EXPIRED`, which is final.\n\n`PAYMENT_LINK_INVALID_PRODUCT_STATUS` — A product is not in your organization's catalog, is not active, or has no price above zero.\n\n`PAYMENT_LINK_INVALID_EXPIRATION_DATE` — The link's `expirationDate` is before today (UTC); it expires at the next daily run.\n\n`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": [ "PAYMENT_LINK_EXPIRED", "PAYMENT_LINK_INVALID_PRODUCT_STATUS", "PAYMENT_LINK_INVALID_EXPIRATION_DATE", "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": "PAYMENT_LINK_EXPIRED", "origin": "BILLING", "message": "Payment link is expired" } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/payment-links/{paymentLinkId}/deactivate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdPaymentLinksByPaymentLinkIdDeactivate", "summary": "Deactivate a payment link", "tags": [ "Payment Links" ], "x-p3-sidebar-order": 7, "description": "Deactivates an active payment link: its checkout page stops accepting payers.", "x-mint": { "content": "Send no body and no `Content-Type` (or the body `{}`). Checkouts already made are not affected, and the link can be activated again. Deactivating a link that is already `DEACTIVATED` changes nothing and answers it as it is; an `EXPIRED` link can't be deactivated.\n\nAny member of the organization, or an admin of the realm, can deactivate one; `updatedBy` is set to the ID of the authenticated caller. Answers the link." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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 sells through the link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "paymentLinkId", "in": "path", "required": true, "description": "ID of the payment link.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the payment link. The checkout page of the link is addressed by it.", "example": "5c1e8d2a-7b4f-4e3a-9d6c-2a1b0f9e8d7c" }, "name": { "type": "string", "description": "Name of the link.", "example": "Plano anual" }, "description": { "type": "string", "description": "What the link sells. Absent when it has none.", "example": "Acesso completo por 12 meses." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "EXPIRED" ], "description": "`ACTIVE`: payers can check out. `DEACTIVATED`: switched off; it can be activated again. `EXPIRED`: its `expirationDate` passed; final.", "example": "DEACTIVATED" }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "description": "ID of the product in your organization's catalog.", "example": "8c7d6e5f-4a3b-4c2d-9e1f-0a9b8c7d6e5f" }, "quantity": { "type": "integer", "description": "How many units of the product each checkout sells.", "example": 1 } }, "required": [ "product", "quantity" ], "description": "A product the link sells." }, "description": "What the link sells." }, "expirationDate": { "description": "Last day the link can be paid (midnight UTC of that day), or `null` when it never expires.", "example": "2026-12-31T00:00:00.000Z", "type": "string", "format": "date-time", "nullable": true }, "type": { "type": "string", "enum": [ "RECURRENT", "ONE_TIME" ], "description": "`ONE_TIME`: each checkout charges once. `RECURRENT`: monthly, `numberOfInstallments` times.", "example": "ONE_TIME" }, "paymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "The ways the payer can choose from at checkout.\n\n---\n\nExample: `[\"PIX\",\"BANK_SLIP\"]`" }, "secondaryPaymentMethod": { "type": "array", "items": { "type": "string", "enum": [ "BANK_SLIP", "PIX_INITIATION", "PIX", "PIX_AUTOMATIC" ], "example": "PIX" }, "description": "Other ways each invoice can also be paid. Empty when there are none.\n\n---\n\nExample: `[\"PIX\"]`" }, "firstPaymentDate": { "type": "object", "properties": { "pix": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX`.", "example": "SAME_DAY" }, "bankSlip": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `BANK_SLIP`.", "example": "FIVE_DAYS" }, "pixAutomatic": { "type": "string", "enum": [ "SAME_DAY", "EXPIRATION_DATE", "ONE_DAY", "FIVE_DAYS", "TEN_DAYS", "THIRTY_DAYS", "SIXTY_DAYS" ], "description": "When the first payment is due, for `PIX_AUTOMATIC`.", "example": "TEN_DAYS" } }, "description": "When the first payment of a checkout is due, per payment method." }, "numberOfInstallments": { "type": "integer", "description": "How many monthly payments a checkout of a `RECURRENT` link creates, or `null` (1).", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the link was created.", "example": "2026-10-26T14:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the link was last changed.", "example": "2026-10-28T09:15:00.000Z" } }, "required": [ "id", "name", "status", "products", "expirationDate", "type", "paymentMethod", "secondaryPaymentMethod" ], "description": "A payment link." } } } }, "404": { "description": "`PAYMENT_LINK_NOT_FOUND` — The organization has no payment link 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": [ "PAYMENT_LINK_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": "PAYMENT_LINK_NOT_FOUND", "origin": "BILLING", "message": "Payment link not found" } } } }, "409": { "description": "`PAYMENT_LINK_CONCURRENT_UPDATE` — The link's status kept changing while it was being deactivated; retrying is safe.", "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": [ "PAYMENT_LINK_CONCURRENT_UPDATE" ], "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": "PAYMENT_LINK_CONCURRENT_UPDATE", "origin": "BILLING", "message": "Payment link was changed concurrently, try again" } } } }, "422": { "description": "`PAYMENT_LINK_EXPIRED` — The link is `EXPIRED`, which is final.\n\n`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": [ "PAYMENT_LINK_EXPIRED", "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": "PAYMENT_LINK_EXPIRED", "origin": "BILLING", "message": "Payment link is expired" } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }