> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/ambientes-e-autenticacao.md).

# Ambientes e Autenticação

## Ambientes disponíveis

A API GTFgts disponibiliza dois ambientes para integração:

| Ambiente        | URL Base                                   | Finalidade                       |
| --------------- | ------------------------------------------ | -------------------------------- |
| **Homologação** | `https://ingress.gtfgts.staging.giro.tech` | Testes e validação da integração |
| **Produção**    | `https://ingress.gtfgts.giro.tech`         | Operações reais                  |

Todos os endpoints do originator ficam sob `/api/v1/**`.

{% hint style="warning" %}
Utilize **sempre** o ambiente de homologação durante o desenvolvimento e testes. O ambiente de produção deve ser utilizado apenas após validação completa do fluxo.
{% endhint %}

***

## Autenticação

A API utiliza **JWT (JSON Web Token)** para autenticação. O token é fornecido e rotacionado pela equipe de integração da Giro.Tech durante o onboarding do originator. Ele identifica o originator e é exigido em **todos** os endpoints `/api/v1/**`.

{% hint style="info" %}
Qualquer chamada a `/api/v1/**` sem um JWT válido retorna `401`.
{% endhint %}

### Como obter o token

1. Entre em contato com a equipe de integração da Giro.Tech
2. Informe os dados do originator (CNPJ, razão social, contato técnico)
3. O token JWT será gerado e entregue de forma segura

### Utilizando o token

Inclua o token no header `Authorization` de **todas** as requisições:

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET 'https://ingress.gtfgts.staging.giro.tech/api/v1/webhooks' \
  -H 'Authorization: Bearer {{seu_token_jwt}}' \
  -H 'Content-Type: application/json'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://ingress.gtfgts.staging.giro.tech/api/v1/webhooks', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{seu_token_jwt}}',
    'Content-Type': 'application/json'
  }
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {
    'Authorization': 'Bearer {{seu_token_jwt}}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://ingress.gtfgts.staging.giro.tech/api/v1/webhooks',
    headers=headers
)
```

{% endtab %}
{% endtabs %}

***

## Headers obrigatórios

| Header          | Valor              | Descrição                                      |
| --------------- | ------------------ | ---------------------------------------------- |
| `Authorization` | `Bearer {token}`   | Token JWT do originator                        |
| `Content-Type`  | `application/json` | Formato do corpo da requisição (para POST/PUT) |

### Header opcional

| Header            | Valor               | Descrição                                                                                                                                                |
| ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | `string` (máx. 100) | Chave de idempotência de negócio na submissão de operações. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md). |

***

## Códigos de resposta comuns

| Código | Significado         | Quando ocorre                                                                                                                                                                                                                                                    |
| ------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Sucesso             | Requisição síncrona processada — inclui a **resposta em cache** de consulta de saldo (`status: COMPLETED` com `result` inline)                                                                                                                                   |
| `201`  | Criado              | Recurso criado com sucesso (ex.: cadastro de webhook, simulação)                                                                                                                                                                                                 |
| `202`  | Aceito              | Operação FGTS admitida para **processamento assíncrono** (`status: QUEUED`) — acompanhe por webhook ou polling                                                                                                                                                   |
| `400`  | Requisição inválida | Falha de validação (`errorCode: VALIDATION_ERROR`)                                                                                                                                                                                                               |
| `401`  | Não autenticado     | Token ausente, inválido ou expirado (`errorCode: UNAUTHORIZED`)                                                                                                                                                                                                  |
| `403`  | Sem permissão       | Consulta de operação (`GET /api/v1/fgts/operations/{requestId}`) com `requestId` de outro originator (`errorCode: ORIGINATOR_OWNERSHIP_VIOLATION`). Nas demais rotas, recurso de outro originator responde `404`                                                 |
| `404`  | Não encontrado      | Recurso inexistente ou que não pertence ao originator autenticado                                                                                                                                                                                                |
| `409`  | Conflito            | Estado que impede a operação (ex.: cadastro de webhook já existente)                                                                                                                                                                                             |
| `429`  | Limite excedido     | Rate limit por originator excedido — `INGRESS_RATE_LIMIT_EXCEEDED` nas operações FGTS, `RATE_LIMIT_EXCEEDED` em contratos e cadastro de webhook. Ver [Rate Limit Excedido](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#rate-limit-exceeded) |
| `500`  | Erro interno        | Erro inesperado no servidor (`errorCode: INTERNAL_ERROR`)                                                                                                                                                                                                        |
| `503`  | Indisponível        | Indisponibilidade momentânea; repita após `Retry-After`. Ver [Serviço Indisponível](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#upstream-unavailable)                                                                                       |

Todos os códigos, com o que fazer em cada caso, estão no [Catálogo de códigos](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo). | `503` | Indisponível | Serviço temporariamente indisponível — aguarde o header `Retry-After`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#upstream-unavailable) |

{% hint style="info" %}
Quando o token expirar, será necessário solicitar um novo token à equipe de integração. Tokens expirados retornam `401 Unauthorized`.
{% endhint %}

Detalhes do fluxo assíncrono (`202` → webhook/polling) em [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md); o formato dos erros em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

***

## Restrição de IPs

Se necessário, a Giro.Tech pode configurar restrição de IP (allowlist) para acesso ao ambiente de produção. Solicite à equipe de integração caso sua política de segurança exija essa configuração.

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
