{
  "info": {
    "name": "Folit Integration API",
    "description": "Generated from canonical OpenAPI. Configure baseUrl and an explicitly scoped integration token. HTTP 200 can report partial failures; inspect ok/failed/items.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{integrationToken}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://YOUR_FOLIT_API_ORIGIN"
    },
    {
      "key": "integrationToken",
      "value": ""
    }
  ],
  "item": [
    {
      "name": "Artigos e lotes",
      "item": [
        {
          "name": "getCatalogueSyncCheckpoint",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/articles/sync/{{connection}}",
            "header": [],
            "description": "Permission: articles:read. "
          }
        },
        {
          "name": "getCatalogueSyncBatch",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/articles/sync/{{connection}}/{{sequence}}",
            "header": [],
            "description": "Permission: articles:read. "
          }
        },
        {
          "name": "submitCatalogueSyncBatch",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/sync/{{connection}}",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: articles:write. ",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sequence\": 1,\n  \"lower\": \"EXEMPLO\",\n  \"upper\": \"EXEMPLO\",\n  \"mode\": \"bootstrap\",\n  \"final\": false,\n  \"articles\": [\n    \"EXEMPLO\"\n  ]\n}"
            }
          }
        },
        {
          "name": "retryCatalogueSyncBatch",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/sync/{{connection}}/{{sequence}}/retry",
            "header": [],
            "description": "Permission: articles:write. "
          }
        },
        {
          "name": "getErpCatalogueImportCurrent",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/articles/imports/current",
            "header": [],
            "description": "Permission: articles:read. "
          }
        },
        {
          "name": "getErpCatalogueImport",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/articles/imports/{{id}}",
            "header": [],
            "description": "Permission: articles:read. "
          }
        },
        {
          "name": "createErpCatalogueImport",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/imports",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: articles:write. ",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"id\": \"EXEMPLO\",\n  \"expected\": 1\n}"
            }
          }
        },
        {
          "name": "receiveErpCatalogueImportBatch",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/imports/{{id}}/batches",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: articles:write. ",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"batch\": 0,\n  \"articles\": [\n    {}\n  ]\n}"
            }
          }
        },
        {
          "name": "sealErpCatalogueImport",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/imports/{{id}}/seal",
            "header": [],
            "description": "Permission: articles:write. "
          }
        },
        {
          "name": "retryErpCatalogueImport",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/imports/{{id}}/retry",
            "header": [],
            "description": "Permission: articles:write. "
          }
        },
        {
          "name": "cancelErpCatalogueImport",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/imports/{{id}}/cancel",
            "header": [],
            "description": "Permission: articles:write. "
          }
        },
        {
          "name": "Consultar artigos pendentes de sincronização",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/articles/pending-sync",
            "header": [],
            "description": "Permission: articles:read. Handles legacy Timestamp and epoch-millis records together. Use nextCursorMs AND nextCursorId for the next page. Retrieve photos through GET /api/v1/articles/{id}."
          }
        },
        {
          "name": "Consultar um artigo, EANs e fotografias",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/articles/{{id}}",
            "header": [],
            "description": "Permission: articles:read. Devolve o artigo completo, com `photos[]` (URLs assinadas 15min),\n`eans[]` e `coverPhotoId`. Útil para sincronizar para o ERP o\nmaterial curado no telemóvel (Folit Data, Business+).\n"
          }
        },
        {
          "name": "Criar ou actualizar artigos",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/upsert",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: articles:write. Validates the payload before writing. Each record is transactional. HTTP 200 may contain ok:false and skipped items: inspect failed/items and retry only after resolving the reason. Safe to retry by stable reference; no batch-wide atomicity. No automatic merging of conflicting identities.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"articles\": [\n    {\n      \"externalRef\": \"ART-001\",\n      \"description\": \"Artigo Exemplo\",\n      \"basePrice\": 10,\n      \"taxRate\": 23\n    }\n  ]\n}"
            }
          }
        },
        {
          "name": "Confirmar a referência ERP de artigos",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/sync-back",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: articles:write. Confirms the ERP reference on the original Folit article. Idempotent for the same identity. Cross-tenant targets, reassignments and collisions are rejected per item. Inspect ok/failed/items.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"items\": [\n    {\n      \"id\": \"ID_FOLIT\",\n      \"externalRef\": \"ART-001\"\n    }\n  ]\n}"
            }
          }
        },
        {
          "name": "Criar ou actualizar lotes",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/articles/lots/upsert",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: lots:write. Validates the payload before writing. Each record is transactional. HTTP 200 may contain ok:false and skipped items: inspect failed/items and retry only after resolving the reason. Safe to retry by stable reference; no batch-wide atomicity. No automatic merging of conflicting identities.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"lots\": [\n    {\n      \"externalRef\": \"ART-001\",\n      \"lot\": \"LOTE-001\",\n      \"qty\": 10,\n      \"expiry\": \"2027-12-31\"\n    }\n  ]\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Diagnóstico",
      "item": [
        {
          "name": "Verificar a ligação e o token",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/health",
            "header": [],
            "description": "Permission: valid token. Verifica o token, devolve o tenantId resolvido e a versão da API.\nÚtil em `init-db.js` do KIT antes de tentar a primeira chamada.\n"
          }
        }
      ]
    },
    {
      "name": "Fornecedores",
      "item": [
        {
          "name": "Criar ou actualizar fornecedores",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/suppliers/upsert",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: suppliers:write. Validates the payload before writing. Each record is transactional. HTTP 200 may contain ok:false and skipped items: inspect failed/items and retry only after resolving the reason. Safe to retry by stable reference; no batch-wide atomicity. No automatic merging of conflicting identities.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"suppliers\": [\n    {\n      \"externalRef\": \"FOR-001\",\n      \"name\": \"Fornecedor Exemplo\",\n      \"nif\": \"501234567\"\n    }\n  ]\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Referências de fornecedores",
      "item": [
        {
          "name": "Consultar referências de fornecedores",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/supplier-references",
            "header": [],
            "description": "Permission: supplier-references:read. "
          }
        },
        {
          "name": "Associar referências de fornecedores a artigos",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/supplier-references/upsert",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: supplier-references:write. Validates the payload before writing. Each record is transactional. HTTP 200 may contain ok:false and skipped items: inspect failed/items and retry only after resolving the reason. Safe to retry by stable reference; no batch-wide atomicity. No automatic merging of conflicting identities.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"references\": [\n    {\n      \"supplierExternalRef\": \"FOR-001\",\n      \"supplierReference\": \"REF-001\",\n      \"articleExternalRef\": \"ART-001\"\n    }\n  ]\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Documentos",
      "item": [
        {
          "name": "Consultar documentos novos ou alterados",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/purchases/changes",
            "header": [],
            "description": "Permission: purchases:read. Entrega dados a staging mesmo sem fornecedor ERP. exportWarnings identifica avisos de negócio sem bloquear a página. A política explícita de exportar apenas conciliados continua aplicável ao incremental. Use id para recuperar um documento depois do cursor, sem o alterar."
          }
        },
        {
          "name": "erpDocumentDeletions",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/purchases/deletions",
            "header": [],
            "description": "Permission: purchases:read. "
          }
        },
        {
          "name": "erpDocumentLifecycle",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/purchases/{{id}}/lifecycle",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: purchases:ack. ",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"action\": \"inspect\"\n}"
            }
          }
        },
        {
          "name": "Confirmar a integração de um documento",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/purchases/{{id}}/ack",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: purchases:ack. Regista o resultado devolvido pelo ERP. Sem status mantém o comportamento antigo (integrated). Não altera o cursor de exportação. Requer Sincronização ERP ativa.",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"externalRef\": \"ERP-DOC-001\"\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Recepções",
      "item": [
        {
          "name": "Consultar recepções novas ou alteradas",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/receptions/changes",
            "header": [],
            "description": "Permission: receptions:read. Devolve eventos de recepção física, unificando dois modelos:\n\n- **`kind: \"linked\"`** — recepção contra uma fatura existente\n  (Folit Check Fase A). `linkedPurchaseId` aponta para o documento\n  de compra; cada linha traz `qtyExpected` / `qtyReceived` /\n  `qtyShortage` / `qtyOverage` pré-calculados pelo servidor.\n- **`kind: \"standalone\"`** — recepção \"à parte\", sem fatura\n  (Folit Check Fase B). Material entrou antes do documento; útil\n  para emitir guia de entrada provisória no ERP. Quando o\n  utilizador associa a fatura mais tarde, o evento é re-emitido\n  com `standaloneStatus: \"linked\"` + `linkedPurchaseId`.\n\nCursor composite idêntico a `/purchases/changes`. Eventos\ncancelados são emitidos com `standaloneStatus: \"cancelled\"` para\no ERP poder anular o documento de entrada criado.\n"
          }
        },
        {
          "name": "Confirmar a integração de uma recepção",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/receptions/{{id}}/ack",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: receptions:ack. Para `kind: \"linked\"` use o `id` composto `purchaseId#receptionId`\nURL-encoded. Para `kind: \"standalone\"` use o `id` simples.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"externalRef\": \"ERP-REC-001\"\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Contabilidade",
      "item": [
        {
          "name": "Consultar movimentos contabilísticos",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/accounting/movements",
            "header": [],
            "description": "Permission: accounting:read. Movimentos equilibrados, excluindo adiantamentos. markExported=true altera o estado e exige também accounting:write. Filtrar por datas para limitar a consulta."
          }
        },
        {
          "name": "Confirmar número de lançamento",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/api/v1/accounting/entry-number",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: accounting:write. ",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sourceType\": \"document\",\n  \"sourceId\": \"ID_FOLIT\",\n  \"entryNumber\": \"LANC-001\"\n}"
            }
          }
        }
      ]
    },
    {
      "name": "Colaboradores",
      "item": [
        {
          "name": "Consultar colaboradores",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/employees",
            "header": [],
            "description": "Permission: employees:read. "
          }
        },
        {
          "name": "Consultar um colaborador",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/api/v1/employees/{{id}}",
            "header": [],
            "description": "Permission: employees:read. "
          }
        },
        {
          "name": "Criar ou actualizar um colaborador",
          "request": {
            "method": "PUT",
            "url": "{{baseUrl}}/api/v1/employees/by-reference/{{externalRef}}",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "description": "Permission: employees:write. ",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Colaborador Exemplo\",\n  \"employeeNumber\": \"E001\"\n}"
            }
          }
        }
      ]
    }
  ]
}
