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

# API Reference

> How the Portão 3 API reference is organized and how to read it

The reference is grouped by service. Every service is a separate API with its own base URL, listed on each endpoint page:

```text theme={null}
https://api.<service>.v2.portao3.com.br
```

<Note>
  **Shortlinks** is the exception: it runs on the custom domain `api.links.portao3.com.br` and is production-only (no development server).
</Note>

## Authentication

Unless an endpoint says otherwise, every request requires a JWT bearer token issued by the Identity service:

```text theme={null}
Authorization: Bearer <accessToken>
```

See the [Quickstart](/quickstart) for how to obtain and refresh tokens. A few endpoints are public by design — for example the sign-in and password-recovery endpoints under `/auth`, service health checks (`GET /health`), and the hosted checkout pages for payment links.

Some sensitive operations also require the user's **transaction PIN** in a `pin` header — see [Authentication](/#authentication) in the introduction.

<Note>
  A few authentication flows carry more options than the generated schema shows today: `POST /auth/sign-in` also accepts API-client credentials (HTTP Basic + `grantType: "client_credentials"`), and `POST /auth/confirm-mfa` takes `email`, `userCode`, and `session`. The [Quickstart](/quickstart) documents these flows end to end.
</Note>

## Tenancy

Endpoints whose path starts with `/realms/{realmId}/organizations/{organizationId}/` are tenant-scoped: the token you send must belong to that realm and be entitled to that organization. Your IDs are provided during onboarding.

## How to read the reference

These pages are generated directly from the API source code, so paths, methods, and parameters always reflect the deployed APIs.

Request and response schemas are being rolled out progressively:

* Endpoints with a documented **request or response body** show the exact schema the API validates — field names, types, formats, and allowed enum values come straight from the code.
* Endpoints **without a documented body yet** are still listed with their full path, parameters, and auth requirements, but the body shape is omitted rather than guessed. Coverage expands with every release.

The services with the richest typed coverage today are **Identity**, **Scheduling**, **Accounting**, **Customer**, **Platform**, and **Rule Engine**.

<Tip>
  Need a schema that isn't documented yet? Email [suporte@portao3.com.br](mailto:suporte@portao3.com.br) and we'll prioritize it.
</Tip>

### Internal endpoints

The reference is generated from the complete API surface, so it also lists a small number of endpoints that back Portão 3's own operations — paths under `/support` or `/internal`, and webhook receivers for our payment providers. They appear for completeness but are not part of a typical integration, and most are not available to customer credentials.

## Services

| Service                      | What you can do                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Identity**                 | Sign in and refresh tokens, manage users, organizations, MFA, and API clients                                 |
| **Banking**                  | Manage accounts, wallets, and cards; send and receive PIX; issue and pay boleto; query the transaction ledger |
| **Billing**                  | Manage contracts, deals, invoices, entries, and statements; settle invoices; orchestrate NFSe issuance        |
| **Payment Links & Checkout** | Create payment links, run hosted checkouts, manage products and suppliers                                     |
| **Accounting**               | Configure tax issuers and issue, cancel, and download NFSe fiscal documents                                   |
| **Customer**                 | Manage payer/customer records, look up customers by hash, export customer data                                |
| **Platform**                 | Aggregated operations across wallets, cards, payments, batch payments, and reports                            |
| **Notification**             | Configure notification routing, channels, and webhook destinations                                            |
| **Rule Engine**              | Define transaction security policies and manage blocked wallet balances                                       |
| **Scheduling**               | Schedule future PIX, boleto, and wallet-to-wallet transfers and track their execution                         |
| **Travel**                   | Search air, hotel, bus, and vehicle inventory; manage passengers; create, issue, and cancel trip reservations |
| **Shortlinks**               | Create short URLs under `links.portao3.com.br`                                                                |

Not sure where to start? **Billing** manages the agreement and invoice lifecycle between you and your counterparties; **Payment Links & Checkout** is for collecting one-off payments through a hosted page; **Banking** is where money actually moves (PIX, boleto, wallets, cards).

### Travel

The **Travel** service groups the corporate-travel APIs across four verticals — **air**, **hotel**, **bus**, and **vehicle**:

* **Search proxy** — `POST /travel/{vertical}/searches` and the matching `GET` endpoints fan a single query out to the upstream inventory providers per vertical and return normalized offers.
* **Passenger directory** — `/travel/passengers` stores reusable traveler profiles (documents, contact info, custom fields) that trips reference by ID.
* **Trip lifecycle** — `/travel/trips` and `/travel/trips/{tripId}/items/{itemId}` model a trip as a container of items (one per booked segment) that move through a **create → issue → cancel** state machine, with `history` for auditing.
* **TaaS webhook receiver** — Travel-as-a-Service provider callbacks land on an internal webhook receiver that advances item state asynchronously, so you can rely on trip and item state instead of polling providers directly.

Travel emits a `TRAVEL_RESERVATION_*` event family (created, issued, cancelled, and related states) that the **Notification** service consumes to send transactional e-mails to travelers and administrators.