# Testando a API

Este guia mostra como realizar seus primeiros testes com a GoPag API.

## Pré-requisitos

Antes de começar, certifique-se de ter:

* ✅ Bearer Token (obtido via Portal GoPag ou consultor)
* ✅ Certificado mTLS (ICP-Brasil) instalado e configurado
* ✅ Marketplace ID fornecido pela GoPag
* ✅ Acesso ao ambiente de homologação

## Ferramentas Recomendadas

### cURL

Disponível nativamente em Linux/MacOS, ou via Git Bash/WSL no Windows.

### Postman

* Download: <https://www.postman.com/downloads/>
* Suporta mTLS nativamente
* Facilita organização de coleções

### Insomnia

* Download: <https://insomnia.rest/download>
* Interface simples e intuitiva
* Suporte completo a certificados

## Teste 1: Listar Vendedores

Teste básico para validar autenticação completa (mTLS + Bearer Token).

### Request

```bash
curl --location 'https://api-stage.gopag.com.br/v1/marketplaces/SEU_MARKETPLACE_ID/sellers?limit=10' \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```

### Response Esperada

```json
{
  "resource": "list",
  "uri": "/v1/marketplaces/abc123.../sellers",
  "limit": 10,
  "offset": 0,
  "has_more": false,
  "query_count": 2,
  "total": 2,
  "items": [
    {
      "id": "17d9e827664b47509f12a082b6047e7a",
      "status": "pending",
      "resource": "seller",
      "type": "business",
      "business_name": "Empresa XYZ LTDA",
      "ein": "12345678000190",
      "created_at": "2025-12-15T10:30:00Z"
    }
  ]
}
```

### ✅ Teste bem-sucedido se:

* Status code: `200 OK`
* Campo `items` retorna array (pode estar vazio)
* Estrutura HAL+JSON válida

## Teste 2: Criar Transação PIX

Teste de criação de transação simples.

### Request

```bash
curl --location 'https://api-stage.gopag.com.br/v1/marketplaces/SEU_MARKETPLACE_ID/transactions' \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "payment_type": "pix",
  "on_behalf_of": "SELLER_ID",
  "description": "Teste de integração PIX",
  "currency": "BRL",
  "amount": 1000,
  "pix_expiration_date_time": "2025-12-22 23:59:59"
}'
```

### Response Esperada

```json
{
  "id": "abc123def456...",
  "status": "pending",
  "resource": "transaction",
  "payment_type": "pix",
  "amount": "10.00",
  "currency": "BRL",
  "description": "Teste de integração PIX",
  "on_behalf_of": "SELLER_ID",
  "qr_code": "00020126....",
  "qr_code_url": "https://...",
  "created_at": "2025-12-21T14:30:00Z"
}
```

### ✅ Teste bem-sucedido se:

* Status code: `201 Created`
* Campo `qr_code` presente
* Status inicial: `pending`

## Teste 4: Consultar Transação

Verificar status de transação criada.

### Request

```bash
curl --location 'https://api-stage.gopag.com.br/v1/marketplaces/SEU_MARKETPLACE_ID/transactions/TRANSACTION_ID' \
--cert /etc/ssl/gopag/client.crt \
--key /etc/ssl/gopag/client.key \
--cacert /etc/ssl/gopag/ca.crt \
--header 'Authorization: Bearer SEU_ACCESS_TOKEN'
```

### Response Esperada

```json
{
  "id": "abc123def456...",
  "status": "succeeded",
  "resource": "transaction",
  "payment_type": "pix",
  "amount": "10.00",
  "fees": "0.50",
  "created_at": "2025-12-21T14:30:00Z",
  "updated_at": "2025-12-21T14:35:00Z"
}
```

## Configurando Postman

### 1. Importar Certificados

1. Settings → Certificates → Add Certificate
2. Host: `api-stage.gopag.com.br`
3. CRT file: Selecione `client.crt`
4. KEY file: Selecione `client.key`
5. PFX/P12: (deixe vazio se usar CRT+KEY)

### 2. Criar Environment

```json
{
  "base_url": "https://api-stage.gopag.com.br",
  "marketplace_id": "abc123...",
  "bearer_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```

### 3. Configurar Authorization

Em cada requisição ou na collection:

1. Authorization → Type: **Bearer Token**
2. Token: `{{bearer_token}}`

## Troubleshooting

### SSL Certificate Error

**Erro:**

```
SSL certificate problem: unable to get local issuer certificate
```

**Solução:**

```bash
# Adicione o CA certificate
curl --cacert /etc/ssl/gopag/ca.crt ...
```

### Bearer Token Inválido

**Erro:**

```json
{
  "status": 401,
  "detail": "Invalid or expired access token"
}
```

**Solução:**

* Verifique se o Bearer Token está correto
* Solicite novo token via Portal GoPag ou consultor

### Marketplace ID Incorreto

**Erro:**

```json
{
  "status": 403,
  "detail": "Certificate serial number does not match marketplace_id"
}
```

**Solução:**

* Verifique se `certSerialNumber` do certificado === `marketplace_id` na URL
* Use `openssl x509 -in client.crt -serial -noout` para verificar

### Campos Inesperados

**Erro:**

```json
{
  "status": 400,
  "detail": "Unexpected fields found: ['campo_invalido']"
}
```

**Solução:**

* A API valida campos estritamente
* Remova campos não documentados do payload

## Próximos Passos

Agora que você testou a API com sucesso:

1. [Criar Transações de Cartão](/developers/transacoes/criar-transacao-sem-checkout/cartao.md)
2. [Gerenciar Vendedores](/developers/cadastro/vendedores/listar.md)
3. [Entender Webhooks](https://github.com/Gestao-Online/gopag-public-docs/blob/master/DEVELOPERS/webhooks/introducao.md)
4. [Códigos de Erro](/developers/introducao/codigos-erro.md)

## Ambiente de Produção

Quando estiver pronto para produção:

1. ✅ Substitua base URL para `https://api.gopag.com.br`
2. ✅ Use certificado mTLS de **produção**
3. ✅ Use Bearer Token de **produção**
4. ✅ Configure monitoramento e logs
5. ✅ Implemente tratamento de erros robusto
6. ✅ Configure webhooks para notificações

**⚠️ NUNCA use credenciais de produção em homologação!**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gopag.com.br/developers/introducao/testando.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.