Primeiros Passos - PIED API

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

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.

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

2. Faça sua Primeira Requisição

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

API v2 (Recomendada)
API v1

Buscar Lista de Orçamentos (v2)

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

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.

{
  "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
}

Buscar Lista de Orçamentos (v1)

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"

Migração recomendada: Para novos projetos, considere usar a API v2 que oferece melhor performance e novos recursos.

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

# 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"

# 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"

4. Dicas para Otimização

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

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

# 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

Requests v2

Gerencie orçamentos e pedidos com a v2

Requests v1

Endpoints específicos da v1

Equipamentos

Acesse o catálogo de produtos

Empresas

Gerencie empresas parceiras

6. Configure Webhooks

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

Acesse sua plataforma PIED
Vá até Configurações > API e Webhooks
Clique na aba “Webhooks”
Clique em “Adicionar”
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

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

Próximos Passos

Referência API v2

Explore todos os endpoints da v2

Referência API v1

Consulte endpoints específicos da v1

Webhooks

Configure notificações em tempo real

​1. Obtenha seu Token de Acesso

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

​Buscar Lista de Orçamentos (v2)

​Resposta Esperada

​Buscar Lista de Orçamentos (v1)

​3. Entenda a Estrutura da URL

​Parâmetros

​Exemplos

​4. Dicas para Otimização

​5. Explore os Endpoints

Requests v2

Requests v1

Equipamentos

Empresas

​6. Configure Webhooks

​Próximos Passos

Referência API v2

Referência API v1

Webhooks

1. Obtenha seu Token de Acesso

2. Faça sua Primeira Requisição

Buscar Lista de Orçamentos (v2)

Resposta Esperada

Buscar Lista de Orçamentos (v1)

3. Entenda a Estrutura da URL

Parâmetros

Exemplos

4. Dicas para Otimização

5. Explore os Endpoints

6. Configure Webhooks

Próximos Passos