Referência

Contratos

Contratos de cliente e de fornecedor: partes, valores, prazo, renovação, versões e adendas, aprovação e assinatura, documentos anexos e o plano de facturação periódico, que emite as facturas dos períodos. Os estados de um contrato são: Rascunho, EmAprovacao, Aprovado, Assinado, Activo, Suspenso, EmRenovacao, Expirado, Rescindido e Encerrado. Quem submete um contrato não o aprova; a equipa do contrato e a alçada de aprovação não se gerem pela API.

Operação	O que faz
GET `/api/contratos`	Os contratos com o número, o título, a contraparte, o estado, os valores e a próxima emissão.
GET `/api/contratos/{id}`	Um contrato completo: termos, versões, plano de facturação, execuções, acertos, documentos, registo de eventos e equipa.
GET `/api/contratos/pendentes-de-facturacao`	Os períodos de facturação pendentes de cada contrato: o período, a data de emissão, o valor-base e os períodos em atraso.
GET `/api/contratos/acertos`	Os acertos dos contratos: a diferença entre o que se facturou e o que era esperado num período.
GET `/api/contratos/configuracao`	A configuração dos contratos da empresa: a alçada anual do gestor, acima da qual só a direcção aprova.
POST `/api/contratos`	Cria um contrato em rascunho, com o sentido (cliente ou fornecedor), o tipo, a parte, os termos e, se houver, o plano de facturação.
PUT `/api/contratos/{id}`	Altera o título, o objecto, a data de início, o responsável, os termos e o plano de um contrato ainda em rascunho.
POST `/api/contratos/{id}/submeter`	Submete um rascunho a aprovação.
POST `/api/contratos/{id}/devolver`	Devolve a rascunho um contrato que está em aprovação.
POST `/api/contratos/{id}/aprovar`	Aprova o contrato: atribui-lhe o número (por exemplo, CT 2026/0042) e congela a versão inicial.
POST `/api/contratos/{id}/assinatura`	Regista a assinatura do contrato, com a data e os signatários.
POST `/api/contratos/{id}/dispensar-assinatura`	Dispensa a assinatura (por exemplo, uma aceitação por e-mail, que se anexa), com motivo.
POST `/api/contratos/{id}/activar`	Activa o contrato assinado: a versão inicial passa a vigorar e o plano de facturação começa a contar.
POST `/api/contratos/{id}/suspender`	Suspende um contrato activo (ou em renovação), com motivo.
POST `/api/contratos/{id}/reactivar`	Reactiva um contrato suspenso: volta a activo.
POST `/api/contratos/{id}/renovar`	Renova à mão: mais N meses, com os mesmos termos ou outros.
POST `/api/contratos/{id}/rescindir`	Rescinde o contrato, com o motivo, a data de efeito e, se houver, a penalidade.
POST `/api/contratos/{id}/encerrar`	Encerra o contrato terminado, depois dos acertos: o plano já facturou tudo e não há acertos por tratar.
POST `/api/contratos/{id}/adendas`	Propõe uma adenda: uma versão nova dos termos, com a data de efeito e o motivo.
POST `/api/contratos/{id}/versoes/{numero}/aprovar`	Aprova uma adenda (ou a revisão de preço que o sistema propôs).
POST `/api/contratos/{id}/versoes/{numero}/recusar`	Recusa uma versão proposta, com motivo.
POST `/api/contratos/acertos/{id}/resolver`	Dá um acerto por resolvido, com a referência de como se resolveu.
POST `/api/contratos/acertos/{id}/dispensar`	Dispensa um acerto, com motivo.
POST `/api/contratos/{id}/documentos`	Anexa um documento a um contrato (ou a uma das suas versões).
GET `/api/contratos/{id}/documentos/{documentoId}`	Descarrega um documento anexado a um contrato.
GET `/api/contratos/modelos`	Os modelos de contrato.
POST `/api/contratos/modelos`	Cria um modelo de contrato.
PUT `/api/contratos/modelos/{id}`	Altera um modelo de contrato.
POST `/api/contratos/gerar-facturas`	Emite os períodos pendentes dos contratos dos estabelecimentos da chave.

GET/api/contratos#

Os contratos com o número, o título, a contraparte, o estado, os valores e a próxima emissão.

Permissão Contratos.Ler

Filtros: estado, sentido (Cliente ou Fornecedor), filtro (texto), clienteId, fornecedorId e soMeus (os contratos de que a pessoa é responsável ou participante). tamanho (por omissão 200).

Parâmetros

Nome	Onde	Tipo
`estado`	na pesquisa	uma de: «Rascunho», «EmAprovacao», «Aprovado», «Assinado», «Activo», «Suspenso», «EmRenovacao», «Expirado», «Rescindido», «Encerrado», «null»
`sentido`	na pesquisa	uma de: «Cliente», «Fornecedor», «null»
`filtro`	na pesquisa	texto
`clienteId`	na pesquisa	identificador (UUID)
`fornecedorId`	na pesquisa	identificador (UUID)
`tamanho`	na pesquisa	número inteiro
`soMeus`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/contratos/{id}#

Um contrato completo: termos, versões, plano de facturação, execuções, acertos, documentos, registo de eventos e equipa.

Permissão Contratos.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/contratos/pendentes-de-facturacao#

Os períodos de facturação pendentes de cada contrato: o período, a data de emissão, o valor-base e os períodos em atraso.

Permissão Contratos.Facturar

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos/pendentes-de-facturacao' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/contratos/acertos#

Os acertos dos contratos: a diferença entre o que se facturou e o que era esperado num período.

Permissão Contratos.Facturar

estado (por omissão Pendente): Pendente, Resolvido ou Dispensado.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`estado`	na pesquisa	uma de: «Pendente», «Resolvido», «Dispensado», «null»

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos/acertos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/contratos/configuracao#

A configuração dos contratos da empresa: a alçada anual do gestor, acima da qual só a direcção aprova.

Permissão Contratos.Ler

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos/configuracao' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos#

Cria um contrato em rascunho, com o sentido (cliente ou fornecedor), o tipo, a parte, os termos e, se houver, o plano de facturação.

Permissão Contratos.Editar
Idempotência aceita Idempotency-Key

sentido: Cliente ou Fornecedor. tipo: ServicosPeriodicos, Subscricao, Aluguer, ProjectoPorMarcos, Consumo, ManutencaoComSla ou Fornecimento. modeloId parte de um modelo.

Corpo do pedido (JSON · CriarContratoCommand)

Campo	Tipo	Obrigatório	Significado
`sentido`	uma de: «Cliente», «Fornecedor», «null»	sim
`tipo`	uma de: «ServicosPeriodicos», «Subscricao», «Aluguer», «ProjectoPorMarcos», «Consumo», «ManutencaoComSla», «Fornecimento», «Outro»	sim
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.
`fornecedorId`	identificador (UUID) ou nulo
`modeloId`	identificador (UUID) ou nulo
`titulo`	texto	sim
`objecto`	texto ou nulo
`dataInicio`	data (AAAA-MM-DD)	sim
`responsavelUserId`	identificador (UUID) ou nulo
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`termos`	objecto	sim
`termos.duracaoEmMeses`	número inteiro ou nulo
`termos.preAvisoDias`	número inteiro	sim
`termos.renovacao`	uma de: «Nenhuma», «Tacita», «Manual»	sim
`termos.renovacaoMeses`	número inteiro	sim
`termos.limiteDeRenovacoes`	número inteiro ou nulo
`termos.revisao`	uma de: «Nenhuma», «PercentualFixo», «Negociada»	sim
`termos.percentagemDeRevisao`	número ou nulo
`termos.prazoPagamentoDias`	número inteiro	sim
`termos.condicoes`	texto ou nulo
`termos.linhas`	lista de objectos	sim
`termos.linhas[].produtoId`	identificador (UUID)	sim	O artigo.
`termos.linhas[].descricao`	texto ou nulo		A descrição.
`termos.linhas[].quantidade`	número	sim	A quantidade.
`termos.linhas[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`plano`	objecto ou nulo
`plano.frequencia`	uma de: «Mensal», «Trimestral», «Semestral», «Anual»	sim
`plano.diaDeEmissao`	número inteiro	sim
`plano.antecipada`	verdadeiro/falso	sim
`plano.enviarEmail`	verdadeiro/falso	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "sentido": "Cliente",
  "tipo": "ServicosPeriodicos",
  "titulo": "texto",
  "dataInicio": "2026-10-12",
  "termos": {
    "preAvisoDias": 1,
    "renovacao": "Nenhuma",
    "renovacaoMeses": 1,
    "revisao": "Nenhuma",
    "prazoPagamentoDias": 1,
    "linhas": [
      {
        "produtoId": "00000000-0000-0000-0000-000000000000",
        "quantidade": 0,
        "precoUnitario": 0
      }
    ]
  }
}'

PUT/api/contratos/{id}#

Altera o título, o objecto, a data de início, o responsável, os termos e o plano de um contrato ainda em rascunho.

Permissão Contratos.Editar

Só se edita um contrato que ainda é rascunho; depois de activo, as alterações são adendas.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · EditarContratoPedido)

Campo	Tipo	Obrigatório	Significado
`titulo`	texto	sim
`objecto`	texto ou nulo
`dataInicio`	data (AAAA-MM-DD)	sim
`responsavelUserId`	identificador (UUID) ou nulo
`termos`	objecto	sim
`termos.duracaoEmMeses`	número inteiro ou nulo
`termos.preAvisoDias`	número inteiro	sim
`termos.renovacao`	uma de: «Nenhuma», «Tacita», «Manual»	sim
`termos.renovacaoMeses`	número inteiro	sim
`termos.limiteDeRenovacoes`	número inteiro ou nulo
`termos.revisao`	uma de: «Nenhuma», «PercentualFixo», «Negociada»	sim
`termos.percentagemDeRevisao`	número ou nulo
`termos.prazoPagamentoDias`	número inteiro	sim
`termos.condicoes`	texto ou nulo
`termos.linhas`	lista de objectos	sim
`termos.linhas[].produtoId`	identificador (UUID)	sim	O artigo.
`termos.linhas[].descricao`	texto ou nulo		A descrição.
`termos.linhas[].quantidade`	número	sim	A quantidade.
`termos.linhas[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`plano`	objecto ou nulo
`plano.frequencia`	uma de: «Mensal», «Trimestral», «Semestral», «Anual»	sim
`plano.diaDeEmissao`	número inteiro	sim
`plano.antecipada`	verdadeiro/falso	sim
`plano.enviarEmail`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/contratos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "titulo": "texto",
  "dataInicio": "2026-10-12",
  "termos": {
    "preAvisoDias": 1,
    "renovacao": "Nenhuma",
    "renovacaoMeses": 1,
    "revisao": "Nenhuma",
    "prazoPagamentoDias": 1,
    "linhas": [
      {
        "produtoId": "00000000-0000-0000-0000-000000000000",
        "quantidade": 0,
        "precoUnitario": 0
      }
    ]
  }
}'

POST/api/contratos/{id}/submeter#

Submete um rascunho a aprovação.

Permissão Contratos.Editar

A alçada e os desvios ao modelo dizem se só a direcção pode aprovar.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/submeter' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/{id}/devolver#

Devolve a rascunho um contrato que está em aprovação.

Permissão Contratos.Aprovar
Idempotência aceita Idempotency-Key

comentario é obrigatório: diz o que há a corrigir.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ComentarioPedido)

Campo	Tipo	Obrigatório
`comentario`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/devolver' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "comentario": "texto"
}'

POST/api/contratos/{id}/aprovar#

Aprova o contrato: atribui-lhe o número (por exemplo, CT 2026/0042) e congela a versão inicial.

Permissão Contratos.Aprovar

Quem submeteu não aprova; se o contrato passa a alçada ou tem desvios ao modelo, só quem tem a permissão da direcção. Devolve o novo estado.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/aprovar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/{id}/assinatura#

Regista a assinatura do contrato, com a data e os signatários.

Permissão Contratos.Gerir
Idempotência aceita Idempotency-Key

Exige que o contrato assinado já esteja anexado.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AssinaturaPedido)

Campo	Tipo	Obrigatório	Significado
`data`	data (AAAA-MM-DD)	sim	A data e hora (UTC).
`signatarios`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/assinatura' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": "2026-10-12"
}'

POST/api/contratos/{id}/dispensar-assinatura#

Dispensa a assinatura (por exemplo, uma aceitação por e-mail, que se anexa), com motivo.

Permissão Contratos.Gerir
Idempotência aceita Idempotency-Key

O motivo fica no registo e o contrato fica sinalizado.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/dispensar-assinatura' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/contratos/{id}/activar#

Activa o contrato assinado: a versão inicial passa a vigorar e o plano de facturação começa a contar.

Permissão Contratos.Gerir

É em nome de quem activa que o robô emite as facturas (o seu estabelecimento e as suas permissões), por isso quem activa um contrato de cliente tem de poder emitir documentos.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/activar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/{id}/suspender#

Suspende um contrato activo (ou em renovação), com motivo.

Permissão Contratos.Gerir
Idempotência aceita Idempotency-Key

motivo é obrigatório.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/suspender' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/contratos/{id}/reactivar#

Reactiva um contrato suspenso: volta a activo.

Permissão Contratos.Gerir

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/reactivar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/{id}/renovar#

Renova à mão: mais N meses, com os mesmos termos ou outros.

Permissão Contratos.Gerir
Idempotência aceita Idempotency-Key

mesesAdicionais e, se mudarem, os termos. A versão nova nasce aprovada (quem renova é quem a aprova) e entra em vigor no dia a seguir ao fim. Devolve o número da versao.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · RenovarPedido)

Campo	Tipo	Obrigatório	Significado
`mesesAdicionais`	número inteiro	sim
`termos`	objecto ou nulo
`termos.duracaoEmMeses`	número inteiro ou nulo
`termos.preAvisoDias`	número inteiro	sim
`termos.renovacao`	uma de: «Nenhuma», «Tacita», «Manual»	sim
`termos.renovacaoMeses`	número inteiro	sim
`termos.limiteDeRenovacoes`	número inteiro ou nulo
`termos.revisao`	uma de: «Nenhuma», «PercentualFixo», «Negociada»	sim
`termos.percentagemDeRevisao`	número ou nulo
`termos.prazoPagamentoDias`	número inteiro	sim
`termos.condicoes`	texto ou nulo
`termos.linhas`	lista de objectos	sim
`termos.linhas[].produtoId`	identificador (UUID)	sim	O artigo.
`termos.linhas[].descricao`	texto ou nulo		A descrição.
`termos.linhas[].quantidade`	número	sim	A quantidade.
`termos.linhas[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/renovar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "mesesAdicionais": 1
}'

POST/api/contratos/{id}/rescindir#

Rescinde o contrato, com o motivo, a data de efeito e, se houver, a penalidade.

Permissão Contratos.Gerir
Idempotência aceita Idempotency-Key

O plano factura até à data de efeito (a última factura, ao dia) e pára.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · RescindirPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim
`dataDeEfeito`	data (AAAA-MM-DD)	sim
`penalidade`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/rescindir' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto",
  "dataDeEfeito": "2026-10-12"
}'

POST/api/contratos/{id}/encerrar#

Encerra o contrato terminado, depois dos acertos: o plano já facturou tudo e não há acertos por tratar.

Permissão Contratos.Gerir

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/encerrar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/{id}/adendas#

Propõe uma adenda: uma versão nova dos termos, com a data de efeito e o motivo.

Permissão Contratos.Editar
Idempotência aceita Idempotency-Key

Devolve 201 com o numero da versão proposta.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AdendaPedido)

Campo	Tipo	Obrigatório	Significado
`dataDeEfeito`	data (AAAA-MM-DD)	sim
`motivo`	texto	sim
`termos`	objecto	sim
`termos.duracaoEmMeses`	número inteiro ou nulo
`termos.preAvisoDias`	número inteiro	sim
`termos.renovacao`	uma de: «Nenhuma», «Tacita», «Manual»	sim
`termos.renovacaoMeses`	número inteiro	sim
`termos.limiteDeRenovacoes`	número inteiro ou nulo
`termos.revisao`	uma de: «Nenhuma», «PercentualFixo», «Negociada»	sim
`termos.percentagemDeRevisao`	número ou nulo
`termos.prazoPagamentoDias`	número inteiro	sim
`termos.condicoes`	texto ou nulo
`termos.linhas`	lista de objectos	sim
`termos.linhas[].produtoId`	identificador (UUID)	sim	O artigo.
`termos.linhas[].descricao`	texto ou nulo		A descrição.
`termos.linhas[].quantidade`	número	sim	A quantidade.
`termos.linhas[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/adendas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "dataDeEfeito": "2026-10-12",
  "motivo": "texto",
  "termos": {
    "preAvisoDias": 1,
    "renovacao": "Nenhuma",
    "renovacaoMeses": 1,
    "revisao": "Nenhuma",
    "prazoPagamentoDias": 1,
    "linhas": [
      {
        "produtoId": "00000000-0000-0000-0000-000000000000",
        "quantidade": 0,
        "precoUnitario": 0
      }
    ]
  }
}'

POST/api/contratos/{id}/versoes/{numero}/aprovar#

Aprova uma adenda (ou a revisão de preço que o sistema propôs).

Permissão Contratos.Aprovar

Quem propôs não aprova; a revisão exige a direcção. Se a data de efeito já chegou, entra logo em vigor e o plano e os acertos actualizam-se. Devolve emVigor: se a versão já está em vigor.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`numero`	no caminho	número inteiro	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/versoes/<numero>/aprovar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/{id}/versoes/{numero}/recusar#

Recusa uma versão proposta, com motivo.

Permissão Contratos.Aprovar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`numero`	no caminho	número inteiro	sim

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/versoes/<numero>/recusar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/contratos/acertos/{id}/resolver#

Dá um acerto por resolvido, com a referência de como se resolveu.

Permissão Contratos.Facturar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ReferenciaPedido)

Campo	Tipo	Obrigatório
`referencia`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/acertos/<id>/resolver' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "referencia": "texto"
}'

POST/api/contratos/acertos/{id}/dispensar#

Dispensa um acerto, com motivo.

Permissão Contratos.Facturar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · MotivoPedido)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/acertos/<id>/dispensar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/contratos/{id}/documentos#

Anexa um documento a um contrato (ou a uma das suas versões).

Permissão Contratos.Editar

Envio de ficheiro (multipart/form-data): o ficheiro vai no campo ficheiro e o tipo (Proposta, ContratoAssinado, Adenda, AnexoTecnico, Comprovativo ou Outro) é obrigatório; versao (opcional) liga-o a uma versão.

Um ficheiro vazio, ou que exceda o limite de tamanho, é recusado.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`tipo`	na pesquisa	uma de: «Proposta», «ContratoAssinado», «Adenda», «AnexoTecnico», «Comprovativo», «Outro»	sim
`versao`	na pesquisa	número inteiro

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/<id>/documentos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/contratos/{id}/documentos/{documentoId}#

Descarrega um documento anexado a um contrato.

Permissão Contratos.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`documentoId`	no caminho	identificador (UUID)	sim

Resposta

Devolve 200 com o ficheiro anexado.

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos/<id>/documentos/<documentoId>' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/contratos/modelos#

Os modelos de contrato.

Permissão Contratos.Ler

apenasActivos (por omissão, verdadeiro).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`apenasActivos`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/contratos/modelos' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/contratos/modelos#

Cria um modelo de contrato.

Permissão Contratos.ModelosEditar
Idempotência aceita Idempotency-Key

Corpo do pedido (JSON · ModeloInput)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`sentido`	uma de: «Cliente», «Fornecedor», «null»	sim
`tipo`	uma de: «ServicosPeriodicos», «Subscricao», «Aluguer», «ProjectoPorMarcos», «Consumo», «ManutencaoComSla», «Fornecimento», «Outro»	sim
`descricao`	texto ou nulo		A descrição.
`clausulas`	texto ou nulo
`duracaoEmMeses`	número inteiro ou nulo
`preAvisoDias`	número inteiro	sim
`renovacao`	uma de: «Nenhuma», «Tacita», «Manual»	sim
`renovacaoMeses`	número inteiro	sim
`revisao`	uma de: «Nenhuma», «PercentualFixo», «Negociada»	sim
`percentagemDeRevisao`	número ou nulo
`prazoPagamentoDias`	número inteiro	sim
`frequencia`	uma de: «Mensal», «Trimestral», «Semestral», «Anual»	sim
`diaDeEmissao`	número inteiro	sim
`antecipada`	verdadeiro/falso	sim
`prazoMinimoDePagamentoDias`	número inteiro ou nulo
`valorAnualMinimo`	número ou nulo
`activo`	verdadeiro/falso		Se está activo.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/modelos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "sentido": "Cliente",
  "tipo": "ServicosPeriodicos",
  "preAvisoDias": 1,
  "renovacao": "Nenhuma",
  "renovacaoMeses": 1,
  "revisao": "Nenhuma",
  "prazoPagamentoDias": 1,
  "frequencia": "Mensal",
  "diaDeEmissao": 1,
  "antecipada": false
}'

PUT/api/contratos/modelos/{id}#

Altera um modelo de contrato.

Permissão Contratos.ModelosEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ModeloInput)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`sentido`	uma de: «Cliente», «Fornecedor», «null»	sim
`tipo`	uma de: «ServicosPeriodicos», «Subscricao», «Aluguer», «ProjectoPorMarcos», «Consumo», «ManutencaoComSla», «Fornecimento», «Outro»	sim
`descricao`	texto ou nulo		A descrição.
`clausulas`	texto ou nulo
`duracaoEmMeses`	número inteiro ou nulo
`preAvisoDias`	número inteiro	sim
`renovacao`	uma de: «Nenhuma», «Tacita», «Manual»	sim
`renovacaoMeses`	número inteiro	sim
`revisao`	uma de: «Nenhuma», «PercentualFixo», «Negociada»	sim
`percentagemDeRevisao`	número ou nulo
`prazoPagamentoDias`	número inteiro	sim
`frequencia`	uma de: «Mensal», «Trimestral», «Semestral», «Anual»	sim
`diaDeEmissao`	número inteiro	sim
`antecipada`	verdadeiro/falso	sim
`prazoMinimoDePagamentoDias`	número inteiro ou nulo
`valorAnualMinimo`	número ou nulo
`activo`	verdadeiro/falso		Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/contratos/modelos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "sentido": "Cliente",
  "tipo": "ServicosPeriodicos",
  "preAvisoDias": 1,
  "renovacao": "Nenhuma",
  "renovacaoMeses": 1,
  "revisao": "Nenhuma",
  "prazoPagamentoDias": 1,
  "frequencia": "Mensal",
  "diaDeEmissao": 1,
  "antecipada": false
}'

POST/api/contratos/gerar-facturas#

Emite os períodos pendentes dos contratos dos estabelecimentos da chave.

Permissão Contratos.Facturar

É o botão «Gerar facturas pendentes»: recupera mais períodos em atraso do que o robô, com um limite por pedido. Devolve o resultado da facturação.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/contratos/gerar-facturas' \
  -H 'X-Api-Key: <a-sua-chave>'