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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/signs | Lista com paginação |
GET | /external/v1/signs/:id | Busca um registro pelo ID |
POST | /external/v1/signs | Cria um registro |
PUT | /external/v1/signs/: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/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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
orderedSigning | boolean | Não | Assinatura em ordem: o próximo signatário só é notificado após o anterior assinar. Padrão: false. |
purpose | enum | Não | Finalidade do envelope (contrato principal, aditivo, renovação, distrato). Valores: MAIN_CONTRACT, AMENDMENT, ATTACHMENT, POWER_OF_ATTORNEY, TERMINATION, OTHER. |
relatedEntityType | enum | Não | Tipo da entidade à qual o envelope está vinculado. Valores: CONTRACT, DEAL, QUOTE, PERSON, PROJECT, PURCHASE_ORDER, SERVICE_ORDER, NONE. |
relatedEntityId | string | Não | ID de vinculada ao envelope (contrato, negócio, projeto etc.). |
documentFileIds | string[] | Não | IDs 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. |
expiresAt | string | Não | Data limite para assinatura. Se omitida, usa o prazo padrão configurado pela empresa. |
businessUnitId | string | Não | ID de unidade de negócio. Se omitido e a feature FK_BSN_UNT estiver ativa, será resolvido automaticamente. |
responsibleUserId | string | Sim | ID de usuário da empresa. |
customerId | string | Sim | ID de pessoa. |
dealId | string | Não | ID de negócio. |
workspaceId | string | Não | ID de workspace. |
title | string | Sim | Título do documento/contrato. |
description | string | Não | Descrição do documento e suas principais características. |
tags | string[] | Não | Tags para categorizar o documento. |
signatureMethod | enum | Sim | Como o documento é assinado: manualmente ou por assinatura digital. Valores: MANUAL, DIGITAL. |
urlDocument | string | Não | URL para acessar o documento armazenado. |
externalCodeId | string | Não | ID do documento em um sistema de assinatura externo. |
finishedAt | string (data ISO 8601) | Não | Data de finalização do processo. |
reasonOfTermination | string | Não | Motivo ou razão de encerramento do contrato. |
dueDate | number | Não | Prazo de vencimento/limite para assinatura. |
status | enum | Sim | Status atual do processo de assinatura. Valores: CANCELED, REVERSED, SENT, SIGNED, SKETCH. |
metadata | object | Não | Objeto JSON livre. |
isExternallyVisible | boolean | Sim | Indica 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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/contracts | Lista com paginação |
GET | /external/v1/contracts/:id | Busca um registro pelo ID |
POST | /external/v1/contracts | Cria um registro |
PUT | /external/v1/contracts/:id | Atualiza 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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
businessUnitId | string | Não | ID da unidade de negócio (CompanyBusinessUnit). |
title | string | Sim | Título do contrato. |
description | string | Não | Descrição detalhada do contrato. |
customerId | string | Sim | ID do cliente (Person). |
responsibleUserId | string | Não | ID do responsável (CompanyUser). |
signId | string | Não | ID do documento assinado (Sign). |
startDate | string (data ISO 8601) | Sim | Data de início do contrato. |
endDate | string (data ISO 8601) | Não | Data de término do contrato (null = indeterminado). |
renewalType | enum | Sim | Tipo de renovação do contrato. Valores: AUTOMATIC, MANUAL, NONE. |
renewalNoticeDays | number | Não | Dias antes do vencimento para notificar renovação. |
autoRenewMonths | number | Não | Meses de renovação automática. |
monthlyAmount | number | Sim | Valor mensal do contrato. |
adjustmentIndex | enum | Não | Índice de reajuste. Valores: IGPM, IPCA, INPC, CUSTOM. |
adjustmentPercentage | number | Não | Percentual de reajuste customizado (se index = CUSTOM). |
dealId | string | Não | ID do negócio vinculado (Deal). |
slaId | string | Não | ID do SLA vinculado. |
externalSource | string | Não | Código de referência externa: sistema de origem do contrato (ex.: TALKPLAY). Genérico, serve a qualquer integração. |
externalRef | string | Não | Código de referência externa: identificador do contrato (ou do cliente) no sistema de origem. |
metadata | object | Não | Campo 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étodo | Rota | O que faz |
|---|---|---|
GET | /external/v1/contract-items | Lista com paginação |
GET | /external/v1/contract-items/:id | Busca um registro pelo ID |
POST | /external/v1/contract-items | 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":{"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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contractId | string | Sim | ID de contrato. |
productId | string | Não | ID de produto. |
productPriceTableId | string | Não | ID 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. |
description | string | Sim | Descrição do item. |
itemType | enum | Não | Tipo do item (Produto, Serviço, Mão de obra, Outros). Valores: LABOR, SERVICE, PARTS, OTHERS. |
billingMode | enum | Não | Modo 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. |
valueType | enum | Não | Formato do preço. AMOUNT (padrão): unitPrice é valor em reais. PERCENTAGE: unitPrice é percentual aplicado sobre originalUnitPrice. Valores: PERCENTAGE, AMOUNT. |
quantity | number | Sim | Quantidade. |
originalUnitPrice | number | Não | Preço unitário cheio/base. Obrigatório quando valueType=PERCENTAGE (base do percentual). Se omitido, assume o unitPrice. |
unitPrice | number | Sim | Preço unitário negociado. Em AMOUNT é valor em reais; em PERCENTAGE é o percentual aplicado sobre originalUnitPrice. |
installmentsCount | number | Não | Quantidade de parcelas. Aplica-se a billingMode=ONE_SHOT. Vazio = pagamento único. |
startDate | string (data ISO 8601) | Não | Início da vigência do item no contrato. |
endDate | string (data ISO 8601) | Não | Fim da vigência do item no contrato. |
externalSource | string | Não | Código de referência externa: sistema de origem do item (ex.: TALKPLAY). Genérico, serve a qualquer integração. |
externalRef | string | Não | Código de referência externa: identificador do item no sistema de origem. |
A nossa equipe ajuda você a configurar e usar esse recurso.