Pular para conteúdo

Anexo A — Contrato da API REST da PIED

Informação extraída em 16/06/2026 da documentação da API da PIED (OpenAPI v2/v1). Resumo simplificado, só com o necessário para definir o escopo.

Acesso

  • Base URL (v2): https://backend-pied-prod.piedadmin.com.br/api/v2 (v1 atende empresas).
  • Autenticação: header Authorization: Bearer <token>.
  • Paginação: /{rota}/{página}/{limite} — limite máx. 50.
  • Limite de uso: dois tetos por hora (qtd. de chamadas e tempo de processamento) → ritmo controlado.

A.1 Produtos — GET /equipments/{página}/{limite}

Request 

GET /api/v2/equipments/1/50
Authorization: Bearer <token>
Reply (200) 
{
  "data": [
    {
      "productCode": "MOD-550",
      "name": "Painel Solar 550W Monocristalino",
      "manufacturer": "Canadian Solar",
      "model": "CS6W-550MS",
      "type": "module",
      "baseprice": 780.00,
      "inventory": { "current": 320, "reserved": 12, "minimum": 50 }
    }
  ],
  "totalItems": 1
}

A.2 Pedidos — GET /requests/order/{página}/{limite}

Cliente (company) e itens (products) vêm embutidos no pedido.

Request 

GET /api/v2/requests/order/1/50?lastUpdateAfter=2026-06-10
Authorization: Bearer <token>
Reply (200) 
{
  "data": [
    {
      "id": "6f3a9c12", "code": "200000123", "type": "order",
      "kind": "Kit Personalizado", "totalPower": 5.5,
      "dealStatus": "Novo", "originalValue": 25000, "discount": 5, "finalValue": 23750,
      "company": {
        "cnpj": "12.345.678/0001-09", "companyName": "Solar Sul Ltda",
        "mainContact": { "name": "João", "surname": "Silva", "email": "joao@solarsul.com", "cellphone": "5642999990000" },
        "address": { "CEP": "84010-000", "state": "PR", "city": "Ponta Grossa",
                     "neighborhood": "Centro", "patio": "Rua das Acácias", "number": "100", "complement": "" }
      },
      "products": [
        { "productCode": "MOD-550", "type": "module", "quantity": 10,
          "singlePrice": 780, "totalPrice": 7800, "center": { "code": "CD001" } }
      ],
      "payment": { "type": "credito", "status": "received",
                   "condition": { "name": "30/60 dias", "quantityOfInstallments": 2 } },
      "freight": { "type": "CIF", "price": 350 },
      "lastUpdate": "2026-06-15T19:12:24.391Z"
    }
  ],
  "totalItems": 1
}

204 = nenhum registro. Orçamentos usam GET /requests/budget/... com o mesmo formato (coletados só para uso interno — não vão ao X-Adm).

A.3 Clientes — GET /companies/{página}/{limite} (v1)

Mesmo objeto company do pedido (cnpj/cpf, companyName, mainContact, address), mais stateInscription. Use quando precisar de clientes que ainda não geraram pedido.

A.4 Incremental (delta)

Chamando requests sem parâmetros, a API retorna só o que mudou desde a última chamada (marcadores apiSent/apiSentUpdated). Cuidado: persistir o bruto antes de processar + manter reconciliação por data como rede de segurança.

Campos não cobertos pela documentação da PIED (pendências) em ../../PENDENCIAS.md.