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

# Primeiros Passos

> Configure sua primeira requisição à API PIED em minutos

<Note>
  **🚀 Usando a v2?** Ótima escolha! Este guia mostra exemplos para ambas as versões, mas recomendamos a v2 para novos projetos.
</Note>

## 1. Obtenha seu Token de Acesso

Para usar a API PIED, você precisa de um token Bearer. Gere o token diretamente em sua plataforma PIED.

<img src="https://mintcdn.com/pied-3a231858/LUsafqzn6f6bEeVa/images/gerarChaveApi.png?fit=max&auto=format&n=LUsafqzn6f6bEeVa&q=85&s=42910635d0c7cc119b194df7dc0be130" alt="Gerar chave API" width="1041" height="117" data-path="images/gerarChaveApi.png" />

<Warning>
  **Segurança:** Mantenha seu token seguro e nunca o compartilhe publicamente. Use variáveis de ambiente em produção.
</Warning>

## 2. Faça sua Primeira Requisição

Escolha a versão da API que você deseja usar:

<Tabs>
  <Tab title="API v2 (Recomendada)">
    ### Buscar Lista de Orçamentos (v2)

    ```bash theme={null}
    curl -X GET "https://backend-pied-prod.piedadmin.com.br/api/v2/requests/budget/1/10" \
      -H "Authorization: Bearer SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json"
    ```

    ### Resposta Esperada

    <Note>
      **Sobre o tamanho da resposta:** A resposta real pode ser significativamente maior, contendo dezenas de campos adicionais por item, incluindo detalhes completos de equipamentos, informações de contato, dados técnicos, histórico de alterações, e muito mais. O exemplo abaixo mostra apenas os campos principais para simplicidade.
    </Note>

    ```json theme={null}
    {
      "data": [
        {
          "id": "123456",
          "name": "Orçamento Solar Residencial",
          "code": "200000001",
          "kind": "Kit Personalizado",
          "totalPower": 5.5,
          "budgetCreated": "2024-01-15T10:30:00.000Z",
          "dealStatus": "Em Análise",
          "originalValue": 25000,
          "finalValue": 22500
          // ... muitos outros campos disponíveis
        }
      ],
      "totalItems": 340
    }
    ```
  </Tab>

  <Tab title="API v1">
    ### Buscar Lista de Orçamentos (v1)

    ```bash theme={null}
    curl -X GET "https://backend-pied-prod.piedadmin.com.br/api/v1/requests/budget/1/10" \
      -H "Authorization: Bearer SEU_TOKEN_AQUI" \
      -H "Content-Type: application/json"
    ```

    <Info>
      **Migração recomendada:** Para novos projetos, considere usar a [API v2](/api-reference/v2/overview) que oferece melhor performance e novos recursos.
    </Info>
  </Tab>
</Tabs>

## 3. Entenda a Estrutura da URL

Ambas as versões usam paginação para listar recursos:

```
GET /{versão}/requests/budget/{pageNumber}/{pageLimit}
```

### Parâmetros

* **pageNumber**: Número da página (inicia em 1)
* **pageLimit**: Itens por página (máximo 50)

### Exemplos

<CodeGroup>
  ```bash v2 theme={null}
  # Primeira página com 10 itens
  curl -X GET "https://backend-pied-prod.piedadmin.com.br/api/v2/requests/budget/1/10" \
    -H "Authorization: Bearer SEU_TOKEN_AQUI"
  ```

  ```bash v1 theme={null}
  # Primeira página com 10 itens
  curl -X GET "https://backend-pied-prod.piedadmin.com.br/api/v1/requests/budget/1/10" \
    -H "Authorization: Bearer SEU_TOKEN_AQUI"
  ```
</CodeGroup>

## 4. Dicas para Otimização

<Warning>
  **Atenção ao volume de dados:** As respostas da API podem ser extensas (vários KB por item). Para otimizar performance:
</Warning>

* **Use paginação adequada:** Ajuste os parâmetros de página e limite conforme necessário
* **Implemente cache:** Para dados que não mudam frequentemente
* **Monitore timeouts:** Configure timeouts adequados em suas requisições
* **Filtre por data:** Use filtros de data quando disponíveis para reduzir o volume

```bash theme={null}
# Exemplo com paginação menor para testes
curl -X GET "https://backend-pied-prod.piedadmin.com.br/api/v2/requests/budget/1/5" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"
```

## 5. Explore os Endpoints

<CardGroup cols={2}>
  <Card title="Requests v2" icon="file-invoice" href="/api-reference/v2/request/get-requests">
    Gerencie orçamentos e pedidos com a v2
  </Card>

  <Card title="Requests v1" icon="file-invoice" href="/api-reference/v1/request/get-requests">
    Endpoints específicos da v1
  </Card>

  <Card title="Equipamentos" icon="solar-panel" href="/api-reference/v2/equipment/get-equipments">
    Acesse o catálogo de produtos
  </Card>

  <Card title="Empresas" icon="building" href="/api-reference/v2/company/post-company">
    Gerencie empresas parceiras
  </Card>
</CardGroup>

## 6. Configure Webhooks

Para receber notificações automáticas sobre mudanças em orçamentos e pedidos:

1. **Acesse sua plataforma PIED**
2. **Vá até Configurações > API e Webhooks**
3. **Clique na aba "Webhooks"**
4. **Clique em "Adicionar"**
5. **Preencha os campos:**
   * **Nome do webhook:** Adicione um nome descritivo
   * **Endpoint:** URL do seu sistema que receberá as notificações
   * **Gatilho:** Selecione os eventos (ex: orçamento criado, pedido atualizado)
   * **Autenticação:** Configure se necessário

<img src="https://mintcdn.com/pied-3a231858/Yv40P3HvT7ieGLcn/images/adicionarWebhook.png?fit=max&auto=format&n=Yv40P3HvT7ieGLcn&q=85&s=19c771ec58e23e89e73fad83f9fb8948" alt="Configurar Webhooks" width="548" height="528" data-path="images/adicionarWebhook.png" />

<Tip>
  **Dica de desenvolvimento:** Use ferramentas como ngrok para desenvolvimento local, ou webhook.site para testar as notificações.
</Tip>

## Próximos Passos

<CardGroup cols={3}>
  <Card title="Referência API v2" icon="rocket" href="/api-reference/v2/overview">
    Explore todos os endpoints da v2
  </Card>

  <Card title="Referência API v1" icon="archive" href="/api-reference/v1/request/get-requests">
    Consulte endpoints específicos da v1
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/introduction">
    Configure notificações em tempo real
  </Card>
</CardGroup>