--- title: Artia slug: artia createdAt: 2025-07-17T12:11:53.307Z --- ## Objetivo/Resumo O conector Artia permite a interação com as APIs GraphQL do Artia de maneira eficiente, permitindo consultas e mutações de dados para gerenciamento de projetos através da plataforma Artia. ## Funcionalidades principais - **Consultas e Mutations**: Permite realizar queries e mutations nas APIs GraphQL fornecidas pelo Artia. - **Configuração de Template**: Facilita a criação e manutenção de templates para montagem da query para consultas complexas. - **Integração com Artia**: Acesso completo aos recursos de gerenciamento de projetos do Artia. ## Autenticação O Conector Fluid Artia GraphQL API utiliza autenticação baseada em **Client ID** e **Client Secret** para garantir a segurança das suas requisições. Para obter essas credenciais, você precisa: 1. Acessar o painel administrativo do Artia 2. Navegar até as configurações de API 3. Gerar um novo Client ID e Client Secret para sua aplicação 4. Configurar as credenciais no seu workspace da Fluid ## Configuração do conector ### Parâmetros de configuração - **Operação**: O conector Artia expõe apenas a operação **Query** — é por meio dela que tanto consultas quanto mutações são enviadas, já que o protocolo GraphQL usa uma única chamada HTTP para os dois casos. Para executar uma mutação, basta escrever a sintaxe mutation{...} dentro do campo **Template**, representado pelo ícone de plug no conector. - **Template**: Área onde você pode definir e editar o corpo da consulta ou mutação GraphQL (campo query do JSON), independentemente de qual operação GraphQL está sendo executada. - **Client ID**: Identificador único da sua aplicação no Artia. - **Client Secret**: Chave secreta para autenticação da aplicação. ### Exemplo de Template para visualizar um projeto ![](https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/Tn8bzA1PIZX0C3LUGnsWe_image.png) ## Guia de utilização ### Passo a passo para configuração 1. **Selecionar Operação**: O conector Artia possui apenas a operação Query, utilizada tanto para consultas quanto para mutações nas APIs GraphQL do Artia. 2. **Definir Template**: Utilize a aba Template para inserir a consulta ou mutação GraphQL desejada em formato json. Você pode utilizar variáveis e parâmetros para tornar a operação dinâmica. 3. **Configurar Autenticação**: Adicione suas credenciais do Artia (Client ID e Client Secret) nas propriedades do conector. ### Exemplo de configuração: Busca de tarefas por projeto Neste exemplo, efetuaremos uma busca de tarefas de um projeto específico. Primeiro, adiciono o conector Artia ao canvas. Para isso basta arrastá-lo: Adiciono o tipo da operação (neste caso **Query**). ::Image[]{src="https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/nWz8LoF1TyImeZFFwdK-O_image.png" size="60" width="670" height="515" position="center" darkWidth="670" darkHeight="515" showCaption="false"} Agora, nas propriedades, também preciso adicionar **Client ID** e **Client Secret**, com as credenciais de autenticação do Artia: ![](https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/WVRWOodz4H8BowEFqb4_r_image.png) Em seguida, navego até **Template**, agora adiciono a query que quero executar: Exemplo de query para visualizar um projeto: ```json { "query":"query{\n showProject(\n id: 0, \n accountId: 0 \n ) {\n id,\n name,\n status,\n description,\n projectNumber,\n customerName,\n priority,\n estimatedStart,\n estimatedEnd,\n actualStart,\n actualEnd,\n estimatedEffort,\n actualEffort,\n completedPercent,\n responsibleName,\n createdAt,\n updatedAt\n }\n}" } ``` ## Casos de uso práticos Além de consultas pontuais, o conector Artia costuma ser utilizado em fluxos de **sincronização entre a Fluid e um sistema externo** (como um ERP), garantindo que registros criados de um lado sejam refletidos e confirmados do outro. Os exemplos a seguir descrevem esse padrão de forma genérica. ### Sincronização de projetos com um sistema externo Um cenário comum é manter projetos sincronizados entre a Fluid e um sistema de gestão externo, evitando duplicidade de registros. O fluxo costuma seguir esta estrutura: 1. **Consultar** no Artia (operação Query) os projetos já existentes. 2. Usar um passo **Condicional (IF)** para verificar se o projeto recebido do sistema externo já existe no Artia. 3. Caso não exista, usar um passo **For** para iterar sobre os projetos pendentes de criação. 4. Montar dinamicamente a mutation GraphQL (passo de **Template**) com os dados de cada projeto. 5. Executar essa mutation no conector Artia (operação Query) para criar o projeto. 6. Validar o sucesso da operação com um passo **Condicional (IF)**; em caso de falha, direcionar para um passo dedicado de tratamento de erro. 7. Confirmar a criação do projeto de volta no sistema externo, chamando o conector correspondente. 8. Verificar se essa confirmação foi bem-sucedida, com outro passo **Condicional (IF)** e um passo de tratamento de erro dedicado para falhas de confirmação. Esse padrão de "criar e confirmar" é útil quando o sistema externo precisa registrar o ID do projeto gerado no Artia, mantendo rastreabilidade entre os dois sistemas. ### Lançamentos no Artia com confirmação externa Outro cenário recorrente é o envio de lançamentos (por exemplo, apontamentos de horas ou custos de projeto) para o Artia, também com confirmação de volta no sistema de origem. A lógica segue a mesma estrutura do exemplo anterior: 1. Consultar os lançamentos existentes no Artia (Query). 2. Verificar quais lançamentos ainda não foram criados (Condicional - IF). 3. Iterar sobre os lançamentos pendentes (For). 4. Montar a mutation com os dados de cada lançamento (Template). 5. Criar o lançamento no Artia, executando a mutation no conector (operação Query). 6. Verificar o sucesso da criação e, em caso de falha, acionar um passo de erro específico. 7. Confirmar o lançamento no sistema de origem e verificar essa confirmação, com tratamento de erro dedicado para falhas de confirmação. Trate os erros de criação e de confirmação separadamente: um registro pode ser criado com sucesso no Artia, mas falhar na confirmação do sistema externo — são cenários distintos que merecem tratamentos e alertas diferentes. ## Melhores práticas - **Utilização de Variáveis**: Utilize as respostas de outros passos para criar queries e mutations dinâmicas e poderosas. - **Verifique antes de criar**: Em fluxos de sincronização, consulte o Artia (Query) antes de enviar uma mutation de criação, para evitar registros duplicados. - **Separe erros de criação e de confirmação**: Quando o fluxo envolve confirmar a operação em outro sistema, trate essas duas falhas em passos distintos. - **Segurança das Credenciais**: Mantenha seu Client ID e Client Secret seguros e nunca os exponha em código cliente. - **Retorne o que precisar**: Para uma melhor performance, aproveite o poder do GraphQL e defina exatamente os campos que precisará na resposta. - **Tratamento de Erros**: Implemente tratamento adequado de erros para cenários de autenticação e autorização. - **Rate Limiting**: Respeite os limites de taxa da API do Artia para evitar bloqueios. ## Limitações conhecidas - As credenciais Client ID e Client Secret devem ser válidas e ter as permissões adequadas no Artia - Algumas operações podem requerer permissões específicas do usuário ou aplicação - Rate limiting pode ser aplicado dependendo do plano do Artia ## Conclusão O conector Artia simplifica a interação com os serviços GraphQL do Artia, permitindo a realização de consultas e mutações de forma eficiente e configurável. Com uma interface intuitiva, autenticação segura baseada em Client ID/Client Secret, a capacidade de definir templates personalizados e suporte a fluxos de sincronização com sistemas externos, este conector é uma ferramenta poderosa para integrações modernas com a plataforma Artia de gerenciamento de projetos.