# Introdução à API

A API de parceiros FaciConnect: URLs base, autenticação, erros e convenções (AOA).

A **FaciConnect API** é uma API REST de parceiros para criar e consultar ordens de
pagamento. É consumida pelo seu **backend** — nunca diretamente pelo browser, porque exige
o `clientSecret`.

## URLs base

| Ambiente | Base URL |
|---|---|
| Sandbox | `https://sandbox.api.faciconnect.com` |
| Produção | `https://api.faciconnect.com` |

## Autenticação

Em dois passos:

1. Troque `clientId`/`clientSecret` por um `access_token` em [`POST /token`](/pt/api-reference/authentication).
2. Use `Authorization: Bearer <access_token>` nos restantes endpoints.

```http
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...
```

## Convenções

<ResponseField name="amount" type="integer">
  Valores monetários são **inteiros em AOA, sem casas decimais** (`15000` = 15.000 Kz).
</ResponseField>

<ResponseField name="applicationUUID" type="string">
  A sua `publishableKey` **sem** o prefixo `pk_test_`/`pk_live_`.
</ResponseField>

<ResponseField name="Accept-Language" type="header">
  Idioma das mensagens: `pt` (predefinido), `en`, `fr`.
</ResponseField>

## Formato de erros

As respostas de erro seguem este formato:

```json
{
  "code": 401,
  "message": "Unauthorized",
  "error": "invalid_client"
}
```

| Código | Significado |
|---|---|
| `401` | Token ausente, expirado ou credenciais inválidas. |
| `404` | Recurso não encontrado. |
| `422` | Corpo inválido (ex.: `amount` não-inteiro). |

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /token" icon="key" href="/pt/api-reference/authentication">
    Obter access token.
  </Card>
  <Card title="POST /facipaypartner/createPaymentOrder" icon="plus" href="/api-reference/payment-orders/criar-ordem-de-pagamento">
    Criar ordem de pagamento.
  </Card>
  <Card title="GET /facipaypartner/paymentByExternalTransaction" icon="magnifying-glass" href="/api-reference/payment-orders/consultar-pagamento-por-externaltransactionid">
    Consultar estado (fallback).
  </Card>
  <Card title="Webhook" icon="bell" href="/pt/api-reference/webhooks">
    Notificações de estado (fonte da verdade).
  </Card>
</CardGroup>

<Note>
A referência completa de cada endpoint — com playground interativo — está no grupo
**Endpoints** da barra lateral, gerada a partir da especificação OpenAPI.
</Note>