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

# Introdução

> Integre pagamentos, serviços bancários, cobrança e identidade com as APIs da plataforma Portão 3

O Portão 3 é uma plataforma brasileira de pagamentos e serviços bancários corporativos. Nossas APIs permitem gerenciar contas e carteiras, emitir e controlar cartões, movimentar dinheiro com PIX, boleto e transferências entre carteiras, executar seu ciclo de cobrança (contratos, negociações, faturas, links de pagamento), emitir documentos fiscais NFSe e gerenciar as pessoas e organizações que usam sua conta.

## Como a plataforma está organizada

A API do Portão 3 é dividida em serviços focados. Cada serviço tem sua própria URL base:

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

| Serviço                  | URL base                                | O que abrange                                                            |
| ------------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
| Identity                 | `api.identity.v2.portao3.com.br`        | Login, usuários, organizações, MFA, clientes de API                      |
| Banking                  | `api.banking.v2.portao3.com.br`         | Contas, carteiras, cartões, PIX, boleto, transações                      |
| Billing                  | `api.billing.v2.portao3.com.br`         | Contratos, negociações, faturas, extratos, orquestração de NFSe          |
| Payment Links & Checkout | `api.billing-cluster.v2.portao3.com.br` | Links de pagamento, checkout, produtos, fornecedores                     |
| Accounting               | `api.accounting.v2.portao3.com.br`      | Emissão de NFSe e gestão de documentos fiscais                           |
| Customer                 | `api.customer.v2.portao3.com.br`        | Registros de pagadores/clientes e exportações                            |
| Platform                 | `api.platform.v2.portao3.com.br`        | Carteiras, cartões, pagamentos e relatórios agregados                    |
| Notification             | `api.notification.v2.portao3.com.br`    | Preferências de notificação, canais e webhooks                           |
| Rule Engine              | `api.ruleengine.v2.portao3.com.br`      | Políticas de segurança de transações e bloqueios de saldo                |
| Scheduling               | `api.scheduling.v2.portao3.com.br`      | PIX, boleto e transferências entre carteiras agendados                   |
| Travel                   | `api.travel.v2.portao3.com.br`          | Busca de aéreo, hotel, ônibus e veículo; passageiros; reservas de viagem |
| Shortlinks               | `api.links.portao3.com.br`              | Criação de URLs curtas (`links.portao3.com.br`)                          |

<Note>
  **Shortlinks** é a exceção ao padrão acima: ele roda no domínio customizado `api.links.portao3.com.br` e está disponível **apenas em produção** — não há ambiente de desenvolvimento.
</Note>

## Autenticação

As APIs do Portão 3 se autenticam com **tokens JWT bearer**. Exceto por alguns endpoints públicos (login, recuperação de senha, verificações de saúde, páginas de checkout hospedadas), toda requisição deve carregar um token obtido do serviço Identity:

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

Existem duas formas de obter um token:

* **Credenciais de usuário** — faça login com e-mail e senha via `POST /auth/sign-in`. Usuários com MFA habilitado completam uma segunda etapa.
* **Credenciais de cliente de API** — para integrações servidor a servidor, faça login com um par `client_id` / `client_secret` emitido pelo Portão 3. Consulte o [Início rápido](/quickstart) para ambos os fluxos.

Os tokens expiram após um curto período; use `POST /auth/refresh-token` para obter novos sem precisar autenticar novamente.

### PIN de transação

Algumas operações sensíveis — confirmação de pagamentos e transferências, visualização de detalhes completos de cartão, administração de usuários — exigem adicionalmente o **PIN de transação** do usuário autenticado, enviado em um cabeçalho `pin` junto com o token bearer. Requisições a esses endpoints sem um PIN válido são rejeitadas com `403`.

### Multi-tenancy: realms e organizações

Seu acesso é restrito a um **realm** (seu tenant) e a uma ou mais **organizações** dentro dele. A maioria dos endpoints carrega ambos no caminho:

```text theme={null}
/realms/{realmId}/organizations/{organizationId}/...
```

Você recebe seu `realmId` e `organizationId` durante o onboarding. Requisições a um realm ou organização aos quais seu token não tem direito são rejeitadas com `403`.

## Ambientes

As URLs base acima são de **produção**. Um ambiente de desenvolvimento separado está disponível para construir e testar sua integração antes de ir ao ar — cada página de endpoint na referência da API lista ambos os servidores, e seu contato no Portão 3 pode fornecer credenciais de desenvolvimento. Os dados são totalmente isolados entre ambientes. (**Shortlinks** é a exceção: está disponível apenas em produção e não possui ambiente de desenvolvimento.)

## Erros

A maioria dos erros retorna um corpo JSON com este formato:

```json theme={null}
{
  "traceId": "1-67ab12cd-...",
  "code": "RESOURCE_NOT_FOUND",
  "message": "Human-readable description",
  "fields": []
}
```

Algumas operações retornam corpos de erro específicos da operação. Sempre que houver um `traceId`, inclua-o ao entrar em contato com o suporte — ele nos permite localizar a requisição exata.

## Próximos passos

<Columns cols={2}>
  <Card title="Início rápido" icon="rocket" href="/quickstart">
    Autentique-se e faça sua primeira chamada de API em minutos.
  </Card>

  <Card title="Referência da API" icon="code" href="/api-reference/overview">
    Navegue por todos os endpoints, agrupados por serviço.
  </Card>
</Columns>

<Tip>
  Precisa de ajuda ou credenciais de acesso? Fale conosco em [suporte@portao3.com.br](mailto:suporte@portao3.com.br).
</Tip>