Módulo E-commerce

Endpoint público (não requer autenticação). Devolve a lista de todas as empresas TP Software que têm o módulo API e-commerce ativo, abertas a serem contactadas para parcerias e integrações comerciais. Use este endpoint para descobrir potenciais fornecedores ou parceiros dentro da rede TP Software antes sequer de receber um token API.

Parâmetros

Nenhum parâmetro. Pode ser chamado livremente sem autenticação.

Resposta

{
    "success": true,
    "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"
        }
    ]
}

Retorna o inventário completo de peças da empresa, com paginação, filtros e ordenação. Cada peça inclui dados completos da viatura dadora, quantidades por localização, referências OEM, danos, imagens e vídeos.

Query Parameters

Exemplo de Resposta (uma peça)

{
  "id": 309,
  "company_id": "2",
  "vehicle_id": "96",
  "part_code": "ACB-4821-X",
  "quantity": 3,
  "price_1": 250,
  "price_2": 230,
  "part_description": "Front Left Headlight Assembly",
  "is_custom_size": 1,
  "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": "REG-2025-789",
  "state_id": "1",
  "condition_id": "1",
  "product_name": "Front Left Headlight",
  "vehicle_model_name": "Ford Focus 2022",
  "vehicle_make_name": "Ford",
  "vehicle_variant_name": "2.0 EcoBoost ST (206 kW / 280 hp)",
  "brand_name": "Bosch",
  "motor_code": "4G63T",
  "inventory_status": "In Stock",
  "created_at": "2025-03-06T06:25:41.000Z",
  "updated_at": "2025-03-05T09:08:24.136Z",
  "vehicle_year": "2022",
  "bar_code_parts": "1234567890123",
  "is_master_part": "0",
  "master_part_id": "17",
  "master_part_inventory_id": "0",
  "state_name": "New",
  "condition_name": "OEM",
  "token": "9xxffqomimqgph7h8odq5v54ehuw1atjvf",
  "vehicle": {
    "vin_number": "1FA6P8TH9K5123456",
    "registration": "AB-123-CD",
    "registration_plate": "82-83-HM",
    "vehicle_brand": "Ford",
    "vehicle_model": "Focus ST",
    "vehicle_year": "2022",
    "vehicle_kms": "12000",
    "vehicle_doors": "2",
    "vehicle_fuel": "Petrol",
    "vehicle_motorization": "2.0 EcoBoost",
    "vehicle_model_id": "22",
    "make_id": "4",
    "variants_id": "105946",
    "vehicle_uuid": "58725682-b564-4a01-86a2-ed75626b8809",
    "vehicle_type_name": "Car",
    "fuel_type_name": "Petrol",
    "variants_name": "2.0 EcoBoost ST (206 kW / 280 hp)",
    "motor_code": "4G63T",
    "vehicle_category": "Hatchback",
    "vehicle_color": "Blue",
    "vehicle_cyllinder": "4",
    "vehicle_tare": "1400",
    "vehicle_approval": "Yes",
    "vehicle_total_gross_weight": "1800",
    "vehicle_parts": "52",
    "status": 1,
    "vehicle_process_end_date": "2025-03-27T18:30:00.000Z",
    "is_vehicle_depollution": 0,
    "created_by": "2",
    "updated_by": "2",
    "vehicle_internal_id": "12",
    "state_parking": "1",
    "vehicle_image": [
      { "vehicle_image": "https://example.com/uploads/vehicle/images/focus1.jpg", "sort_order": "1" },
      { "vehicle_image": "https://example.com/uploads/vehicle/images/focus2.jpg", "sort_order": "2" }
    ]
  },
  "part_qty_list": [
    {
      "parts_id": "309",
      "uuid": "c970a0c2-8fbf-4a68-9d2a-3a35fdeafe85",
      "id": 264,
      "qty": 1,
      "location_ids": "",
      "part_rating": 5,
      "location_name": "Shelf A1"
    },
    {
      "parts_id": "309",
      "uuid": "6b909262-910a-42c2-99c8-04fce0bf7cf2",
      "id": 265,
      "qty": 2,
      "location_ids": "",
      "part_rating": 5,
      "location_name": "Shelf A2"
    }
  ],
  "parts_reference": [
    {
      "id": 16,
      "parts_id": "309",
      "is_main": 0,
      "condition_id": "1",
      "type_id": "1",
      "reference_code": "OEM-12345",
      "type_name": "Compatible",
      "condition_name": "OEM"
    },
    {
      "id": 17,
      "parts_id": "309",
      "is_main": 1,
      "condition_id": "2",
      "type_id": "2",
      "reference_code": "AF-67890",
      "type_name": "Written on the label",
      "condition_name": "Aftermarket"
    }
  ],
  "part_damage": [
    {
      "damage_description": "1111",
      "location_damage": "Internal",
      "type_damage": "Not affect function",
      "damage_rating": 1.5
    }
  ],
  "image_list": [
    {
      "image_url": "https://tpsoftware.s3.eu-west-1.amazonaws.com/uploads/vehicle/parts/1742277347163-12.jpg",
      "part_name": "Distribuidor",
      "image_uuid": "adae8407-cb7f-4614-b270-2d5b2b6683fc",
      "part_id": "309",
      "uuid": "a83884fc-86f8-4fab-a041-3be250b14eab",
      "part_code": "pvfmnjhmog",
      "quantity": 1,
      "part_price": 0,
      "inventory_status": 1,
      "part_description": "",
      "id": 202,
      "damage_list": [
        {
          "id": 34,
          "video_url": null,
          "damage_description": "1111",
          "vehicle_part_id": "574",
          "img_video_id": "202",
          "damage_id": "39"
        }
      ]
    },
    {
      "image_url": "https://tpsoftware.s3.eu-west-1.amazonaws.com/uploads/vehicle/parts/1742277347982-14.jpg",
      "part_name": "Distribuidor",
      "image_uuid": "95e296bb-7f1c-4f27-8b2c-da62e0a58d0b",
      "part_id": "309",
      "uuid": "a83884fc-86f8-4fab-a041-3be250b14eab",
      "part_code": "pvfmnjhmog",
      "quantity": 1,
      "part_price": 0,
      "inventory_status": 1,
      "part_description": "",
      "id": 203,
      "damage_list": []
    }
  ],
  "video_list": [
    {
      "image_url": "https://tpsoftware.s3.eu-west-1.amazonaws.com/uploads/vehicle/parts/thumb_1742277359082.jpg",
      "video_url": "https://tpsoftware.s3.eu-west-1.amazonaws.com/uploads/vehicle/parts/1742277357393-4114797-sd_640_360_25fps.mp4",
      "part_name": "Distribuidor",
      "image_uuid": "d6717bcd-684a-4549-95a7-45484c55db64",
      "part_id": "309",
      "uuid": "a83884fc-86f8-4fab-a041-3be250b14eab",
      "part_code": "pvfmnjhmog",
      "quantity": 1,
      "part_price": 0,
      "inventory_status": 1,
      "part_description": "",
      "id": 49,
      "damage_list": []
    }
  ]
}

Verifica se uma quantidade específica de um produto está disponível em stock. Útil antes de criar uma encomenda.

Query Parameters

Respostas

{
    "success": true,
    "data": {
        "available": true,
        "message": "Quantidade disponível"
    }
}

Cria uma nova encomenda no TP Software com cliente, fornecedor, produtos, totais e cálculo de IVA. Suporta múltiplas linhas de produto, isenções de IVA por linha, configuração de quem trata do envio e da faturação, e anexo de etiqueta de envio.

Body (JSON)

{
  "tokens": "9xxffqomimqgph7h8odq5v54ehuw1atjvf",
  "num_products": 2,
  "total_value_products": 320,
  "total_value_shipping": 15,
  "total_value_packaging": 4.5,
  "total_value_other_parcel": 2,
  "tax_vat_products": 48,
  "tax_vat_shipping": 2.25,
  "tax_vat_packaging": 0.68,
  "tax_vat_other_parcel": 0.3,
  "exemption_vat_products": 0,
  "exemption_vat_shipping": 0,
  "exemption_vat_packaging": 0,
  "exemption_vat_other_parcel": 0,
  "maximum_sale_alert_date": "2025-03-15",
  "notes_sale": "Fragile items. Deliver between 9 AM - 12 PM.",
  "seller_takes_care_shipping": 1,
  "provider_takes_care_shipping": 0,
  "seller_invoice_provider": 0,
  "seller_invoice_client": 1,
  "shipping_label": "https://example.com/documents/shipping_label_12345.pdf",
  "client": [
    {
      "name": "Michael Johnson",
      "country_code": "US",
      "shipping_address": "789 Sunset Blvd",
      "postal_code": "90028",
      "city": "Los Angeles",
      "invoice_address": "123 Business Lane",
      "vat_number": "US987654321",
      "country_code_vat_number": "US",
      "phone": "+13235551234",
      "email": "michael.johnson@example.com",
      "whatsapp": "+13235551234"
    }
  ],
  "provider": [
    {
      "name": "Elite Auto Parts Ltd.",
      "country_code": "DE",
      "shipping_address": "42 Autobahnstrasse",
      "postal_code": "60314",
      "city": "Frankfurt",
      "invoice_address": "10 Industrial Park",
      "vat_number": "DE876543210",
      "country_code_vat_number": "DE",
      "phone": "+492215554321",
      "email": "sales@eliteautoparts.de",
      "whatsapp": "+492215554321"
    }
  ],
  "products": [
    {
      "product_id": 380,
      "product_name": "Front Brake Pads - Bosch",
      "part_qty_id": 1056,
      "price_without_vat": 95,
      "tax_vat": 14.25,
      "exemption_vat": 0,
      "images": [1, 2]
    },
    {
      "product_id": 395,
      "product_name": "Air Filter - Mann Filter",
      "part_qty_id": 1057,
      "price_without_vat": 130,
      "tax_vat": 19.5,
      "exemption_vat": 0,
      "images": [1, 2]
    }
  ]
}

Descrição dos Campos

Resposta

Devolve o objeto da venda criada com a mesma estrutura do endpoint GET /sales, incluindo o id interno, ecommerce_id de referência, estado inicial e timestamps.

Lista as encomendas/vendas da empresa, com filtros por estado e paginação. Cada item inclui linhas de produto, dados do cliente, do fornecedor, faturação e estado de reembolso.

Query Parameters

Exemplo de Resposta (uma venda)

{
  "id": 1024,
  "ecommerce_id": "ORD-20250311-001",
  "order_status": 2,
  "num_products": 2,
  "total_value_products": "499.99",
  "total_value_shipping": "15.00",
  "total_value_packaging": "3.50",
  "total_value_other_parcel": "0.00",
  "tax_vat_products": "39.99",
  "tax_vat_shipping": "1.50",
  "tax_vat_packaging": "0.25",
  "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": "2025-03-15T00:00:00.000Z",
  "notes_sale": "Customer requested express shipping. Contact before delivery.",
  "seller_takes_care_shipping": true,
  "provider_takes_care_shipping": false,
  "seller_invoice_provider": false,
  "seller_invoice_client": true,
  "shipping_label": "https://example.com/shipping/ORD-20250311-001.pdf",
  "shipping_company": "FedEx",
  "shipping_tracking_code": "FDX123456789",
  "reason_failed_sale": null,
  "created_at": "2025-03-11T10:45:32.714Z",
  "updated_at": "2025-03-11T12:01:10.512Z",
  "invoice_number": "INV-20250311-001",
  "order_status_name": "Shipped",
  "product_list": [
    {
      "id": 341,
      "product_id": 7654,
      "quantity": 1,
      "price_without_vat": 299.99,
      "tax_vat": 23.99,
      "exemption_vat": false,
      "product_name": "Gaming Laptop - 15.6 inch",
      "image_list": [
        "https://example.com/products/laptop1.jpg",
        "https://example.com/products/laptop2.jpg"
      ]
    },
    {
      "id": 342,
      "product_id": 3421,
      "quantity": 1,
      "price_without_vat": 200,
      "tax_vat": 16,
      "exemption_vat": false,
      "product_name": "Wireless Mechanical Keyboard",
      "image_list": ["https://example.com/products/keyboard1.jpg"]
    }
  ],
  "client_list": [
    {
      "name": "Michael Johnson",
      "shipping_address": "45 Greenview Ave",
      "country_code": "US",
      "postal_code": "90210",
      "city": "Los Angeles",
      "vat_number": "US987654321",
      "country_code_vat_number": "US",
      "phone": "+13235551234",
      "email": "michael.johnson@example.com",
      "whatsapp": "+13235551234"
    }
  ],
  "provider_list": [
    {
      "name": "Tech Distributors Inc.",
      "shipping_address": "500 Tech Park, Suite 42",
      "country_code": "US",
      "postal_code": "30303",
      "city": "Atlanta",
      "vat_number": "US223344556",
      "country_code_vat_number": "US",
      "phone": "+14045557890",
      "email": "support@techdistributors.com",
      "whatsapp": "+14045557890"
    }
  ],
  "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": "https://example.com/invoices/INV-20250311-001.pdf",
      "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": ""
    }
  ]
}

Descrição dos Campos

Submete um pedido de reembolso para uma venda existente. O reembolso pode ser total (FULL) ou parcial (PARTIAL). A empresa fornecedora tem de ter a opção de reembolsos ativada.

Body (JSON)

{
  "token": "9xxffqomimqgph7h8odq5v54ehuw1atjvf",
  "id_sale": 1024,
  "type_refund": "FULL",
  "refund_request_value": 499.99,
  "reason_refund": "Received incorrect product variant"
}

Descrição dos Campos

Respostas

[
  {
    "message": "Refund successfully created.",
    "status": 200
  },
  {
    "message": "Invalid token request or company does not allow refund",
    "status": 404
  }
]

200 — pedido de reembolso aceite e criado. 404 — token inválido ou a empresa fornecedora não permite reembolsos via API.

Cria uma reserva de produtos para um cliente, com data limite, notificações automáticas (email/WhatsApp) e alerta pré-expiração.

Body (JSON)

{
  "tokens": "9xxffqomimqgph7h8odq5v54ehuw1atjvf",
  "reservation_name": "Reserva João Silva",
  "reservation_end_date": "2026-04-30 18:00",
  "reservation_notes": "Cliente vai levantar",
  "send_email": 1,
  "send_whatsapp": 0,
  "reservation_end_alert": "2026-04-29 09:00",
  "client": {
    "name": "Michael Johnson",
    "country_code": 1,
    "district": 1,
    "city": 1,
    "bill_address": "789 Sunset Blvd",
    "postal_code": "90028",
    "shipping_address": ["123 Business Lane"],
    "vat_number": "US987654321",
    "vat_country_code": "US",
    "vat_percentage": 23,
    "is_vat_exempt": 0,
    "phone_number": "+13235551234",
    "email": "michael.johnson@example.com",
    "whatsapp_number": "+13235551234"
  },
  "products": [
    {
      "product_id": "380",
      "qty": "1",
      "price": "95.00"
    }
  ]
}

Descrição dos Campos

Resposta

Devolve a reserva criada com a mesma estrutura do endpoint GET /reserve-orders/{uuid}, incluindo id, uuid, part_list[] e os totais (total_qty, total_price, total_vat_price).

Lista as reservas ativas, expiradas e canceladas da empresa, com paginação e ordenação. Cada item inclui o cabeçalho da reserva e a lista de peças reservadas.

Query Parameters

Exemplo de Resposta (uma reserva)

{
  "id": 16,
  "uuid": "9dd973a7-2a18-47d1-bd36-00df54b5cc32",
  "company_id": "2",
  "client_id": "7",
  "reservation_end_date": null,
  "warehouses_id": null,
  "users_id": null,
  "shipping_price": "0.00",
  "packing_price": "0.00",
  "parcel_price": "0.00",
  "reservation_notes": null,
  "send_email": 0,
  "send_whatsapp": 0,
  "reservation_status": 1,
  "created_at": "2025-05-12T11:38:11.000Z",
  "updated_at": "2025-05-12T11:38:11.384Z",
  "deleted_at": null,
  "created_by": "1",
  "updated_by": null,
  "deleted_by": null,
  "reservation_name": "My Reserve",
  "task_id": null,
  "reservation_end_alert": null,
  "client_name": "Michael Johnson",
  "status_name": "Active",
  "token": "9xxffqomimqgph7h8odq5v54ehuw1atjvf",
  "part_list": [
    {
      "id": 160,
      "uuid": "cb128000-deaf-4890-985a-7d1b5eee617e",
      "company_id": "2",
      "reservation_id": "16",
      "parts_id": "380",
      "reserve_price": "95.00",
      "reserve_vat_price": "0.00",
      "location_id": null,
      "reservation_order_notes": null,
      "created_at": "2025-05-12T11:38:11.384Z",
      "updated_at": "2025-05-12T11:38:11.384Z",
      "deleted_at": null,
      "created_by": "1",
      "updated_by": "1",
      "deleted_by": null,
      "part_qty_label_id": "381",
      "part_code": "vx8gdtojig",
      "part_name": "Brake Pad - Front",
      "namePartPT": "Pastilha de Freio - Dianteira",
      "warehouse_name": null
    }
  ]
}

Retorna todos os detalhes de uma reserva específica, incluindo a lista de peças (part_list[]) e os totais agregados (total_qty, total_price, total_vat_price).

Parâmetros de URL

Exemplo de Resposta

{
  "message": "success",
  "data": {
    "id": 16,
    "uuid": "9dd973a7-2a18-47d1-bd36-00df54b5cc32",
    "company_id": "2",
    "client_id": "7",
    "reservation_end_date": null,
    "warehouses_id": null,
    "users_id": null,
    "shipping_price": "0.00",
    "packing_price": "0.00",
    "parcel_price": "0.00",
    "reservation_notes": null,
    "send_email": 0,
    "send_whatsapp": 0,
    "reservation_status": 1,
    "created_at": "2025-05-12T11:38:11.000Z",
    "updated_at": "2025-05-12T11:38:11.384Z",
    "deleted_at": null,
    "created_by": "1",
    "updated_by": null,
    "deleted_by": null,
    "reservation_name": "My Reserve",
    "task_id": null,
    "reservation_end_alert": null,
    "client_name": "Michael Johnson",
    "status_name": "Active",
    "token": "9xxffqomimqgph7h8odq5v54ehuw1atjvf",
    "part_list": [
      {
        "id": 160,
        "uuid": "cb128000-deaf-4890-985a-7d1b5eee617e",
        "company_id": "2",
        "reservation_id": "16",
        "parts_id": "380",
        "reserve_price": "95.00",
        "reserve_vat_price": "0.00",
        "location_id": null,
        "reservation_order_notes": null,
        "created_at": "2025-05-12T11:38:11.384Z",
        "updated_at": "2025-05-12T11:38:11.384Z",
        "deleted_at": null,
        "created_by": "1",
        "updated_by": "1",
        "deleted_by": null,
        "part_qty_label_id": "381",
        "part_code": "vx8gdtojig",
        "part_name": "Brake Pad - Front",
        "namePartPT": "Pastilha de Freio - Dianteira",
        "warehouse_name": null
      }
    ],
    "total_qty": 1,
    "total_price": 95,
    "total_vat_price": 0
  }
}

Descrição dos Campos