Histórico da Página

...

Bloco de código

language	js
title	Contract 2.000 - OpenAPI - segmentado
collapse	true

{
  "openapi": "3.0.0",
  "info(...),
  "components": {
    "descriptionschemas": "Contrato",{
      "versionContractModel": "2.000",{
        "titletype": "Contractobject",
    "contact": {
      "nameproperties": "T-Talk"
{
      }
  },
  "pathsCompanyId": {
    "/Contract": {
        "gettype": {"string"
         "operationId": "contractgetall" },
          "descriptionBranchId": {
 "Obtem  os contratos",
        "responsestype": {"string"
          },
          "200CompanyInternalId": {
            "descriptiontype": "Resposta OKstring",
          },
  "content        "InternalId": {
              "application/jsontype": {
"string"
          },
          "schemaContractNumber": {
                  "$reftype": "#/components/schemas/ContractModelstring"
                }},
          "ContractReview": {
   }
            }"type": "string"
          },
        }
    "ProjectInternalId": {
    }
    }
  },
  "serverstype": [{"string"
      "url": "http://api.totvs.com.br/"
    },
  ],
   "components": {
    "schemasBeginDate": {
      "ContractModel": {
        "type": "objectstring",
            "propertiesformat": {"date-time"
          "CompanyId": {
  },
          "typeFinalDate": "string"
    {
      },
          "BranchIdtype": {"string",
            "typeformat": "stringdate-time"
          },
          "CompanyInternalIdCustomerCode": {
            "type": "string"
          },
          "InternalIdCustomerInternalId": {
            "type": "string"
          },
          "ContractNumberContractTotalValue": {
            "type": "number",
            "format": "stringfloat"
          },
          "ContractReviewContractTypeCode": {
            "type": "string"
          },
          "ProjectInternalIdContractTypeInternalId": {
            "type": "string"
          },
          "BeginDateListOfSheet": {
            "type": "stringarray",
            "formatitems": "date-time"
{
            },
  "$ref": "#/components/schemas/SheetModel"
           "FinalDate": {}
          }
  "type": "string",
      },
        "formatdescription": "date-timeContrato"
          },
          "CustomerCodeSheetModel": {
            "type": "stringobject",
          },"properties": {
          "CustomerInternalIdSheetNumber": {
            "type": "string"
          },
          "ContractTotalValueSheetTypePoperty": {
            "type": "numberstring",
          },
  "format": "float"
       "UnitPrice": {
  },
          "ContractTypeCodetype": {"number",
            "typeformat": "stringfloat"
          },
          "ContractTypeInternalIdSheetTotalValue": {
            "type": "stringnumber",
            "format": "float"
          },
          "ListOfSheetListOfItem": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SheetModelItemModel"
            }
          }
        },
        "description": "Contrato"
      },
      "SheetModelItemModel": {
        "type": "object",
        "properties": {
          "SheetNumberItemCode": {
            "type": "string"
          },
          "SheetTypePopertyItemInternalId": {
            "type": "string"
          },
          "UnitPriceAccountantAcountCode": {
            "type": "numberstring",
          },
          "formatAccountantAcountInternalId": "float"{
          },
  "type": "string"
       "SheetTotalValue": {
  },
          "typeCostCenterCode": "number",{
            "formattype": "floatstring"
          },
          "ListOfItemCostCenterInternalId": {
            "type": "arraystring",

          },
          "itemsAccountingItemCode": {
              "$reftype": "#/components/schemas/ItemModelstring"
            },
          }
        }"AccountingItemInternalId": {
      },
      "ItemModel": {
        "type": "objectstring",
         "properties": { },
          "ItemCodeClassValueCode": {
            "type": "string"
          },
          "ItemInternalIdClassValueInternalId": {
            "type": "string"
          },
          "AccountantAcountCodeItemQuantity": {
            "type": "string"
          },
          "AccountantAcountInternalId": {number",
            "typeformat": "stringfloat"
          },
          "CostCenterCodeItemUnitPrice": {
            "type": "stringnumber",
          },  "format": "float"
          "CostCenterInternalId": {},
            "typeItemTotalValue": "string"
        {
  },
          "AccountingItemCodetype": {"number",
            "typeformat": "stringfloat"
          },
          "AccountingItemInternalIdPercentageOfDiscount": {
            "type": "stringnumber",
          },
          "ClassValueCodeformat": {"float"
          }
  "type": "string"
      }
      },
          "ClassValueInternalId": {
            "type": "string"
          },
          "ItemQuantity": }
  }
}

Consequentemente, esta segmentação será refletida nos endpoints das APIs. Tomando por base a divisão realizada, teríamos o seguinte template:

/v2.000/contracts/{ContractNumber}/sheets/{SheetNumber}/items/{ItemCode}

Neste template, temos as seguintes considerações:

No nível de contracts utilizamos o submodelo ContractModel. Nos atributos ListOfSheet e ListOfItem, utilizamos os submodelos SheetModel e ItemModel quando os mesmos forem expandidos.
No nível de sheets, utilizamos apenas o submodelo SheetModel. O modelo ItemModel será utilizado quando o atributo ListOfItem for expandido.
No nível de items, utilizamos apenas o submodelo ItemModel.
Observe a equivalencia entre o item do modelo e o item de path correspondente:
- ListOfSheet (atributo de ContractModel) equivale a sheets.
- ListOfItem (atributo de SheetModel) equivale a items.

Nos exemplos a seguir veremos a utilização dos possíveis endpoints e seus respectivos modelos:

Inclusão de um contrato de forma completa

Bloco de código

language	js
title	POST /v2.000/contracts/
collapse	true

{
  "CompanyId": "1",
  "BranchId": "1",
  "CompanyInternalId": "1",
  "InternalId": "1|1|1",
  "ContractNumber": "1",
  "ContractReview": "1",
  "ProjectInternalId": "1|1",
  "BeginDate": "2018-07-25T14:24:00",
  "FinalDate": "2019-07-25T14:24:00",
  "CustomerCode": "1",
  "CustomerInternalId": "1",
  "ContractTotalValue": 1.0,
  "ContractTypeCode": "1",
  "ContractTypeInternalId": "1",
  "ListOfSheet": [{
      "SheetNumber": "1",
      "SheetTypePoperty": "1",
      "UnitPrice": 1.0,
      "SheetTotalValue": 1.0,
      "ListOfItem": [{
          "ItemCode": "1",
          "ItemInternalId": "1|1",
          "AccountantAcountCode": "0001",
          "AccountantAcountInternalId": "1|0001",
          "CostCenterCode": "1",
          "CostCenterInternalId": "1|1",
          "AccountingItemCode": "111",
          "AccountingItemInternalId": "1|111",
          "ClassValueCode": "001",
          "ClassValueInternalId": "1|001",
          "ItemQuantity": 1.0,
          "ItemUnitPrice": 1.0,
          "ItemTotalValue": 1.0,
          "PercentageOfDiscount": 0.0
        }
      ]
    }
  ]
}

Inclusão de um contrato sem folhas (se a regra de negócio permitir)

Bloco de código

language	js
title	POST /v2.000/contracts/
collapse	true

{
  "CompanyId": "1",
  "BranchId": "1",
  "CompanyInternalId": "1",
  "InternalId": "1|1|1",
  "ContractNumber": "1",
  "ContractReview": "1",
  "ProjectInternalId": "1|1",
  "BeginDate": "2018-07-25T14:24:00",
  "FinalDate": "2019-07-25T14:24:00",
  "CustomerCode": "1",
  "CustomerInternalId": "1",
  "ContractTotalValue": 1.0,
  "ContractTypeCode": "1",
  "ContractTypeInternalId": "1",
  "ListOfSheet": []
}

Recuperando contratos (apenas cabeçalho, 1a página, até o limite de uma página)

Bloco de código

language	js
title	GET /v2.000/contracts
collapse	true

{
  "hasNext": false,
  "items": [{
      "_expandables": ["ListOfSheet"],
      "CompanyId": "1",
      "BranchId": "1",
      "CompanyInternalId": "1",
      "InternalId": "1|1|1",
      "ContractNumber": "1",
      "ContractReview": "1",
      "ProjectInternalId": "1|1",
      "BeginDate": "2018-07-25T14:24:00",
      "FinalDate": "2019-07-25T14:24:00",
      "CustomerCode": "1",
      "CustomerInternalId": "1",
      "ContractTotalValue": 1.0,
      "ContractTypeCode": "1",
      "ContractTypeInternalId": "1",
      "ListOfSheet": []
    }
  ]
}

Recuperando um contrato, expandindo os atributos ListOfSheet e ListOfItem

Bloco de código

language	js
title	GET /v2.000/contracts/1?expand=ListOfSheet.ListOfItem
collapse	true

{
  "_expandables": ["ListOfSheet"],
  "CompanyId": "1",
  "BranchId": "1",
  "CompanyInternalId": "1",
  "InternalId": "1|1|1",
  "ContractNumber": "1",
  "ContractReview": "1",
  "ProjectInternalId": "1|1",
  "BeginDate": "2018-07-25T14:24:00",
  "FinalDate": "2019-07-25T14:24:00",
  "CustomerCode": "1",
  "CustomerInternalId": "1",
  "ContractTotalValue": 1.0,
  "ContractTypeCode": "1",
  "ContractTypeInternalId": "1",
  "ListOfSheet": [{
      "_expandable": ["ListOfItem"],
      "SheetNumber": "1",
      "SheetTypePoperty": "1",
      "UnitPrice": 1.0,
      "SheetTotalValue": 1.0,
      "ListOfItem": [{
          "ItemCode": "1",
          "ItemInternalId": "1|1",
          "AccountantAcountCode": "0001",
          "AccountantAcountInternalId": "1|0001",
          "CostCenterCode": "1",
          "CostCenterInternalId": "1|1",
          "AccountingItemCode": "111",
          "AccountingItemInternalId": "1|111",
          "ClassValueCode": "001",
          "ClassValueInternalId": "1|001",
          "ItemQuantity": 1.0,
          "ItemUnitPrice": 1.0,
          "ItemTotalValue": 1.0,
          "PercentageOfDiscount": 0.0
        }
      ]
    }
  ]
}

Incluindo uma folha no contrato

Bloco de código

language	js
title	POST /v2.000/contracts/1/sheets
collapse	true

{
  "SheetNumber": "1",
  "SheetTypePoperty": "1",
  "UnitPrice": 1.0,
  "SheetTotalValue": 1.0,
  "ListOfItem": [{
            "type"ItemCode": "number1",
            "formatItemInternalId": "float"
          }1|1",
          "ItemUnitPrice": {
"AccountantAcountCode": "0001",
      "AccountantAcountInternalId": "1|0001",
      "typeCostCenterCode": "number1",
      "CostCenterInternalId": "1|1",
      "formatAccountingItemCode": "float111",
          }"AccountingItemInternalId": "1|111",
          "ItemTotalValueClassValueCode": {"001",
      "ClassValueInternalId": "1|001",
      "typeItemQuantity": "number"1.0,
      "ItemUnitPrice": 1.0,
      "formatItemTotalValue": "float"1.0,
      "PercentageOfDiscount": 0.0
    },
          "PercentageOfDiscount": {
            "type": "number]
}

Incluindo um item de uma folha do contrato

Bloco de código

language	js
title	POST /v2.000/contracts/1/sheets/1/items
collapse	true

{
  "ItemCode": "1",
  "ItemInternalId": "1|1",
  "AccountantAcountCode": "0001",
  "AccountantAcountInternalId": "1|0001",
  "CostCenterCode": "1",
  "CostCenterInternalId": "1|1",
   "formatAccountingItemCode": "float111",
          }"AccountingItemInternalId": "1|111",
        }"ClassValueCode": "001",
      }"ClassValueInternalId": "1|001",
    }
  }
}

Consequentemente, esta segmentação será refletida nos endpoints das APIs. Tomando por base a divisão realizada, teríamos o seguinte template:

/v2.000/Contracts/{ContractNumber}/Sheets/{SheetNumber}/Items/{ItemCode}

Neste template, temos as seguintes considerações:

No nível de Contracts utilizamos o submodelo ContractModel. Nos atributos ListOfSheet e ListOfItem, utilizamos os submodelos SheetModel e ItemModel quando os mesmos forem expandidos.
No nível de Sheets, utilizamos apenas o submodelo SheetModel. O modelo ItemModel será utilizado quando o atributo ListOfItem for expandido.
No nível de Items, utilizamos apenas o submodelo ItemModel.

Nos exemplos a seguir veremos a utilização dos endpoints e seus respectivos modelos:

POST /v2.000/Contracts - para inclusão de contratos de forma completa.
GET /v2.000/Contracts - para recuperar a lista de contratos. Nesta chamada podemos retornar apenas os cabeçalhos. As folhas do contrato (Sheets) seriam um item a expandir, assim como os itens (Items).
GET /v2.000/Contracts/100?expand=ListOfSheet - para recuperar um contrato específico, expandindo o atributo ListOfSheet.
POST /v2.000/Contracts/100/Sheets - para incluir uma folha num contrato existente.
DELETE /v2.000/Contracts/100/Sheets/2/Items/1 - para eliminar o item 1 da folha 2 do contrato 100.

...

"ItemQuantity": 1.0,
  "ItemUnitPrice": 1.0,
  "ItemTotalValue": 1.0,
  "PercentageOfDiscount": 0.0
}

Eliminando um item de uma folha

DELETE /v2.000/contracts/1/sheets/1/items/1

Eliminando uma folha de um contrato

DELETE /v2.000/contracts/1/sheets/1

Links relacionados

Guia de implementação de APIs TOTVS

Elaboração de mensagem padronizada REST/JSON

Elaboração de mensagem padronizada SOAP/XML

Repositório de mensagens padronizadas (TFS) - STABLE - requer login TOTVS para acesso

Repositório de mensagens padronizadas (TFS) - DEV - requer login TOTVS para acesso

Especificação OpenAPI 3.0

Editor Swagger/OpenAPI - permite a criação de documentos Swagger 2.0 ou OpenAPI 3.0 através da edição de tags YAML.

Conversor Swagger 2.0 para OpenAPI - converte um documento Swagger 2.0 em um documento OpenAPI 3.0.

Modelador de APIs Restlet Studio - permite a modelagem de APIs (endpoints, tipos de dados, etc.) gerando documentação em Swagger 2.0 e RAML 1.0.

Atalhos

Páginas filhas

Versões comparadas

Versão antiga 3

Nova versão 4

Chave

Links relacionados