CRM-API | Angebote

​

Überblick

1. Ein Angebot erstellen: Erstellen Sie ein Angebot mit einigen Details wie Name und Ablaufdatum. Sie können das Angebot auch so konfigurieren, dass eSignatures und Zahlungen aktiviert werden.
2. Zuordnungen einrichten: Ordnen Sie das Angebot anderen Arten von CRM-Objekten zu, z. B. Artikeln, einer Angebotsvorlage, einem Deal und mehr. Im nächsten Schritt erbt das Angebot Eigenschaftswerte von einigen dieser zugeordneten Datensätze sowie die Einstellungen des Accounts.
3. Den Angebotsstatus festlegen: Legen Sie den Status des Angebots fest, um seine Bereitschaft zur Weitergabe an Käufer widerzuspiegeln. Wenn Sie den Status des Angebots festlegen, z. B. indem Sie es zu einem bearbeitbaren Entwurf oder einem vollständig veröffentlichten und öffentlich zugänglichen Angebot machen, erbt es bestimmte Eigenschaften von seinen zugeordneten CRM-Datensätzen und Account-Einstellungen.
4. Das Angebot teilen: Sobald ein Angebot veröffentlicht wurde, können Sie es mit Ihren Käufern teilen.

​

Angebot erstellen

{
  "properties": {
    "hs_title": "CustomerName - annual SEO audit",
    "hs_expiration_date": "2023-12-10"
  }
}

​

Zuständiger Mitarbeiter für Angebot

• Wenn ein Deal mit dem Angebot verknüpft ist, spiegelt die hubspot_owner_id-Eigenschaft die hs_associated_deal_owner_id-Eigenschaft wider (hs_associated_deal_owner_id ist eine berechnete Eigenschaft).
• Wenn ein Deal nicht mit dem Angebot verknüpft ist, spiegelt die hubspot_owner_id-Eigenschaft die hs_quote_owner_id-Eigenschaft wider.

​

eSignatures aktuivieren

{
  "properties": {
    "hs_title": "CustomerName - annual SEO audit",
    "hs_expiration_date": "2023-12-10",
    "hs_esign_enabled": "true"
  }
}

​

Zahlungen aktivieren

{
  "properties": {
    "hs_title": "CustomerName - annual SEO audit",
    "hs_expiration_date": "2023-12-10",
    "hs_payment_enabled": "true",
    "hs_payment_type": "HUBSPOT",
    "hs_allowed_payment_methods": "CREDIT_OR_DEBIT_CARD;ACH"
  }
}

• Wenn Sie ein Angebot mit aktivierten Zahlungen veröffentlichen, setzt HubSpot die Eigenschaft hs_payment_status automatisch auf PENDING.
• Wenn Sie ACH verwenden, legt HubSpot beim Abwickeln der Zahlung automatisch die Eigenschaft hs_payment_status auf PROCESSING fest.
• Wenn die Zahlung bestätigt wird, legt HubSpot die Eigenschaft hs_payment_status automatisch auf PAID fest.
• Sobald das Angebot bezahlt ist, legt HubSpot die Eigenschaft hs_payment_date automatisch auf den Zeitpunkt ( Datum und Uhrzeit) fest, zu dem die Zahlung bestätigt wurde.
• Sobald die Zahlung bestätigt ist, wird die Zahlung automatisch dem Angebot zugeordnet. Weitere Informationen zu der Zahlung finden Sie in der Zahlungen-API.

​

Hinzufügen von Zuordnungen

​

Abrufen von IDs für Zuordnungen

GET request for line items
/crm/v3/objects/line_items?properties=name

GET request for quote templates
/crm/v3/objects/quote_template?properties=hs_name

GET request for deals
/crm/v3/objects/deals?properties=dealname

GET request for contacts
/crm/v3/objects/contacts?properties=email

GET request for companies
/crm/v3/objects/companies?properties=name

GET request for discounts
crm/v3/objects/discounts?properties=hs_type,hs_value

GET request for fees
crm/v3/objects/fees?properties=hs_type,hs_value

GET request for taxes
crm/v3/objects/taxes?properties=hs_type,hs_value

{
  "results": [
    {
      "id": "235425923863",
      "properties": {
        "hs_createdate": "2023-06-12T16:27:32.794Z",
        "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z",
        "hs_name": "Default Basic",
        "hs_object_id": "235425923863"
      },
      "createdAt": "2023-06-12T16:27:32.794Z",
      "updatedAt": "2023-06-12T16:27:32.794Z",
      "archived": false
    },
    {
      "id": "235425923864",
      "properties": {
        "hs_createdate": "2023-06-12T16:27:32.794Z",
        "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z",
        "hs_name": "Default Modern",
        "hs_object_id": "235425923864"
      },
      "createdAt": "2023-06-12T16:27:32.794Z",
      "updatedAt": "2023-06-12T16:27:32.794Z",
      "archived": false
    },
    {
      "id": "235425923865",
      "properties": {
        "hs_createdate": "2023-06-12T16:27:32.794Z",
        "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z",
        "hs_name": "Default Original",
        "hs_object_id": "235425923865"
      },
      "createdAt": "2023-06-12T16:27:32.794Z",
      "updatedAt": "2023-06-12T16:27:32.794Z",
      "archived": false
    }
  ]
}

​

Erstellen von Zuordnungen

PUT request to associate a line item
/crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{lineItemId}

PUT request to associate a quote template
/crm/v4/objects/quotes/{quoteId}/associations/default/quote_template/{quoteTemplateId}

PUT request to associate a deal
/crm/v4/objects/quotes/{quoteId}/associations/default/deals/{dealId}

PUT request to associate contacts
/crm/v4/objects/quotes/{quoteId}/associations/default/contacts/{contactId}

PUT request to associate companies
/crm/v4/objects/quotes/{quoteId}/associations/default/companies/{companyId}

PUT request to associate discounts
/crm/v4/objects/quotes/{quoteId}/associations/default/discounts/{discountId}

PUT request to associate fees
/crm/v4/objects/quotes/{quoteId}/associations/default/fees/{feeId}

PUT request to associate taxes
/crm/v4/objects/quotes/{quoteId}/associations/default/taxes/{taxId}

• Artikel (IDs: 55555, 66666):
  • /crm/v4/objects/quotes/123456/associations/default/line_items/55555
  • /crm/v4/objects/quotes/123456/associations/default/line_items/66666
• Angebotsvorlage (ID: 987654): /crm/v4/objects/quotes/123456/associations/default/quote_template/987654
• Deal (ID: 345345): /crm/v4/objects/quotes/123456/associations/default/deals/345345

{
  "status": "COMPLETE",
  "results": [
    {
      "from": {
        "id": "115045534742"
      },
      "to": {
        "id": "102848290"
      },
      "associationSpec": {
        "associationCategory": "HUBSPOT_DEFINED",
        "associationTypeId": 285
      }
    },
    {
      "from": {
        "id": "102848290"
      },
      "to": {
        "id": "115045534742"
      },
      "associationSpec": {
        "associationCategory": "HUBSPOT_DEFINED",
        "associationTypeId": 286
      }
    }
  ],
  "startedAt": "2023-10-12T16:48:40.624Z",
  "completedAt": "2023-10-12T16:48:40.712Z"
}

​

Zuordnen von Angebotsunterzeichnern

[
  {
    "associationCategory": "HUBSPOT_DEFINED",
    "associationTypeId": 702
  }
]

​

Ein Angebot mit Zuordnungen erstellen (Einzelanfrage)

{
  "properties": {
    "hs_title": "CustomerName - annual SEO audit",
    "hs_expiration_date": "2023-09-30"
  },
  "associations": [
    {
      "to": {
        "id": 115045534742
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 286
        }
      ]
    },
    {
      "to": {
        "id": 14795354663
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 64
        }
      ]
    },
    {
      "to": {
        "id": 75895447
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 67
        }
      ]
    },
    {
      "to": {
        "id": 256143985
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 67
        }
      ]
    }
  ]
}

​

Angebotsstatus aktualisieren

• Kein Status: Wenn für das hs_status-Feld kein Wert angegeben wird, hat das Angebot den Status Minimal. Das Angebot wird auf der Indexseite des Angebote-Tools angezeigt, kann aber nicht direkt bearbeitet werden. Angebote mit diesem Status können weiterhin in der Automatisierung verwendet werden, z. B. im Sequenzen-Tool, und können auch im Reporting-Tool analysiert werden.
• DRAFT: ermöglicht die Bearbeitung des Angebots in HubSpot. Dieser Status kann nützlich sein, wenn das Angebot nicht vollständig konfiguriert ist oder wenn Sie es den Vertriebsmitarbeitern lieber ermöglichen möchten, den Angebotskonfigurationsprozess in HubSpot abzuschließen.
• APPROVAL_NOT_NEEDED: veröffentlicht das Angebot unter einer öffentlich zugänglichen URL (hs_quote_link), ohne dass es genehmigt werden muss.
• PENDING_APPROVAL: gibt an, dass das Angebot auf die Genehmigung wartet, bevor es veröffentlicht werden kann.
• APPROVED: Das Angebot wurde genehmigt und wird nun unter einer öffentlich zugänglichen URL (hs_quote_link) veröffentlicht.
• REJECTED: gibt an, dass das Angebot eingerichtet, aber nicht für die Veröffentlichung genehmigt wurde und bearbeitet werden muss, bevor es erneut zur Genehmigung eingereicht werden kann.

{
  "properties": {
    "hs_status": "APPROVAL_NOT_NEEDED"
  }
}

​

Nach Angebotsstatus festgelegte Eigenschaften

• hs_quote_amount: wird auf der Grundlage aller zugeordneten Artikel, Steuern, Rabatte und Gebühren berechnet.
• hs_domain: wird von der zugeordneten Angebotsvorlage festgelegt.
• hs_slug: wird zufällig generiert, wenn keiner explizit angegeben wird.
• hs_quote_total_preference: wird basierend auf Ihren Account-Einstellungen festgelegt. Wenn Sie diese Einstellung nicht konfiguriert haben, wird sie standardmäßig auf den Wert des total_first_payment-Felds festgelegt.
• hs_timezone: wird standardmäßig auf die Zeitzone Ihres HubSpot-Accounts festgelegt.
• hs_locale: wird von der zugeordneten Angebotsvorlage festgelegt.
• hs_quote_number: wird basierend auf dem aktuellen Datum und der aktuellen Uhrzeit festgelegt, es sei denn, es wird eine angegeben.
• hs_language: wird von der zugeordneten Angebotsvorlage festgelegt.
• hs_currency: wird basierend auf dem zugeordneten Deal festgelegt. Wenn Sie dem Angebot keinen Deal zugeordnet haben, wird die Standardwährung Ihres HubSpot-Accounts verwendet.

• hs_pdf_download_link: wird mit einer URL von einer PDF-Datei für das Angebot ausgefüllt.
• hs_locked: festgelegt auf true. Zum Ändern von Eigenschaften, nachdem Sie ein Angebot veröffentlicht haben, müssen Sie zunächst den hs_status des Angebots zurück auf DRAFT, PENDING_APPROVAL oder REJECTED aktualisieren.
• hs_quote_link: die öffentlich zugängliche URL des Angebots. Dies ist eine schreibgeschützte Eigenschaft und kann nach der Veröffentlichung nicht über die API festgelegt werden.
• hs_esign_num_signers_required: Wenn Sie eSignatures aktiviert haben, wird die Anzahl der erforderlichen Unterschriften angezeigt.
• hs_payment_status: der Status des Zahlungseinzugs, wenn Sie Zahlungen aktiviert haben. Nach der Veröffentlichung mit aktivierten Zahlungen wird diese Eigenschaft auf PENDING festgelegt. Sobald der Käufer die Zahlung über das Angebot übermittelt, wird der Status automatisch entsprechend aktualisiert. Erfahren Sie mehr über das Aktivieren von Zahlungen.

​

Angebote abrufen

• Um ein einzelnes Angebote abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/quotes/{quoteID} durch.
• Um eine Liste aller Angebote anzufragen, führen Sie eine GET-Anfrage an /crm/v3/objects/quotes durch.

{
  "inputs": [{ "id": "342007287" }, { "id": "81204505203" }],
  "properties": ["hs_content", "hs_sentiment", "hs_submission_timestamp"]
}

​

Bereiche

• crm.objects.quotes.write, crm.objects.quotes.read, crm.objects.line_items.write, crm.objects.line_items.read, crm.objects.owners.read, crm.objects.contacts.write, crm.objects.contacts.read, crm.objects.deals.write, crm.objects.deals.read, crm.objects.companies.write, crm.objects.companies.read
• crm.schemas.quote.read, crm.schemas.line_items.read, crm.schemas.contacts.read, crm.schemas.deals.read, crm.schemas.companies.read