Pular para o conteúdo principal

Contratos

Documentos enviados para assinatura (signs), contratos recorrentes (contracts) e os itens de cada contrato (contract-items).

Documentos para assinatura​

Recurso do plano: Assinaturas Digitais.

MétodoRotaO que faz
GET/external/v1/signsLista com paginação
GET/external/v1/signs/:idBusca um registro pelo ID
POST/external/v1/signsCria um registro
PUT/external/v1/signs/:idAtualiza 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/signs" \
-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/signs/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.

CampoTipoObrigatórioDescrição
orderedSigningbooleanNãoAssinatura em ordem: o próximo signatário só é notificado após o anterior assinar. Padrão: false.
purposeenumNãoFinalidade do envelope (contrato principal, aditivo, renovação, distrato). Valores: MAIN_CONTRACT, AMENDMENT, ATTACHMENT, POWER_OF_ATTORNEY, TERMINATION, OTHER.
relatedEntityTypeenumNãoTipo da entidade à qual o envelope está vinculado. Valores: CONTRACT, DEAL, QUOTE, PERSON, PROJECT, PURCHASE_ORDER, SERVICE_ORDER, NONE.
relatedEntityIdstringNãoID de vinculada ao envelope (contrato, negócio, projeto etc.).
documentFileIdsstring[]NãoIDs de arquivos. Anexos do contrato vinculado que já nascem como documentos do envelope, na ordem do array (o primeiro é o documento principal). Exige relatedEntityType = CONTRACT e relatedEntityId. Cada arquivo precisa ser anexo ativo desse contrato, PDF e até 25 MB; qualquer um fora disso recusa a criação inteira. Arquivos que falharem na cópia voltam em documentFilesMissing.
expiresAtstringNãoData limite para assinatura. Se omitida, usa o prazo padrão configurado pela empresa.
businessUnitIdstringNãoID de unidade de negócio. Se omitido e a feature FK_BSN_UNT estiver ativa, será resolvido automaticamente.
responsibleUserIdstringSimID de usuário da empresa.
customerIdstringSimID de pessoa.
dealIdstringNãoID de negócio.
workspaceIdstringNãoID de workspace.
titlestringSimTítulo do documento/contrato.
descriptionstringNãoDescrição do documento e suas principais características.
tagsstring[]NãoTags para categorizar o documento.
signatureMethodenumSimComo o documento é assinado: manualmente ou por assinatura digital. Valores: MANUAL, DIGITAL.
urlDocumentstringNãoURL para acessar o documento armazenado.
externalCodeIdstringNãoID do documento em um sistema de assinatura externo.
finishedAtstring (data ISO 8601)NãoData de finalização do processo.
reasonOfTerminationstringNãoMotivo ou razão de encerramento do contrato.
dueDatenumberNãoPrazo de vencimento/limite para assinatura.
statusenumSimStatus atual do processo de assinatura. Valores: CANCELED, REVERSED, SENT, SIGNED, SKETCH.
metadataobjectNãoObjeto JSON livre.
isExternallyVisiblebooleanSimIndica se o documento é visível externamente.

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.

Contratos recorrentes​

Recurso do plano: Contratos Recorrentes.

MétodoRotaO que faz
GET/external/v1/contractsLista com paginação
GET/external/v1/contracts/:idBusca um registro pelo ID
POST/external/v1/contractsCria um registro
PUT/external/v1/contracts/:idAtualiza 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":{"customerId":"ID_DA_PESSOA"}}):

curl -G "https://erp-api.ideros.api.br/external/v1/contracts" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"customerId":"ID_DA_PESSOA"}}'

Buscar por ID​

curl "https://erp-api.ideros.api.br/external/v1/contracts/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.

CampoTipoObrigatórioDescrição
businessUnitIdstringNãoID da unidade de negócio (CompanyBusinessUnit).
titlestringSimTítulo do contrato.
descriptionstringNãoDescrição detalhada do contrato.
customerIdstringSimID do cliente (Person).
responsibleUserIdstringNãoID do responsável (CompanyUser).
signIdstringNãoID do documento assinado (Sign).
startDatestring (data ISO 8601)SimData de início do contrato.
endDatestring (data ISO 8601)NãoData de término do contrato (null = indeterminado).
renewalTypeenumSimTipo de renovação do contrato. Valores: AUTOMATIC, MANUAL, NONE.
renewalNoticeDaysnumberNãoDias antes do vencimento para notificar renovação.
autoRenewMonthsnumberNãoMeses de renovação automática.
monthlyAmountnumberSimValor mensal do contrato.
adjustmentIndexenumNãoÍndice de reajuste. Valores: IGPM, IPCA, INPC, CUSTOM.
adjustmentPercentagenumberNãoPercentual de reajuste customizado (se index = CUSTOM).
dealIdstringNãoID do negócio vinculado (Deal).
slaIdstringNãoID do SLA vinculado.
externalSourcestringNãoCódigo de referência externa: sistema de origem do contrato (ex.: TALKPLAY). Genérico, serve a qualquer integração.
externalRefstringNãoCódigo de referência externa: identificador do contrato (ou do cliente) no sistema de origem.
metadataobjectNãoCampo genérico para guardar objetos estruturados como JSON.

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.

Itens do contrato​

Itens só podem ser listados, consultados e criados pela API. Não há rota de atualização.

Recurso do plano: Contratos Recorrentes.

MétodoRotaO que faz
GET/external/v1/contract-itemsLista com paginação
GET/external/v1/contract-items/:idBusca um registro pelo ID
POST/external/v1/contract-itemsCria 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":{"contractId":"ID_DO_CONTRATO"}}):

curl -G "https://erp-api.ideros.api.br/external/v1/contract-items" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-company-token: $COMPANY_TOKEN" \
--data-urlencode "page=1" \
--data-urlencode "limit=25" \
--data-urlencode 'relations={"where":{"contractId":"ID_DO_CONTRATO"}}'

Buscar por ID​

curl "https://erp-api.ideros.api.br/external/v1/contract-items/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.

CampoTipoObrigatórioDescrição
contractIdstringSimID de contrato.
productIdstringNãoID de produto.
productPriceTableIdstringNãoID de tabela de preço de origem do preço. Quando informado, o sistema valida a tabela (titularidade, produto, tipo de venda, ativa e vigente) e usa o preço-base dela. Envie 'null' para desvincular a tabela e manter o item com preço avulso.
descriptionstringSimDescrição do item.
itemTypeenumNãoTipo do item (Produto, Serviço, Mão de obra, Outros). Valores: LABOR, SERVICE, PARTS, OTHERS.
billingModeenumNãoModo de cobrança do item no contrato. RECURRING (padrão): mensalidade fixa, soma na fatura recorrente. ONE_SHOT: cobrança única (ex: setup/adesão), cobrada uma vez e não repete. Valores: ONE_SHOT, RECURRING.
valueTypeenumNãoFormato do preço. AMOUNT (padrão): unitPrice é valor em reais. PERCENTAGE: unitPrice é percentual aplicado sobre originalUnitPrice. Valores: PERCENTAGE, AMOUNT.
quantitynumberSimQuantidade.
originalUnitPricenumberNãoPreço unitário cheio/base. Obrigatório quando valueType=PERCENTAGE (base do percentual). Se omitido, assume o unitPrice.
unitPricenumberSimPreço unitário negociado. Em AMOUNT é valor em reais; em PERCENTAGE é o percentual aplicado sobre originalUnitPrice.
installmentsCountnumberNãoQuantidade de parcelas. Aplica-se a billingMode=ONE_SHOT. Vazio = pagamento único.
startDatestring (data ISO 8601)NãoInício da vigência do item no contrato.
endDatestring (data ISO 8601)NãoFim da vigência do item no contrato.
externalSourcestringNãoCódigo de referência externa: sistema de origem do item (ex.: TALKPLAY). Genérico, serve a qualquer integração.
externalRefstringNãoCódigo de referência externa: identificador do item no sistema de origem.
Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.