Skip to main content
GET
List an organization's invoices
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. Filter 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). Any member of the organization, or an admin of the realm, can list them.

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of your organization: the one that issues the invoices (or pays them, with role=BUYER).

Format: UUID

Query Parameters

​
status
enum<string>[]

Only invoices in these stored statuses (OPEN, CLOSED, PAID, CANCELED). Repeat the parameter or separate values with commas.

Example (comma-separated list): ?status=CLOSED,PAID

Available options:
OPEN,
CLOSED,
PAID,
CANCELED
​
debitPartyDocuments
string[]

Only invoices whose payer (the debit party) has one of these CPF/CNPJ documents, digits only (exact match).

Example (comma-separated list): ?debitPartyDocuments=11144477735,39053344705

Maximum string length: 32
​
debitPartyOrgIds
string<uuid>[]

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.

Format: UUID

Example: ?debitPartyOrgIds=5e0a1c2b-3d4f-4a6b-8c9d-0e1f2a3b4c5d

​
chargeType
enum<string>[]

Only invoices whose deal has one of these charge types (SINGLE, RECURRENT, SUBSCRIPTION).

Example: ?chargeType=SINGLE

Available options:
SINGLE,
RECURRENT,
SUBSCRIPTION
​
description
string

Only invoices whose name contains this text (case-insensitive).

Maximum string length: 250
​
startDueAt

Only invoices due on or after this moment, inclusive (ISO 8601 date or date-time).

​
endDueAt

Only invoices due on or before this moment, inclusive (ISO 8601 date or date-time).

​
role
enum<string>
default:VENDOR

VENDOR (default): the invoices your organization issues. BUYER: the invoices your organization pays.

Available options:
VENDOR,
BUYER
​
order
enum<string>
default:DESC

Sort direction. Case-insensitive.

Available options:
ASC,
DESC
​
orderBy
enum<string>
default:createdAt

Field to sort the invoices by.

Available options:
createdAt,
dueAt,
closingAt,
description,
status,
amount,
invoiceNumber
​
limit
integer
default:15

Page size.

Required range: 1 <= x <= 1000
​
next
string

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.

Maximum string length: 128
Pattern: ^[A-Za-z0-9+/]+={0,2}$

Response

Successful response

A page of invoices.

​
items
object[]
required
​
next
string | null
required

Cursor for the next page. null on the last page.

Example:

"NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy"