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

# Entendendo Malga API SDK

Nessa seção você poderá compreender como configurar o API SDK,
acessar as especificações detalhadas de cada método, além de entender
como usar a Chave de Idempotência e fazer o tratamento de erros corretamente.

### Configuração

Configurar o Malga API SDK é simples, inicialmente você precisará das credenciais que são
o `API Key`, `Client ID` e `Merchant ID`. Se você ainda não tem uma conta Malga
basta [clicar aqui](https://dashboard.malga.io/sign-up) e criar uma conta em nosso Dashboard e você terá
acesso às credenciais para iniciar sua integração.

Agora que você já está com as chaves de acesso, você só precisará baixar o pacote no seu projeto
importar o pacote no seu arquivo e usar o seguinte código:

<Tabs>
  <Tab title="Node.js">
    ```typescript theme={null}
    import { Malga } from "malga";

    const malga = new Malga({
      apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0",
      clientId: "d1d2b51a-0446-432a-b055-034518c2660e",
      options: {
        sandbox: true,
        http: {
          retries: 3,
          retryDelay: 10000,
        },
      },
    });
    ```
  </Tab>
</Tabs>

Abaixo está a lista detalhada com todos os parâmetros de configuração disponíveis.

<Expandable title="Parâmetros de Configuração">
  <ParamField path="apiKey" type="uuid" required>
    Chave de acesso à API
  </ParamField>

  <ParamField path="clientId" type="uuid" required>
    Identificador único da sua conta na Malga
  </ParamField>

  <ParamField path="options" type="object">
    Configurações adicionais

    <Expandable title="Parâmetros de options">
      <ParamField path="sandbox" type="string">
        Define se integração está rodando no ambiente de teste ou produção
      </ParamField>

      <ParamField path="http" type="object">
        Configurações das requisições http

        <Expandable title="Parâmetros de http">
          <ParamField path="retries" type="number">
            Número de retentativa de uma requisição em caso de falha para evitar
            condições de corrida
          </ParamField>

          <ParamField path="retryDelay" type="number">
            Tempo entre uma retentativa e outra em milisegundos
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

### Chave de Idempotência

O Malga API SDK suporta chaves de idempotência para evitar duplicidade no
processamento de requisições no caso de retentativas de uma mesma operação. Para que isso
seja possível, cada um dos nossos métodos de criação suporta um parâmetro adicional chamado `idempotencyKey`
para que seja definida a chave de idempotência.

Abaixo está um exemplo de como utilizar:

<Tabs>
  <Tab title="Node">
    ```typescript theme={null}
    import { Malga } from "malga";

    const malga = new Malga({
      apiKey: "17a64c8f-a387-4682-bdd8-d280493715e0",
      clientId: "d1d2b51a-0446-432a-b055-034518c2660e",
    });

    await malga.charges.create(
      {
        merchantId: "8cfef0d1-73af-4bdb-b6c4-09ad3fbfc7f1",
        amount: 100,
        paymentMethod: {
          type: "credit",
          installments: 1,
          card: {
            holderName: "João da Silva",
            number: "5453881028277600",
            cvv: "170",
            expirationDate: "10/2030",
          },
        },
      },
      { idempotencyKey: "518eb962-cccd-4bc3-a497-4e48335dc8c4" }
    );
    ```
  </Tab>
</Tabs>

Basta [clicar aqui](/documentations/more/idempotency) para saber mais detalhes sobre a chave de idempotência.

### Tratamento de Erros

No Malga API SDK o tratamento de erros é padronizado, todos os erros são
retornados da mesma forma com uma estrutura unificada. Dessa forma damos mais previsibilidade
de como é o comportamento dos métodos.

Abaixo está a estrutura detalhada de como é o retorno dos erros.

<Expandable title="Tratamento de Erros">
  <ParamField path="error" type="object">
    Objeto com os detalhes do erro

    <Expandable title="Parâmetros do error">
      <ParamField path="type" type="string">
        Tipo do erro
      </ParamField>

      <ParamField path="code" type="number">
        Status code da requisição
      </ParamField>

      <ParamField path="message" type="string">
        Mensagem resumida do erro
      </ParamField>

      <ParamField path="details" type="string | array">
        Mensagem detalhada do erro contendo os campos
      </ParamField>

      <ParamField path="declinedCode" type="string | array">
        Códigos de negação repassado pelo provedor
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

<br />

Basta [clicar aqui](/documentations/welcome/errors) para saber mais detalhes sobre o nosso tratamento de erros.