Módulo E-commerce

Endpoint público. Devolve as empresas TP Software com o módulo API e-commerce ativo, abertas a parcerias e integrações comerciais. Use-o para descobrir potenciais fornecedores antes de receber um token.

Query Parameters

Exemplo

curl https://hub.tp.software/api/v1/ecommerce/companies

{
  "success": true,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "Auto Peças, Lda",
      "address": "Rua das Peças, 123",
      "zipcode": "4700-000",
      "company_registration_number": "500000000",
      "reg_number_dismantler": "DM/2026/001",
      "phone_number": "+351 253 000 000",
      "country": "Portugal",
      "email": "contacto@autopecas.pt"
    }
  ],
  "total": 10,
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total": 10,
    "total_pages": 1,
    "has_more": false
  },
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

Peças disponíveis da empresa do token (em stock, com quantidade livre e não em rascunho), com paginação, pesquisa e ordenação. Cada peça inclui imagens, vídeos, unidades por localização, viaturas compatíveis, referências, danos, atributos e categorias.

Query Parameters

Exemplo

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://hub.tp.software/api/v1/ecommerce/product-inventory?limit=50&page=1&order_field=updated_at&order_type=desc&language=pt"

Resposta (uma peça)

{
  "success": true,
  "message": "success",
  "data": [
    {
      "id": 309,
      "part_catelog": "1520",
      "company_id": "179",
      "vehicle_id": "96",
      "part_code": "ACB-4821-X",
      "quantity": 2,
      "reserved_quantity": 0,
      "part_description": "Farol esquerdo completo",
      "is_custom_size": 0,
      "parts_weight": 4.5,
      "parts_length": 60,
      "parts_width": 25,
      "parts_height": 20,
      "vat_included": 1,
      "cc": "1998",
      "cv": "150",
      "kw": "110",
      "parts_internal_id": "FH-789654",
      "reg_number_dismantler": "DM/2026/001",
      "state_id": "1",
      "condition_id": "1",
      "product_name": "Farol Esquerdo",
      "vehicle_model_name": "Focus",
      "vehicle_make_name": "Ford",
      "vehicle_variant_name": "2.0 EcoBoost ST",
      "brand_name": "Valeo",
      "motor_code": "R9DA",
      "inventory_status": "In Stock",
      "created_at": "2026-09-20T10:15:00.000Z",
      "updated_at": "2026-10-07T16:02:11.000Z",
      "vehicle_year": "2018",
      "bar_code_parts": "1234567890123",
      "is_master_part": null,
      "master_part_id": null,
      "master_part_inventory_id": null,
      "part_rating": 5,
      "green_part_rating": 4,
      "on_order": false,
      "deposit_value": null,
      "vehicle_type_name": "Ligeiro",
      "fuel_type_name": "Gasolina",
      "state_name": "Used",
      "condition_name": "OEM",
      "sync_id": 60,
      "part_price": "95.00",
      "image_list": [
        {
          "image_url": "https://images.tp.software/uploads/vehicle/parts/1742277347163-12.jpg",
          "part_name": "Farol",
          "image_uuid": "adae8407-cb7f-4614-b270-2d5b2b6683fc",
          "part_id": 309,
          "uuid": "a83884fc-86f8-4fab-a041-3be250b14eab",
          "part_code": "ACB-4821-X",
          "quantity": 2,
          "inventory_status": 1,
          "part_description": "Farol esquerdo completo",
          "id": 202,
          "damage_list": []
        }
      ],
      "video_list": [],
      "part_qty_list": [
        {
          "parts_id": "309",
          "uuid": "c970a0c2-8fbf-4a68-9d2a-3a35fdeafe85",
          "id": 264,
          "qty": 1,
          "location_ids": "12.40",
          "part_rating": 5,
          "location_name": "Armazém 1.Estante A1"
        }
      ],
      "parts_associate": [
        {
          "id": 31,
          "make_name": "Ford",
          "model_name": "Focus",
          "vehicle_year": "2018",
          "variant_name": "2.0 EcoBoost ST",
          "vehicle_type_name": "Ligeiro"
        }
      ],
      "parts_reference": [
        {
          "id": 17,
          "parts_id": "309",
          "is_main": 1,
          "condition_id": "1",
          "type_id": "2",
          "reference_code": "90012345",
          "brand": "Valeo",
          "manufacter": null,
          "type_name": "Written on the label",
          "condition_name": "OEM"
        }
      ],
      "parts_damage": [],
      "part_attribute": [],
      "parts_checklist": [],
      "category_hierarchies": []
    }
  ],
  "total": 541,
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 541,
    "total_pages": 11,
    "has_more": true
  },
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

Campos principais

Verifica se uma quantidade de uma peça está livre (stock menos reservas). Útil antes de criar uma encomenda.

Query Parameters

Exemplo

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://hub.tp.software/api/v1/ecommerce/product-inventory/check?product_id=309&qty=1"

{
  "success": true,
  "data": {
    "available": true,
    "company_id": 179,
    "product_id": 309,
    "qty": 1,
    "message": "Quantidade disponível"
  },
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

Sem quantidade livre a resposta é igualmente 200, com "available": false.

Cria uma encomenda na empresa do token e reserva as peças. A encomenda só entra se todas as peças forem da empresa e tiverem unidade livre — caso contrário nada é gravado (422 ORDER_REJECTED).

Body (JSON)

{
  "num_products": 2,
  "total_value_products": 225,
  "total_value_shipping": 15,
  "total_value_packaging": 4.5,
  "total_value_other_parcel": 0,
  "tax_vat_products": 51.75,
  "tax_vat_shipping": 3.45000000000000017763568394002504646778106689453125,
  "tax_vat_packaging": 1.04000000000000003552713678800500929355621337890625,
  "tax_vat_other_parcel": 0,
  "exemption_vat_products": 0,
  "exemption_vat_shipping": 0,
  "exemption_vat_packaging": 0,
  "exemption_vat_other_parcel": 0,
  "maximum_sale_alert_date": "2026-10-15",
  "notes_sale": "Frágil. Entregar entre as 9h e as 12h.",
  "seller_takes_care_shipping": 1,
  "provider_takes_care_shipping": 0,
  "seller_invoice_provider": 0,
  "seller_invoice_client": 1,
  "shipping_label": "https://example.com/etiquetas/12345.pdf",
  "client": [
    {
      "name": "Miguel Santos",
      "country_code": "PT",
      "shipping_address": "Rua do Sol, 789",
      "postal_code": "4700-123",
      "city": "Braga",
      "invoice_address": "Rua do Sol, 789",
      "vat_number": "123456789",
      "country_code_vat_number": "PT",
      "phone": "+351910000000",
      "email": "miguel.santos@example.com",
      "whatsapp": "+351910000000"
    }
  ],
  "products": [
    {
      "product_id": 309,
      "part_qty_id": 264,
      "price_without_vat": 95,
      "tax_vat": 21.85000000000000142108547152020037174224853515625,
      "exemption_vat": 0,
      "images": [
        202
      ]
    },
    {
      "product_id": 395,
      "price_without_vat": 130,
      "tax_vat": 29.89999999999999857891452847979962825775146484375,
      "exemption_vat": 0
    }
  ]
}

Descrição dos Campos

Resposta

{
  "success": true,
  "message": "Order has been generated successfully!",
  "invoice_number": 12,
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

invoice_number é o número da encomenda na empresa. Para obter o id (necessário num reembolso) use GET /ecommerce/sales?search=12.

Erros mais comuns: 400 VALIDATION_ERROR (campo em falta ou inválido), 403 PERMISSION_DENIED (o token não tem a permissão Vendas), 422 ORDER_REJECTED (peça inexistente, de outra empresa ou sem unidade livre).

Encomendas criadas com este token, da mais recente para a mais antiga. Cada uma inclui as linhas de produto, o cliente, o fornecedor e o estado de faturação/reembolso.

Query Parameters

Estados

Resposta (uma venda)

{
  "success": true,
  "message": "success",
  "data": [
    {
      "id": 1024,
      "ecommerce_id": "60",
      "order_status": 3,
      "num_products": 1,
      "total_value_products": "95.00",
      "total_value_shipping": "15.00",
      "total_value_packaging": "0.00",
      "total_value_other_parcel": "0.00",
      "tax_vat_products": "21.85",
      "tax_vat_shipping": "3.45",
      "tax_vat_packaging": "0.00",
      "tax_vat_other_parcel": "0.00",
      "exemption_vat_products": false,
      "exemption_vat_shipping": false,
      "exemption_vat_packaging": false,
      "exemption_vat_other_parcel": false,
      "maximum_sale_alert_date": "2026-10-14T23:00:00.000Z",
      "notes_sale": "Frágil.",
      "seller_takes_care_shipping": true,
      "provider_takes_care_shipping": false,
      "seller_invoice_provider": false,
      "seller_invoice_client": true,
      "shipping_label": "https://example.com/etiquetas/12345.pdf",
      "shipping_company": "CTT",
      "shipping_tracking_code": "RR123456789PT",
      "reason_failed_sale": null,
      "created_at": "2026-10-08T10:45:32.714Z",
      "updated_at": "2026-10-09T12:01:10.512Z",
      "invoice_number": "12",
      "order_status_name": "Delivered",
      "product_list": [
        {
          "id": 341,
          "product_id": "309",
          "quantity": 1,
          "price_without_vat": 95,
          "tax_vat": 21.85000000000000142108547152020037174224853515625,
          "exemption_vat": false,
          "product_name": "Farol Esquerdo",
          "image_list": [
            {
              "image_id": 202,
              "image_url": "https://images.tp.software/uploads/vehicle/parts/1742277347163-12.jpg",
              "product_id": 309
            }
          ]
        }
      ],
      "client_list": [
        {
          "name": "Miguel Santos",
          "shipping_address": "Rua do Sol, 789",
          "country_code": "PT",
          "postal_code": "4700-123",
          "city": "Braga",
          "vat_number": "123456789",
          "country_code_vat_number": "PT",
          "phone": "+351910000000",
          "email": "miguel.santos@example.com",
          "whatsapp": "+351910000000"
        }
      ],
      "provider_list": [],
      "bill_list": [
        {
          "proposal_seller_refund_value": null,
          "refund_reason": null,
          "proposal_provider_refund_value": null,
          "proposal_seller_type_refund": null,
          "proposal_provider_type_refund": null,
          "refund_state_provider": null,
          "refund_accept_full": false,
          "refund_accept_partial": false,
          "refund_accept_value": null,
          "arrived_to_warehouse": null,
          "billing_document": "",
          "id_billing_document": 1024,
          "billing_credit_note": null,
          "id_billing_credit_note": null,
          "billing_other_document": null,
          "id_other_document": null,
          "type_other_document": null,
          "refund_status_name": ""
        }
      ]
    }
  ],
  "total": 1,
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  },
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

Descrição dos Campos

Pede o reembolso total (FULL) ou parcial (PARTIAL) de uma venda entregue (estado 3 — Delivered). Cada venda aceita um pedido de reembolso; a empresa aprova-o ou recusa-o no TP Software.

Body (JSON)

{
  "id_sale": 1024,
  "type_refund": "PARTIAL",
  "refund_request_value": 50,
  "reason_refund": "Peça com um suporte partido"
}

Descrição dos Campos

Respostas

{
  "success": true,
  "message": "Refund successfully created.",
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

Reserva peças para um cliente, com data de fim, notificações (email/WhatsApp) e alerta antes de expirar.

Body (JSON)

{
  "reservation_name": "Reserva João Silva",
  "reservation_end_date": "2026-10-30 18:00",
  "reservation_end_alert": "2026-10-29 09:00",
  "reservation_notes": "Cliente vai levantar",
  "send_email": 1,
  "send_whatsapp": 0,
  "client": {
    "name": "João Silva",
    "country_code": 1,
    "district": 1,
    "city": 1,
    "bill_address": "Rua das Flores, 10",
    "postal_code": "4700-321",
    "shipping_address": [
      "Rua das Flores, 10"
    ],
    "vat_number": "123456789",
    "vat_country_code": "PT",
    "vat_percentage": 23,
    "is_vat_exempt": 0,
    "phone_number": "+351910000001",
    "email": "joao.silva@example.com",
    "whatsapp_number": "+351910000001"
  },
  "products": [
    {
      "product_id": 309,
      "qty": 1,
      "price": "95.00",
      "reservation_order_notes": "Guardar com a embalagem"
    }
  ]
}

Descrição dos Campos

Resposta

{
  "success": true,
  "message": "Order has been generated successfully!",
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

A reserva (com o uuid) aparece de seguida em GET /ecommerce/reserve-orders.

Antes de reservar, a API confirma cada peça com a mesma regra de /product-inventory/check (stock menos reservas, na empresa do token; a mesma peça em várias linhas soma as quantidades). Se uma peça não tiver a quantidade livre, não existir ou não estiver disponível, nada é reservado: 422 ORDER_REJECTED com o motivo. Também 422 se faltar um dado obrigatório (ex.: data de fim no passado).

Reservas criadas com este token (ativas, canceladas e convertidas em venda), com as peças reservadas.

Query Parameters

Exemplo de Resposta (uma reserva)

{
  "success": true,
  "message": "success",
  "data": [
    {
      "id": 16,
      "uuid": "9dd973a7-2a18-47d1-bd36-00df54b5cc32",
      "company_id": "179",
      "client_id": null,
      "reservation_name": "Reserva João Silva",
      "reservation_end_date": "2026-10-30T18:00:00.000Z",
      "reservation_end_alert": "2026-10-29T09:00:00.000Z",
      "reservation_notes": "Cliente vai levantar",
      "send_email": 1,
      "send_whatsapp": 0,
      "reservation_status": 1,
      "status_name": "Active",
      "client_name": "João Silva",
      "client_email": "joao.silva@example.com",
      "client_phone_number": "+351910000001",
      "market_place_regervation": 1,
      "rev_sync_id": "60",
      "sync_id": 60,
      "created_at": "2026-10-08T11:38:11.000Z",
      "updated_at": "2026-10-08T11:38:11.384Z",
      "part_list": [
        {
          "id": 160,
          "uuid": "cb128000-deaf-4890-985a-7d1b5eee617e",
          "reservation_id": "16",
          "parts_id": "309",
          "part_qty_label_id": "264",
          "reserve_price": "95.00",
          "reserve_vat_price": "0.00",
          "reservation_order_notes": "Guardar com a embalagem",
          "part_code": "ACB-4821-X",
          "part_name": "Farol",
          "namePartPT": "Farol Esquerdo",
          "warehouse_name": null
        }
      ]
    }
  ],
  "total": 1,
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 1,
    "total_pages": 1,
    "has_more": false
  },
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

reservation_status: 1 Active · 2 Cancelled · 3 Converted into Sales. O nome da peça em namePartPT segue o idioma de language.

Todos os dados de uma reserva criada com este token, com a lista de peças e os totais.

Parâmetros

Exemplo

curl -H "Authorization: Bearer SEU_TOKEN" \
  https://hub.tp.software/api/v1/ecommerce/reserve-orders/9dd973a7-2a18-47d1-bd36-00df54b5cc32

{
  "success": true,
  "message": "success",
  "data": {
    "id": 16,
    "uuid": "9dd973a7-2a18-47d1-bd36-00df54b5cc32",
    "company_id": "179",
    "reservation_name": "Reserva João Silva",
    "reservation_end_date": "2026-10-30T18:00:00.000Z",
    "reservation_status": 1,
    "status_name": "Active",
    "client_name": "João Silva",
    "sync_id": 60,
    "part_list": [
      {
        "id": 160,
        "parts_id": "309",
        "reserve_price": "95.00",
        "reserve_vat_price": "0.00",
        "part_code": "ACB-4821-X",
        "namePartPT": "Farol Esquerdo",
        "warehouse_name": null
      }
    ],
    "total_qty": 1,
    "total_price": 95,
    "total_vat_price": 0
  },
  "meta": {
    "generated_at": "2026-10-08T21:30:00+01:00",
    "api_version": "v1"
  }
}

Reserva inexistente, ou de outro token: 404 NOT_FOUND. UUID mal formado: 400.