API de Integração

Autenticação

Toda requisição precisa enviar sua chave de integração no header x-api-key:

x-api-key: ppk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• A chave é gerada pelo administrador da sua empresa dentro do ProdPlan (menu de Integração).
• Ela é exibida uma única vez, no momento da criação. Guarde-a em local seguro (cofre de segredos / variável de ambiente). Se perder, gere uma nova e revogue a antiga.
• A chave identifica sua empresa automaticamente — você não precisa (nem deve) enviar nenhum identificador de empresa nas requisições.

Erros de autenticação

Base URL

https://api.prodplan.com.br/integration/v1

Todos os caminhos abaixo são relativos a essa base.

Consultar pedidos

Retorna pedidos com seus itens e, para cada item, o histórico de leituras de produção.

Parâmetros de consulta

Todos são opcionais e combináveis.

Sem filtros, retorna todos os pedidos da empresa (paginados), do mais recente para o mais antigo.

Exemplos

# Um pedido específico
curl -H "x-api-key: SUA_CHAVE" \
  "https://api.prodplan.com.br/integration/v1/orders?orderNumber=101"

# Vários pedidos
curl -H "x-api-key: SUA_CHAVE" \
  "https://api.prodplan.com.br/integration/v1/orders?orderNumber=101,102,103"

# Um lote inteiro
curl -H "x-api-key: SUA_CHAVE" \
  "https://api.prodplan.com.br/integration/v1/orders?batchNumber=5"

# Lote + paginação
curl -H "x-api-key: SUA_CHAVE" \
  "https://api.prodplan.com.br/integration/v1/orders?batchNumber=5&page=2&limit=100"

Resposta 200 OK

{
  "data": [
    {
      "orderNumber": 101,
      "batchNumber": 5,
      "boxNumber": 12,
      "customerName": "Marcenaria Silva",
      "buyOrder": "OC-2024-889",
      "loadNumber": "CARGA-31",
      "orderDate": "2026-07-10T00:00:00.000Z",
      "deliveryDate": "2026-07-25T00:00:00.000Z",
      "totalAmount": 12500.0,
      "createdAt": "2026-07-10T13:02:11.000Z",
      "progress": {
        "totalItems": 120,
        "itemsStarted": 120,
        "itemsFinished": 84,
        "cutting":   { "total": 120, "done": 120 },
        "drilling":  { "total": 120, "done": 100 },
        "border":    { "total": 120, "done": 96  },
        "packaging": { "total": 120, "done": 84  },
        "firstReadDate": "2026-07-11T08:15:00.000Z",
        "lastReadDate":  "2026-07-18T16:40:00.000Z"
      },
      "items": [
        {
          "barcode": "7891234500017",
          "quantity": 2,
          "product": {
            "itemCode": "MDF-18-BRANCO",
            "description": "Lateral 18mm Branco TX 700x400"
          },
          "readings": [
            {
              "readingType": "Normal",
              "readDate": "2026-07-11T08:15:00.000Z",
              "machineId": 7,
              "machineDescription": "Seccionadora 01",
              "poId": 1
            }
          ]
        }
      ]
    }
  ],
  "total": 37,
  "page": 1,
  "limit": 50
}

Dicionário de campos

Pedido (data[])

Progresso (progress)

Contadores por etapa de produção. Cada etapa traz total (itens que passam por ela) e done (itens já lidos nela). Etapas: cutting (corte), drilling (furação), border (bordagem/coladeira), packaging (embalagem). itemsFinished == totalItems indica pedido concluído.

Item (items[])

Leitura (readings[])

Cada apontamento de produção do item, em ordem cronológica.

Rate limit

• 120 requisições por minuto, por chave.
• Cada resposta traz os headers padrão RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset.
• Ao exceder, a API responde 429 com { "error": "RATE_LIMITED" }. Aguarde a janela reiniciar (respeite RateLimit-Reset) e evite polling agressivo — prefira consultar por lote/pedido.

Boas práticas

• Guarde a chave como segredo. Nunca a exponha em código-fonte público, front-end ou logs.
• Rotação: para trocar a chave sem downtime, gere a nova, atualize sua integração e só então revogue a antiga.
• Paginação: ao varrer muitos pedidos, itere page até page * limit >= total.
• Datas: todas em UTC, formato ISO 8601. Converta para o fuso local ao exibir.
• Versionamento: o caminho começa em /v1. Mudanças incompatíveis virão em /v2, sem quebrar o /v1.

Suporte

Dúvidas de integração ou solicitação de habilitação/aumento de limite: entre em contato com a equipe ProdPlan.