> ## Documentation Index
> Fetch the complete documentation index at: https://documentacao.parcelemais.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK .NET

> SDK oficial em .NET para integrar com a API do Parcele+.

O SDK oficial em .NET encapsula autenticação, renovação de token, política de retry/circuit breaker e serialização, para que você chame a API do Parcele+ a partir de código C# sem lidar diretamente com HTTP.

<Card title="Código-fonte no GitHub" icon="github" href="https://github.com/Twila-Digital/twila-parcelemais-dotnet-sdk" horizontal>
  Repositório público — código, exemplos (`samples/`) e histórico de versões.
</Card>

## Compatibilidade

O pacote publica dois target frameworks: `netstandard2.0` e `net8.0` (build nativo, com as dependências mais recentes).

| Runtime              | Versões aceitas                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| .NET / .NET Core     | 2.0 até a versão mais recente (5, 6, 7, 8, 9, 10) — via `netstandard2.0` a partir de 2.0, nativamente a partir da 8 |
| .NET Framework       | 4.6.2 ou superior                                                                                                   |
| Xamarin / Mono / UWP | Qualquer versão compatível com .NET Standard 2.0                                                                    |

<Warning>
  **.NET Core 1.0 e 1.1 não são suportados** — essas versões só implementam .NET Standard 1.6, e o SDK exige .NET Standard 2.0.
</Warning>

## Instalação

```bash theme={null}
dotnet add package ParceleMais
```

## Configuração

```csharp theme={null}
using ParceleMais;
using ParceleMais.Configuration;
using ParceleMais.DependencyInjection;

services.AddParceleMais(options =>
{
    options.ClientId = "<seu-client-id>";
    options.ClientSecret = "<seu-client-secret>";
    options.Environment = ParceleMaisEnvironment.Staging;
});
```

## Uso

```csharp theme={null}
var client = provider.GetRequiredService<IParceleMaisClient>();

var parcelas = await client.Simulations.SimulateInstallmentsAsync(
    new SimulateInstallmentsRequest(valor: 1500.00m));

foreach (var parcela in parcelas)
    Console.WriteLine($"{parcela.Term}x de {parcela.InstallmentAmount:C}");
```

O `IParceleMaisClient` expõe um cliente por recurso:

| Cliente              | Recurso                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `client.Orders`      | Pedidos (criar, consultar, listar, iniciar venda CDC, importar nota fiscal) |
| `client.Simulations` | Simulação de parcelas e valores                                             |
| `client.Customers`   | Clientes (consultar, listar)                                                |
| `client.Webhooks`    | Webhooks (criar, listar, atualizar, remover)                                |

## Tratamento de erros

Exceções são tipadas por categoria: `ParceleMaisAuthenticationException`, `ParceleMaisValidationException`, `ParceleMaisRateLimitException`, `ParceleMaisTimeoutException`, e a base `ParceleMaisApiException` para os demais erros de API.

```csharp theme={null}
catch (ParceleMaisApiException ex)
{
    Console.WriteLine($"Erro da API ({ex.StatusCode}, {ex.ErrorCode}): {ex.Message}");
}
```

## Validando assinatura de webhooks

```csharp theme={null}
using ParceleMais.Webhooks;

var evento = ParceleMaisWebhookEvent.Parse(rawJson, signatureHeader, signingSecret);
```

## Exemplos completos

O repositório inclui samples prontos para rodar em `samples/`:

<CardGroup cols={3}>
  <Card title="Console" icon="terminal">
    `ParceleMais.Sample.Console` — .NET 8, DI standalone.
  </Card>

  <Card title="ASP.NET Core" icon="server">
    `ParceleMais.Sample.AspNetCore` — .NET 8, minimal API.
  </Card>

  <Card title=".NET Framework" icon="window">
    `ParceleMais.Sample.NetFramework` — net472, `ServiceCollection` standalone.
  </Card>
</CardGroup>