🧭

Escopo e primeiros passos

4 artigos Suporte Por Suporte

O que o cliente pode usar na API IAra, limites de escopo, base URL, autenticacao e padroes de resposta.

Escopo publico da API IAra

Escopo publico da API IAra A API publica da IAra e voltada para operacoes dentro da conta do cliente. Ela permite integrar sistemas externos com contatos, conversas, mensagens, etiquetas, atributos, filtros, webhooks, relatorios e outros recursos liberados no proprio painel da conta. O que esta dentro do escopo - Consultar e atualizar dados da propria conta, conforme permissao do token. - Criar, buscar, atualizar e organizar contatos. - Criar e acompanhar conversas. - Enviar mensagens e anexos em conversas existentes. - Atribuir conversas a agentes e times disponiveis na conta. - Usar etiquetas, atributos personalizados, filtros, respostas prontas e webhooks. - Consumir relatorios e eventos quando o usuario tiver permissao. - Usar Client API para experiencias proprias de chat em uma caixa de API ja configurada. O que nao faz parte da documentacao publica Esta central documenta apenas operacoes disponiveis ao cliente dentro da propria conta. Configuracoes que nao aparecem no painel, provisionamentos feitos pela Digi2B e rotinas internas de operacao devem ser solicitados ao suporte. Regra de ouro Se a acao nao puder ser feita no painel da sua conta ou nas rotas documentadas aqui, nao tente contornar pela API. Abra demanda com a Digi2B.

Base URL, autenticacao e IDs

Base URL, autenticacao e IDs Os exemplos da API IAra usam a URL da plataforma Digi2B: export BASE_URL="https://app.digi2b.com" export ACCOUNT_ID="59" export API_TOKEN="seu_token_da_iara" Application API Use para automacoes autenticadas no escopo da conta: /api/v1/accounts/:account_id Autenticacao: -H "api_access_token: $API_TOKEN" Client API Use para experiencias proprias de chat em uma caixa de API ja configurada: /public/api/v1/inboxes/:inbox_identifier A Client API usa inbox_identifier, contact_identifier e, quando habilitado, identifier_hash. IDs comuns ID Onde aparece account_id URL da conta e rotas autenticadas inbox_id Caixas/canais da conta inbox_identifier Caixa de API para Client API contact_id Contato dentro da conta conversation_id Conversa interna display_id Numero visivel da conversa no painel agent_id Agente da conta team_id Time da conta Primeiro teste curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/inboxes" \ -H "api_access_token: $API_TOKEN" Se esse teste falhar, confira token, conta, permissao do usuario e ambiente antes de seguir.

Mapa completo dos recursos de conta

Mapa completo dos recursos de conta A documentacao da API IAra separa os recursos entre Application API e Client API. O cliente deve usar somente rotas que atuam dentro da propria conta. Application API incluida nesta central Grupo oficial Escopo IAra Account Consultar/atualizar dados permitidos da conta Profile Consultar/atualizar perfil do usuario autenticado Agents Gerenciar agentes conforme permissao Teams Gerenciar times conforme permissao Inboxes Consultar caixas; criacao de canais pode depender da Digi2B Contacts Criar, buscar, atualizar, filtrar e mesclar contatos Contact Labels Ler e atualizar etiquetas de contato Conversations Listar, filtrar, criar, atualizar, priorizar e alterar status Conversation Assignments Atribuir conversa a agente/time Conversation Labels Ler e atualizar etiquetas de conversa Messages Listar, criar e, quando permitido, remover mensagens Canned Responses Gerenciar respostas prontas Labels Gerenciar etiquetas da conta Custom Attributes Gerenciar campos personalizados Custom Filters Gerenciar filtros salvos Automation Rules Gerenciar automacoes liberadas na conta Integrations Gerenciar hooks de integracoes liberadas Webhooks Enviar eventos para sistemas externos Reports Consumir metricas e eventos de atendimento Audit Logs Disponivel apenas quando habilitado no plano/conta Help Center Gerenciar portais, categorias e artigos da conta Fora do escopo Acoes fora da conta do cliente, provisionamentos e configuracoes gerenciadas pela Digi2B nao entram nesta central publica. Quando um recurso depender da Digi2B, o artigo deve dizer isso de forma explicita.

Paginacao, filtros e respostas

Paginacao, filtros e respostas Muitos endpoints retornam listas paginadas. O formato pode variar por recurso, mas geralmente a resposta vem com payload e meta. Exemplo curl -X GET "$BASE_URL/api/v1/accounts/$ACCOUNT_ID/conversations?page=2" \ -H "api_access_token: $API_TOKEN" Filtros comuns Filtros variam por endpoint. Os mais frequentes sao: - page - status - inbox_id - team_id - assignee_id - from - to - q Recomendacao para integracoes - Sempre leia a resposta antes de assumir formato fixo. - Trate pagina vazia como fim da sincronizacao. - Grave IDs externos para evitar duplicidade. - Nao use consultas grandes em tempo real se puder sincronizar em lote. - Em retries, evite repetir criacoes sem idempotencia. Exemplo de loop conceitual page = 1 while true: buscar page se payload vazio: parar processar itens page += 1