Integração com a API Pública de iClips

Informações importantes antes de começar

A iClips Public API está disponível exclusivamente para agências assinantes do Plano PRO. Se você está em outro plano e deseja fazer o upgrade, entre em contato com o nosso time de CS.

A integração via API não é um processo simples ou automatizado de “clique e configure”. É fundamental que a sua agência conte com um desenvolvedor de software ou profissional de TI experiente para construir e manter essa conexão. Nosso suporte técnico fornece a documentação dos endpoints, mas não realiza o desenvolvimento ou a manutenção de códigos de terceiros.

🔑 Como Gerar a sua Chave de API

Para que o seu desenvolvedor consiga conectar à nossa API, ele precisará de uma credencial de segurança. Siga o passo a passo abaixo para gerá-la:

1. No iClips, clique no seu Avatar (botão de Conta e Ajuda) localizado no canto inferior esquerdo da tela.
2. Em seguida, selecione a opção CHAVE DE API. Note que essa opção irá aparecer somente se você tiver a permissão de administrador do sistema.
3. Copie o token gerado e envie de forma segura para o seu desenvolvedor.

Nota de segurança: Trate essa chave como uma senha. Nunca a compartilhe publicamente ou em códigos front-end.

O que é possível fazer com a API?

Para ajudar a alinhar o projeto com a sua equipe, a iClips Public API divide suas permissões de forma estratégica para garantir a segurança dos seus dados:

• Módulo Financeiro (Apenas Consulta / Leitura): Por segurança, os endpoints financeiros operam apenas para extração de dados. Isso significa que seu sistema integrado poderá ler e consultar contas bancárias, lançamentos financeiros de entrada/saída e notas fiscais emitidas, mas nunca criar, alterar ou apagar movimentações financeiras por fora do iClips.
• Módulo de Projetos e Peças (Gerenciamento Completo / Leitura e Escrita): Aqui o desenvolvedor tem total liberdade para automatizar os fluxos de trabalho. É possível criar, consultar, atualizar e excluir Projetos e Peças do catálogo, além de gerenciar checklists de produção e consultar templates de workflow.
• Módulo de Extração de Dados (Apenas Consulta / Leitura): Permite extrair a hierarquia completa de dados da agência num só pedido (Projetos → Peças → Workflows → Atividades e Tarefas → Apontamentos de horas). É o recurso ideal para criar integrações de BI (Business Intelligence), exportações de dados e sincronização com ferramentas externas de relatórios.

Diretrizes da API

Antes de iniciar a programação, sua equipe de TI deve estar ciente das seguintes regras fundamentais de arquitetura da nossa API:

• URL Base de Produção: https://public-api.iclips.com.br
• Protocolo de Autenticação: Todas as requisições HTTP devem obrigatoriamente incluir o cabeçalho X-Api-Key contendo o token gerado pela agência. Requisições sem o cabeçalho ou com tokens inválidos receberão um erro HTTP 401 Unauthorized.
• Formato dos Dados: A API opera estritamente no padrão REST com envio e recebimento de dados estruturados em formato JSON.
• Obrigatoriedade de Período (Financeiro): Para os endpoints de listagem do módulo financeiro (exceto contas bancárias), os parâmetros de query string from (data inicial) e to (data final) no formato YYYY-MM-DD são obrigatórios.
• Limite de Período: Para os endpoints do módulo financeiro, a diferença entre as datas from e to não pode ser superior a 366 dias por consulta. Já para o novo endpoint de extração de projetos, a diferença entre dataInicio e dataFim não pode exceder 31 dias por consulta
• Paginação: Para garantir a performance, as listagens são paginadas.
  • No Financeiro, a paginação é feita via limit (padrão 50, máximo 200 registros) e offset (deslocamento).
  • Em Projetos e Peças, utiliza-se os parâmetros page (número da página) e pageSize (padrão de 20 itens).
  • Na Extração de Dados, utiliza-se page e pageSize, com um limite máximo de 50 itens por página.
• Limite de Taxa (Rate Limit): O módulo de Extração de Dados possui um controle rigoroso de requisições. São permitidas no máximo 10 requisições por minuto por cada API Key. Ultrapassar este volume resultará em um erro de excesso de requisições.

Catálogo de endpoints disponíveis

Abaixo está a lista completa de recursos disponíveis na versão atual da API. (Para consultar a estrutura exata do corpo das requisições e respostas, faça o download do arquivo de referência.

Módulo Financeiro

Método	Endpoint	Descrição e Regras de Negócio
GET	/api/v1/financial/accounts	Retorna todas as contas bancárias ativas da agência. Não possui filtros nem paginação.
GET	/api/v1/financial/entries	Lista os lançamentos financeiros (entradas e saídas). Permite filtrar por tipo (Entrada, Saída, A Receber, A Pagar), conta bancária, categoria, indicador DRE, destinatário/fornecedor e ID do Projeto.
GET	/api/v1/financial/entries/{id}	Retorna o detalhe completo de um lançamento financeiro específico através do seu ID único.
GET	/api/v1/financial/invoices	Lista as notas fiscais emitidas pela agência. Suporta filtros por status da nota (pending, issued, cancelled, error).
GET	/api/v1/financial/invoices/{id}	Retorna o detalhe completo de uma nota fiscal específica (incluindo valores brutos, líquidos, alíquotas de impostos retidos e dados do cliente tomador).

Módulo de Projetos

Método	Endpoint	Descrição e Regras de Negócio
POST	/api/v1/jobs	Cria um novo Job (Projeto) no iClips. Exige título, status e a definição obrigatória de um clienteId OU de um grupoClienteId (valores mutuamente exclusivos).
PUT	/api/v1/jobs/{id}	Atualiza um Projeto existente (como alteração de título, status ou atribuição de funcionários responsáveis).
DELETE	/api/v1/jobs/{id}	Remove um Projeto do iClips.
GET	/api/v1/pieces	Lista as peças do catálogo da agência, permitindo busca textual por nome (q), categoria, status ou ID do template base.
GET	/api/v1/pieces/{id}	Retorna o detalhe de uma peça específica, trazendo as estruturas de workflowJson e checklistJson.
POST	/api/v1/pieces	Cria uma nova peça no catálogo. Exige a definição de um fluxo de trabalho, que pode ser herdado de um template (basedOnTemplateId) ou customizado diretamente via workflowJson.
PUT	/api/v1/pieces/{id}	Atualiza os dados cadastrais, fluxo de trabalho e checklist de uma peça específica.
PATCH	/api/v1/pieces/{id}/checklist	Permite marcar ou desmarcar como concluído (done: true/false) um item específico dentro do checklist de produção de uma peça.
DELETE	/api/v1/pieces/{id}	Realiza a exclusão lógica (soft-delete) de uma peça do catálogo da agência.
GET	/api/v1/workflow-templates	Lista os modelos de fluxo de trabalho (templates de workflow) configurados na agência. Útil para capturar os IDs que alimentam a criação de novas peças.
GET	/api/v1/workflow-templates/{id}	Detalha um template de workflow específico, expondo sua estrutura de JSON completa.
GET	/api/v1/piece-categories	Lista as categorias de peças disponíveis para uso na agência.
GET	/api/v1/piece-categories/dropdown	Retorna a listagem de categorias em um formato simplificado, ideal para alimentar campos de seleção (dropdowns) em sistemas externos.
GET	/api/v1/projetos	Retorna a hierarquia completa de Projetos (Jobs → Peças → Workflows → Atividades e Tarefas → Atividades) para o período informado. Ideal para integrações de BI, exportações e sincronização com ferramentas externas. Filtros obrigatórios: dataInicio e dataFim (com limite máximo de 31 dias de intervalo entre eles). Filtros opcionais: idCliente (filtra pelo ID de um cliente específico) ou idGrupoCliente (filtra pelo ID de um grupo de clientes). Limite de taxa: 10 requisições por minuto por API Key. Se excedido, a API retorna um erro HTTP 429. Paginação: Utiliza os parâmetros page e pageSize (máximo de 50 itens por página).

Tabela de códigos de status e erros de negócio

Para que o desenvolvedor saiba exatamente como tratar as respostas do servidor, a nossa API utiliza os códigos HTTP padrões acompanhados de mensagens amigáveis de validação:

Código HTTP	Tipo de Erro (code)	Motivo do Erro
401 Unauthorized	—	Cabeçalho X-Api-Key ausente, inválido, malformado ou expirado.
400 Bad Request	VALIDATION_ERROR	Parâmetro obrigatório ausente (como as datas from/to), valor fora do intervalo permitido (ex: limit maior que 200) ou período de consulta maior que 366 dias.
404 Not Found	NOT_FOUND	O recurso (Projeto, Peça, Lançamento) solicitado pelo ID não existe ou não pertence à agência autenticada.
429 Too Many Requests		Limite de taxa excedido (ex: mais de 10 requisições por minuto no endpoint de extração). O cabeçalho Retry-After indicará ao desenvolvedor quantos segundos aguardar antes de realizar uma nova tentativa

Exemplos práticos de rejeição de validação (HTTP 400)

A API ajuda o programador detalhando qual campo quebrou a regra de negócio:

• from ou to com a issue missing: Esqueceram de passar as datas na listagem financeira.
• limit com a issue out_of_range: Tentativa de puxar mais de 200 registros de uma vez.
• date_range com a issue exceeded: Filtro de período superior a um ano.
• status com a issue invalid: Enviou um texto ou código que o iClips não reconhece para aquele recurso.

Escopo de suporte técnico da iClips

Para garantir o sucesso da sua integração, é importante alinhar o papel do nosso time de suporte:

• O que nós FAZEMOS: Esclarecemos dúvidas sobre as regras de negócio do iClips (ex: o que significa cada indicador DRE ou quais são os status válidos de um projeto na nossa plataforma).
• O que nós NÃO FAZEMOS: Não realizamos consultoria de arquitetura de software, correção de erros de sintaxe em códigos escritos pela sua equipe (seja em PHP, Python, JavaScript, C#, etc.), e nem criamos scripts personalizados de integração. Essa responsabilidade é inteiramente do profissional técnico contratado pela agência.

Documentação técnica completa (para desenvolvedores)

Se o seu desenvolvedor já validou as regras acima e está pronto para começar a codificar, ele precisará dos exemplos de código em cURL, estruturas completas de payloads de envio e exemplos reais das respostas em formato JSON de cada endpoint.

Disponibilizamos o portal oficial de especificação técnica da nossa API no link abaixo: