Holdprint para LLMs

Converse com a IA usando os dados do seu ERP.

Conecte Claude, ChatGPT, Cursor, Gemini ou Copilot ao Holdprint e peça relatórios, análises e automações em português. Sem depender de um programador.

recomendado

MCP hospedado

Login por OAuth (seu e-mail e senha do Holdprint). 10 tools prontas para ler e operar o ERP com segurança. Funciona em todas as principais LLMs.

Banco read-only

Conexão MongoDB somente-leitura para casos avançados que precisam de queries diretas. Liberado sob demanda pela equipe Holdprint.

Início rápido

Dois passos: ensine a LLM a falar “Holdprint” (skills) e conecte ela aos seus dados (MCP).

Instale as skills

Um comando ensina sua LLM o domínio do ERP (orçamento, custeio, campos dinâmicos).

terminal

npx @holdprint/skills install

Conecte ao MCP

No Claude Code, um comando. No claude.ai/ChatGPT, um conector. O login abre no navegador.

terminal

claude mcp add --transport http holdprint https://mcp.holdprint.net/mcp

Pergunte

Pronto. Fale em português com a IA.

prompt

Quanto eu faturei este ano e qual meu saldo em caixa?

Instalar no Claude Code

Terminal, um comando. Ideal para quem já usa Claude Code no editor.

Adicione o servidor MCP

terminal

claude mcp add --transport http holdprint https://mcp.holdprint.net/mcp

Faça login

Na primeira chamada, o Claude abre o navegador na tela de login da Holdprint. Entre com o seu e-mail e senha do ERP — nenhum token é colado.

mcp.holdprint.net/authorize

Verifique

terminal

claude mcp list
# holdprint ✓ conectado

Instalar no claude.ai & ChatGPT

Pelo navegador, sem instalar nada. Adicione um conector personalizado apontando para o MCP.

Abra os conectores

Em claude.ai: Configurações → Conectores → Adicionar conector personalizado.

Cole o endpoint

Informe um nome e a URL do MCP. Salve.

claude.ai/settings/connectors

Adicionar conector personalizado

Conecte uma ferramenta via MCP.

Nome

Holdprint ERP

URL do servidor MCP

https://mcp.holdprint.net/mcp

Adicionar

Faça login (OAuth)

Ao conectar, abre a tela de login da Holdprint. Entre com seu e-mail e senha do ERP e autorize. O conector fica Conectado.

Use no chat

As tools holdprint_* ficam disponíveis. Pergunte em português.

Abra os conectores

No ChatGPT (planos com conectores): Settings → Connectors → Add custom / MCP server.

Cole o endpoint

Tipo http (streamable), URL abaixo. Autenticação: OAuth.

endpoint

https://mcp.holdprint.net/mcp

Faça login e use

O login da Holdprint abre automaticamente. Depois é só pedir à IA.

Endpoint a confirmar

A URL oficial de produção do MCP será confirmada na publicação. Se não responder, peça a URL atual ao suporte Holdprint.

Instalar as skills

As skills ensinam a LLM a entender o domínio do Holdprint: onde fica o custo (CostMemento), como resolver campos dinâmicos, blocos e medidas. Sem elas, a IA chuta.

Instale com um comando

Detecta os harnesses instalados (Claude Code, Codex, Cursor, Gemini CLI, Copilot) e copia as skills para cada um.

terminal

npx @holdprint/skills install

Alvos específicos & manutenção

terminal

npx @holdprint/skills install --harness=claude,codex
npx @holdprint/skills check
npx @holdprint/skills update

O que vem instalado

holdprint-mcpOperar o ERP pelo MCP (as 10 tools).

holdprint-mongoLer o ERP por conexão MongoDB read-only.

Reinicie o harness

Depois de instalar, reinicie a ferramenta (ou abra uma nova sessão) para ela carregar as skills.

Como usar

Depois de conectar, converse em português. Exemplos que funcionam de imediato:

“Quanto eu faturei em 2026 e qual meu lucro mensal?”

Usa os relatórios de dashboard (faturamento, lucro, margem).

“Qual meu saldo total em caixa e bancos?”

Soma as contas financeiras, separando ativas.

“Liste meus 10 orçamentos abertos de maior valor.”

Filtra por status e ordena — sem você montar query.

“Quantas notas emiti no mês e qual o total?”

Conta e soma as NFes do período.

Tools do MCP

10 tools genéricas — a LLM as compõe para qualquer pergunta. Você não precisa decorá-las; esta referência é para conferência.

Fluxo canônico

Não chute nomes de entidade ou campo. Sempre: discover → describe → query / count / aggregate. Para valores em R$ que somam sub-documentos, use report. Para escrever, discover_actions → action (dry-run primeiro).

holdprint_discoverleitura

Resolve um termo em português para a entidade canônica, ou lista todas.

term?termo livre pt-BR ou nome técnico. Vazio = lista tudo.

holdprint_describeleitura

Retorna os campos exatos (nome, tipo, enum e valores) de uma entidade. Use antes de filtrar.

collectionentidade ou termo pt-BR.

holdprint_queryleitura

Lê registros com filtro, ordenação e paginação. Traz só deleted:false por padrão.

collectionentidade.

where?igualdade {campo: valor} ou operadores {campo: {gte: x}}: eq, ne, contains, notContains, lt, lte, gt, gte, in.

fields?campos a retornar.

sort?'-campo' (desc), 'campo' (asc), ['-a','b'] ou {campo:-1}.

limit?1–500 (default 50).

skip?paginação.

search?busca textual livre.

exemplo

holdprint_query({
  collection: "Budget",
  where: { state: "Won" },
  sort: "-total_price", limit: 10
})

holdprint_countleitura

Conta registros no servidor sem trazer a lista. Exato.

collection, where?mesma sintaxe do query.

holdprint_aggregateleitura

sum / avg / min / max / count de um campo numérico, com agrupamento opcional. Some/avg varrem o conjunto inteiro (exato).

opcount | sum | avg | min | max.

field?campo numérico (obrigatório p/ sum/avg/min/max). Aceita dot-notation: bankAccount.amount.

groupBy?campo para agrupar (ex.: status, vendedor).

exemplo

holdprint_aggregate({
  collection: "Budget", op: "count",
  where: { state: "Won" }, groupBy: "sellerName"
})

holdprint_getleitura

Busca um registro por id.

collection, id—

holdprint_reportleitura · R$

Relatórios de dashboard que somam sub-documentos (o que o aggregate genérico não alcança).

reportvendas_total · nfe_faturamento_valor · nfe_faturamento_qtd · jobs_atrasados · jobs_finalizados · jobs_a_entregar · lucro_mensal · margem_contribuicao · custo_fixo · saldo_contas.

startDate, endDateYYYY-MM-DD (saldo_contas dispensa datas).

holdprint_discover_actionsação

Descobre ações não-CRUD (ganhar orçamento, emitir NFe, liquidar despesa…) e seus parâmetros.

queryintenção pt-BR ou nome (ex.: "ganhar orçamento").

holdprint_actionescrita

Executa uma ação. Roda em prévia (dry-run) por padrão — nada é gravado sem confirmação.

actionNamede discover_actions.

args?path params + corpo.

dryRun?default true. false para efetivar.

confirmed?true para ações destrutivas.

holdprint_examplesleitura

Retorna jornadas comuns com os args já modelados — use antes de montar do zero.

Escrever exige confirmação

Ações que alteram dados rodam primeiro em prévia (dry-run). Nada é gravado sem você confirmar.

Skills & domínio do Holdprint

As skills (holdprint-mcp e holdprint-mongo) ensinam a LLM as regras do domínio que ela erraria sozinha. O essencial:

O custo do orçamento NÃO está no Budget

O preço/custo vive em CostMemento (versionado — use a maior version). Join: Budget.code == CostMemento.public_identification (inteiro, não ObjectId); ou Budget.winner_propose_id → Propose.calc_id → CostMemento._id. Quantidade em CostMementoItem.quantity.

Campos dinâmicos & medidas

Campos dinâmicos ficam em fields_values com chaves "hold"+ObjectId → resolva pela collection Fields (remove "hold", casa o _id, lê o name_key: WIDTH/LARGURA, HEIGHT/ALTURA…). O valor é polimórfico, discriminado por class_name (a classe .NET, não _t). Feedstock.fields_values é array; em Product/Process/Equipment é objeto.

Enums e exclusão

No Mongo cru, enums são inteiros (Budget.state: 1=Open, 2=Lost, 3=Won) — o MCP aceita string e converte. Exclusão é lógica: filtre sempre deleted:false. Product/Entity têm active; Budget/Process/Equipment não.

Pelo MCP, você não lida com isso

A skill holdprint-mcp + as tools já cuidam de enums, soft-delete e nomes. O detalhe acima importa para quem usa o banco read-only (skill holdprint-mongo).

Banco read-only (avançado)

Para quem precisa de queries diretas no MongoDB. A connection string é liberada manualmente pela equipe — não é gerada sozinha.

Solicite o acesso

Fale com o suporte Holdprint para receber uma string de conexão somente-leitura ao seu banco de produção.

Use a skill holdprint-mongo

Ela ensina a LLM a navegar o schema (orçamento ↔ custeio, campos dinâmicos, blocos) e a montar queries corretas.

Regras de ouro

É somente leitura — nunca escreva. Filtre sempre deleted: false (a exclusão é lógica). Nunca compartilhe a string: ela dá acesso aos seus dados.

API REST

API REST do Holdprint

Integração direta via HTTP, autenticada por API Key. Para conectar uma LLM, prefira o MCP (acima). A API REST é para integrações de sistema.

basehttps://api.holdworks.ai

Todas as requisições usam a URL base acima e exigem o header x-api-key. Respostas em JSON, padrão REST.

header

x-api-key: sua_api_key_aqui

Onde pegar seu token

Acesse Ajustes

No menu lateral do app Holdprint, clique em Ajustes.

Abra API/MCP

Dentro de Ajustes, clique em API/MCP.

Copie o token

Na aba Chave de API, clique em Copiar (ou Gerar novo token para criar um novo).

app.holdprint.net/holdprint/settings/api-ai

holdprint

Cadastros

Financeiro

Produção

Ajustes

Ajustes / API/MCP

Chave de APIInstalar skillsConectar MCP

Seu token pessoal de API

••••••••••••••••••••••••

Copiar

Gerar novo token

Mantenha sua API Key segura

Nunca exponha a chave em código cliente ou repositórios públicos. Use variáveis de ambiente. Para LLMs, prefira o MCP (login OAuth, sem colar token).

Formato de resposta

json

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": { "page": 1, "limit": 50, "total": 100, "pages": 2 }
  },
  "message": "Success"
}

Códigos de status

Código	Significado
200	OK — requisição bem-sucedida
400	Bad Request — parâmetros inválidos
401	Unauthorized — API Key inválida ou ausente
404	Not Found — recurso não encontrado
500	Internal Server Error

Rate limiting

100 requisições por minuto por API Key. Header de resposta X-RateLimit-Remaining; reset a cada minuto. Implemente retry com backoff exponencial.

Clientes

Consulta, criação e atualização do cadastro de clientes na plataforma Holdprint, com suporte a endereços múltiplos, contatos, limite de crédito e campos fiscais específicos por país.

GET/api-key/customers/data

Consulta dados de clientes cadastrados na plataforma de forma paginada, com suporte a busca por nome, e-mail ou documento. Os dados retornados incluem informações completas de contato, endereço e status do cliente, facilitando integrações com CRM e sistemas de gestão. Se nenhum parâmetro for informado, o endpoint retorna todos os clientes ativos cadastrados.

Autenticação via API Key no header x-api-key.

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
page	int	opcional	Número da página para paginação (padrão: 1)
limit	int	opcional	Quantidade de registros por página (padrão: 50 • máximo: 100)
search	string	opcional	Busca por nome, e-mail ou documento do cliente (exemplo: Empresa Exemplo)
active	boolean	opcional	Filtrar apenas clientes ativos (true/false) (padrão: true)
translate	boolean	opcional	Traduzir nomes de campos (true/false) (padrão: false)

bash

curl -X GET "https://api.holdworks.ai/api-key/customers/data?page=1&limit=50&search=Empresa" \
  -H "x-api-key: sua_api_key_aqui"

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 789,
        "name": "Empresa Exemplo LTDA",
        "email": "contato@exemplo.com",
        "phone": "+55 11 98765-4321",
        "document": "12.345.678/0001-99",
        "address": {
          "street": "Rua Exemplo, 123",
          "complement": "Sala 501",
          "neighborhood": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "zip_code": "01234-567",
          "country": "Brasil"
        },
        "contact_person": "João Silva",
        "active": true,
        "notes": "Cliente preferencial com desconto especial",
        "created_at": "2024-01-10T10:00:00Z",
        "updated_at": "2025-01-15T14:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 145,
      "pages": 3
    }
  },
  "message": "Success"
}

Estrutura de Dados

Campo	Tipo	Descrição
id	number	Identificador único do cliente
name	string	Nome ou razão social do cliente
email	string	E-mail de contato
phone	string	Telefone de contato
document	string	CPF ou CNPJ do cliente
address	object	Endereço completo do cliente
contact_person	string	Nome da pessoa de contato
active	boolean	Indica se o cliente está ativo
notes	string \| null	Observações sobre o cliente
created_at	string	Data de cadastro (ISO 8601)
updated_at	string	Data da última atualização (ISO 8601)

Dica

Use o parâmetro search para criar funcionalidades de autocomplete ou busca rápida de clientes no seu sistema.

Objeto Address

Campo	Tipo	Descrição
street	string	Logradouro e número
complement	string	Complemento (opcional)
neighborhood	string	Bairro
city	string	Cidade
state	string	Estado (sigla)
zip_code	string	CEP
country	string	País

Boas Práticas

Use paginação para grandes volumes de dados
Implemente cache local para reduzir requisições
Utilize o filtro active=true para exibir apenas clientes ativos
Normalize documentos antes de buscar (remover pontos e traços)

POST/api-key/customers

Cria um novo cliente na plataforma via API Key. Você pode cadastrar informações completas incluindo endereços múltiplos, contatos, limite de crédito e campos específicos por país. O sistema gera automaticamente o ID do cliente e registra as datas de criação. Apenas o campo Name é obrigatório; todos os demais são opcionais.

Autenticação via API Key no header x-api-key e Content-Type: application/json.

Request Body

Campo	Tipo	Obrigatório	Descrição
Name	string	Sim	Nome ou razão social do cliente
FullName	string	Não	Nome completo/razão social completa (padrão: Name)
MainEmail	string	Não	E-mail principal de contato
MainPhoneNumber	string	Não	Telefone principal de contato
Site	string	Não	Website do cliente
Addresses	array	Não	Lista de endereços do cliente
Contacts	array	Não	Lista de contatos do cliente
CustomerDetails	object	Não	Detalhes de crédito do cliente
SpecificFields	object	Não	Campos específicos por país

Estrutura de Addresses

O campo Addresses aceita um array de objetos de endereço. Existem dois tipos de endereço. Endereço Genérico:

Campo	Tipo	Descrição
Description	string	Descrição do endereço (ex: "Sede", "Filial")
Country	string	País
AddressLine1	string	Logradouro e número
AddressLine2	string	Complemento
Locality	string	Cidade
AdministrativeAreaL1	string	Estado/Província
AdministrativeAreaL2	string	Bairro/Distrito
PostalCode	string	Código postal/CEP
Number	string	Número do endereço
Type	string	Tipo: "Generic" ou "BR"

Endereço Brasil (BR): para endereços no Brasil, use Type: "BR" e inclua campos adicionais:

Campo Adicional	Tipo	Descrição
AddressLine3	string	Linha adicional de endereço
IbgeLocalityCode	int	Código IBGE da cidade
IbgeStateCode	int	Código IBGE do estado
IbgeCountryCode	int	Código IBGE do país (1058 para Brasil)

Estrutura de Contacts

O campo Contacts aceita um array de objetos de contato:

Campo	Tipo	Descrição
Name	string	Nome do contato
Role	string	Cargo/função do contato
Phone	string	Telefone do contato
Email	string	E-mail do contato
BirthDate	string	Data de nascimento (ISO 8601)
ContactType	string	Tipo: "Customer", "Supplier", "Commercial", "Financial", "Other"

Estrutura de CustomerDetails

O campo CustomerDetails contém informações sobre limite de crédito:

Campo	Tipo	Descrição
SalesCreditLimit	decimal	Limite de crédito para vendas (padrão: 0)
SalesCreditLimitExpirationDate	string	Data de expiração do limite (ISO 8601)

Campos Específicos por País

O campo SpecificFields contém informações específicas de cada país. Campos disponíveis:

País	Campos Disponíveis
Brasil (BR)	CNPJ (string) - CNPJ da empresa; CPF (string) - CPF do cliente; InscricaoEstadual (string) - Inscrição estadual; InscricaoMunicipal (string) - Inscrição municipal; RegimeTributario (string) - Regime tributário
Argentina (AR)	CUIT (string) - CUIT da empresa; CUIL (string) - CUIL da pessoa; IngresosBrutos (string) - Ingresos brutos
Portugal (PT)	NIF (string) - Número de Identificação Fiscal; NIPC (string) - Número de Identificação de Pessoa Coletiva
Chile (CL)	RUT (string) - Rol Único Tributario
Colômbia (CO)	NIT (string) - Número de Identificación Tributaria
Estados Unidos (US)	EIN (string) - Employer Identification Number; SSN (string) - Social Security Number
Paraguai (PY)	RUC (string) - Registro Único de Contribuyentes
Reino Unido (GB)	VATNumber (string) - VAT Registration Number; CompanyNumber (string) - Company Registration Number
Uruguai (UY)	RUT (string) - Registro Único Tributario

Dica

Você precisa especificar o tipo de campo no objeto. Por exemplo, para Brasil use "SpecificFields": {"BR": {"CNPJ": "12.345.678/0001-99"}}

Exemplo de Requisição - Básico (apenas campos obrigatórios):

bash

curl -X POST "https://api.holdworks.ai/api-key/customers" \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Empresa Exemplo LTDA"
  }'

Exemplo de Requisição - Completo (todos os campos opcionais):

bash

curl -X POST "https://api.holdworks.ai/api-key/customers" \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Empresa Exemplo LTDA",
    "FullName": "Empresa Exemplo Comércio e Serviços LTDA",
    "MainEmail": "contato@exemplo.com",
    "MainPhoneNumber": "+55 11 98765-4321",
    "Site": "https://www.exemplo.com",
    "Addresses": [
      {
        "Type": "BR",
        "Description": "Sede",
        "Country": "Brasil",
        "AddressLine1": "Rua Exemplo",
        "AddressLine2": "Sala 501",
        "AddressLine3": "",
        "Locality": "São Paulo",
        "AdministrativeAreaL1": "SP",
        "AdministrativeAreaL2": "Centro",
        "PostalCode": "01234-567",
        "Number": "123",
        "IbgeLocalityCode": 3550308,
        "IbgeStateCode": 35,
        "IbgeCountryCode": 1058
      }
    ],
    "Contacts": [
      {
        "Name": "João Silva",
        "Role": "Gerente Comercial",
        "Phone": "+55 11 91234-5678",
        "Email": "joao.silva@exemplo.com",
        "BirthDate": "1985-03-15T00:00:00Z",
        "ContactType": "Commercial"
      }
    ],
    "CustomerDetails": {
      "SalesCreditLimit": 50000.00,
      "SalesCreditLimitExpirationDate": "2025-12-31T23:59:59Z"
    },
    "SpecificFields": {
      "BR": {
        "CNPJ": "12.345.678/0001-99",
        "InscricaoEstadual": "123.456.789.012",
        "InscricaoMunicipal": "98765432",
        "RegimeTributario": "Simples Nacional"
      }
    }
  }'

Exemplo de Resposta:

json

{
  "Id": "507f1f77bcf86cd799439011",
  "Name": "Empresa Exemplo LTDA",
  "FullName": "Empresa Exemplo Comércio e Serviços LTDA",
  "MainEmail": "contato@exemplo.com",
  "MainPhoneNumber": "+55 11 98765-4321",
  "Site": "https://www.exemplo.com",
  "EntityType": "Customer",
  "Active": true,
  "CreationTime": "2025-01-15T10:30:00Z",
  "LastUpdateTime": "2025-01-15T10:30:00Z",
  "Addresses": [
    {
      "Type": "BR",
      "Description": "Sede",
      "Country": "Brasil",
      "AddressLine1": "Rua Exemplo",
      "AddressLine2": "Sala 501",
      "AddressLine3": "",
      "Locality": "São Paulo",
      "AdministrativeAreaL1": "SP",
      "AdministrativeAreaL2": "Centro",
      "PostalCode": "01234-567",
      "Number": "123",
      "IbgeLocalityCode": 3550308,
      "IbgeStateCode": 35,
      "IbgeCountryCode": 1058
    }
  ],
  "Contacts": [
    {
      "Id": 1,
      "Name": "João Silva",
      "Role": "Gerente Comercial",
      "Phone": "+55 11 91234-5678",
      "Email": "joao.silva@exemplo.com",
      "BirthDate": "1985-03-15T00:00:00Z",
      "ContactType": "Commercial"
    }
  ],
  "CustomerDetails": {
    "SalesCreditLimit": 50000.00,
    "AvaibleSalesCreditLimit": 50000.00,
    "SalesCreditLimitExpirationDate": "2025-12-31T23:59:59Z"
  },
  "SpecificFields": {
    "BR": {
      "CNPJ": "12.345.678/0001-99",
      "InscricaoEstadual": "123.456.789.012",
      "InscricaoMunicipal": "98765432",
      "RegimeTributario": "Simples Nacional"
    }
  }
}

Dica

A resposta inclui campos gerados pelo sistema como Id, EntityType, Active, CreationTime e LastUpdateTime. O campo AvaibleSalesCreditLimit é inicializado com o mesmo valor de SalesCreditLimit.

Boas Práticas

Sempre valide e-mails e telefones antes de enviar
Use o campo FullName para armazenar razão social completa
Para endereços BR, sempre forneça os códigos IBGE quando possível
Inclua múltiplos contatos com tipos específicos (Commercial, Financial, etc.)
Defina limites de crédito com datas de expiração apropriadas
Use os campos específicos do país para compliance fiscal

Códigos de Status

Código	Descrição
200	Cliente criado com sucesso
400	Dados inválidos (campo obrigatório ausente ou formato incorreto)
401	API Key inválida ou ausente
500	Erro interno do servidor

PUT/api-key/customers/{id}

Atualiza um cliente existente na plataforma via API Key. Você pode modificar todas as informações do cliente, incluindo endereços, contatos, limite de crédito e status de ativação. O sistema atualiza automaticamente o campo LastUpdateTime. Diferença do POST: este endpoint inclui o campo Active (boolean, obrigatório) que permite ativar ou desativar o cliente — esse campo não está disponível no endpoint de criação.

Autenticação via API Key no header x-api-key e Content-Type: application/json.

Parâmetros de URL

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID do cliente a ser atualizado (MongoDB ObjectId). Exemplo: 507f1f77bcf86cd799439011

Dica

O sistema valida se o cliente pertence à conta associada à API Key. Se o ID não existir ou não pertencer à sua conta, será retornado erro 404.

Request Body

O corpo da requisição é similar ao POST, mas inclui o campo Active:

Campo	Tipo	Obrigatório	Descrição
Name	string	Sim	Nome ou razão social do cliente
Active	boolean	Sim	NOVO: Status do cliente (true = ativo, false = inativo)
FullName	string	Não	Nome completo/razão social completa (padrão: Name)
MainEmail	string	Não	E-mail principal de contato
MainPhoneNumber	string	Não	Telefone principal de contato
Site	string	Não	Website do cliente
Addresses	array	Não	Lista de endereços do cliente
Contacts	array	Não	Lista de contatos do cliente
CustomerDetails	object	Não	Detalhes de crédito do cliente
SpecificFields	object	Não	Campos específicos por país

Dica

Os campos Addresses, Contacts, CustomerDetails e SpecificFields seguem a mesma estrutura documentada na seção de Criação acima. Consulte aquela seção para detalhes completos.

Exemplo de Requisição - Básico (atualizando nome e status):

bash

curl -X PUT "https://api.holdworks.ai/api-key/customers/507f1f77bcf86cd799439011" \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Empresa Exemplo LTDA - Atualizada",
    "Active": true
  }'

Exemplo de Requisição - Desativar Cliente:

bash

curl -X PUT "https://api.holdworks.ai/api-key/customers/507f1f77bcf86cd799439011" \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Empresa Exemplo LTDA",
    "Active": false
  }'

Exemplo de Requisição - Completo (atualizando todos os dados):

bash

curl -X PUT "https://api.holdworks.ai/api-key/customers/507f1f77bcf86cd799439011" \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Empresa Exemplo LTDA - Atualizada",
    "FullName": "Empresa Exemplo Comércio e Serviços LTDA - Atualizada",
    "Active": true,
    "MainEmail": "novo-contato@exemplo.com",
    "MainPhoneNumber": "+55 11 99999-9999",
    "Site": "https://www.exemplo-novo.com",
    "Addresses": [
      {
        "Type": "BR",
        "Description": "Sede - Novo Endereço",
        "Country": "Brasil",
        "AddressLine1": "Av. Paulista",
        "AddressLine2": "10º andar",
        "AddressLine3": "",
        "Locality": "São Paulo",
        "AdministrativeAreaL1": "SP",
        "AdministrativeAreaL2": "Bela Vista",
        "PostalCode": "01310-100",
        "Number": "1000",
        "IbgeLocalityCode": 3550308,
        "IbgeStateCode": 35,
        "IbgeCountryCode": 1058
      }
    ],
    "Contacts": [
      {
        "Name": "Maria Santos",
        "Role": "Diretora Comercial",
        "Phone": "+55 11 98888-8888",
        "Email": "maria.santos@exemplo.com",
        "BirthDate": "1980-05-20T00:00:00Z",
        "ContactType": "Commercial"
      }
    ],
    "CustomerDetails": {
      "SalesCreditLimit": 100000.00,
      "SalesCreditLimitExpirationDate": "2026-12-31T23:59:59Z"
    },
    "SpecificFields": {
      "BR": {
        "CNPJ": "12.345.678/0001-99",
        "InscricaoEstadual": "999.888.777.666",
        "InscricaoMunicipal": "11223344",
        "RegimeTributario": "Lucro Real"
      }
    }
  }'

Exemplo de Resposta:

json

{
  "Id": "507f1f77bcf86cd799439011",
  "Name": "Empresa Exemplo LTDA - Atualizada",
  "FullName": "Empresa Exemplo Comércio e Serviços LTDA - Atualizada",
  "MainEmail": "novo-contato@exemplo.com",
  "MainPhoneNumber": "+55 11 99999-9999",
  "Site": "https://www.exemplo-novo.com",
  "EntityType": "Customer",
  "Active": true,
  "CreationTime": "2025-01-15T10:30:00Z",
  "LastUpdateTime": "2025-01-28T14:45:00Z",
  "Addresses": [
    {
      "Type": "BR",
      "Description": "Sede - Novo Endereço",
      "Country": "Brasil",
      "AddressLine1": "Av. Paulista",
      "AddressLine2": "10º andar",
      "AddressLine3": "",
      "Locality": "São Paulo",
      "AdministrativeAreaL1": "SP",
      "AdministrativeAreaL2": "Bela Vista",
      "PostalCode": "01310-100",
      "Number": "1000",
      "IbgeLocalityCode": 3550308,
      "IbgeStateCode": 35,
      "IbgeCountryCode": 1058
    }
  ],
  "Contacts": [
    {
      "Id": 1,
      "Name": "Maria Santos",
      "Role": "Diretora Comercial",
      "Phone": "+55 11 98888-8888",
      "Email": "maria.santos@exemplo.com",
      "BirthDate": "1980-05-20T00:00:00Z",
      "ContactType": "Commercial"
    }
  ],
  "CustomerDetails": {
    "SalesCreditLimit": 100000.00,
    "AvaibleSalesCreditLimit": 100000.00,
    "SalesCreditLimitExpirationDate": "2026-12-31T23:59:59Z"
  },
  "SpecificFields": {
    "BR": {
      "CNPJ": "12.345.678/0001-99",
      "InscricaoEstadual": "999.888.777.666",
      "InscricaoMunicipal": "11223344",
      "RegimeTributario": "Lucro Real"
    }
  }
}

Dica

Note que o campo LastUpdateTime é atualizado automaticamente pelo sistema para refletir o horário da última modificação.

Boas Práticas

Sempre valide o ID do cliente antes de enviar a requisição
Use Active: false em vez de deletar clientes permanentemente
Atualize o limite de crédito com data de expiração apropriada
Ao atualizar endereços e contatos, envie a lista completa desejada
Mantenha histórico das alterações no seu sistema
Implemente retry logic para falhas temporárias de rede

Códigos de Status

Código	Descrição
200	Cliente atualizado com sucesso
400	Dados inválidos (campo obrigatório ausente ou formato incorreto)
401	API Key inválida ou ausente
404	Cliente não encontrado ou não pertence à sua conta
500	Erro interno do servidor

Fornecedores

Consulta o cadastro de fornecedores de forma paginada, com busca por nome, e-mail ou documento, filtro por categoria e dados completos de contato, endereço e condições de pagamento.

GET/api-key/suppliers/data

Consulta dados de fornecedores cadastrados na plataforma. Este endpoint permite consultar o cadastro de fornecedores de forma paginada, com suporte a busca por nome, e-mail ou documento, e filtro por categoria. Os dados retornados incluem informações completas de contato, endereço, categoria e condições de pagamento, facilitando integrações com sistemas de compras e controle de estoque. Se nenhum parâmetro for informado, o endpoint retorna todos os fornecedores ativos cadastrados.

Autenticação via API Key no header x-api-key. Base da API: https://api.holdworks.ai.

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
page	int	opcional	Número da página para paginação (padrão: 1)
limit	int	opcional	Quantidade de registros por página (padrão: 50 • máximo: 100)
search	string	opcional	Busca por nome, e-mail ou documento do fornecedor (exemplo: Fornecedor XYZ)
category	string	opcional	Filtrar por categoria de fornecedor (exemplo: paper_supplies)
active	boolean	opcional	Filtrar apenas fornecedores ativos (true/false) (padrão: true)
translate	boolean	opcional	Traduzir nomes de campos (true/false) (padrão: false)

bash

curl -X GET "https://api.holdworks.ai/api-key/suppliers/data?page=1&limit=50&category=paper_supplies" \
  -H "x-api-key: sua_api_key_aqui"

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 55,
        "name": "Fornecedor XYZ",
        "email": "vendas@fornecedor.com",
        "phone": "+55 11 91234-5678",
        "document": "98.765.432/0001-11",
        "category": "paper_supplies",
        "address": {
          "street": "Rua Industrial, 500",
          "complement": "Galpão 3",
          "neighborhood": "Distrito Industrial",
          "city": "São Paulo",
          "state": "SP",
          "zip_code": "03456-789",
          "country": "Brasil"
        },
        "contact_person": "Carlos Almeida",
        "payment_terms": "30/60 dias",
        "active": true,
        "notes": "Fornecedor principal de papel offset",
        "created_at": "2023-08-10T10:00:00Z",
        "updated_at": "2025-01-05T09:30:00Z"
      },
      {
        "id": 56,
        "name": "Tintas Premium LTDA",
        "email": "comercial@tintaspremium.com",
        "phone": "+55 11 98765-4321",
        "document": "12.345.678/0001-22",
        "category": "ink_supplies",
        "address": {
          "street": "Av. das Tintas, 200",
          "complement": null,
          "neighborhood": "Zona Norte",
          "city": "São Paulo",
          "state": "SP",
          "zip_code": "02123-456",
          "country": "Brasil"
        },
        "contact_person": "Ana Paula",
        "payment_terms": "À vista com desconto",
        "active": true,
        "notes": null,
        "created_at": "2024-02-15T14:00:00Z",
        "updated_at": "2024-12-20T10:15:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 78,
      "pages": 2
    }
  },
  "message": "Success"
}

Categorias de Fornecedores

Campo	Tipo	Descrição
paper_supplies	string	Fornecedores de papel e substratos
ink_supplies	string	Fornecedores de tintas e consumíveis
equipment	string	Fornecedores de equipamentos e maquinário
services	string	Fornecedores de serviços terceirizados
other	string	Outros fornecedores

Dica

Filtre fornecedores por categoria para encontrar rapidamente parceiros específicos para cada tipo de insumo ou serviço necessário na produção.

Estrutura de Dados

Campo	Tipo	Descrição
id	number	Identificador único do fornecedor
name	string	Nome ou razão social do fornecedor
email	string	E-mail de contato
phone	string	Telefone de contato
document	string	CNPJ do fornecedor
category	string	Categoria do fornecedor
address	object	Endereço completo do fornecedor
contact_person	string	Nome da pessoa de contato
payment_terms	string	Condições de pagamento acordadas
active	boolean	Indica se o fornecedor está ativo
notes	string \| null	Observações sobre o fornecedor
created_at	string	Data de cadastro (ISO 8601)
updated_at	string	Data da última atualização (ISO 8601)

Objeto Address

Campo	Tipo	Descrição
street	string	Logradouro e número
complement	string	Complemento (opcional)
neighborhood	string	Bairro
city	string	Cidade
state	string	Estado (sigla)
zip_code	string	CEP
country	string	País

Boas Práticas

Use paginação para grandes volumes de dados
Implemente cache local para reduzir requisições
Utilize filtros por categoria para encontrar fornecedores específicos
Mantenha as condições de pagamento atualizadas (payment_terms)

Orçamentos

Consulta paginada de orçamentos com propostas, itens, produtos e checklists — ideal para integração, análises e relatórios.

GET/api-key/budgets/data

Consulta dados detalhados de orçamentos de forma paginada, incluindo informações sobre propostas, itens, produtos e checklists. Suporta paginação, filtros por data e tradução de campos, retornando dados em formato estruturado para integração com sistemas externos.

Este endpoint requer autenticação via API Key no header x-api-key:

http

GET /api-key/budgets/data HTTP/1.1
Host: api.holdworks.ai
x-api-key: sua_api_key_aqui

Parâmetros de Consulta

Todos os parâmetros são opcionais e enviados via query string na URL.

Campo	Tipo	Obrigatório	Descrição
page	integer	opcional	Número da página a ser retornada, mínimo: 1 (padrão: 1)
pageSize	integer	opcional	Quantidade de registros por página, mínimo: 1, máximo: 100 (padrão: 20)
startDate	datetime	opcional	Data inicial para filtrar orçamentos, formato ISO 8601 (padrão: null)
endDate	datetime	opcional	Data final para filtrar orçamentos, formato ISO 8601 (padrão: null)
language	string	opcional	Código do idioma para tradução de campos (padrão: "pt-BR")

Filtro de Datas

Se nenhuma data for informada, retorna todos os orçamentos. O filtro é aplicado sobre o campo CreationDate dos orçamentos.

Estrutura da Resposta — PagedResult<BudgetDataModel>

json

{
  "data": [ /* Array de BudgetDataModel */ ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Estrutura de Dados — BudgetDataModel

Cada item no array data representa um orçamento:

Campo	Tipo	Descrição
code	integer	Código único do orçamento
title	string	Título/descrição do orçamento
customerName	string	Nome do cliente associado ao orçamento
budgetState	integer	Estado atual do orçamento (1=Open, 2=Lost, 3=Won)
creationDate	datetime	Data e hora de criação do orçamento
deliveryNeed	datetime?	Data necessária para entrega (pode ser null)
wonDate	datetime?	Data em que o orçamento foi ganho (pode ser null)
lostDate	datetime?	Data em que o orçamento foi perdido (pode ser null)
proposes	array	Lista de propostas deste orçamento

Estrutura de Dados — ProposeDataModel

Campo	Tipo	Descrição
paymentOption	string	Forma de pagamento desta proposta
totalPrice	decimal	Preço total da proposta
totalProfitPercentual	decimal	Percentual de lucro total sobre a proposta
productionCost	decimal	Custo total de produção
sellingCost	decimal	Custo total de venda
proposeItems	array	Lista de itens desta proposta

Estrutura de Dados — ProposeItemDataModel

Campo	Tipo	Descrição
itemName	string	Nome do item
quantity	double	Quantidade do item
unitSymbol	string	Símbolo da unidade de medida
unitPrice	double	Preço unitário
totalPrice	decimal	Preço total do item
totalProfit	decimal	Lucro total do item
profitPercentual	decimal	Percentual de lucro sobre o item
productionCost	decimal	Custo de produção do item
sellingCost	decimal	Custo de venda do item
products	array	Lista de produtos que compõem este item

Estrutura de Dados — BudgetProductDataModel

Cada produto é um objeto dinâmico (dicionário) com propriedades fixas e campos customizáveis:

Estrutura Dinâmica

Além das propriedades fixas documentadas, o produto pode conter campos customizáveis adicionais (ex: "Material", "Acabamento", "Cores") que variam conforme a configuração da sua conta.

Campo	Tipo	Descrição
Name	string	Nome do produto
Description	string	Descrição do produto
Quantity	decimal	Quantidade de produção
SaleQuantity	decimal	Quantidade de venda
UnitPrice	decimal	Preço unitário
TotalValue	decimal	Valor total
ProductionCost	decimal	Custo de produção
SellingCost	decimal	Custo de venda
Checklists	array	Lista de checklists respondidos

Exemplos de Uso

Exemplo 1: Requisição básica.

bash

curl -X GET "https://holdprintwebapi-prod.azurewebsites.net/api-key/budgets/data?page=1&pageSize=20" \
  -H "x-api-key: sua_api_key_aqui"

Exemplo 2: Com filtro de data.

bash

curl -X GET "https://holdprintwebapi-prod.azurewebsites.net/api-key/budgets/data?page=1&pageSize=10&startDate=2025-10-01&endDate=2025-10-31&language=pt-BR" \
  -H "x-api-key: sua_api_key_aqui"

Exemplo de Resposta

json

{
  "data": [
    {
      "code": 12345,
      "title": "Impressão de Folhetos Promocionais",
      "customerName": "Empresa XYZ Ltda",
      "budgetState": 1,
      "creationDate": "2025-10-15T14:30:00Z",
      "deliveryNeed": "2025-10-25T10:00:00Z",
      "wonDate": null,
      "lostDate": null,
      "proposes": [
        {
          "paymentOption": "À Vista",
          "totalPrice": 1500.00,
          "totalProfitPercentual": 35.50,
          "productionCost": 967.50,
          "sellingCost": 532.50,
          "proposeItems": [
            {
              "itemName": "Folheto A4 - 4x4 cores",
              "quantity": 5000.0,
              "unitSymbol": "un",
              "unitPrice": 0.30,
              "totalPrice": 1500.00,
              "totalProfit": 532.50,
              "profitPercentual": 35.50,
              "productionCost": 967.50,
              "sellingCost": 532.50,
              "products": [
                {
                  "Name": "Impressão Digital",
                  "Description": "Impressão em papel couché 170g",
                  "Quantity": 5000,
                  "SaleQuantity": 5000,
                  "UnitPrice": 0.15,
                  "TotalValue": 750.00,
                  "ProductionCost": 500.00,
                  "SellingCost": 250.00,
                  "Checklists": [
                    {
                      "question": "Qual tipo de papel?",
                      "answer": "Papel Couché 170g"
                    }
                  ],
                  "Material": [
                    {
                      "fieldName": "Material",
                      "value": "Papel Couché 170g"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8,
  "hasNextPage": true,
  "hasPreviousPage": false
}

Códigos de Status

Campo	Tipo	Descrição
200 OK	—	Requisição bem-sucedida, retorna os dados
401 Unauthorized	—	API Key inválida ou ausente
400 Bad Request	—	Parâmetros inválidos (ex: formato de data incorreto)
500 Internal Server Error	—	Erro interno no servidor

Boas Práticas

Sempre verifique hasNextPage antes de solicitar a próxima página
Use totalPages para implementar navegação direta por número de página
Limite o pageSize conforme necessário para otimizar performance
Cache os resultados quando apropriado para reduzir chamadas à API
Use filtros de data para reduzir o conjunto de dados retornado

Dica de Performance

Para grandes volumes de dados, recomenda-se usar pageSize entre 20 e 50 e sempre aplicar filtros de data quando possível.

Jobs · Produção

Consulta de jobs (trabalhos/pedidos) com custos em 4 fases (orçado, aprovado, planejado, realizado) e dados completos de produção: progresso, tasks e insumos consumidos.

GET/api-key/jobs/data

Consulta dados detalhados de jobs com paginação, filtros por data e tradução de campos. Retorna custos em diferentes fases e informações de produção (status, progresso, tasks, feedstocks). Autenticação via API Key no header x-api-key.

Filtro padrão

Sem datas, retorna apenas jobs do mês corrente. Para jobs históricos, informe startDate e endDate explicitamente.

Parâmetros de Consulta

Campo	Tipo	Padrão	Descrição
page	integer	1	Número da página (mínimo: 1)
pageSize	integer	20	Registros por página (mínimo: 1, máximo: 100)
startDate	datetime	1º dia do mês	Data inicial do filtro (ISO 8601)
endDate	datetime	último dia do mês	Data final do filtro (ISO 8601)
language	string	"pt-BR"	Idioma para tradução de campos

Exemplos

bash · mês atual

curl -X GET "https://api.holdworks.ai/api-key/jobs/data?page=1&pageSize=20" \
  -H "x-api-key: sua_api_key_aqui"

bash · todos (sem filtro de data)

curl -X GET "https://api.holdworks.ai/api-key/jobs/data?page=1&pageSize=100&startDate=2000-01-01&endDate=2099-12-31" \
  -H "x-api-key: sua_api_key_aqui"

bash · período específico

curl -X GET "https://api.holdworks.ai/api-key/jobs/data?page=1&pageSize=10&startDate=2025-10-01&endDate=2025-10-31&language=pt-BR" \
  -H "x-api-key: sua_api_key_aqui"

Estrutura da Resposta — JobDataModel

Campo	Tipo	Descrição
id	string	Identificador único (ObjectId) do job
code	integer	Código sequencial do job
title	string	Título/descrição do job
customerName	string	Nome do cliente associado
responsibleName	string	Nome do responsável pelo job
commercialResponsibleName	string	Nome do responsável comercial
creationTime	datetime	Data e hora de criação
deliveryNeeded	datetime?	Data necessária para entrega
deliveryExpected	datetime?	Data esperada de entrega
totalPrice	decimal	Preço total do job
paymentOption	string	Forma de pagamento selecionada
jobChargeStatus	string	Status de cobrança (Pending, Partial, Paid, Overdue)
jobInvoiceStatus	string	Status de faturamento (NotIssued, Partial, Issued, Cancelled)
isFinalized	boolean	Indica se o job foi finalizado
costs	object	Detalhes de custos em diferentes fases
production	object	Informações de produção (status, progresso, items, tasks)
products	array	Lista de produtos do job (do memento de custo)

JobCostDataModel — custos em 4 fases

Fase	Descrição
budgeted	Valores orçados (TotalPrice, ProductionCost, SellingCost, Profit, ProfitPercentual)
approved	Valores aprovados pelo cliente
planned	Valores planejados para produção
realized	Valores realizados (custos reais)

JobProductionDataModel

Campo	Tipo	Descrição
status	string	"Started" ou "NotStarted"
progressPercentage	decimal?	Percentual de progresso (0-100), por tasks finalizadas
startDate	datetime?	Menor data entre as tasks
endDate	datetime?	Maior data entre as tasks
items	array	Itens de produção com tasks e feedstocks

Cálculos automáticos

progressPercentage: (tasks finalizadas / total) × 100. startDate: menor entre StartedDate/ReleasedDate/ScheduleStartDate. endDate: maior entre FinalizedDate/ScheduleEndDate.

JobProductionTaskDataModel

Campo	Tipo	Descrição
publicId	integer	ID público da tarefa
name	string	Nome da tarefa
processPublicId	integer	ID público do processo associado
productionStatus	string	NotStarted, InProgress, Paused, Finalized, Cancelled
duration	decimal	Duração estimada/real (minutos)
scheduleStartDate	datetime?	Data agendada de início
scheduleEndDate	datetime?	Data agendada de término
startedDate	datetime?	Data real de início
finalizedDate	datetime?	Data real de finalização

JobProductionFeedstockDataModel

Campo	Tipo	Descrição
feedstockId	string	ID único (ObjectId) do feedstock
publicId	integer	ID público do feedstock
comercialId	integer	ID comercial do feedstock
options	object	Dicionário com opções traduzidas (ex.: "Largura": "210mm")

Boas práticas

Sempre especifique startDate/endDate para jobs históricos
Use pageSize entre 20 e 50 para otimizar performance
Verifique hasNextPage antes da próxima página
Implemente cache local para reduzir chamadas

Diferenças vs. Orçamentos

Aspecto	Jobs
Filtro de data	Padrão = mês corrente (Orçamentos não têm filtro padrão)
Custos	4 fases (budgeted, approved, planned, realized)
Produção	Dados completos (items, tasks, feedstocks, progresso)
Produtos	Do memento de custo (Orçamentos usam produtos de catálogo)

Contas a Pagar

Consulta despesas com classificações contábeis e centros de custo, permitindo análise financeira detalhada.

GET/api-key/expenses/data

Consulta despesas de forma paginada, com suporte a filtros por data, status, fornecedor e categoria. Os dados incluem informações contábeis, centros de custo e detalhes de pagamento, facilitando relatórios financeiros e controle de custos. Requer autenticação via API Key no header x-api-key.

Filtro Padrão

Se nenhuma data for informada, este endpoint retorna apenas despesas do mês corrente. Para consultar despesas de outros períodos, sempre especifique as datas.

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
page	int	opcional	Número da página para paginação (padrão: 1)
limit	int	opcional	Quantidade de registros por página (padrão: 50 • máximo: 100)
start_date	string	opcional	Data inicial para filtro (formato: YYYY-MM-DD). Exemplo: 2025-01-01
end_date	string	opcional	Data final para filtro (formato: YYYY-MM-DD). Exemplo: 2025-12-31
translate	boolean	opcional	Traduzir nomes de campos (true/false). Padrão: false
status	string	opcional	Filtrar por status (pending, paid, overdue, cancelled). Exemplo: paid
supplier_id	int	opcional	Filtrar despesas de um fornecedor específico. Exemplo: 55
category	string	opcional	Filtrar por categoria de despesa. Exemplo: equipment_rental

bash

curl -X GET "https://api.holdworks.ai/api-key/expenses/data?page=1&limit=50&start_date=2025-01-01&end_date=2025-12-31&status=paid" \
  -H "x-api-key: sua_api_key_aqui"

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1001,
        "description": "Aluguel de Impressora Digital",
        "amount": 3500.00,
        "due_date": "2025-02-05",
        "payment_date": "2025-02-05",
        "status": "paid",
        "supplier": {
          "id": 55,
          "name": "Fornecedor XYZ",
          "document": "98.765.432/0001-11"
        },
        "category": "equipment_rental",
        "cost_center": "production",
        "payment_method": "bank_transfer",
        "invoice_number": "NF-12345",
        "notes": "Referente ao mês de janeiro/2025",
        "created_at": "2025-01-15T10:00:00Z",
        "updated_at": "2025-02-05T14:30:00Z"
      },
      {
        "id": 1002,
        "description": "Compra de Papel Offset A4",
        "amount": 1250.00,
        "due_date": "2025-02-15",
        "payment_date": null,
        "status": "pending",
        "supplier": {
          "id": 56,
          "name": "Papelaria Central",
          "document": "12.345.678/0001-90"
        },
        "category": "paper_supplies",
        "cost_center": "production",
        "payment_method": null,
        "invoice_number": "NF-67890",
        "notes": null,
        "created_at": "2025-01-20T11:30:00Z",
        "updated_at": "2025-01-20T11:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 120,
      "pages": 3
    }
  },
  "message": "Success"
}

Status das Despesas

Campo	Tipo	Descrição
pending	string	Pendente - Despesa aguardando pagamento
paid	string	Paga - Despesa quitada
overdue	string	Vencida - Despesa não paga após o vencimento
cancelled	string	Cancelada - Despesa cancelada

Categorias de Despesas

Campo	Tipo	Descrição
paper_supplies	string	Papel e substratos
ink_supplies	string	Tintas e consumíveis de impressão
equipment_rental	string	Aluguel de equipamentos
equipment_maintenance	string	Manutenção de equipamentos
utilities	string	Utilidades (luz, água, internet)
labor	string	Mão de obra
services	string	Serviços terceirizados
other	string	Outras despesas

Centros de Custo

Campo	Tipo	Descrição
production	string	Custos diretos de produção
administration	string	Custos administrativos
sales	string	Custos comerciais e vendas
logistics	string	Custos de logística e entrega

Dica

Use os filtros de category e cost_center para gerar relatórios específicos por tipo de despesa ou área da empresa.

Estrutura de Dados

Campo	Tipo	Descrição
id	number	Identificador único da despesa
description	string	Descrição da despesa
amount	number	Valor da despesa
due_date	string	Data de vencimento (YYYY-MM-DD)
payment_date	string \| null	Data do pagamento (YYYY-MM-DD)
status	string	Status da despesa (pending, paid, overdue, cancelled)
supplier	object	Informações do fornecedor
category	string	Categoria da despesa
cost_center	string	Centro de custo contábil
payment_method	string \| null	Método de pagamento utilizado
invoice_number	string	Número da nota fiscal

Boas Práticas

Sempre especifique datas para evitar dados incompletos
Use paginação para grandes volumes de dados
Monitore despesas vencidas (status: overdue) regularmente
Filtre por centro de custo para análises departamentais

Contas a Receber

Consulta receitas com classificações contábeis e centros de receita, permitindo análise financeira detalhada e controle de fluxo de caixa.

GET/api-key/incomes/data

Consulta receitas de forma paginada, com suporte a filtros por data, status e cliente. Os dados incluem informações contábeis, centros de receita e detalhes de recebimento, facilitando o controle de fluxo de caixa e análises financeiras. A autenticação é feita via API Key no header x-api-key.

Filtro Padrão

Se nenhuma data for informada, este endpoint retorna apenas receitas do mês corrente. Para consultar receitas de outros períodos, sempre especifique as datas.

Parâmetros de Query

Campo	Tipo	Obrigatório	Descrição
page	int	opcional	Número da página para paginação (padrão: 1)
limit	int	opcional	Quantidade de registros por página (padrão: 50 • máximo: 100)
start_date	string	opcional	Data inicial para filtro (formato: YYYY-MM-DD). Exemplo: 2025-01-01
end_date	string	opcional	Data final para filtro (formato: YYYY-MM-DD). Exemplo: 2025-12-31
translate	boolean	opcional	Traduzir nomes de campos (true/false). Padrão: false
status	string	opcional	Filtrar por status (pending, received, overdue, cancelled). Exemplo: received
customer_id	int	opcional	Filtrar receitas de um cliente específico. Exemplo: 789

bash

curl -X GET "https://api.holdworks.ai/api-key/incomes/data?page=1&limit=50&start_date=2025-01-01&end_date=2025-12-31&status=received" \
  -H "x-api-key: sua_api_key_aqui"

json

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 2001,
        "description": "Pagamento Job #5678 - Cartões de Visita",
        "amount": 12500.00,
        "expected_date": "2025-02-15",
        "received_date": "2025-02-14",
        "status": "received",
        "customer": {
          "id": 789,
          "name": "Empresa Exemplo LTDA",
          "document": "12.345.678/0001-99"
        },
        "revenue_center": "sales",
        "payment_method": "bank_transfer",
        "invoice_number": "NFS-45678",
        "job_id": 5678,
        "notes": "Pagamento antecipado",
        "created_at": "2025-01-15T10:00:00Z",
        "updated_at": "2025-02-14T16:20:00Z"
      },
      {
        "id": 2002,
        "description": "Pagamento Job #5680 - Impressão de Catálogos",
        "amount": 8750.00,
        "expected_date": "2025-02-20",
        "received_date": null,
        "status": "pending",
        "customer": {
          "id": 790,
          "name": "Editora ABC",
          "document": "98.765.432/0001-10"
        },
        "revenue_center": "sales",
        "payment_method": null,
        "invoice_number": "NFS-45679",
        "job_id": 5680,
        "notes": null,
        "created_at": "2025-01-18T14:00:00Z",
        "updated_at": "2025-01-18T14:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 95,
      "pages": 2
    }
  },
  "message": "Success"
}

Status das Receitas

Campo	Tipo	Descrição
pending	string	Pendente - Receita a receber
received	string	Recebida - Receita quitada
overdue	string	Vencida - Receita não recebida após a data esperada
cancelled	string	Cancelada - Receita cancelada

Centros de Receita

Campo	Tipo	Descrição
sales	string	Receitas de vendas de produtos e serviços
services	string	Receitas de serviços complementares
recurring	string	Receitas recorrentes (contratos, assinaturas)
other	string	Outras receitas

Dica

Monitore receitas com status overdue para identificar clientes com pagamentos atrasados e tomar ações de cobrança apropriadas.

Estrutura de Dados

Campo	Tipo	Descrição
id	number	Identificador único da receita
description	string	Descrição da receita
amount	number	Valor da receita
expected_date	string	Data esperada de recebimento (YYYY-MM-DD)
received_date	string \| null	Data do recebimento (YYYY-MM-DD)
status	string	Status da receita (pending, received, overdue, cancelled)
customer	object	Informações do cliente
revenue_center	string	Centro de receita contábil
payment_method	string \| null	Método de pagamento utilizado
invoice_number	string	Número da nota fiscal
job_id	number \| null	ID do job relacionado

Boas Práticas

Sempre especifique datas para evitar dados incompletos
Use paginação para grandes volumes de dados
Compare expected_date vs received_date para análise de inadimplência
Filtre por centro de receita para análises de rentabilidade

Perguntas frequentes

Preciso saber programar?

Não. Você conversa em português com a LLM; ela usa as tools do MCP (ou o banco read-only) para responder, gerar relatórios e montar integrações.

Qual a diferença entre MCP e banco read-only?

O MCP é o caminho recomendado: simples e seguro, com login por OAuth e tools prontas. O banco read-only é para casos avançados que precisam de queries diretas no MongoDB.

É seguro? A IA pode alterar meus dados?

Pelo MCP, ações que alteram dados rodam primeiro em prévia (dry-run) e exigem confirmação. O acesso ao banco é somente leitura. Você continua no controle.

As skills funcionam em quais ferramentas?

Claude Code, Codex, Cursor, Gemini CLI e GitHub Copilot. O comando npx @holdprint/skills install detecta o que você tem instalado.

Meus dados ficam expostos publicamente?

Não. O acesso é por conta: o login OAuth identifica você e a IA só enxerga os dados da sua empresa. As credenciais não são compartilhadas com o aplicativo de IA.