Financeiro
Recursos do financeiro. Cada um exige o seu recurso no plano, indicado em cada seção.
Lançamentos financeiros
Lançamentos (contas a pagar e a receber) podem ser listados, consultados e criados. Não há rota de atualização nem de baixa pela API.
Recurso do plano: Financeiro.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/financial-entries | Lista com paginação |
GET | /external/v1/financial-entries/:id | Busca um registro pelo ID |
POST | /external/v1/financial-entries | Cria um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
Exemplo com filtro (o valor de relations vai codificado para URL; aqui ele aparece legível: {"where":{"typeCategory":"REVENUE","originalDueDate":{"gte":"2026-11-01","lte":"2026-11-30"}}}):
curl -G "https://erp-api.ideros.api.br/external/v1/financial-entries" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"typeCategory":"REVENUE","originalDueDate":{"gte":"2026-11-01","lte":"2026-11-30"}}}'
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/financial-entries/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
businessUnitId | string | Não | ID de unidade de negócio. |
workspaceId | string | Não | ID de workspace. |
personId | string | Sim | ID de pessoa. |
typeCategory | enum | Sim | Tipo da categoria financeira. Valores: REVENUE, EXPENSE, TRANSFER. |
financialCategoryId | string | Não | ID de categoria financeira. |
bankAccountId | string | Não | ID de conta bancária. |
creditCardId | string | Não | ID de cartão de crédito. |
parentId | string | Não | ID de lançamento financeiro. |
installmentNumber | number | Não | Número da parcela atual. |
totalInstallments | number | Sim | Quantidade total de parcelas. |
title | string | Não | Titulo do lançamento. |
description | string | Não | Descrição detalhada do lançamento. |
observations | string | Não | Observações adicionais para o lançamento contábil. |
natureOfOperation | string | Não | Natureza da operação fiscal (CFOP) ou descrição. |
competenceDate | string (data ISO 8601) | Não | Data de competência contábil (quando a receita foi ganha ou despesa incorrida). |
documentType | enum | Não | Tipo de documento que comprova a obrigação financeira. Valores: NONE, BANK_SLIP, PIX, DUPLICATE, PROMISSORY_NOTE, RECEIPT, CHECK, INVOICE, BILL, CONTRACT, INSTALLMENT_PLAN, OTHER. |
documentNumber | string | Não | Número do documento fiscal ou financeiro. |
currencyCode | string | Não | Código da moeda no padrão ISO 4217. |
exchangeRate | number | Não | Taxa de câmbio aplicada para conversão da moeda. |
originalCurrencyAmount | number | Não | Valor do lançamento na moeda original (antes da conversão). |
dueDate | string (data ISO 8601) | Não | Data de vencimento do lançamento. |
originalDueDate | string (data ISO 8601) | Sim | Data original de vencimento antes de alterações. |
paymentMethod | enum | Sim | Método de pagamento utilizado. Valores: VOUCHER, TED, PIX, CASH, DEBIT, CREDIT, CHECK, TICKET. |
originalAmount | number | Sim | Valor original do lançamento. |
fineAmount | number | Não | Valor de multa aplicado. |
interestAmount | number | Não | Valor de juros aplicado. |
discountAmount | number | Não | Valor de desconto aplicado. |
tags | string[] | Não | Tags do lançamento, utilizadas para filtros. |
sourceBilletFileUrl | string | Não | URL do arquivo do boleto. |
sourceEntryFileUrl | string | Não | URL do arquivo da entrada financeira. |
entrySource | enum | Sim | Origem do lançamento. Valores: SALES, PROVISIONING, MEASUREMENT, DETACHED, BANK_RECONCILIATION, EMAIL, PAYROLL, CONTRACT, VOUCHER, BOOKING, INVOICE. |
isExternallyVisible | boolean | Sim | Indica se o lançamento é visível externamente. |
autoBankPayment | boolean | Não | Pagamento automático pelo banco: ligado, o sistema envia o título ao banco sozinho (a aprovação continua no app do banco). Só aceito quando a conta do título tem a iniciação de pagamento ativa; senão 400 paymentOrder.auto_not_available. |
isReimbursable | boolean | Não | Indica se o lançamento é reembolsável. |
reimbursementStatus | enum | Não | Status do reembolso do lançamento. Valores: NONE, PENDING, REIMBURSED, REJECTED. |
metadata | object | Não | Objeto JSON livre. |
targetBankAccountId | string | Não | ID de conta bancária. Representa a conta bancário de destino de uma transferência. Deve ser enviado apenas se o 'typeCategory' for igual a 'TRANSFER' |
payeeBankAccountId | string | Não | ID de conta bancária da pessoa: conta bancária do fornecedor usada para pagar este lançamento (conta a pagar). Se omitido em despesas, o sistema puxa automaticamente a conta principal (isMain) do fornecedor e congela um snapshot dos dados bancários. |
entryCostCenter | object[] | Não | Lista de Centro de custos |
Categorias financeiras
Recurso do plano: Financeiro.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/financial-categories | Lista com paginação |
GET | /external/v1/financial-categories/:id | Busca um registro pelo ID |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/financial-categories" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/financial-categories/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Campos do registro
Além de id, isActive, createdAt e updatedAt, o registro traz:
| Campo | Tipo | Descrição |
|---|---|---|
code | string | Código único da categoria dentro da empresa. |
title | string | Título da categoria. |
description | string | Descrição opcional da categoria. |
typeCategory | enum | Tipo da categoria. Valores: REVENUE, EXPENSE, TRANSFER. |
managementGroup | enum | Grupo da DRE gerencial (Health Score / Raio-X do Dono): receita operacional, custo variável, despesa fixa, aporte de sócio, investimento etc. Se vazio, o sistema usa o padrão pelo código da categoria. Valores: OPERATING_REVENUE, FINANCIAL_REVENUE, OWNER_CONTRIBUTION, LOAN_INFLOW, NON_OPERATING_INFLOW, SALES_DEDUCTION, VARIABLE_COST, FIXED_EXPENSE, FINANCIAL_EXPENSE, CAPEX, OWNER_DISTRIBUTION, ADVANCE, TRANSFER. |
tags | string[] | Lista de tags associadas à categoria. |
isDefault | boolean | Define se é uma categoria padrão para o "typeCategory". |
Contas bancárias
Recurso do plano: Contas Bancárias.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/bank-accounts | Lista com paginação |
GET | /external/v1/bank-accounts/:id | Busca um registro pelo ID |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/bank-accounts" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/bank-accounts/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Campos do registro
Além de id, isActive, createdAt e updatedAt, o registro traz:
| Campo | Tipo | Descrição |
|---|---|---|
businessUnitId | string | ID de unidade de negócio. |
accountType | enum | Tipo da conta bancária. Valores: CHECKING_ACCOUNT, PAYMENT_ACCOUNT, SAVINGS_ACCOUNT, INVESTMENT_ACCOUNT, PETTY_CASH, GATEWAY, CREDIT_CARD. |
codeBank | string | Código do banco. |
nameBank | string | Nome do banco. |
title | string | Título da conta. |
description | string | Descrição da conta. |
openingBalance | number | Saldo inicial da conta. |
balanceDate | string (data ISO 8601) | Data do saldo inicial. |
agencyNumber | string | Número da agência. |
agencyCheckDigit | string | Dígito da agência. |
accountNumber | string | Número da conta. |
accountCheckDigit | string | Dígito da conta. |
ibanCode | string | Código IBAN da conta. |
swiftCode | string | Código SWIFT da conta. |
pixKeys | object[] | Chaves PIX associadas à conta. |
isMain | boolean | Define se a conta é a principal. |
hasCard | boolean | Indica se a conta possui cartão. |
Medições
Recurso do plano: Medições.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/measurements | Lista com paginação |
GET | /external/v1/measurements/:id | Busca um registro pelo ID |
POST | /external/v1/measurements | Cria um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/measurements" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/measurements/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
userApplicantId | string | Sim | ID do usuário logado que está criando o registro de medição. |
customerId | string | Sim | ID de pessoa. |
businessUnitId | string | Não | ID de unidade de negócio. Resolvido automaticamente quando a feature FK_BSN_UNT está inativa. |
workspaceId | string | Não | ID de workspace. |
dealId | string | Não | ID de negócio. Vincula a medição a um negócio/OS específico (COMMERCIAL ou SERVICE). Mutuamente exclusivo com projectId — apenas um dos dois pode ser informado. |
projectId | string | Não | ID de projeto. Vincula a medição a um projeto específico. Mutuamente exclusivo com dealId — apenas um dos dois pode ser informado. |
purchaseOrderId | string | Não | ID de pedido de compra. Vincula a medição a um pedido de compra (lado COST). Pode coexistir com dealId/projectId — medição mista gera tanto FinancialEntry REVENUE quanto EXPENSE. |
measurementCode | string | Sim | Código único ou chave para identificar o tipo de medição. |
title | string | Sim | Título ou nome da medição. |
description | string | Não | Descrição detalhada sobre esta medição. |
measurementDate | string (data ISO 8601) | Sim | Data em que a medição foi realizada ou finalizada. |
basePeriod | string | Sim | Período base. |
startDateMeasuredPeriod | string (data ISO 8601) | Sim | Data de início do período que foi medido. |
endDateMeasuredPeriod | string (data ISO 8601) | Sim | Data de fim do período que foi medido. |
measurementType | enum | Não | Tipo de medição (SIMPLE para pontual, PROGRESSIVE para acumulada). Valores: SIMPLE, PROGRESSIVE. |
previousMeasurementId | string | Não | ID de medição. Medição anterior (para medição progressiva). |
contractTotalAmount | number | Não | Valor total do contrato em reais (decimal com 2 casas). Usado para cálculo de % progresso em medição progressiva. |
retentionRate | number | Não | Taxa de retenção contratual (0-100%). Ex: 5 = 5%. |
generateInvoice | boolean | Não | Indica se esta medição deve emitir nota fiscal ao faturar. Deixe vazio para herdar o plano de medição (ou a configuração da empresa); true força a emissão; false impede. |
generateCharge | boolean | Não | Indica se esta medição deve gerar cobrança ao faturar. Deixe vazio para herdar o plano de medição (ou a configuração da empresa); true força a geração; false impede. |
billingBankAccountId | string | Não | ID de conta bancária. Conta bancária do lançamento gerado no faturamento desta medição. Se vazio, herda o plano. |
billingFinancialCategoryId | string | Não | ID de categoria financeira. Categoria financeira do lançamento gerado no faturamento desta medição. Se vazio, herda o plano. |
billingCostCenterId | string | Não | ID de centro de custo. Centro de custo rateado no lançamento gerado. Se vazio, herda o plano. |
billingPaymentMethod | enum | Não | Forma de pagamento do lançamento gerado no faturamento desta medição. Se vazio, herda o plano. Valores: VOUCHER, TED, PIX, CASH, DEBIT, CREDIT, CHECK, TICKET. |
billingDueDate | string (data ISO 8601) | Não | Vencimento do lançamento gerado no faturamento desta medição. Se vazio, é calculado pelo prazo ou dia fixo do plano. |
billingInstallments | number | Não | Quantidade de parcelas do lançamento gerado. Se vazio, herda o plano. |
gatewayConfigId | string | Não | ID de configuração de gateway. Configuração de gateway usada na cobrança desta medição. Se vazio, herda o plano. |
chargeType | enum | Não | Tipo da cobrança gerada por esta medição. Só se aplica quando há gateway configurado. Se vazio, herda o plano. Valores: BOLETO, PIX, CREDIT_CARD, BANK_TRANSFER. |
chargeForceManual | boolean | Não | Quando true, a cobrança é gerada pelo fluxo manual (PIX/TED com os dados bancários da conta do lançamento), ignorando provedores de pagamento. Equivale às opções de cobrança manual da tela de cobrança. |
executionOrder | enum | Não | Ordem de execução quando nota e cobrança estão ligadas. INVOICE_FIRST (padrão) emite a nota antes, permitindo que o texto da cobrança cite o número dela; CHARGE_FIRST cria a cobrança antes e a nota é encadeada por ela. Valores: INVOICE_FIRST, CHARGE_FIRST. |
invoiceType | enum | Não | Tipo de nota fiscal emitida por esta medição. Se vazio, herda o plano ou é derivado do tipo de produto predominante dos itens. Valores: NFE, NFSE, NFCE. |
splitInvoiceByProductType | boolean | Não | Indica se, havendo linhas de produto E de serviço na mesma medição, devem ser emitidas DUAS notas (NF-e para os produtos e NFS-e para os serviços) em vez de uma só pelo tipo predominante. Só tem efeito quando existem os dois tipos de linha. |
defaultProductId | string | Não | ID de produto. Produto/serviço padrão usado como identidade fiscal das linhas sem produto próprio. Se vazio, herda o plano. |
cnaeCode | string | Não | Código CNAE usado na nota de serviço desta medição. Se vazio, herda o plano ou a configuração fiscal da empresa. |
serviceCode | string | Não | Código do serviço (lista LC 116) usado na nota de serviço desta medição. Se vazio, herda o plano ou a configuração fiscal da empresa. |
nationalTaxationCode | string | Não | Código de Tributação Nacional (cTribNac) da NFS-e nacional. Se vazio, herda o plano ou é derivado da configuração fiscal da empresa. |
nbsCode | string | Não | Código NBS (Nomenclatura Brasileira de Serviços) usado na nota de serviço. Se vazio, herda o plano ou a configuração fiscal da empresa. |
cityServiceCode | string | Não | Código do serviço no município usado na nota de serviço. Se vazio, herda o plano ou a configuração fiscal da empresa. |
invoiceDescription | string | Não | Discriminação do serviço na nota fiscal desta medição. É diferente da descrição da medição, que é interna. Se vazio, herda o plano. |
additionalInformation | string | Não | Informações complementares impressas na nota fiscal desta medição. Se vazio, herda o plano. |
issWithheld | boolean | Não | Indica se o ISS é retido na fonte na nota de serviço desta medição. Deixe vazio para herdar o plano e a regra do produto. |
metadata | object | Não | Objeto JSON livre. |
Notas fiscais
Cria e consulta o registro da nota no Tesselys. Criar o registro não transmite a nota ao Emissor Nacional: a emissão segue o fluxo da tela.
Recurso do plano: Nota Fiscal.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/invoices | Lista com paginação |
GET | /external/v1/invoices/:id | Busca um registro pelo ID |
POST | /external/v1/invoices | Cria um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/invoices" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/invoices/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
customerId | string | Sim | ID de pessoa. |
title | string | Sim | Título ou descrição principal da fatura. |
invoiceAmount | number | Sim | Valor total da fatura. |
isExternallyVisible | boolean | Sim | Indica se a fatura é visível externamente. |
status | enum | Sim | Status atual da fatura. Em criação manual, normalmente SKETCH. Valores: SKETCH, SENT, CANCELED, REPLACED, EXCLUDED, ENQUEUED, AUTHORIZED, REJECTED, DENIED, CANCELLATION_REQUESTED. |
description | string | Não | Descrição detalhada do conteúdo da fatura. |
tags | string[] | Não | Tags para categorizar a fatura. |
invoiceNumber | string | Não | Número de referência da fatura/nota fiscal. |
xmlFileUrl | string | Não | URL do arquivo XML da Nota Fiscal. |
pdfFileUrl | string | Não | URL do arquivo PDF da fatura/DANFE. |
customerEmail | string[] | Não | E-mails para os quais a fatura foi ou deve ser enviada. |
issueDateAt | string (data ISO 8601) | Não | Data de emissão da fatura. |
emissionMode | enum | Não | Modo de emissão da nota fiscal. Valores: MANUAL, ACCOUNTING_EMAIL, AUTOMATED. |
invoiceType | enum | Não | Tipo da nota fiscal. Valores: NFE, NFSE, NFCE. |
nfeSerie | string | Não | Série da nota fiscal. |
metadata | object | Não | Objeto JSON livre. |
items | object[] | Não | Lista opcional de itens (apenas na criação manual SKETCH). Se vazio, é montado 1 item agregado com o valor total da nota. |
provisioningLinkable | boolean | Não | Marca a nota para ser usada pelo provisionamento do cliente: no próximo ciclo, com o valor batendo, o provisionamento vincula esta nota em vez de emitir outra. Opcional; se não for enviado, nasce false e a nota entra avulsa. |
Cobranças
Recurso do plano: Cobranças e Pagamentos.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/charges | Lista com paginação |
GET | /external/v1/charges/:id | Busca um registro pelo ID |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/charges" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/charges/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Campos do registro
Além de id, isActive, createdAt e updatedAt, o registro traz:
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID do registro. |
financialEntryId | string | ID de lançamento financeiro. |
personId | string | ID de pessoa. Representa o pagador. |
gatewayConfigId | string | ID de configuração de gateway. |
gatewayChargeId | string | ID da cobrança no gateway de pagamento externo. Gerado automaticamente ao criar a cobrança. |
type | enum | Tipo da cobrança. Valores: BOLETO, PIX, CREDIT_CARD, BANK_TRANSFER. |
amount | number | Valor da cobrança em reais (decimal com 2 casas). |
dueDate | string | Data de vencimento da cobrança. |
paidAmount | number | Valor pago em reais (decimal com 2 casas). Preenchido automaticamente após confirmação do pagamento. |
paidAt | string | Data e hora do pagamento. Preenchido automaticamente após confirmação. |
status | string | Status atual da cobrança (PENDING, PAID, CANCELLED, OVERDUE, etc.). Gerenciado automaticamente pelo sistema. |
boletoUrl | string | URL do boleto para visualização. Disponível apenas para cobranças do tipo BOLETO. |
boletoDigitableLine | string | Linha digitável do boleto. Disponível apenas para cobranças do tipo BOLETO. |
boletoPdfUrl | string | URL do PDF do boleto. Disponível apenas para cobranças do tipo BOLETO. |
pixQrCode | string | QR Code PIX em formato base64. Disponível apenas para cobranças do tipo PIX. |
pixCopyPaste | string | Código PIX copia e cola. Disponível apenas para cobranças do tipo PIX. |
notificationsSent | number | Quantidade de notificações enviadas para esta cobrança. Gerenciado automaticamente. |
isActive | boolean | Indica se o registro está ativo. |
Provisionamentos
Recurso do plano: Provisões.
| Método | Rota | O que faz |
|---|---|---|
GET | /external/v1/provisioning | Lista com paginação |
GET | /external/v1/provisioning/:id | Busca um registro pelo ID |
POST | /external/v1/provisioning | Cria um registro |
PUT | /external/v1/provisioning/:id | Atualiza um registro |
Listar
Aceita page, limit e relations, como descrito em Paginação e filtros.
curl -G "https://erp-api.ideros.api.br/external/v1/provisioning" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25"
Buscar por ID
curl "https://erp-api.ideros.api.br/external/v1/provisioning/ID_DO_REGISTRO" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN"
Devolve o registro. Se o ID não existir ou for de outra empresa, a resposta é 200 com corpo {} (objeto vazio).
Criar
Responde 201 com o registro criado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
personId | string | Sim | ID de pessoa. Com 'contractId', precisa ser o cliente do contrato. |
businessUnitId | string | Não | ID de unidade de negócio. |
workspaceId | string | Não | ID de workspace. |
bankAccountId | string | Não | ID de conta bancária. |
financialCategoryId | string | Não | ID de categoria financeira. |
costCenterId | string | Não | ID de centro de custo. |
title | string | Sim | Título da provisão. |
description | string | Não | Descrição detalhada da provisão. |
firstDueDate | string (data ISO 8601) | Sim | Data de inicio do processamento. |
typeCategory | enum | Sim | Tipo de categoria financeira associada à provisão. Valores: REVENUE, EXPENSE, TRANSFER. |
paymentMethod | enum | Sim | Método de pagamento usado para gerar os lançamentos da provisão. Valores: VOUCHER, TED, PIX, CASH, DEBIT, CREDIT, CHECK, TICKET. |
amount | number | Sim | Valor da provisão que será aplicado nos lançamentos gerados. |
tags | string[] | Não | Lista de tags ou metadados adicionais. |
repeatPeriod | enum | Sim | Período de repetição da provisão. Valores: DAILY, WEEKLY, BIWEEKLY, SEMIMONTHLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMIANNUAL, YEARLY. |
numberOfRepetitions | number | Não | Número total de repetições. Se nulo, a provisão repete indefinidamente. |
requiresInvoice | boolean | Não | Define se é um provisionamento que depende de uma fatura para ser processado. |
generateCharge | boolean | Não | Define se o provisionamento deve gerar uma cobrança automaticamente ao processar. |
gatewayConfigId | string | Não | ID de configuração de gateway. Provedor FIXADO para as cobranças deste provisionamento (multiprovedor). Se vazio, o provedor é resolvido no momento da cobrança: o padrão da empresa para o tipo escolhido e, na falta dele, o único que atende o tipo. Se o provedor fixado estiver inativo na hora da cobrança, a mesma régua resolve o substituto. |
chargeForceManual | boolean | Não | Quando true, a cobrança é gerada pelo fluxo manual (PIX/TED ou boleto manual, com os dados bancários da conta do lançamento), ignorando provedores de pagamento. Equivale às opções de cobrança manual da tela de cobrança. |
chargeType | enum | Não | Tipo da cobrança a ser gerada (BOLETO, PIX, CREDIT_CARD, BANK_TRANSFER). Obrigatório quando a geração de cobrança está ativa. O provedor é o de gatewayConfigId, quando informado; sem ele, é resolvido no momento da cobrança entre os que atendem o tipo (padrão da empresa primeiro). Valores: BOLETO, PIX, CREDIT_CARD, BANK_TRANSFER. |
invoiceType | enum | Não | OBSOLETO. A nota do provisionamento é sempre NFS-e (serviço). Para emitir nota de PRODUTO, use medição via ordem de serviço. Enviar NFE/NFCE resulta em erro. Valores: NFE, NFSE, NFCE. |
defaultProductId | string | Não | OBSOLETO. Só fazia sentido para nota de produto, que o provisionamento não emite mais. |
generateInvoice | boolean | Não | Define se o processamento do provisionamento emite nota fiscal de serviço (NFS-e). Só é permitido em provisionamento de RECEITA e exige que a empresa tenha um gatilho de emissão configurado (diferente de NONE). |
executeOnInvoiceIssued | boolean | Não | Quando true, o provisionamento é disparado pela nota fiscal emitida: ao processar, o usuário escolhe uma ou mais notas do cliente que ainda não estejam vinculadas a nenhum lançamento, e o provisionamento cria o lançamento vinculando-as. Exige que a emissão automática de nota esteja desligada e só vale para receita. |
executionOrder | enum | Não | Ordem de execução quando nota e cobrança estão ligadas. INVOICE_FIRST (padrão) emite a nota antes, permitindo que o texto da cobrança cite o número dela; CHARGE_FIRST cria a cobrança antes e a nota é encadeada por ela. Valores: INVOICE_FIRST, CHARGE_FIRST. |
invoiceDescription | string | Não | Discriminação do serviço na nota (o texto que o tomador lê). Aceita variáveis, ex.: {{competencia}}. Diferente da descrição do provisionamento, que é interna. |
additionalInformation | string | Não | Informações complementares da nota (ex.: texto de retenções). Aceita variáveis, ex.: {{competencia}}. |
serviceCode | string | Não | Código do serviço (item da LC 116) da nota. Se vazio, herda a configuração fiscal da empresa. |
cityServiceCode | string | Não | Código complementar municipal (cTribMun) da nota. Se vazio, herda a configuração fiscal da empresa. |
cnaeCode | string | Não | Código CNAE da atividade da nota. Se vazio, herda a configuração fiscal da empresa. |
nbsCode | string | Não | Código NBS do serviço. Se vazio, herda a configuração fiscal da empresa. |
nationalTaxationCode | string | Não | Código de Tributação Nacional (cTribNac) da nota, 6 dígitos. Se vazio, é derivado do código de serviço. |
ibsCbsCst | string | Não | CST do IBS/CBS (3 dígitos), da tabela oficial de CST (IT 2025.002). Nulo = herda. |
ibsCbsClassTrib | string | Não | Código de classificação tributária do IBS/CBS (cClassTrib, 6 dígitos), da tabela oficial (IT 2025.002). Precisa pertencer ao CST informado. Nulo = herda. |
ibsCbsIndOp | string | Não | Indicador da operação do IBS/CBS (indOp, 6 dígitos, Anexo VII da NFS-e). Só para serviço. Nulo = herda ou vem da sugestão oficial. |
ibsCbsOnerous | boolean | Não | Indica se a operação é onerosa (com contraprestação). Muda o indOp (regra do Anexo VIII). Só para serviço. Vazio (null) = herda do produto ou segue a sugestão oficial, que é onerosa. |
ibsCbsAcquirerAbroad | boolean | Não | Indica se o adquirente está no exterior. Muda o indOp (regra do Anexo VIII). Nulo = deduz do país do tomador. |
simplesActivityCode | string | Não | Código da atividade no Simples Nacional (cAtvSN, NT SE/CGNFS-e 009): 7 a 14 ou 90. Usado pela NFS-e do optante a partir de 2027. |
taxReformPriceMode | enum | Não | Como o preço trata o IBS/CBS nas notas desta origem: ADDED = tributo acrescido ao preço; INCLUDED = embutido no preço. Nulo = herda do produto e, depois, da configuração fiscal da empresa. Valores: ADDED, INCLUDED. |
ibsCbsPersonalUse | boolean | Não | Operação de uso ou consumo pessoal (LC 214, art. 57; indFinal da NFS-e). Marcada, o tomador não toma crédito do IBS/CBS desta nota. |
ibsCbsOperationType | enum | Não | Tipo de operação (tpOper, NT 009): obrigatório na compra governamental e nos serviços de imóvel 25.05, 15.09, 17.12 e 10.05. Na compra governamental, vazio = fornecimento com pagamento posterior. Valores: SUPPLY_WITH_SUBSEQUENT_PAYMENT, PAYMENT_RECEIVED_AFTER_SUPPLY, SUPPLY_WITH_PRIOR_PAYMENT, PAYMENT_RECEIVED_BEFORE_SUPPLY, SIMULTANEOUS_SUPPLY_AND_PAYMENT. |
ibsCbsProperty | object | Não | Bem imóvel da operação (grupo imovel da NFS-e): inscrição imobiliária, CIB e endereço. Só para serviços sobre imóvel, exceto obra. |
issWithheld | boolean | Não | Indica se o ISS da nota é retido na fonte pelo tomador. |
status | enum | Não | Situação do ciclo de vida: DRAFT (rascunho — não processa), ACTIVE (ativo — o único que fatura) ou BLOCKED (bloqueado — pausado de propósito). Omitido na criação, o registro nasce DRAFT. O valor INACTIVE existe no enum mas NÃO é atribuível aqui: ele acompanha a inativação do registro e é gravado pela ação de inativar; enviá-lo retorna 400. O valor FINISHED (finalizado) é gravado pelo sistema quando o ciclo de repetições termina: o registro continua ativo e ainda recebe a nota do último ciclo, mas não processa. Escolher FINISHED retorna 400; reenviar o mesmo valor numa edição é aceito. Para um novo ciclo, envie ACTIVE junto com um número de repetições maior que o já gerado (ou nulo, sem fim) — sem isso retorna 400. Valores: DRAFT, ACTIVE, BLOCKED, INACTIVE, FINISHED. |
competenceMode | enum | Não | Como a competência da nota é definida: ISSUE_DATE (data de emissão da nota — recomendado, é quando a receita é reconhecida no Simples), DUE_MONTH (mês do vencimento agendado, padrão retrocompatível), CURRENT_MONTH (mês do processamento), PREVIOUS_MONTH (mês anterior ao processamento) ou OFFSET (processamento somado a competenceOffsetMonths). NÃO confundir com o mês do SERVIÇO prestado, que vive na descrição da nota pelas tags de mês. Valores: ISSUE_DATE, DUE_MONTH, CURRENT_MONTH, PREVIOUS_MONTH, OFFSET. |
competenceOffsetMonths | number | Não | Meses somados ao mês do processamento para formar a competência. Obrigatório quando competenceMode = OFFSET. Use negativo para meses anteriores. |
chargeDescription | string | Não | Texto da cobrança enviado ao provedor de pagamento (aparece no boleto). Aceita variáveis, inclusive as da nota quando a ordem de execução é INVOICE_FIRST, ex.: {{numero_nota}}. |
emailDescription | string | Não | Texto fixo do corpo do e-mail enviado ao cliente ao fechar o ciclo (card Comunicação). Aceita variáveis, ex.: {{competencia}} e {{numero_nota}}. É somado ao texto informado no processamento manual. NÃO confundir com description, que é anotação interna do provisionamento e não vai ao cliente. |
internalNote | string | Não | Anotacao INTERNA sobre o proprio provisionamento (card Governanca), como instrucoes de operacao. NAO e copiada para o lancamento financeiro, nem para a nota, nem para o e-mail: fica somente neste registro. Use description para o texto que deve acompanhar o lancamento. |
chargeDueDayOffset | number | Não | Dias somados ao vencimento do lançamento para formar o vencimento da cobrança. Se vazio, a cobrança vence junto com o lançamento. |
outboundChannelId | string | Não | ID do canal de e-mail (InboxChannel) usado como caixa de saída das comunicações deste provisionamento. Se vazio, usa o e-mail automático da plataforma. |
recipientPersonEmailIds | object[] | Não | IDs dos e-mails da pessoa (PersonEmail) que devem receber as comunicações deste provisionamento. Se vazio, usa todos os e-mails habilitados para a ação. |
emailSubject | string | Não | Assunto do e-mail enviado ao cliente. Aceita variáveis, ex.: {{numero_nota}} e {{competencia}}. Vazio usa o assunto padrão do template da cobrança. |
recipientCcPersonEmailIds | object[] | Não | Destinatários em CÓPIA. Mesmos formatos aceitos em recipientPersonEmailIds (id, endereço digitado ou {personEmailId, email}). Vazio = sem cópia — a cópia não tem fallback. |
invoiceReceiverEmailMode | enum | Não | Qual e-mail vai como e-mail do TOMADOR na nota fiscal emitida por este provisionamento (a nota aceita um endereço só). AUTOMATIC (padrão, também quando nulo): o 1º de recipientPersonEmailIds; sem destinatário escolhido, o e-mail principal do cadastro da pessoa. CUSTOM: o endereço informado em 'invoiceReceiverEmail' (obrigatório nesse modo). NONE: a nota sai sem e-mail do tomador. Não muda quem recebe o e-mail de envio da nota/cobrança. Valores: AUTOMATIC, CUSTOM, NONE. |
invoiceReceiverEmail | object | Não | E-mail do tomador na nota quando invoiceReceiverEmailMode = CUSTOM. Mesmos formatos de recipientPersonEmailIds: {personEmailId, email} quando escolhido do cadastro da pessoa, ou o endereço digitado. Ignorado nos demais modos. |
entryTitleTemplate | string | Não | Modelo do TÍTULO do lançamento gerado. Aceita variáveis, ex.: {{competencia}} e {{parcela_atual}}. Vazio herda o title do provisionamento, que identifica o contrato. |
allowForcedReprocess | boolean | Não | Permite reprocessar o provisionamento no mesmo período. Quando false (padrão), o provisionamento roda uma única vez por período e uma segunda execução é recusada mesmo se forçada. |
suppressPendingAlert | boolean | Não | Silencia o alerta de documento pendente deste provisionamento. Útil quando o valor chega por automação ou anexo, e não por documento do fornecedor. |
amountFloorMode | enum | Não | Piso do valor quando o processamento informa um valor externo. NONE (padrão) usa o valor informado; LAST_VALUE mantém o valor vigente do provisionamento quando o informado for menor. Valores: NONE, LAST_VALUE, UPDATE_BASE. |
linkCode | string | Não | Código de vínculo usado para engatar um protocolo/e-mail neste provisionamento (ex.: assunto '[FATURAR] #PRV-0042'). Único por empresa. |
broadcastAutomations | boolean | Não | Define se o provisionamento dispara automações de broadcast (genéricas) ao processar. Quando false, só executa automações explicitamente vinculadas a ele (AutomationEntity) — útil para provisionamentos que não devem notificar o fornecedor (ex.: aluguel). É gerenciado automaticamente ao vincular/desvincular uma automação, mas pode ser definido manualmente. |
requiresApproval | boolean | Não | Governança: quando true, o processamento automático (CRON) NÃO gera o lançamento deste provisionamento — ele exige processamento manual (a ação humana funciona como a aprovação). Padrão false. |
notifyResponsible | boolean | Não | Governança: quando true (padrão), notifica o responsável (provisioningdById) a cada processamento automático deste provisionamento. |
processingLeadDays | number | Não | Dias de antecedência para o processamento (corridos com processingAnchor LEAD_DAYS, úteis com LEAD_BUSINESS_DAYS). O provisionamento é executado N dias ANTES do vencimento. 0 = processa no próprio dia do vencimento. O máximo depende do período (ver GET /system-lookup/provisioning-schedule-options). |
processingAnchor | enum | Não | Âncora da data de PROCESSAMENTO. LEAD_DAYS (padrão) processa N dias corridos antes do vencimento (processingLeadDays). LAST_BUSINESS_DAY processa no último dia útil do mês anterior ao vencimento. FIRST_BUSINESS_DAY processa no primeiro dia útil do mês do vencimento. NTH_BUSINESS_DAY processa no dia útil informado em processingBusinessDay. Valores: LEAD_DAYS, LAST_BUSINESS_DAY, FIRST_BUSINESS_DAY, NTH_BUSINESS_DAY, LEAD_BUSINESS_DAYS. |
processingBusinessDay | number | Não | Qual dia útil do mês processa o provisionamento. Obrigatório quando processingAnchor = NTH_BUSINESS_DAY. Considera o calendário e os feriados da empresa. |
dueDateRule | enum | Não | Regra do VENCIMENTO do lançamento. FIXED_DAY (padrão) mantém o dia fixo do primeiro vencimento. NTH_BUSINESS_DAY faz vencer no dia útil informado em dueBusinessDay, recalculado a cada competência. LAST_DAY vence no último dia do mês (útil ou não). LAST_BUSINESS_DAY vence no último dia útil do mês, no calendário da empresa. FIRST_DAY vence no dia 1º. FIRST_BUSINESS_DAY vence no primeiro dia útil do mês. Valores: FIXED_DAY, NTH_BUSINESS_DAY, LAST_DAY, LAST_BUSINESS_DAY, FIRST_DAY, FIRST_BUSINESS_DAY. |
dueBusinessDay | number | Não | Qual dia útil do mês é o vencimento. Obrigatório quando dueDateRule = NTH_BUSINESS_DAY. Considera o calendário e os feriados da empresa. |
dueDateAdjust | enum | Não | O que fazer quando o vencimento cai em dia não útil da empresa. FORWARD empurra para o próximo dia útil, BACKWARD antecipa para o dia útil anterior, NONE mantém a data. SKIP ("apenas dias úteis") só vale na recorrência DAILY: a cadência pula fim de semana e feriado. Se vazio, mantém a regra atual do sistema: receita é empurrada para frente e despesa não é ajustada. As opções aceitas dependem do período (ver GET /system-lookup/provisioning-schedule-options). O mesmo ajuste vale para o vencimento da cobrança (chargeDueDayOffset). Valores: FORWARD, BACKWARD, NONE, SKIP. |
secondDueDay | number | Não | Segundo dia de vencimento do mês na recorrência SEMIMONTHLY (quinzenal de dois dias fixos). O primeiro dia é o dia do firstDueDate. Obrigatório em SEMIMONTHLY, maior que o primeiro dia com pelo menos 7 dias de intervalo; proibido nos demais períodos. Dia inexistente no mês cai no último dia (31 em fevereiro vira 28/29). |
dueDay | number | Não | Dia do vencimento dos PRÓXIMOS ciclos (1 a 31). Vale na recorrência mensal ou maior com a regra de vencimento "dia fixo" (FIXED_DAY ou vazia); proibido nos demais casos. Pode ser alterado mesmo depois de ciclos gerados — diferente do firstDueDate, que é histórico e trava. Os lançamentos já gerados não mudam: o próximo ciclo nasce no mês seguinte ao último gerado, neste dia. Dia inexistente no mês cai no último dia (31 em fevereiro vira 28/29). Nulo = dia do firstDueDate. |
autoBankPayment | boolean | Não | Pagamento automático pelo banco da DESPESA gerada a cada ciclo: vazio/null = herda o padrão da conta bancária (autoPaymentDefault), true = sempre envia ao banco, false = nunca envia. Só vale para despesa; true exige a iniciação de pagamento ativa na conta do provisionamento. |
amountSource | enum | Não | De onde sai o valor de cada ciclo. FIXED (ou vazio) = o campo amount. CONTRACT = todos os itens do contrato vinculado, compostos a cada ciclo (recorrentes em vigência, avulsos uma vez e parcelas nos primeiros ciclos). CONTRACT_ITEM = um item do contrato (contractItemId). Com origem no contrato, o amount vira projeção calculada pelo sistema (o valor enviado é ignorado), o provisionamento precisa ter contractId, o período tem de ser mensal ou maior e o piso de valor (amountFloorMode) não se aplica. Valores: FIXED, CONTRACT, CONTRACT_ITEM. |
contractItemId | string | Não | ID do item do contrato faturado por este provisionamento. Obrigatório com amountSource = CONTRACT_ITEM; o item precisa ser do contrato vinculado e estar ativo. |
ingestionChannelId | string | Não | ID do canal de ingestão (IDP) vinculado à provisão. Ativa o cruzamento automático do protocolo recebido com este provisionamento. |
contractId | string | Não | ID do contrato que comanda este provisionamento. Informado só na CRIAÇÃO a partir da tela de contrato: 'personId' tem de ser o cliente do contrato (outro é recusado) e o status nasce igual ao do contrato (rascunho, ativo ou bloqueado se o contrato estiver suspenso). Depois de criado, o vínculo muda apenas pelas rotas de vincular/desvincular do contrato; na edição este campo é ignorado. |
metadata | object | Não | Objeto JSON livre. |
Atualizar
Envie no corpo só os campos que mudam, com os mesmos nomes da tabela de criação. Responde 200 com o registro atualizado. Registro de outra empresa responde 403; registro inexistente, 404.
A nossa equipe ajuda você a configurar e usar esse recurso.