> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create a statement > 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. 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. A 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. Answers the statement it recorded. ## OpenAPI ````yaml /api-reference/billing.openapi.json post /realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements openapi: 3.0.3 info: title: Billing version: 1.0.0 description: >- Portão 3 billing API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Full billing surface — contracts, deals, invoices, statements, payment links, checkout and NFSe orchestration. (The product/supplier catalog moved to registry.) Confidence tiers: generated:typed=74 copied:manual=0 unknown=5. servers: - url: https://api.billing.v2.portao3.com.br/ description: production - url: https://api.billing.dev.3pers.com.br/ description: development security: [] tags: - name: Contracts - name: Deals - name: Invoices - name: Invoice Entries - name: Invoice Statements - name: NFSe Configuration - name: Payment Links paths: /realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements: post: tags: - Invoice Statements summary: Create a statement 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. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdStatements parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization that issued the invoice. Format: `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. Format: `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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.