> ## Documentation Index > Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # API do CRM | Cartões de CRM > **[Run in Postman](https://app.getpostman.com/run-collection/26126890-b4ebfe97-5852-4a5d-a9be-d171474df3b1)** Dentro de um [aplicativo público](https://br.developers.hubspot.com/docs/apps/legacy-apps/public-apps/overview.md), você pode criar cartões de CRM personalizados para exibir informações de outros sistemas nos registros de contatos, empresas, negócios e tickets da HubSpot. Cada aplicativo pode incluir até 25 cartões de CRM. > [!NOTE] > > Desde 16 de junho de 2025, a funcionalidade dos cartões de CRM clássicos descritos neste artigo não têm mais suporte e será oficialmente descontinuada em 31 de outubro de 2026. Você pode saber mais sobre este anúncio no [Registro de alterações do desenvolvedor HubSpot](https://community.hubspot.com/t5/Developer-Announcements/Deprecating-Support-for-Classic-Legacy-CRM-Cards/m-p/1153039#M1048). > > Os cartões de CRM clássicos são diferentes dos cartões de aplicativo que você pode [criar como extensões de IU com projetos](https://br.developers.hubspot.com/docs/guides/crm/ui-extensions/create). Esses novos cartões de aplicativo oferecem mais flexibilidade, personalização e interatividade usando um conjunto de ferramentas mais moderno, baseado em React. Se seu aplicativo atualmente inclui um card clássico do CRM, saiba como [migrá-lo para o framework de projetos](https://br.developers.hubspot.com/docs/apps/developer-platform/build-apps/overview) para utilizar os novos cards de aplicativo. **Exemplo de caso de uso:** você está criando uma integração para o Marketplace de aplicativos para o seu software de rastreamento de bugs. Você quer poder expor bugs rastreados em registros de contatos para que os representantes de suporte possam referenciá-los ao trabalhar com clientes. Seu aplicativo pode definir um cartão personalizado que exibe essas informações diretamente no registro de contato do HubSpot. ![CRM\_Card\_1](https://cdn2.hubspot.net/hubfs/53/CRM_Card_1.png) Os cartões podem ser definidos como parte das configurações de recurso do aplicativo. Assim que o aplicativo for instalado e um usuário visualizar os registros do CRM de destino, o HubSpot fará uma solicitação de saída para o aplicativo, recuperará os dados relevantes e os exibirá em um cartão na página de registro. Os apps também podem especificar ações personalizadas que o usuário pode realizar com base nessas informações. Por exemplo, seu aplicativo pode incluir uma ação para abrir um modal para exibir a própria interface do usuário do aplicativo no HubSpot. ![crm-card-data-flow-chart](https://br.hubspot.com/hubfs/Knowledge_Base_2023-24-25/crm-card-diagram.png) ## Requisitos do escopo Para criar cartões de CRM personalizados, seu aplicativo precisa solicitar os escopos de OAuth necessários para modificar os registros de CRM em que seu cartão aparecerá. Por exemplo, para que um cartão do CRM apareça nos registros de contato, o aplicativo deve ter os escopos `crm.objects.contacts.read` e `crm.objects.contacts.write` Se mais tarde precisar remover escopos de objeto do CRM do seu aplicativo, primeiro será necessário excluir todos os cartões existentes para esses tipos de objetos. Veja a documentação de OAuth para [obter mais detalhes sobre os escopos](https://br.developers.hubspot.com/docs/apps/legacy-apps/authentication/working-with-oauth.md) e configurar o URL de autorização para seu aplicativo. ## Criar um cartão de CRM Você pode criar cartões do CRM para o seu aplicativo por meio da API ou editando o aplicativo na sua conta de desenvolvedor. Para saber mais sobre a configuração de um cartão por meio da API, confira a [documentação de referência](https://br.developers.hubspot.com/docs/api-reference/crm-public-app-crm-cards-v3/guide.md). Para criar um cartão do CRM usando a interface do usuário da HubSpot: * Na sua conta de desenvolvedor da HubSpot, acesse **Aplicativos** na barra de navegação principal. * Selecione o **aplicativo** no qual deseja adicionar um cartão. * No menu da barra lateral esquerda, selecione **Cartões do CRM**. * No canto superior direito, clique em**Criar cartão do CRM**. ![private-app-create-crm-card](https://br.hubspot.com/hubfs/Knowledge_Base_2023/private-app-create-crm-card.png) Saiba mais sobre as opções de configuração em cada guia. > [!NOTE] > > As extensões de UI criadas com projetos de desenvolvedores oferecem maneiras mais flexíveis de exibir dados e permitir a interação do usuário, incluindo a exibição de conteúdo externo em quadros. Se usar um aplicativo privado for viável para a sua integração, confira o [guia de início rápido das extensões de UI](https://br.developers.hubspot.com/docs/apps/developer-platform/build-apps/overview) para começar, ou [veja exemplos de projetos da HubSpot](https://br.developers.hubspot.com/docs/guides/crm/ui-extensions/sample-extensions/overview) para ver exemplos do que é possível fazer. ## Solicitação de dados Quando um usuário da HubSpot visualiza um registro do CRM no qual o cartão do CRM está ativo, o HubSpot fará uma solicitação de busca de dados para a integração. Essa solicitação é feita para o URL de destino especificado, que inclui um conjunto de parâmetros de consulta padrão, juntamente com parâmetros adicionais que contêm dados de propriedade, conforme especificado nas configurações do cartão. ![private-app-create-crm-card-data-request-tab](https://br.hubspot.com/hubfs/Knowledge_Base_2023/private-app-create-crm-card-data-request-tab.png) * No campo do *URL de busca de dados*, digite o **URL** de onde você buscará dados. Na API, este URL está adicionado ao campo `targetUrl`. * Na seção *Tipos de registro de destino*, clique para ativar os **botões** para selecionar em quais registos do CRM o cartão será exibido. Em seguida, use os menus suspensos **Propriedades enviadas do HubSpot** para selecionar as **propriedades do HubSpot** que serão incluídas como parâmetros de consulta no URL de solicitação. Na API, cada tipo de registro e suas propriedades correspondentes são adicionados como objetos na matriz `objectTypes`. ```json theme={null} { "title": "New CRM Card", "fetch": { "targetUrl": "https://www.example.com/demo-fetch", "objectTypes": [ { "name": "contacts", "propertiesToSend": [ "firstname", "email", "lastname" ] } ] } ... } ``` ### Exemplo de solicitação A configuração acima faria com que o HubSpot enviasse a solicitação `GET` da seguinte forma. ```shell theme={null} https://www.example.com/demo-fetch?userId=12345&userEmail=loggedinuser@hubspot.com&associatedObjectId=53701&associatedObjectType=CONTACT&portalId=987654&firstname=Tim&email=timrobinson@itysl.com&lastname=Robinson ``` | Parâmetro | Tipo | Descrição | | - | - | - | | `userId` | Padrão | O ID do usuário do HubSpot que carregou o registo do CRM. | | `userEmail` | Padrão | O endereço de e-mail do usuário que carregou o registo do CRM. | | `associatedObjectId` | Padrão | O ID do registo do CRM que foi carregado. | | `associatedObjectType` | Padrão | O tipo de registo do CRM carregado (por exemplo, contato, empresa, negócio). | | `portalId` | Padrão | O ID da conta da HubSpot na qual o registro do CRM foi carregado. | | `firstname` | Personalizado | O primeiro nome do contato, conforme especificado no menu suspenso \*Propriedades enviadas do HubSpot \*(no aplicativo) e na matriz `propertiesToSend` (API). | | `email` | Personalizado | O endereço de e-mail do contato, conforme especificado no menu suspenso \_Propriedades enviadas do HubSpot \_(no aplicativo) e na matriz `propertiesToSend` (API). | | `lastname` | Personalizado | O sobrenome do contato, conforme especificado no menu suspenso \*Propriedades enviadas do HubSpot \*(no aplicativo) e na matriz `propertiesToSend` (API). | > [!WARNING] > > ### Observação: > > Uma conexão deve ser feita em até três segundos, e as solicitações expirarão após cinco segundos. ### Exemplo de resposta Veja abaixo um exemplo de resposta que o integrador pode fornecer para a solicitação acima. ```json theme={null} { "results": [ { "objectId": 245, "title": "API-22: APIs working too fast", "link": "http://example.com/1", "created": "2016-09-15", "priority": "HIGH", "project": "API", "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.", "reporter_type": "Account Manager", "status": "In Progress", "ticket_type": "Bug", "updated": "2016-09-28", "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit", "associatedObjectProperties": [] }, { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/reassign-iframe-contents", "label": "Reassign", "associatedObjectProperties": [] }, { "type": "ACTION_HOOK", "httpMethod": "PUT", "associatedObjectProperties": [], "uri": "https://example.com/tickets/245/resolve", "label": "Resolve" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": ["protected_account"], "uri": "https://example.com/tickets/245", "label": "Delete" } ] }, { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "project": "API", "reported_by": "ksmith@hubspot.com", "description": "Customer is not able to find documentation about our bulk Contacts APIs.", "reporter_type": "Support Rep", "status": "Resolved", "ticket_type": "Bug", "updated": "2016-09-23", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/edit-iframe-contents", "label": "Edit" }, { "type": "CONFIRMATION_ACTION_HOOK", "confirmationMessage": "Are you sure you want to delete this ticket?", "confirmButtonText": "Yes", "cancelButtonText": "No", "httpMethod": "DELETE", "associatedObjectProperties": ["protected_account"], "uri": "https://example.com/tickets/245", "label": "Delete" } ] } ], "settingsAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/settings-iframe-contents", "label": "Settings" }, "primaryAction": { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/create-iframe-contents", "label": "Create Ticket" } } ``` | Prop | Tipo | Descrição | | - | - | - | | `results` | Matriz | Uma matriz de até cinco [propriedades do cartão](#card-properties). Se mais propriedades de cartão estiverem disponíveis para um Objeto do CRM específico, seu aplicativo poderá vinculá-las. | | `objectId` | Número | Um ID exclusivo para este objeto. | | `title` | Sequência de caracteres | O título deste objeto. | | `link` | Sequência de caracteres | A URL que o usuário pode seguir para obter mais detalhes sobre o objeto. Se nenhum objeto tiver um link, você deverá fornecer um valor de `null`. | | `created` | Sequência de caracteres | A [propriedade personalizada](#card-properties) conforme definido nas configurações da placa que indica a data de criação do objeto. | | `priority` | Sequência de caracteres | A [propriedade personalizada](#card-properties) conforme definido nas configurações do cartão que indicam o nível de prioridade do tíquete externo. | | `actions` | Matriz | Uma lista de [ações](#action-types) que um usuário pode aceitar. | | `properties` | Propriedades | Uma lista de propriedades personalizadas que não estão definidas nas configurações do cartão. Você pode usar essa lista para exibir propriedades exclusivas de objeto específico. Estas propriedades serão mostradas na ordem em que são fornecidas, mas após as propriedades definidas nas configurações do cartão. | | `settingsAction` | Objeto | Uma ação iframe que permite que os usuários atualizem as configurações do aplicativo. | | `primaryAction` | Objeto | A ação principal de um tipo de registro, geralmente uma ação de criação. | | `secondaryActions` | Matriz | Uma lista de outras ações exibidas no cartão. | ### Solicitar assinaturas Para garantir que as solicitações venham realmente do HubSpot, o seguinte cabeçalho de solicitação está incluído. Este cabeçalho conterá um hash do segredo do aplicativo para seu aplicativo e os detalhes da solicitação. `X-HubSpot-Signature: ` Para verificar essa assinatura, execute as seguintes etapas: 1. Crie uma string que concatene o seguinte: `` + `` + `` + ` (if present)`. 2. Crie um hash SHA-256 da string resultante. 3. Compare o valor do hash à assinatura. Se forem iguais, a solicitação passou na validação. Se os valores não corresponderem, a solicitação pode ter sido adulterada em trânsito ou alguém pode estar falsificando solicitações para seu ponto de extremidade. Saiba mais sobre [como validar solicitações do HubSpot](https://br.developers.hubspot.com/docs/apps/legacy-apps/authentication/validating-requests.md). ## Propriedades do cartão Na guia *Propriedades do cartão*, defina quaisquer propriedades personalizadas que você deseja que o HubSpot exiba no cartão do CRM. Depois de definidas, a integração poderá preencher essas propriedades, incluindo-as em sua resposta. * Clique em **Adicionar propriedade** para adicionar uma nova propriedade para ser exibida pelo cartão. A carga útil fornecida em resposta à chamada de busca de dados deve conter valores para todas essas propriedades. * No painel direito, defina o nome exclusivo da propriedade, o rótulo de exibição e o tipo de dados. Você pode selecionar entre os seguintes tipos: *Moeda*, *Data*, *Data/hora*, *E-mail*, *Link*, *Numérico*, *Status* e \_String. Saiba mais sobre como [usar os tipos de propriedade de extensão](https://br.developers.hubspot.com/docs/apps/legacy-apps/extensions/overview). * Clique em **Adicionar** para salvar a propriedade. ![private-app-create-crm-card-card-properties-tab](https://br.hubspot.com/hubfs/Knowledge_Base_2023/private-app-create-crm-card-card-properties-tab.png) Quando o HubSpot enviar sua solicitação de dados, a integração poderá fornecer valores para essas propriedades em sua resposta junto com outros valores em cada objeto em `results`. Além das propriedades configuradas nesta guia, a integração também pode incluir suas próprias propriedades personalizadas sem precisar que elas sejam definidas nas configurações do cartão. Por exemplo, na resposta abaixo, `created` e `priority` são ambos definidos na guia *Propriedades do cartão*, enquanto a matriz `properties` envia suas próprias definições e valores de propriedade. Essas propriedades específicas do objeto devem ser definidas por objeto. ```json theme={null} { "objectId": 988, "title": "API-54: Question about bulk APIs", "link": "http://example.com/2", "created": "2016-08-04", "priority": "HIGH", "properties": [ { "label": "Resolved by", "dataType": "EMAIL", "value": "ijones@hubspot.com" }, { "label": "Resolution type", "dataType": "STRING", "value": "Referred to documentation" }, { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ], "actions": [ ... ] } ``` Ao enviar propriedades personalizadas, o campo `dataType` para cada propriedade pode ser definido como: `CURRENCY`, `DATE`, `DATETIME`, `EMAIL`, `LINK`, `NUMERIC`, `STATUS`, `STRING`. Dependendo do tipo de propriedade, a integração pode precisar fornecer campos adicionais. Saiba mais sobre cada tipo de propriedade. ### Propriedades da moeda As propriedades de `CURRENCY` devem incluir um `currencyCode`, que precisa ser um código [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) válido. Isso garantirá que o usuário veja o símbolo da moeda e a formatação numérica corretos. ```json theme={null} { "results": [ { "properties": [ { "label": "Resolution impact", "dataType": "CURRENCY", "value": "94.34", "currencyCode": "GBP" } ] } ] } ``` ### Propriedades de data As propriedades de `DATE` devem estar no formato `yyyy-mm-dd`. Estas propriedades serão exibidas em um formato apropriado à localidade do usuário. Se precisar incluir um carimbo de data/hora, use uma propriedade de `DATETIME`. ```json theme={null} { "results": [ { "properties": [ { "label": "Date", "dataType": "DATE", "value": "2023-10-13" } ] } ] } ``` ### Propriedades de data/hora As propriedades `DATETIME` indicam uma hora específica e devem ser fornecidas em milissegundos. Estas propriedades serão exibidas em um formato apropriado à localidade do usuário. ```json theme={null} { "results": [ { "properties": [ { "label": "Timestamp", "dataType": "DATETIME", "value": "1697233678777" } ] } ] } ``` ### Propriedades de e-mail Propriedades de `EMAIL` são para valores que contêm um endereço de e-mail. Essas propriedades serão exibidas como links mailto. ```json theme={null} { "results": [ { "properties": [ { "label": "Email address", "dataType": "EMAIL", "value": "hobbes.baron@gmail.com" } ] } ] } ``` ### Propriedades de link Propriedades de `LINK` exibem hiperlinks e abrem em uma nova janela. Você pode especificar um `linkLabel`; caso contrário, o próprio URL será exibido. ```json theme={null} { "results": [ { "properties": [ { "label": "Link property", "dataType": "LINK", "value": "https://www.hubspot.com", "linkLabel": "Test link" } ] } ] } ``` ### Propriedades numéricas As propriedades `NUMERIC` exibem números. ```json theme={null} { "results": [ { "properties": [ { "label": "Number", "dataType": "NUMERIC", "value": "123.45" } ] } ] } ``` ### Propriedades de status Propriedades de `STATUS` são exibidas como indicadores coloridos. Para definir uma propriedade de status, a integração deve fornecer um `optionType` que descreva os possíveis status. Os status incluem: * `DEFAULT`: Cinza * `SUCCESS`: Verde * `WARNING`: Amarelo * `DANGER`: Vermelho * `INFO`: Azul ```json theme={null} { "results": [ { "properties": [ { "label": "Status", "dataType": "STATUS", "value": "Errors occurring", "optionType": "DANGER" } ] } ] } ``` ### Propriedades de string Texto de exibição de propriedades de `STRING`. ```json theme={null} { "results": [ { "properties": [ { "label": "First name", "dataType": "STRING", "value": "Tim Robinson" } ] } ] } ``` ## Ações personalizadas Na guia *Ações personalizadas*, você pode definir os URLs base que serão solicitados quando um usuário clicar em um botão de ação. Você pode incluir vários URLs de ação para várias ações no seu cartão do CRM. As ações do cartão devem chamar um ponto de extremidade especificado nesta guia. ![aplicativo-privado-criar-cartão-crm-ações-personalizadas-guia](https://br.hubspot.com/hubfs/Knowledge_Base_2023/private-app-create-crm-card-custom-actions-tab.png) Os ganchos de ação e as solicitações de ganchos de confirmação incluirão um `X-HubSpot-Signature` cabeçalho para verificar a solicitação. As solicitações de ação do iframe não incluirão uma assinatura de solicitação. Consulte [solicitar assinaturas](#request-signatures) para obter mais informações. Os URLs de ação são acessados no campo `uri` em uma ação. Semelhante à [solicitação de busca de dados](#data-request), os hooks de ação incluirão um conjunto padrão de parâmetros de consulta. Você pode incluir outros parâmetros de consulta, adicionando um campo `associatedObjectProperties` na ação. A resposta irá variar dependendo do tipo de ação. Saiba mais sobre os tipos de ação. ### Tipos de ação #### Ações Iframe As ações `IFRAME` abrirão um modal com um iframe apontando para o URL fornecido. Nenhuma assinatura de solicitação é enviada quando o iframe é aberto usando a UI do CRM. Isso ocorre porque o URL do iframe é retornado na solicitação de busca de dados original e nenhuma solicitação de proxy adicional é necessária. ```json theme={null} { "type": "IFRAME", "width": 890, "height": 748, "uri": "https://example.com/iframe-contents", "label": "Edit", "associatedObjectProperties": ["some_crm_property"] } ``` Quando o usuário terminar de concluir uma ação dentro do iframe, o modal deverá fechar e retornar o usuário ao registro de origem do CRM. Para fechar o modal, a integração pode usar `window.postMessage` para sinalizar ao CRM que o usuário está pronto. As seguintes mensagens são aceitas: * `{"action": "DONE"}`: o usuário concluiu a ação com sucesso. * `{"action": "CANCEL"}`: o usuário cancelou a ação. ```json theme={null} window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*"); ``` #### Ações do hook de ação As ações `ACTION_HOOK` enviam uma solicitação do lado do servidor para o integrador. A única UI que um usuário vê para essa ação é uma mensagem de sucesso ou de erro. Este tipo de ação é útil para operações simples que não exigem entradas adicionais do usuário. Um cabeçalho `X-HubSpot-Signature` será incluído na solicitação para verificação. Saiba mais sobre as [assinaturas de solicitação](#request-signatures). ```json theme={null} { "type": "ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": ["some_crm_property"] } ``` O `httpMethod` pode ser definido como `GET`, `POST`, `PUT`, `DELETE` ou `PATCH`. Se estiver usando `GET` ou`DELETE`, os valores de `associatedObjectProperties` serão anexados ao URL da solicitação como parâmetros de consulta. Caso contrário, as propriedades serão enviadas no corpo da solicitação. ```json theme={null} window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*"); ``` #### Ações de confirmação As ações `CONFIRMATION_ACTION_HOOK` se comportam como as ações `ACTION_HOOK`, exceto que uma caixa de diálogo de confirmação é mostrada para o usuário antes de executar a solicitação do lado do servidor. Um cabeçalho `X-HubSpot-Signature` será incluído na solicitação para verificação. Saiba mais sobre as [assinaturas de solicitação](#request-signatures). ```json theme={null} { "type": "CONFIRMATION_ACTION_HOOK", "httpMethod": "POST", "uri": "https://example.com/action-hook", "label": "Example action", "associatedObjectProperties": ["some_crm_property"], "confirmationMessage": "Are you sure you want to run example action?", "confirmButtonText": "Yes", "cancelButtonText": "No" } ``` O `httpMethod` pode ser definido como `GET`, `POST`, `PUT`, `DELETE` ou `PATCH`. Se estiver usando `GET` ou`DELETE`, os valores de `associatedObjectProperties` serão anexados ao URL da solicitação como parâmetros de consulta. Caso contrário, as propriedades serão enviadas no corpo da solicitação. ## Exclusão de um cartão de CRM Depois de criado, você pode excluir um card do CRM nas configurações do aplicativo: * Na sua conta de desenvolvedor da HubSpot, acesse **Aplicativos** na barra de navegação principal. * Clique no **nome** do aplicativo do qual você deseja excluir um cartão. * No menu da barra lateral esquerda, selecione **Cartões do CRM**. * Passe o mouse sobre o cartão e clique **Excluir**. ![delete-a-classic-crm-card-from-within-app-settings](https://br.hubspot.com/hubfs/Knowledge_Base_2023-24-25/public-app-delete-crm-card.png) * Na caixa de diálogo, confirme a exclusão clicando em **Excluir este cartão**.