Extensão de contabilidade

Please note: starting July 14th, 2022, net new developers can no longer build using the Accounting Extension API. The API will be officially sunsetted on December 1, 2022. 

Learn more about this change and how to migrate an existing Accounting Extension integration

Introdução

Nesta página, abordamos as etapas de como obter sua integração trabalhando com a extensão de contabilidade do HubSpot

Criar a definição de seu aplicativo no HubSpot

Para que sua integração se conecte a uma conta do usuário da HubSpot, crie uma definição de aplicativo no HubSpot para ela.  Aqui, você insere detalhes como o logotipo e texto a serem mostrados para o usuário do HubSpot quando sua integração tenta estabelecer uma conexão inicial para sua conta e também define quais permissões (escopos) sua integração precisa na conta de usuário do HubSpot.

Existe uma visão geral sobre como usar as ferramentas de desenvolvedor da HubSpot, mas estas são as etapas para começar a usá-las:

  1. Obtenha uma conta de desenvolvedor
  2. Crie uma definição de aplicativo em sua conta de desenvolvedor
  3. Você precisará modificar o aplicativo que criou e adicionar accounting como um escopo usado.  Caso pretenda sincronizar contatos com o HubSpot, também deverá adicionar o escopo contacts.

Conectando a uma conta de usuário do HubSpot

OAuth

Para conectar e obter acesso a uma conta de usuário do HubSpot, sua integração precisa iniciar uma solicitação de conexão OAuth ao HubSpot. Consulte Trabalhando com o OAuth para obter mais informações sobre como iniciar a conexão ao HubSpot.

Detalhes da conta de usuário

Depois que a conexão OAuth com a HubSpot for estabelecida, você precisará de informações adicionais sobre a conta do usuário em seu sistema de contabilidade externo. Para obter essas informações, faça uma solicitação PUT para o seguinte endpoint: /crm/v3/extensions/accounting/user-account.

Além disso, você precisa fazer uma solicitação adicional para fornecer à HubSpot o ID da conta do usuário em seu sistema de contabilidade como parte dessas chamadas de webhook. Para fornecer essas informações, faça uma solicitação PUT para o endpoint a seguir: https://api.hubapi.com/crm/v3/extensions/accounting/user-account.

Você precisará incluir o token de acesso OAuth que acabou de receber e que fornece à HubSpot as informações sobre a conta do sistema que estava conectada com esse token. Veja a seguir um exemplo de payload:

// Example account details { "accountId": "acct-app-123", "accountName": "My Coffee Shop Accounts", "currencyCode": "USD" }

Você pode realizar as operações básicas de CRUD usando a API /user-accounts. Quando um cliente instala/desinstala o app, você precisa chamar essa API para dizer à HubSpot quais contas estão disponíveis ou não estão mais disponíveis para uso.

Autenticação

Há 2 maneiras de autenticar solicitações de API feitas no HubSpot:

  1. Chave de API do desenvolvedor. Sua chave de API de desenvolvedor é usada no gerenciamento de configurações relacionadas a seus aplicativos da HubSpot por meio da API (dos endpoints /settings da extensão de contabilidade)
  2. Token OAuth.  Você precisa usar um token OAuth para qualquer solicitação feita em nome de um usuário da HubSpot (os endpoints /callback e /user-accounts para a extensão de contabilidade).  Observe que você deve solicitar o escopo accounting ao solicitar um token OAuth para ser usado com a extensão de contabilidade.

Para obter mais informações, leia a Documentação de autenticação.

Webhooks

Quando o HubSpot enviar uma solicitação para o servidor executar uma ação ou recuperar informações, isso será feito na forma de uma chamada de Webhook para seus endpoints.  As próximas seções descrevem o que o fluxo de chamadas reprensta para chamadas de Webhook e como configurar os endpoints para os quais o HubSpot deve ligar em seu servidor

Fluxo de chamadas

Veja abaixo um gráfico que descreve o fluxo geral de chamadas

plantuml

Estas são as etapas do fluxo de chamadas:

1. Receber o Webhook do HubSpot

Você começará a receber solicitações de API para os URLs configurados. O corpo de cada solicitação será um payload JSON. Para garantir que as solicitações que você está recebendo no endpoint do webhook sejam provenientes da HubSpot, preenchemos um cabeçalho X-HubSpot-Signature com um hash SHA-256 da concatenação do segredo do aplicativo e do corpo da solicitação que estamos enviando. Para obter mais detalhes sobre como validar a assinatura do Webhook, veja esta página.

2. Reconhecer o Webhook

O servidor recebe o Webhook e verifica se a payload JSON tem o formato correto e se a solicitação está assinada corretamente.  O servidor deverá retornar o código de status 200 se a solicitação for válida e o código de status 400 caso ela não seja válida.

Você deve reconhecer o Webhook antes de seu servidor realmente executar a ação solicitada.

3. Enviar resultado da ação para a HubSpot

Depois que o servidor concluir a ação solicitada, ele enviará o resultado para a HubSpot.

Cada payload de solicitação de Webhook enviada do HubSpot contém um objeto metadados com um campo callbackUrl.  Envie o resultado executando o comando POSTpara o endpoint callbackUrl.  Certifique-se de usar o token de acesso OAuth da conta do usuário da HubSpot que está vinculado ao accountId enviado na solicitação.

4. O HubSpot conforma o resultado

O HubSpot responderá com o código de status 200 se o resultado for recebido e validado e com o código de status 400 caso haja um erro.

Enviando um erro como resultado para o HubSpot

Às vezes, o HubSpot pode enviar uma solicitação de Webhook que você considera inválida (por exemplo, o HubSpot envia uma solicitação para criar um cliente que já existe).  Nesses casos, você enviaria a resposta de erro para callbackUrl.

Observe que todas as respostas para os endpoints de retorno dechamada devem conter um campo "@result" com um valor "OK" ou "ERR', que indica se a resposta representa sucesso ou falha da tarefa solicitada.

Estrutura da resposta de erro

Todos os endpoints de retorno de chamada têm o mesmo formato JSON, um objeto com 5 campos:

  • @result: (string) no caso de erro, ele terá o valor “ERR”
  • message: (string) uma descrição de texto do erro que ocorreu.
  • category: (string) o tipo de erro. Um dos seguintes valores:
    • CUSTOMER_ALREADY_EXISTS: Não é possível criar um cliente porque ele já existe
    • VALIDATION_INVALID_INPUT: Um campo de texto contém um caractere ou símbolo inválido.  Por exemplo, o nome de um cliente contém o símbolo ™, que não é compatível.
    • LICENSE_EXPIRED: A solicitação foi rejeitada porque a avaliação/licença do cliente no sistema expirou.
    • TAX_INFO_MISSING: Não foram encontradas informações obrigatórias de impostos; não foi possível concluir a operação.
    • OBJECT_ALREADY_EXISTS: O objeto já existe.
    • CONNECTED_ACCOUNT_ERROR: A solicitação foi rejeitada porque houve um problema com a conta (por exemplo, a conta não existe mais, não tem permissões para fazer a ação solicitada).
    • VALIDATION_ERROR: Falha na validação da entrada (por um motivo não disponível em uma dessas categorias de erro).  Por exemplo, a solicitação recebeu o JSON inválido.
    • UNEXPECTED_ERROR: Representa um erro de servidor no sistema (por exemplo, código de status 500 http).
    • INSUFICIENTE_INVENTÁRIO: Não há itens suficientes em estoque para atender ao número na fatura. Insira valores no campo de contexto para identificar quais produtos na fatura têm estoque insuficiente e inclua o número de inventário restante. Por exemplo, se o produto com o ID shoe-123 tiver apenas 3 itens restantes e o item da linha de fatura para shoe-123 tiver solicitado 5 itens, você poderia retornar o seguinte erro:

      {
      "@result": "ERR",
      "message": "There is not enough inventory to satisfy the requested amounts.",
      "category": "INSUFICIENTO_infer",
      "timestamp": "2020-03-31T10:15:30Z",
      "context": {
      "shoe-123": ["3"]
      }
      }
  • timestamp: (string) uma representação ISO 8601 da data e hora em que o erro ocorreu ou da época em milissegundos.
  • context: (map[string, string[]])  contexto adicional opcional sobre a condição de erro, que será usado pelo HubSpot para criar mais mensagens de erro acionáveis para usuários humanos. Consulte INSUFFICIENT_INVENTORY para ver um exemplo deste campo.

Veja um exemplo de resposta de erro:

// Error format { "@result": "ERR", "message": "The customer you are trying to create already exists.", "category": "CUSTOMER_ALREADY_EXISTS", "timestamp": "2020-03-31T10:15:30Z" }

Configurando endpoints do Webhook

Para que o HubSpot saiba para quais endpoints deve enviar webhooks em seu servidor, você precisa definir as "configurações" para seu aplicativo. Essas configurações contêm os "recursos de contabilidade" do aplicativo, bem como os URLs dos endpoints dos recursos para os quais o HubSpot deve enviar webhooks. Existe uma configuração de endpoint diferente para cada ação que o HubSpot faz.

Recursos de contabilidade

Há vários recursos disponíveis para os usuários do aplicativo quando ele está configurado com a extensão de contabilidade. Você não precisa oferecer suporte a todos os recursos, mas precisa especificar a quais recursos oferece suporte.

Principais recursos

Seu aplicativo precisa oferecer suporte a pelo menos um dos seguintes recursos principais:

  • Criação de fatura- Um usuário pode criar uma fatura em seu sistema de contabilidade do HubSpot
  • Importação de fatura- Um usuário pode importar faturas para o HubSpot de seu sistema de contabilidade

Recursos secundários de criação de fatura

Se o aplicativo permitir a criação de fatura, há recursos opcionais secundários aos quais você também pode oferecer suporte:

  • Criação de clientes - Um cliente pode ser criado como parte da criação da fatura
  • Impostos - Podem ser pesquisados
  • Taxas de câmbio - É possível solicitar uma taxa de câmbio entre duas moedas
  • Termos de pagamento - É possível recuperar termos de pagamento
  • Comentários da fatura -É possível adicionar comentários à fatura a ser criada
  • Descontos da fatura - Indica se é possível associar descontos no nível da fatura às faturas. Se não forem permitidos descontos na fatura, não permitiremos a criação de faturas com base em orçamentos.  Isso acontece porque os orçamentos no HubSpot podem conter descontos e, se não for possível incluir essas informações de desconto nas faturas criadas, informações incorretas poderiam ser geradas.

NOTA: Se o aplicativo não não não não for compatível com a criação de fatura, não será possível ativar esses recursos secundários, pois eles são aplicáveis apenas no contexto de criação da fatura.

Definindo configurações de “webhook” do aplicativo

Você deve especificar os recursos que o aplicativo aceita, bem como os URLs correspondentes a esses recursos.

https://api.hubapi.com/crm/v3/extensions/accounting/settings

Envie uma solicitação PUT para /settings com o corpo obrigatório. Você pode atualizar (PUT) ou visualizar (GET) suas configurações a qualquer momento.

URLs do modelo

Exibimos links diretos para clientes no CRM da HubSpot. Para exibir um link de maneira rápida e correta, pedimos aos integradores para fornecerem URLs de modelo.

Estes são os tokens possíveis: 

JSON
ACCOUNT_NAME
ACCOUNT_ID
INVOICE_ID
CUSTOMER_ID
PRODUCT_ID

por exemplo, link para uma fatura em seu serviço: "https://acountingservice.com/invoice/${ACCOUNT_ID}?invoiceId=${INVOICE_ID}"

Endpoints fictícios

O HubSpot exige que seja especificado um URL de endpoint para cada recurso ativado nas configurações, bem como o endpoint obrigatório. No entanto, ao iniciar a integração, você ainda pode não ter uma implementação de endpoint. Limite-se a preencher um valor provisório (como http://example.com) até estar pronto para implementar o endpoint.

URLs obrigatórios

Os URLs a seguir devem ser definidos:

  • getInvoiceUrl
  • getInvoicePdfUrl
  • searchCustomerUrl

URLs de recursos

Veja a seguir uma lista de recursos com os URLs dos respectivos endpoints.

  • Criação de fatura - createInvoiceUrl, searchProductUrl
  • Importação da fatura - searchInvoiceUrl
  • Criação de clientes - createCustomerUrl
  • Impostos - searchTaxUrl
  • Taxas de câmbio - exchangeRateUrl
  • Termos de pagamento - getTermsUrl
  • Comentários da fatura - Nenhum URL associado a esse recurso
  •  Descontos da fatura - Nenhum URL associado a esse recurso

Pedido de implementação de endpoints de Webhook

Se quiser implementar seus endpoints de Webhook um por vez, você deverá primeiro implementar os URLs obrigatórios, em qualquer ordem.

  • getInvoiceUrl
  • getInvoicePdfUrl
  • searchCustomerUrl

Quando terminar, você poderá implementar os URLs de recursos compatíveis.

Importação de fatura (Recurso principal)

Se seu aplicativo não for compatível com a Importação de fatura, ignore esta seção. Caso contrário, você deverá implementar o seguinte URL de endpoint:

  • searchInvoiceUrl

Criação de fatura (Recurso principal)

Se seu aplicativo for compatível com a Criação de fatura , você deverá implementar os URLs obrigatórios para esse recurso principal na ordem a seguir (isto é, a ordem em que os endpoints serão chamados quando uma fatura estiver sendo criada)

  1. searchProductUrl
  2. createInvoiceUrl

Criação de fatura (Recursos secundários)

Você pode oferecer suporte a todos, nenhum ou alguns dos seguintes recursos secundários. Veja a seguir a ordem em que eles seriam implementados se todos fossem compatíveis:

  1. searchTaxUrl
  2. exchangeRateUrl
  3. getTermsUrl
  4. createCustomerUrl
  5. createInvoiceUrl

Testando sua integração no HubSpot

Criar uma conta de teste no HubSpot

O primeiro passo é criar uma conta de teste no HubSpot de dentro da sua conta de desenvolvedor. Essa conta permitirá testar e usar a maioria dos recursos do HubSpot, inclusive sua integração de contabilidade.

Saiba mais em Como faço para criar uma conta de teste?

Instalando o aplicativo para sua conta de teste

Agora que criou uma conta de teste no HubSpot, você precisará instalar seu aplicativo nela.  Para verificar se o aplicativo foi instalado em sua conta de teste, acesse a página de aplicativos conectados

Para obter mais informações, leia Autorizando e instalando um aplicativo

Criar uma fatura

As faturas no HubSpot são criadas com base em negócios. No HubSpot, um negócio representa uma transação em andamento que uma equipe de vendas está tentando fechar com um contato ou uma empresa.  É possível criar um negócio na interface de usuário selecionando “Vendas” no canto superior direito, “Negócios” e depois pressionando o botão “Criar negócio”.  Depois de criar um negócio, você será levado automaticamente à tela de visão geral do negócio que acabou de criar.  No lado direito da tela, você verá uma seção “Faturas”.  Clique em “Criar fatura” e insira os detalhes da fatura que deseja criar. Você deverá receber chamadas de Webhook do HubSpot para os vários estágios do fluxo de criação da fatura.

Endpoints do Webhook

Veja abaixo os endpoints do Webhook que podem ser configurados com uma chamada para /settings.  O payload JSON enviado para cada endpoint do Webhook e o formato de retorno de chamada esperado são descritos.  Veja a guia Endpoints para obter informações mais específicas sobre endpoints de retorno de chamada individuais.

getInobuiceUrl (Obrigatório)

Um URL que especifica o endpoint em que as faturas podem ser recuperadas.

1) Solicitação para o JSON de seu serviço:

JSON
// Get Invoices Request
{
  "invoiceIds": List<string>
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

Exemplo de JSON

JSON
// Example Request
{
  "invoiceIds": [
    "inv-1",
    "inv-2"
  ],
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação para o JSON do endpoint de retorno de chamada do HubSpot (/callback/invoices/{requestId}:

JSON
// Customer Create Response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": string,
      "invoiceNumber": string,
      "currency": string,
      "amountDue": number,
      "balance": number,
      "dueDate": string,
      "customerId": string,
      "customerName": string,
      "invoiceLink": string,
      "status": string
    }
  ]
}

O campo de status é uma string que deve ter um dos seguintes valores:

  • CRIADO: Aguardando envio ao cliente.
  • ENVIADO: A fatura foi enviada ao cliente.
  • PAGO: O pagamento parcial foi recebido para a fatura.
  • FECHADO: A fatura foi paga integralmente.
  • VENCIDO: A fatura está vencida - a data de vencimento está no passado.
  • Cancelado: A fatura foi cancelada.

Exemplo de JSON

JSON
// Example Response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": "inv-1",
      "invoiceNumber": "INV-123",
      "currency": "USD",
      "amountDue": 100.5,
      "balance": 50,
      "dueDate": "2020-03-31",
      "customerId": "cust-123",
      "customerName": "John Smith",
      "invoiceLink": "https://myapp.com/invoices/1243a2",
      "status": "OVERDUE"
    }
  ]
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

getInviticePdfUrl (Obrigatório)

Um URL que especifica o endpoint onde é possível recuperar o PDF de uma fatura.

1) Solicitação para o JSON de seu serviço:

JSON
// Example Request
{
  "invoiceId": "inv-1",
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/invoice-pdf/{requestId}):

JSON
// Response Structure
{
  "@result": "OK",
  "invoice": string (format: byte)
}

O campo fatura é uma string codificada com BASE64 dos bytes do PDF da fatura.

Exemplo de JSON:

JSON
// Example Response
{
  "@result": "OK",
  "invoice": "U3dhZ2dlciByb2Nrcw=="
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

searchCustomerUrl (Obrigatório)

Um URL que especifica o endpoint em que é possível pesquisar um cliente.

1) Solicitação para o JSON de seu serviço:

JSON
// searchCustomerUrl
{
  "pageNumber": Optional<int>,
  "pageSize": Optional<int>,
  "searchRequests": [
    {
      "query": string,
      "fieldTypes": [string]
    }
  ],
  "metadata": {
    "requestId": string
  },
  "accountId": string
}

Nos casos em que houver várias entradas em searchRequests, elas deverão ser tratadas como OR A distinção entre letras maiúsculas e minúsculas deve seguir o padrão da plataforma. Se existir a possibilidade de haver dois clientes no sistema, John e JOHN, as pesquisas deverão fazer distinção entre letras maiúsculas e minúsculas. Caso contrário, elas não deverão fazer essa distinção.

  • pageNumber é o número da página de resultados que serão retornados da pesquisa. Isso possibilita a paginação na interface de usuário do HubSpot pageNumber começa em 1.
  • pageSize é o número máximo de resultados que serão retornados da pesquisa.
  • fieldTypes é uma lista de strings que descreveram como executar a pesquisa. Estes são os valores possíveis:
    • EMAIL: retorna os clientes cujos endereços de e-mail contêm a string de consulta.
    • NAME: retorna os clientes cujos nomes contêm a string de consulta.
    • ID: retorna os clientes cujo ID corresponde à string de consulta. Será especificado apenas um ID na string de consulta.

Exemplo de JSON

JSON
// example request
{
  "searchRequests": [
    {
      "query": "Amy",
      "fieldTypes": [
        "NAME", "EMAIL"
      ]
    },
    {
      "query": "Birds",
      "fieldTypes": [
        "EMAIL"
      ]
    }
  ],
  "metadata": {
    "requestId": "tests-req-id"
  },
  "accountId": "123146316464684"
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/customer-search/{requestId}):

JSON
// request to hubspot 
{
  "@result": "OK",
  "customers": [
    {
      "id": int,
      "name": string,
      "emailAddress": string,
      "billingAddress": {
        "lineOne": Optional<string>,
        "city": Optional<string>,
        "countrySubDivisionCode": Optional<string>,
        "postalCode": Optional<string>,
        "country": Optional<string>
      }
    },
    ...
  ]
}

Exemplo de JSON

JSON
// example
{
  "@result": "OK",
  "customers": [
    {
      "id": "1",
      "name": "Amy's Bird Sanctuary",
      "emailAddress": "Birds@company.com",
      "billingAddress": {
        "lineOne": "4581 Finch St.",
        "city": "Bayshore",
        "countrySubDivisionCode": "CA",
        "postalCode": "94326",
        "country": null
      }
    },
    {
      "id": "58",
      "name": "Bobby",
      "emailAddress": "bobby@company.com"
    }
  ]
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

searchInvoiceUrl (Obrigatório se o recurso de Importação de fatura estiver ativado)

Um URL que especifica o endpoint em que é possível pesquisar uma fatura.

1) Solicitação para o JSON de seu serviço:

JSON
// Search Taxes Request
{
  "request": {
    "queryType": Optional<{
      "fieldType": string (INVOICE_NUMBER|CUSTOMER_NAME),
      "queryValues": List<string>,
    }>,
    "orderBy": string (DUE_DATE),
    "orderDirection": string (ASC|DESC),
    "pageNumber": Optional<integer>,
    "pageSize": Optional<integer>
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}
  • pageNumber é o número da página de resultados que serão retornados da pesquisa. Isso possibilita a paginação na interface de usuário do HubSpot pageNumber começa em 1.
  • pageSize é o número máximo de resultados que serão retornados da pesquisa.
  • fieldType é uma string que descreveu como executar a pesquisa. Estes são os valores possíveis:
    • INVOICE_NUMBER: retorna as faturas cujos números contêm a string de consulta.
    • CUSTOMER_NAME: retorna as faturas de clientes cujos nomes contêm a string de consulta.

Exemplo de JSON:

JSON
// Example request
{
  "request": {
    "queryType": {
      "fieldType": "CUSTOMER_NAME",
      "queryValues": [
        "Amy"
      ],
    },
    "orderBy": "DUE_DATE",
    "orderDirection": "DESC",
    "pageNumber": 1,
    "pageSize": 20
  },
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/invoice-search/{requestId}):

JSON
// Search Invoice Response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": string,
      "invoiceNumber": string,
      "currency": string,
      "amountDue": number,
      "balance": number,
      "dueDate": string,
      "customerId": string,
      "customerName": string,
      "invoiceLink": string,
      "status": string
    }
  ]
}

Exemplo de JSON:

JSON
// Example response
{
  "@result": "OK",
  "invoices": [
    {
      "invoiceId": "inv-1",
      "invoiceNumber": "INV-123",
      "currency": "USD",
      "amountDue": 100.5,
      "balance": 50,
      "dueDate": "2020-03-31",
      "customerId": "cust-123",
      "customerName": "John Smith",
      "invoiceLink": "https://myapp.com/invoices/1243a2",
      "status": "OVERDUE"
    }
  ]
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

searchProductUrl (Obrigatório se o recurso de Criação de fatura estiver ativado)

Um URL que especifica o endpoint em que é possível pesquisar um produto.

1) Solicitação para o JSON de seu serviço:

// searchProductUrl { "pageNumber": Optional<int>, "pageSize": Optional<int>, "searchRequests": [ { "query": string, "fieldType": [string] } ], "metadata": { "requestId": string }, "accountId": string }

Nos casos em que houver várias entradas em searchRequests, elas deverão ser tratadas como OR A distinção entre letras maiúsculas e minúsculas deve seguir o padrão da plataforma. Se existir a possibilidade de haver dois produtos no sistema, "Shoe" e "SHOE", as pesquisas deverão fazer distinção entre letras maiúsculas e minúsculas. Caso contrário, elas não deverão fazer essa distinção.

  • pageNumber é o número da página de resultados que serão retornados da pesquisa. Isso possibilita a paginação na interface de usuário do HubSpot pageNumber começa em 1.
  • pageSize é o número máximo de resultados que serão retornados da pesquisa.
  • fieldTypes é uma lista de strings que descreveram como executar a pesquisa. Estes são os valores possíveis:
    • NAME_FULL: retorna os produtos cujos nomes correspondem à string de consulta.
    • NAME_PARTIAL: retorna os produtos cujos nomes contêm a string de consulta.
    • ID: retorna os produtos cujos IDs correspondem à string de consulta. Será especificado apenas um ID na string de consulta.

Exemplo de JSON:

// Example request { "searchRequests": [ { "query": "PROD-1", "fieldType": "ID" }, { "query": "Shoes", "fieldType": "NAME_PARTIAL" }, { "query": "Cotton Pants", "fieldType": "NAME_FULL" } ], "metadata": { "requestId": "tests-req-id" }, "accountId": "123146316464684" }

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/product-search/{requestId}):

// Product Search Response Structure { "@result": "OK", "products": [ { "unitPrice": { "amount": number, "taxIncluded": boolean }, "taxExempt": boolean, "salesTaxType": { "code": string, "name": string }, "name": string, "description": string, "id": string } ] }

Exemplo de JSON:

// Product Search Response { "@result": "OK", "products": [ { "unitPrice": { "amount": 10.99, "taxIncluded": false }, "taxExempt": false, "salesTaxType": { "code": "tax-1", "name": "Local Sales Tax" }, "name": "Marketing Services", "description": "Website design, Online advertising and SEO.", "id": "PROD-1" }, { "unitPrice": { "amount": 49.99, "taxIncluded": false }, "taxExempt": false, "salesTaxType": { "code": "tax-1", "name": "Local Sales Tax" }, "name": "Running Shoes", "description": "Special shoes aimed at running.", "id": "PROD-2" }, { "unitPrice": { "amount": 20.99, "taxIncluded": false }, "taxExempt": false, "salesTaxType": { "code": "tax-1", "name": "Local Sales Tax" }, "name": "Cotton Pants", "description": "Cotton pants, a fashion favorite for a stylish look.", "id": "PROD-3" } ] }

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

searchTaxUrl (Obrigatório se o recurso de Imposto estiver ativado)

Um URL que especifica o endpoint em que é possível pesquisar um imposto.

1) Solicitação para o JSON de seu serviço:

JSON
// Search Taxes Request
{
  "searchRequest": {
    "fieldType": "NAME_PARTIAL",
    "query": string,
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

fieldType sempre será NAME_PARTIAL: retorna impostos cujos nomes contêm a string de consulta.

Exemplo de JSON:

JSON
// Search Taxes Request
{
  "searchRequest": {
    "fieldType": "NAME_PARTIAL",
    "query": "VAT",
  },
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/tax-search/{requestId}):

JSON
// Response structure
{
  "@result": "OK",
  "taxes": [
    {
      "code": string,
      "percentage": number,
      "name": string
    }
  ]
}

Exemplo de JSON:

JSON
// Example response
{
  "@result": "OK",
  "taxes": [
    {
      "code": "tax-1",
      "percentage": 13.5,
      "name": "Reduced VAT Rate"
    }
  ]
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

exchangeRateUrl (Obrigatório se o recurso de Taxa de câmbio estiver ativado)

Um URL que especifica o endpoint em que as taxas de câmbio podem ser consultadas.

1) Solicitação para o JSON de seu serviço:

JSON
// Exchange Rate Request
{
  "sourceCurrencyCode": string,
  "targetCurrencyCode": string,
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

Exemplo de JSON:

JSON
// Example request
{
  "sourceCurrencyCode": "USD",
  "targetCurrencyCode": "EUR",
  "accountId": "123146316464684",
  "metadata": { 
    "requestId": "test-req-id" 
  }
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/exchange-rate/{requestId}):

JSON
// Exchange Rate Response
{
  "@result": "OK",
  "sourceCurrencyCode": string,
  "targetCurrencyCode": string,
  "exchangeRate": number,
}

Exemplo de JSON:

JSON
// Example response
{
  "@result": "OK",
  "sourceCurrencyCode": "USD",
  "targetCurrencyCode": "EUR",
  "exchangeRate": 0.910847,
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

getTermsUrl (Obrigatório se o recurso de Termos de pagamento estiver ativado)

Um URL que especifica o endpoint em que os termos de pagamento podem ser recuperados. Enviaremos um campo customerId ao fazer uma solicitação de termos de pagamento para um cliente específico. No entanto, se o usuário do HubSpot tiver optado por criar um novo cliente como parte de criar uma nova fatura, nenhum customerId será enviado.

1) Solicitação para o JSON de seu serviço:

JSON
// Terms Request
{
  "accountId" : string,
  "customerId": Optional<string>,
  "metadata": { 
    "requestId": string 
  }
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/terms/{requestId}):

// Terms Response { "@result": "OK", "terms": [ { "name": string, "id": string, "dueDays": integer } ] }

Exemplo de JSON

//example JSON { "@result": "OK", "terms": [ { "name": "Net 30", "id": "net-30", "dueDays": 30 } ] }

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

createCustomerUrl: (Obrigatório se o recurso de Criação de cliente estiver ativado)

Um URL que especifica o endpoint em que é possível criar um novo cliente.

1) Solicitação para o JSON de seu serviço:

JSON
// Customer Create Request
{
  "customerCreationRequest": {
    "name": string,
    "emailAddress": string,
    "companyName": Optional<String>,
    "billingAddress":{
      "lineOne": Optional<String>,
      "city": Optional<String>,
      "countrySubDivisionCode": Optional<String>,
      "postalCode": Optional<String>,
      "country": Optional<String>
    }
  },
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

Exemplo de JSON

JSON
// Example Request
{
  "customerCreationRequest": {
    "name": "Amy's Bird Sanctuary",
    "emailAddress": "Birds@birds.com",
    "companyName": "HubSpot",
    "billingAddress": {
      "lineOne": "25 First Street",
      "city": "Cambridge",
      "countrySubDivisionCode": "MA",
      "postalCode": "02141",
      "country": "United States"
    }
  },
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/customer-create/{requestId}):

JSON
// Customer Create Response
{
  "@result": "OK",
  "id": string
}

Exemplo de JSON

JSON
// Example Response
{
  "@result": "OK",
  "id": "new-cust-123"
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro

createInvoiceUrl (Obrigatório se o recurso de Criação de fatura estiver ativado)

Um URL que especifica o endpoint em que é possível criar uma fatura.

1) Solicitação para o JSON de seu serviço:

JSON
// Invoice Create Request
{
    "invoiceCreationRequest": {
    "customerId": Optional<String>,
    "invoiceLines": [
      {
        "productId": string,
        "description" : string,
        "qty": int,
        "unitPrice": {
          "amount": double,
          "taxIncluded": boolean
        },
        "amount": double
      }
    ],
    "createDate": date
    "dueDate": date,
    "salesTermId": Optional<string>,
    "customerMessage": Optional<String>,
    "privateMessage": Optional<String>
  },
  "customerCreationRequest": Optional<{
    "name": string,
    "emailAddress": string,
    "companyName": Optional<String>,
    "billingAddress":{
      "lineOne": Optional<String>,
      "city": Optional<String>,
      "countrySubDivisionCode": Optional<String>,
      "postalCode": Optional<String>,
      "country": Optional<String>
    }
  }>,
  "accountId": string,
  "metadata": { 
    "requestId": string 
  }
}

Exemplo de JSON

JSON
// Example Request
{
  "invoiceCreationRequest": {
    "customerId": null,
    "invoiceLines": [
      {
        "productId": "PROD-3",
        "description": "Description to include in the invoice, overriding the product's default description",
        "qty": 3,
        "unitPrice": {
          "amount": 20.99,
          "taxIncluded": false
        },
        "amount": 4
      }
    ],
    "createDate": "2020-03-31T10:15:30Z",
    "dueDate": "2020-04-30T10:15:30Z",
    "salesTermId": "net-30",
    "customerMessage": "Message included on the invoice",
    "privateMessage": "Note attached to the invoice that only the accounting system user can see"
  },
  "customerCreationRequest": {
    "name": "Amy's Bird Sanctuary",
    "emailAddress": "Birds@birds.com",
    "companyName": null,
    "billingAddress": {
      "lineOne": null,
      "city": null,
      "countrySubDivisionCode": null,
      "postalCode": null,
      "country": null
    }
  },
  "metadata": {
    "requestId": "test-req-id"
  },
  "accountId": "123146316464684"
}

2) Resposta para o HubSpot:

    200 (sem corpo)

3) Solicitação ao JSON do endpoint de retorno de chamada do HubSpot (/callback/invoice-create/{requestId}):

JSON
// Invoice Create Response
{
  "@result": "OK",
  "id": string
}

4) Resposta ao JSON de seu serviço:

    200 ou 400 com informações do erro


Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.