Skip to main content
GET
Get an invoice
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. Any member of the organization, or an admin of the realm, can read it.

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of your organization: the one that issued the invoice (or pays it, with role=BUYER).

Format: UUID

​
invoiceId
string<uuid>
required

ID of the invoice.

Format: UUID

Query Parameters

​
role
enum<string>
default:VENDOR

VENDOR (default): read an invoice your organization issued. BUYER: read an invoice your organization pays.

Available options:
VENDOR,
BUYER

Response

Successful response

An invoice, with its customer, totals, ledger and products.

​
id
string<uuid>
required

ID of the invoice.

Example:

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

​
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"

​
deal
string<uuid>
required

ID of the deal that generated the invoice. Read the deal with GET .../deals/{dealId}.

Example:

"3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

​
previousInvoiceId
string
required

Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.

Example:

""

​
dealName
string
required

The deal's description. Empty when the invoice has none.

Example:

"Mensalidade Plano Pro"

​
description
string
required

The invoice's name. Empty when it has none (show dealName instead).

Example:

"Mensalidade Plano Pro - 1/12"

​
allowedPaymentMethods
enum<string>[]
required

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.

Example: ["PIX_AUTOMATIC","PIX"]

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
​
invoiceNumber
integer
required

The installment number, from 1.

Example:

1

​
closingAt
string<date-time>
required

When the invoice closes: it stops gathering charges and its payment is issued.

Example:

"2026-10-01T00:00:00.000Z"

​
dueAt
string<date-time>
required

When the invoice is due.

Example:

"2026-10-10T00:00:00.000Z"

​
expiresAt
string<date-time>
required

The last day the invoice's charge can be paid.

Example:

"2026-11-10T00:00:00.000Z"

​
amount
integer
required

Amount of the invoice, in centavos (15000 is R$ 150,00): the sum of its charges.

Example:

15000

​
status
enum<string>
required

The stored status. OPEN: still gathering charges. CLOSED: issued and waiting for payment. PAID. CANCELED.

Available options:
OPEN,
CLOSED,
PAID,
CANCELED
Example:

"CLOSED"

​
displayStatus
enum<string>
required

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

Available options:
OPEN,
READY_TO_PAYMENT,
OVERDUE,
PAID,
CANCELED,
READY_TO_SCHEDULE,
SCHEDULED,
PAYMENT_FAILED,
REVOKED,
EXPIRED
Example:

"SCHEDULED"

​
paymentStatus
enum<string>
required

Progress of the automatic charge from the payer's Portão 3 account (P2P). NONE for every other invoice.

Available options:
NONE,
PENDING,
PROCESSING,
PROCESSED,
FAILED
Example:

"NONE"

​
paymentsAttempts
integer
required

How many times the automatic P2P charge was attempted.

Example:

0

​
external
object
required

IDs of the invoice's boleto and PIX charge, once created.

​
debitParties
object[]
required

Who pays: one payer.

​
createdBy
string
required

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

Who last changed the invoice.

Example:

"BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

​
createdAt
string<date-time>
required

When the invoice was created.

Example:

"2026-09-01T00:00:00.000Z"

​
updatedAt
string<date-time>
required

When the invoice was created. It does not move when the invoice changes.

Example:

"2026-09-01T00:00:00.000Z"

​
chargeType
enum<string>
required

The deal's charge type: SINGLE (one invoice), RECURRENT (a fixed number of installments) or SUBSCRIPTION (renews until the deal ends).

Available options:
SINGLE,
RECURRENT,
SUBSCRIPTION
Example:

"RECURRENT"

​
totalInstallments
integer
required

How many installments the deal has (1 for a single charge).

Example:

12

​
customer
object | null
required

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

​
financialValues
object
required

The invoice's totals.

​
statements
object[]
required

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
object[]
required

What the invoice charges: its own charges (not deleted), grouped by name and price.

​
contract
string<uuid>

ID of the invoice's contract. Absent on an invoice of a deal created without a contract.

Example:

"7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d"

​
paidAt
string<date-time>

When the invoice was paid. Absent until it is.

Example:

"2026-10-08T14:32:11.000Z"

​
fine
object

Late fee charged after the due date, when the deal has one.

​
interest
object

Interest charged after the due date, when the deal has it.

​
discount
object

Discount for paying early, when the deal has one.

​
creditParties
object[]

Who receives the money. Absent when you read the invoice as its payer (role=BUYER).