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.
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.

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: A diferença entre as datas from e to não pode ser superior a 366 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).

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.

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.

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.

Download da 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 arquivo de especificação técnica original da nossa API para download no botão abaixo: