> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Referência da API REST da Chargefy.

A API da Chargefy permite integrar pagamentos, checkout, catálogo, clientes e operações de plataforma diretamente na sua aplicação.

## URL base

```text theme={}
https://api.chargefy.io
```

Todas as requisições devem usar HTTPS. Requisições HTTP serão rejeitadas.

## Autenticação

A API é autenticada via API key enviada no header `Authorization`:

```bash cURL theme={}
curl -X GET https://api.chargefy.io/v1/products \
  -H "Authorization: Bearer {{API_KEY}}"
```

<Info>
  Consulte [Authentication](/api-reference/authentication) para detalhes.
</Info>

## Endpoints principais

| Recurso                                                                    | Endpoints                              | Descrição                                                       |
| -------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
| [Checkout Sessions](/api-reference/checkout-sessions/create)               | `GET/POST /v1/checkout-sessions`       | Sessões hospedadas de compra                                    |
| [Payment Intents](/api-reference/payment-intents/object)                   | `GET/POST /v1/payment-intents`         | Ciclo de vida de cobranças                                      |
| [Charges](/api-reference/charges/list)                                     | `GET /v1/charges`                      | Cobranças originadas por intents e checkout                     |
| [Invoices](/api-reference/invoices/list)                                   | `GET /v1/invoices` + ações             | Cobranças documentadas com line items e tentativas de pagamento |
| [Payment Methods](/api-reference/payment-methods/list)                     | `GET/POST /v1/payment-methods` + ações | Métodos de pagamento salvos                                     |
| [Setup Intents](/api-reference/setup-intents/create)                       | `GET/POST /v1/setup-intents` + ações   | Preparação de métodos de pagamento                              |
| [Payment Links](/api-reference/payment-links/list)                         | `GET/POST/DELETE /v1/payment-links`    | Links de pagamento compartilháveis                              |
| [Customers](/api-reference/customers/object)                               | `GET/POST/DELETE /v1/customers`        | Gestão de clientes                                              |
| [Customer Portal Sessions](/api-reference/customer-portal-sessions/create) | `POST /v1/customer-portal-sessions`    | Portal hospedado para clientes                                  |
| [Products](/api-reference/products/list)                                   | `GET/POST/DELETE /v1/products`         | Produtos do catálogo                                            |
| [Prices](/api-reference/prices/list)                                       | `GET/POST/DELETE /v1/prices`           | Preços associados a produtos                                    |
| [Files](/api-reference/files/list)                                         | `GET/POST/DELETE /v1/files`            | Upload e gestão de arquivos                                     |
| [Organizations](/api-reference/organizations/object)                       | `GET/POST /v1/organizations`           | Configuração da organização                                     |
| [Onboarding Sessions](/api-reference/onboarding-sessions/object)           | `GET/POST /v1/onboarding-sessions`     | Onboarding hospedado de organizações conectadas                 |

## Modelo de pagamentos

Use [Ciclo de pagamento](/integrate/payment-lifecycle) como referência para escolher o objeto certo:

* `checkout.session` orquestra a experiência de compra hospedada.
* `payment_intent` representa o estado canônico da cobrança.
* `invoice` representa o documento de cobrança ou comprovante, quando o fluxo exige invoice.
* `payment_method` representa o instrumento usado para pagar.

A integração não deve depender de IDs internos de processamento como objeto de sucesso. Para fulfillment e reconciliação, use o recurso público retornado pela API e os webhooks correspondentes.

## Paginação

Endpoints de listagem retornam o envelope canônico de lista e usam cursor. Use `starting_after`, `ending_before` e `limit` para navegar:

```bash theme={}
GET /v1/products?limit=20&starting_after=prod_123
```

### Resposta de lista

```json theme={}
{
  "object": "list",
  "data": [
    {
      "id": "prod_456",
      "object": "product",
      "created_at": "2026-05-16T14:09:27Z",
      "default_price": "price_123",
      "description": null,
      "image_url": null,
      "is_active": true,
      "is_tax_applicable": true,
      "livemode": true,
      "metadata": {},
      "name": "Plano Pro",
      "prices": [
        {
          "id": "price_123",
          "object": "price",
          "created_at": "2026-05-16T14:09:27Z",
          "currency": "brl",
          "is_active": true,
          "livemode": true,
          "metadata": {},
          "name": "Mensal",
          "product": "prod_456",
          "recurring": {
            "interval": "month",
            "interval_count": 1,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "tax_behavior": "unspecified",
          "type": "recurring",
          "unit_amount": 9900,
          "updated_at": "2026-05-16T14:09:27Z"
        }
      ],
      "updated_at": "2026-05-16T14:09:27Z"
    }
  ],
  "has_more": true,
  "url": "/v1/products"
}
```

| Parâmetro        | Tipo      | Padrão | Descrição                                    |
| ---------------- | --------- | ------ | -------------------------------------------- |
| `starting_after` | `string`  | —      | Cursor para buscar itens depois de um objeto |
| `ending_before`  | `string`  | —      | Cursor para buscar itens antes de um objeto  |
| `limit`          | `integer` | `10`   | Itens por página                             |

## Ordenação e filtros

Filtros são específicos por recurso e documentados na página de cada endpoint. Não assuma operadores globais para todos os recursos.

```bash theme={}
# Filtro documentado no endpoint de Payment Intents
GET /v1/payment-intents?status=succeeded
```

Quando um endpoint suporta filtros de intervalo ou igualdade, a página do endpoint lista os parâmetros aceitos.

## Formato de erros

Endpoints públicos retornam erros no formato canônico:

```json theme={}
{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.chargefy.io/errors/parameter-missing",
    "message": "Missing required param: amount.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}
```

`type` é um destes valores: `invalid_request_error`, `api_error`, `authentication_error`, `rate_limit_error`, `card_error`. `message` é em inglês por padrão. `param` e `doc_url` aparecem apenas quando aplicáveis.

### Códigos de status

| Código | Descrição                                                            |
| ------ | -------------------------------------------------------------------- |
| `200`  | Sucesso. Create, update e actions retornam o objeto público completo |
| `400`  | Requisição inválida (parâmetros faltando ou incorretos)              |
| `401`  | Não autenticado (token ausente ou inválido)                          |
| `403`  | Sem permissão (escopo insuficiente)                                  |
| `404`  | Recurso não encontrado                                               |
| `409`  | Conflito de estado do recurso                                        |
| `422`  | Erro de validação                                                    |
| `429`  | Rate limit excedido                                                  |
| `500`  | Erro interno do servidor                                             |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Configurar tokens de acesso
  </Card>

  <Card title="Api Keys" icon="key" href="/integrate/api-keys">
    Gerenciar chaves no dashboard
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/webhook-events/types">
    Consultar eventos emitidos
  </Card>
</CardGroup>