Documentação API

• Introdução
• Autenticação
• Respostas e Erros
• Contatos
• Tags
• Workspace
• Smart Flows

Introdução

[cite_start]

Esta API foi meticulosamente criada para capacitar os nossos utilizadores na gestão eficiente dos seus dados e na aquisição transparente de leads adicionais de sistemas externos. [cite: 282] [cite_start]Desde o seu lançamento a 8 de dezembro de 2023, a API tem facilitado ativamente funcionalidades melhoradas para os nossos utilizadores. [cite: 283]

[cite_start]

Use a seguinte URL base para fazer os seus pedidos: [cite: 310]

https://ra-bcknd.com/v1

[cite_start]

Nota: Pode fazer 100 pedidos por minuto a partir de um único endereço IP. [cite: 312]

---

Autorização

A API do ConverseIA Hub Inovattion utiliza um robusto sistema de tokens para garantir a segurança dos pedidos. [cite_start]Para iniciar um pedido, é imperativo incluir um token no cabeçalho, designado com a chave "Authorization", no seguinte formato: [cite: 285, 286]

Authorization: Bearer <SEU_TOKEN_API>

Obtenção de um Token

Para obter um token, comece por fazer login no seu espaço de trabalho. Após o login bem-sucedido, navegue até à opção Definições no menu principal. Em seguida, clique em Conectar → API na barra lateral. [cite_start]Se uma chave ainda não tiver sido gerada, clique no botão "Gerar Chave". [cite: 288, 289, 290]

Autenticar

[cite_start]

Este endpoint pode ser usado para verificar a sua autenticação. [cite: 364, 365]

Exemplo de Requisição

Exemplo de Resposta de Sucesso

{
    "id": 2,
    "workspace_id": 1,
    "company_id": 2,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "title": null,
    "timezone": null,
    "source": "MANUAL",
    "picture": "https://ui-avatars.com/api/?font-size=0.4&background=02846B&color=fff&name=John+Doe"
}

---

Respostas e Erros

Códigos de Status HTTP

[cite_start]

Utilizamos códigos de resposta HTTP convencionais para transmitir claramente o sucesso ou a falha de cada pedido. [cite: 319]

[cite_start]
• 2xx (Sucesso): A operação foi bem-sucedida (e.g., 200 OK, 201 CREATED). [cite: 320, 322, 324]
[cite_start]
• 4xx (Erro do Cliente): Erros decorrentes da informação fornecida (e.g., 400 BAD REQUEST, 401 UNAUTHORIZED, 404 NOT FOUND). [cite: 320, 330, 332, 339]
[cite_start]
• 5xx (Erro do Servidor): Problemas nos nossos servidores. [cite: 320]

Manipulação de Erros

[cite_start]

Em caso de erros, a resposta contém dados para descrever o erro. [cite: 342]

[cite_start] [cite_start] [cite_start]

Atributo	Descrição
error	true / false [cite: 343]
error_code	Um código de erro em maiúsculas para guiar as suas ações (e.g., UNAUTHORIZED, INVALID_REQUEST). [cite: 343]
message	Uma explicação do erro. [cite: 343]

Exemplo de Resposta de Erro

{
    "error": true,
    "error_message": "You are not authorized for this request.",
    "error_code": "UNAUTHORISED"
[cite_start]}

[cite: 356, 357]

---

Contatos

Adicionar um Contato

[cite_start]

Adiciona um novo contato. [cite: 387]

Corpo (JSON)

{
    "company_id": "",
    "company_name": "John & Co",
    "first_name": "John",
    "last_name": "Doe",
    "title": "Mr. John",
    "locale": "en-US",
    "phone_number": "+15551234561",
    "primary_phone_number": "+15551234562",
    "whatsapp_number": "+15551234563",
    "primary_whatsapp_number": "+15551234564",
    "opt_in_sms": null,
    "opt_in_call": true,
    "email": "secondary-sample@domain.com",
    "primary_email": "primary-sample@domain.com",
    "opt_in_email": true,
    "custom_fields": {
        "text_field": "Some textual data",
        "secondary_number": "545454545",
        "department": "Development",
        "grade": "C"
    }
}

Obter um Contato

[cite_start]

Obtém os detalhes de um contato específico. [cite: 448, 449]

Obter Contato por Campo Personalizado

Parâmetros (formdata)

[cite_start] [cite_start]

Chave	Descrição
fieldName	O nome do campo personalizado. [cite: 424]
fieldValue	O valor a procurar no campo. [cite: 425]

Definir um Campo Personalizado

Corpo (JSON)

{
    "field_value": "Value",
    "system_name": "text_field"
[cite_start]}

[cite: 433, 434]

Desfazer um Campo Personalizado

Corpo (JSON)

{
    "custom_field_id": "text_field"
[cite_start]}

[cite: 446]

Executar uma Ação

Parâmetros (formdata)

[cite_start] [cite_start] [cite_start]

Chave	Valor de Exemplo	Descrição
items[0][action]	add Tag	A ação a ser executada. [cite: 458, 459]
items[0][tagName]	test tag 5	O nome da tag (se a ação for relacionada a tags). [cite: 460, 461]
contactid	2251799813685256	O ID do contato. [cite: 462, 463]

---

Tags

Listar Tags

Obtém uma lista de tags. [cite_start]Pode filtrar por nome e limitar os resultados. [cite: 507, 508]

Parâmetros de Consulta (Query Params)

[cite_start] [cite_start]

Chave	Valor de Exemplo	Descrição
key	b	Opcional: Procura tags por nome. [cite: 512, 513, 514]
limit	25	Opcional: Máximo de 250. [cite: 515, 523, 524]

Aplicar uma Tag a um Contato

Corpo (JSON)

{
    "tag": "Tag A"
[cite_start]}

[cite: 471]

Aplicar Várias Tags a um Contato

Corpo (JSON)

{
    "tags": ["tag a", "tag b"]
[cite_start]}

[cite: 480]

Remover uma Tag de um Contato

Corpo (JSON)

{
    "tag": "Tag A"
[cite_start]}

[cite: 492]

Remover Várias Tags de um Contato

Corpo (JSON)

{
    "tags": ["tag a", "tag b"]
[cite_start]}

[cite: 501]

Gerir Tags (Adicionar/Remover)

Parâmetros (formdata)

[cite_start] [cite_start] [cite_start] [cite_start]

Chave	Valor de Exemplo	Descrição
action	add	Opções: 'add' ou 'remove'. [cite: 532, 533, 537]
item_id	1	O ID do item (e.g., ID do contato). [cite: 536, 540]
tag_name	tag E	O nome da tag. [cite: 534, 538]
item_type	contact	O tipo de item (e.g., 'contact'). [cite: 535, 539]

---

Workspace

Obter Campos Personalizados

[cite_start]

Obtém a lista de todos os campos personalizados definidos no workspace. [cite: 544, 545]

---

Smart Flows

Enviar um Flow

[cite_start]

Inicia um "Smart Flow" para um contato específico. [cite: 551, 552]

Parâmetros (formdata)

[cite_start] [cite_start]

Chave	Valor de Exemplo
automation_id	123456 [cite: 557, 558]
contact_id	78910 [cite: 559, 560]