Skip to main content
POST
Create a statement
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.

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of the organization that issued the invoice.

Format: UUID

​
invoiceId
string<uuid>
required

ID of the invoice the statement is recorded on.

Format: UUID

Body

application/json
​
identifier
string
required

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.

Minimum string length: 1
Example:

"DISCOUNT"

​
billingAmount
integer
required

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.

Required range: x >= 0
Example:

1500

​
originalAmount
integer
required

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.

Required range: x >= 0
Example:

15000

​
effectiveAt
string
required

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).

Minimum string length: 1
Example:

"2026-10-01"

​
description
string

Free text describing the movement.

Example:

"Desconto concedido por pagamento antecipado."

​
financialImpactType
enum<string>

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.

Available options:
CREDIT,
DEBIT,
NONE
Example:

"CREDIT"

Response

Successful response

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.

​
id
string<uuid>
required

ID of the statement.

Example:

"9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f"

​
realm
string<uuid>
required

ID of the realm of the organization that issued the invoice.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

​
organization
string<uuid>
required

ID of the organization that issued the invoice.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

​
invoice
string<uuid>
required

ID of the invoice.

Example:

"0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a"

​
identifier
string
required

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
string
required

Free text describing the movement. Empty when there is none.

Example:

"Desconto concedido por pagamento antecipado."

​
billingAmount
integer
required

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
integer
required

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
enum<string>
required

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.

Available options:
CREDIT,
DEBIT,
NONE
Example:

"CREDIT"

​
status
enum<string>
required

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.

Available options:
CREATED,
PROCESSING,
SCHEDULED,
PAID,
CANCELED,
DONE,
ERROR,
SCHEDULE_ERROR
Example:

"DONE"

​
effectiveAt
string<date-time>
required

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"

​
createdBy
string
required

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
string
required

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
string<date-time>
required

When the statement was recorded.

Example:

"2026-10-25T12:00:00.000Z"

​
updatedAt
string<date-time>
required

When the statement last changed, such as its status.

Example:

"2026-10-25T12:00:00.000Z"

​
paymentData
object

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
object

IDs of the charge in the Banking service: on the same statements as paymentData.

​
error
object | null

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.