Este tema contém os padrões MDM para classificações de empresas, atividades de empresas, grupos econômicos e a base de dados de empresas cadastradas no MDM
Classificações de empresas (companyClass)
-
Descrição:
Esta entidade padroniza os seguintes atributos de classificações de empresas:- Id
- nome
-
Estrutura dos Campos
Campo Descrição Tipo Link dataId Identificador da classificação de empresa int name nome da classificação de empresa string dataIdentifier identificador de unicidade da entidade string -
Como consultar ultima versão do schema da entidade
- Exemplo de response
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": { "_id": "6408e4832fdf838348471ecd", "entityType": "companyClass", "revision": 3, "dataIdentifierSetup": [ "name" ], "jsonSchema": { "title": "", "required": [ "entityType", "revision", "data" ], "properties": { "entityType": { "title": "companyClass", "pattern": "^(.*)$", "$id": "#/properties/entityType", "type": "string" }, "revision": { "title": "The review of this entity.", "default": 1, "$id": "#/properties/revision", "type": "integer" }, "data": { "title": "The composition of the document object", "$id": "#/properties/data", "type": "object", "required": [ "name" ], "properties": { "name": { "title": "Name of company classification", "$id": "#/properties/data/properties/name", "type": "string", "minLength": 3, "maxLength": 200 }, "dataId": { "title": "The Unique Key for a document of this entity. If you don't know, don't put this in the document and it will be generated automatically.", "$id": "#/properties/data/properties/dataId", "type": "integer" } } } }, "$id": "http://example.org/root.json#", "type": "object", "definitions": {}, "$schema": "http://json-schema.org/draft-07/schema#" }, "authDefinition": { "resources": { "companyClass": { "create": true, "update": true, "delete": true, "view": true } } }, "sensiblePropertiesPath": [], "effectiveDate": "2023-01-24T19:08:20.861Z", "status": true, "deleted": false } }
- Exemplo de response
-
Exemplo de chamada ao endpoint (GET) usando “Query By Template”
-
Exemplo de chamada ao endpoint (GET) usando “data id”
-
Exemplo de chamada ao endpoint (GET) usando “updatedAt”
Você pode usar esse método quando precisar consultar países que foram inseridos ou alterados dentro de um determinado período
-
Retorno do exemplo
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": [ { "_id": "636fed6cdd04eb0288a17e2c", "entityType": "companyClass", "revision": 1, "data": { "name": "Matriz", "dataId": 1, "dataIdentifier": { "name": "Matriz" } }, "createdAt": "2022-11-12T19:01:00.351Z", "deleted": false, "userCreator": "service-account-mdm", "updatedAt": "2022-11-12T19:01:00.351Z" }, { "_id": "636fed75dd04eb0288a17e2e", "entityType": "companyClass", "revision": 1, "data": { "name": "Filial", "dataId": 2, "dataIdentifier": { "name": "Filial" } }, "createdAt": "2022-11-12T19:01:09.660Z", "deleted": false, "userCreator": "service-account-mdm", "updatedAt": "2022-11-12T19:01:09.660Z" }, { "_id": "636fed7ddd04eb0288a17e30", "entityType": "companyClass", "revision": 1, "data": { "name": "Centro de Distribuição", "dataId": 3, "dataIdentifier": { "name": "Centro de Distribuição" } }, "createdAt": "2022-11-12T19:01:17.803Z", "deleted": false, "userCreator": "service-account-mdm", "updatedAt": "2022-11-12T19:01:17.803Z" }, { "_id": "636fed87dd04eb0288a17e32", "entityType": "companyClass", "revision": 1, "data": { "name": "Escritório", "dataId": 4, "dataIdentifier": { "name": "Escritório" } }, "createdAt": "2022-11-12T19:01:27.489Z", "deleted": false, "userCreator": "service-account-mdm", "updatedAt": "2022-11-12T19:01:27.489Z" }, { "_id": "636fed8edd04eb0288a17e34", "entityType": "companyClass", "revision": 1, "data": { "name": "Fábrica", "dataId": 5, "dataIdentifier": { "name": "Fábrica" } }, "createdAt": "2022-11-12T19:01:34.632Z", "deleted": false, "userCreator": "service-account-mdm", "updatedAt": "2022-11-12T19:01:34.632Z" } ], "page": 1, "limit": 6, "nextPageURL": "Last Page" }
Atividades de empresas (companyActivity)
-
Descrição:
Esta entidade padroniza os seguintes atributos de atividades de empresas:- nome
- Id
-
Estrutura dos Campos
Campo Descrição Tipo Link dataId identificador da atividade de empresa int name nome da atividade de empresa string dataIdentifier identificador de unicidade da entidade string -
Como consultar ultima versão do schema da entidade
- Exemplo de response
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": { "_id": "6408e4832fdf838348471ecc", "entityType": "companyActivity", "revision": 3, "dataIdentifierSetup": [ "name" ], "jsonSchema": { "title": "", "required": [ "entityType", "revision", "data" ], "properties": { "entityType": { "title": "companyActivity", "pattern": "^(.*)$", "$id": "#/properties/entityType", "type": "string" }, "revision": { "title": "The review of this entity.", "default": 1, "$id": "#/properties/revision", "type": "integer" }, "data": { "title": "The composition of the document object.", "$id": "#/properties/data", "type": "object", "required": [ "name" ], "properties": { "name": { "title": "Company activity name.", "$id": "#/properties/data/properties/name", "type": "string", "minLength": 3, "maxLength": 200 }, "dataId": { "title": "The Unique Key for a document of this entity. If you don't know, don't put this in the document and it will be generated automatically.", "$id": "#/properties/data/properties/dataId", "type": "integer" } } } }, "$id": "http://example.org/root.json#", "type": "object", "definitions": {}, "$schema": "http://json-schema.org/draft-07/schema#" }, "authDefinition": { "resources": { "companyActivity": { "create": true, "update": true, "delete": true, "view": true } } }, "sensiblePropertiesPath": [], "effectiveDate": "2023-01-24T19:08:11.590Z", "status": true, "deleted": false } }
- Exemplo de response
-
Exemplo de chamada ao endpoint (GET) usando “Query By Template”
-
Exemplo de chamada ao endpoint (GET) usando “data id”
-
Exemplo de chamada ao endpoint (GET) usando “updatedAt”
Você pode usar esse método quando precisar consultar países que foram inseridos ou alterados dentro de um determinado período
-
Retorno do exemplo
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": { "_id": "636fedde062b1fff9d9d0304", "entityType": "companyActivity", "revision": 1, "data": { "name": "Tecnologia da informação e software", "dataId": 1, "dataIdentifier": { "name": "Tecnologia da informação e software" } }, "createdAt": "2022-11-12T19:02:54.163Z", "deleted": false, "userCreator": "service-account-mdm", "updatedAt": "2022-11-12T19:02:54.163Z" } }
Grupos econômicos (economicGroup)
-
Descrição:
Esta entidade padroniza os seguintes atributos de grupos econômicos empresariais:- Id
- nome
-
Estrutura dos Campos
Campo Descrição Tipo Link dataId data.id (identificador) do grupo econômico int name nome do grupo econômico string dataIdentifier identificador de unicidade da entidade string -
Como consultar ultima versão do schema da entidade
- Exemplo de response
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": { "_id": "6408e4862fdf838348471ed6", "entityType": "economicGroup", "revision": 2, "dataIdentifierSetup": [ "name" ], "jsonSchema": { "title": "Economic Group Entity", "required": [ "entityType", "revision", "data" ], "properties": { "entityType": { "title": "economicGroup", "pattern": "^(.*)$", "$id": "#/properties/entityType", "type": "string" }, "revision": { "title": "The review of this entity.", "default": 1, "$id": "#/properties/revision", "type": "integer" }, "data": { "title": "The composition of the document object.", "required": [ "name" ], "$id": "#/properties/data", "type": "object", "properties": { "name": { "title": "Name of Economic Group.", "$id": "#/properties/data/properties/name", "type": "string", "minLength": 1, "maxLenght": 200 }, "dataId": { "title": "The Unique Key for a document of this entity. If you don't know, don't put this in the document and it will be generated automatically.", "$id": "#/properties/data/properties/dataId", "type": "integer" } } } }, "$id": "http://example.org/root.json#", "type": "object", "definitions": {}, "$schema": "http://json-schema.org/draft-07/schema#" }, "authDefinition": { "resources": { "economicGroup": { "create": true, "update": true, "delete": true, "view": true } } }, "sensiblePropertiesPath": [ "name" ], "effectiveDate": "2023-01-23T17:39:21.055Z", "status": true, "deleted": false } }
- Exemplo de response
-
Exemplo de chamada ao endpoint (GET) usando “Query By Template”
-
Exemplo de chamada ao endpoint (GET) usando “data id”
-
Exemplo de chamada ao endpoint (GET) usando “updatedAt”
Você pode usar esse método quando precisar consultar países que foram inseridos ou alterados dentro de um determinado período
-
Retorno do exemplo
Clique em "JSON"
Dados de empresas (company)
-
Descrição:
Esta entidade padroniza os dados cadastrais das empresas. -
Estrutura dos Campos
-
Estrutura dos Campos
Campo Descrição Tipo Link dataId identificador da empresa int name nome da razão social string tradeName nome fantasia string companyClassId [array] identificador da classificação int companyClassId companyClassName [array] nome da classificação string companyClassName companyActivityId [array] identificador do tipo de atividade int companyactivityId companyActivityName [array] nome do tipo de atividade string companyActivityName economicGroupId identificador da grupo econômico int economicGroupId economicGroupName nome do grupo econômico string economicGroupName Main identification document countryId identificador do país do documento principal de identificação int countryId countryName nome do país do documento principal de identificação string countryName documentId identificador do documento principal de identificação int documentId documentName nome do documento principal de identificação string documentName docCategoryId identificador da categoria do documento principal de identificação int docCategoryId docCategoryName nome da categoria do documento principal de identificação string docCategoryName documentData número do documento principal de identificação string docIssuerId identificador do órgão emissor do documento principal de identificação int docIssuerId docIssuerName nome do órgão emissor do documento principal de identificação string docIssuerName provinceIssuerId identificador da provincia/estado do órgão emissor do documento principal de identificação int provinceId provinceIssuerName nome da provincia/estado do órgão emissor do documento principal de identificação string ProvinceName issueDate data de emissão do documento principal de identificação string expirationDate data de vencimento do documento principal de identificação string firstIssueDate data da primeira emissão do documento principal de identificação string docPicture foto do documento principal de identificação base64 complement dados adicionais do documento principal de identificação objeto Document [array] countryId identificador do país do documento int countryId countryName nome do país do documento string countryName documentId identificador do documento int documentId documentName nome do documento string documentName docCategoryId identificador da categoria do documento int docCategoryId docCategoryName nome da categoria do documento string docCategoryName documentData número do documento string docIssuerId identificador do órgão emissor do documento int docIssuerId docIssuerName nome do órgão emissor do documento string docIssuerName provinceIssuerId identificador da provincia/estado do órgão emissor do documento int provinceId provinceIssuerName nome da provincia/estado do órgão emissor do documento string ProvinceName issueDate data de emissão do documento string expirationDate data de vencimento do documento string firstIssueDate data da primeira emissão do documento string docPicture foto do documento base64 complement dados adicionais do documento objeto Address [array] countryId identificador do país int countryId countryName nome do país string countryName cityId identificador da cidade int cityId cityName nome da cidade string cityName provinceId identificador da província/estado int provinceId provinceName nome da província/estado string provinceName zipcode CEP string community bairro string addressTypeId identificador do tipo de endereço int addressTypeId addressTypeName nome do tipo de endereço string addressTypeName address endereço string number número int complement complemento string propertyTypeId identificador do tipo de propriedade imobiliária int propertyTypeId propertyTypeName nome do tipo de propriedade imobiliária string propertyTypeName latitude latitude number longitude longitude number Professional contact [array] communicationTypeId identificador do tipo de comunicação int communicationTypeId communicationTypeName nome do tipo de comunicação string communicationTypeName countryPhoneCode DDI (código de telefone) do país int countryPhoneCode cityPhoneCode DDD (código de telefone) da cidade int cityPhoneCode phoneNumber número do telefone int email e-mail string website website da empresa string Logistic Activity [array] logisticActivityId array de identificadores de atividades logísticas int logisticActivityId logisticActivityName array de nomes de atividades logísticas string logisticActivityName Operation Type [array] operationTypeId array de identificadores de tipos de operação int operationTypeId operationTypeName array de nomes de tipos de operação string operationTypeName dataIdentifier identificador de unicidade da entidade string
-
-
Como consultar ultima versão do schema da entidade
- Exemplo de response
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": { "_id": "6418cfb6ccef2b9e4e9d91f1", "entityType": "company", "revision": 10, "dataIdentifierSetup": [ "identificationDocument.countryId", "identificationDocument.documentId", "identificationDocument.documentData" ], "jsonSchema": { "title": "", "required": [ "entityType", "revision", "data" ], "properties": { "entityType": { "title": "accessoryType", "pattern": "^(.*)$", "$id": "#/properties/entityType", "type": "string" }, "revision": { "title": "The review of this entity.", "default": 1, "$id": "#/properties/revision", "type": "integer" }, "dataId": { "title": "The Unique Key for a document of this entity. If you don't know, don't put this in the document and it will be generated automatically.", "$id": "#/properties/dataId", "type": "integer" }, "data": { "title": "The composition of the document object.", "$id": "#/properties/data", "type": "object", "properties": { "name": { "$id": "#/properties/data/properties/name", "type": "string", "minLength": 3, "maxLength": 200 }, "tradeName": { "$id": "#/properties/data/properties/tradeName", "type": "string", "minLength": 3, "maxLength": 200 }, "companyClass": { "$id": "#/properties/data/properties/companyClass", "type": "object", "properties": { "companyClassId": { "$id": "#/properties/data/properties/companyClass/properties/companyClassId", "type": "array", "items": { "type": "integer" } }, "companyClassName": { "$id": "#/properties/data/properties/companyClass/properties/companyClassName", "type": "array", "items": { "type": "string" } } } }, "companyActivity": { "$id": "#/properties/data/properties/companyActivity", "type": "object", "properties": { "companyActivityId": { "$id": "#/properties/data/properties/companyActivity/properties/companyActivityId", "type": "integer" }, "companyActivityName": { "$id": "#/properties/data/properties/companyActivity/properties/companyActivityName", "type": "string" } } }, "economyGroup": { "$id": "#/properties/data/properties/economyGroup", "type": "object", "properties": { "economyGroupId": { "$id": "#/properties/data/properties/economyGroup/properties/economyGroupId", "type": "integer" }, "economyGroupName": { "$id": "#/properties/data/properties/economyGroup/properties/economyGroupName", "type": "string" } } }, "identificationDocument": { "$id": "#/properties/data/properties/identificationDocument", "type": "object", "properties": { "countryId": { "$id": "#/properties/data/properties/identificationDocument/properties/countryId", "type": "integer" }, "countryName": { "$id": "#/properties/data/properties/identificationDocument/properties/countryName", "type": "string" }, "documentId": { "$id": "#/properties/data/properties/identificationDocument/properties/documentId", "type": "integer" }, "documentName": { "$id": "#/properties/data/properties/identificationDocument/properties/documentName", "type": "string" }, "docCategoryId": { "$id": "#/properties/data/properties/identificationDocument/properties/docCategoryId", "type": "integer" }, "docCategoryName": { "$id": "#/properties/data/properties/identificationDocument/properties/docCategoryName", "type": "string" }, "documentData": { "$id": "#/properties/data/properties/identificationDocument/properties/documentData", "type": "string" }, "docIssuerId": { "$id": "#/properties/data/properties/identificationDocument/properties/docIssuerId", "type": "integer" }, "docIssuerName": { "$id": "#/properties/data/properties/identificationDocument/properties/docIssuerName", "type": "string" }, "provinceIssuerId": { "$id": "#/properties/data/properties/identificationDocument/properties/provinceIssuerId", "type": "integer" }, "provinceIssuerName": { "$id": "#/properties/data/properties/identificationDocument/properties/provinceIssuerName", "type": "string" }, "issueDate": { "$id": "#/properties/data/properties/identificationDocument/properties/issueDate", "type": "string", "minLength": 10, "maxLength": 10 }, "expirationDate": { "$id": "#/properties/data/properties/identificationDocument/properties/expirationDate", "type": "string", "minLength": 10, "maxLength": 10 }, "firstIssueDate": { "$id": "#/properties/data/properties/identificationDocument/properties/firstIssueDate", "type": "string", "minLength": 10, "maxLength": 10 }, "docPicture": { "$id": "#/properties/data/properties/identificationDocument/properties/docPicture", "type": "string" }, "complement": { "$id": "#/properties/data/properties/identificationDocument/properties/complement", "type": "string" } } }, "document": { "$id": "#/properties/data/properties/document", "type": "array", "items": { "type": "object", "properties": { "countryId": { "$id": "#/properties/data/properties/document/properties/countryId", "type": "integer" }, "countryName": { "$id": "#/properties/data/properties/document/properties/countryName", "type": "string" }, "documentId": { "$id": "#/properties/data/properties/document/properties/documentId", "type": "integer" }, "documentName": { "$id": "#/properties/data/properties/document/properties/documentName", "type": "string" }, "docCategoryId": { "$id": "#/properties/data/properties/document/properties/docCategoryId", "type": "integer" }, "docCategoryName": { "$id": "#/properties/data/properties/document/properties/docCategoryName", "type": "string" }, "documentData": { "$id": "#/properties/data/properties/document/properties/documentData", "type": "string" }, "docIssuerId": { "$id": "#/properties/data/properties/document/properties/docIssuerId", "type": "integer" }, "docIssuerName": { "$id": "#/properties/data/properties/document/properties/docIssuerName", "type": "string" }, "provinceIssuerId": { "$id": "#/properties/data/properties/document/properties/provinceIssuerId", "type": "integer" }, "provinceIssuerName": { "$id": "#/properties/data/properties/document/properties/provinceIssuerName", "type": "string" }, "issueDate": { "$id": "#/properties/data/properties/document/properties/issueDate", "type": "string", "minLength": 10, "maxLength": 10 }, "expirationDate": { "$id": "#/properties/data/properties/document/properties/expirationDate", "type": "string", "minLength": 10, "maxLength": 10 }, "firstIssueDate": { "$id": "#/properties/data/properties/document/properties/firstIssueDate", "type": "string", "minLength": 10, "maxLength": 10 }, "docPicture": { "$id": "#/properties/data/properties/document/properties/docPicture", "type": "string" }, "complement": { "$id": "#/properties/data/properties/document/properties/complement", "type": "string" } } } }, "address": { "$id": "#/properties/data/properties/address", "type": "array", "items": { "type": "object", "properties": { "countryId": { "$id": "#/properties/data/properties/address/properties/countryId", "type": "integer" }, "countryName": { "$id": "#/properties/data/properties/address/properties/countryName", "type": "string" }, "cityId": { "$id": "#/properties/data/properties/address/properties/cityId", "type": "integer" }, "cityName": { "$id": "#/properties/data/properties/address/properties/cityName", "type": "string" }, "provinceId": { "$id": "#/properties/data/properties/address/properties/provinceId", "type": "integer" }, "provinceName": { "$id": "#/properties/data/properties/address/properties/provinceName", "type": "string" }, "zipCode": { "$id": "#/properties/data/properties/address/properties/zipCode", "type": "string" }, "community": { "$id": "#/properties/data/properties/address/properties/community", "type": "string" }, "addressTypeId": { "$id": "#/properties/data/properties/address/properties/addressTypeId", "type": "integer" }, "addressTypeName": { "$id": "#/properties/data/properties/address/properties/addressTypeName", "type": "string" }, "addressName": { "$id": "#/properties/data/properties/address/properties/addressName", "type": "string" }, "number": { "$id": "#/properties/data/properties/address/properties/number", "type": "integer" }, "complement": { "$id": "#/properties/data/properties/address/properties/complement", "type": "string" }, "propertyTypeId": { "$id": "#/properties/data/properties/address/properties/propertyTypeId", "type": "integer" }, "propertyTypeName": { "$id": "#/properties/data/properties/address/properties/propertyTypeName", "type": "string" }, "latitude": { "$id": "#/properties/data/properties/address/properties/latitude", "type": "integer" }, "longitude": { "$id": "#/properties/data/properties/address/properties/longitude", "type": "integer" } } } }, "professionalContact": { "$id": "#/properties/data/properties/professionalContact", "type": "array", "items": { "type": "object", "properties": { "communicationTypeId": { "$id": "#/properties/data/properties/professionalContact/properties/communicationTypeId", "type": "integer" }, "communicationTypeName": { "$id": "#/properties/data/properties/professionalContact/properties/communicationTypeName", "type": "string" }, "countryPhoneCode": { "$id": "#/properties/data/properties/professionalContact/properties/countryPhoneCode", "type": "integer" }, "cityPhoneCode": { "$id": "#/properties/data/properties/professionalContact/properties/cityPhoneCode", "type": "integer" }, "phoneNumber": { "$id": "#/properties/data/properties/professionalContact/properties/phoneNumber", "type": "integer" }, "email": { "$id": "#/properties/data/properties/professionalContact/properties/email", "type": "string" }, "website": { "$id": "#/properties/data/properties/professionalContact/properties/website", "type": "string" } } } }, "logisticActivity": { "$id": "#/properties/data/properties/logisticActivity", "type": "array", "items": { "type": "object", "properties": { "logisticActivityId": { "$id": "#/properties/data/properties/logisticActivity/properties/logisticActivityId", "type": "integer" }, "logisticActivityName": { "$id": "#/properties/data/properties/logisticActivity/properties/logisticActivityName", "type": "string" } } } }, "operationType": { "$id": "#/properties/data/properties/operationType", "type": "array", "items": { "type": "object", "properties": { "operationTypeId": { "$id": "#/properties/data/properties/operationType/properties/operationTypeId", "type": "integer" }, "operationTypeName": { "$id": "#/properties/data/properties/operationType/properties/operationTypeName", "type": "string" } } } } } } }, "$id": "http://example.org/root.json#", "type": "object", "definitions": {}, "$schema": "http://json-schema.org/draft-07/schema#" }, "authDefinition": { "resources": { "accessoryType": { "create": true, "update": true, "delete": true, "view": true } } }, "sensiblePropertiesPath": [], "queryTemplates": { "queryByDataIdentifier": { "query": "{ \"data.dataIdentifier\": { \"identificationDocument\": { \"countryId\": paramCountryId, \"documentId\": paramDocumentId, \"documentData\": paramDocumentData }}}", "description": "Get Person by dataIdentifier", "parametersRules": { "paramCountryId": { "type": "integer", "description": "Country Id", "minValue": 0 }, "paramDocumentId": { "type": "integer", "description": "Document Id", "minValue": 0 }, "paramDocumentData": { "type": "string", "description": "Document Number", "minValue": 0 } } }, "queryByDataId": { "query": "{ \"data.dataId\": paramDataId }", "description": "Get Person by dataId", "options": "{\"limit\": 1}", "parametersRules": { "paramDataId": { "type": "integer", "description": "DataId", "minValue": 0 } } }, "queryByObjectId": { "query": "{ \"_id\": paramObjectId }", "description": "Get Person by ObjectId", "parametersRules": { "paramObjectId": { "type": "string", "description": "ObjectId as string" } } } }, "effectiveDate": "2023-03-20T21:27:18.114Z", "status": true, "deleted": false } }
- Exemplo de response
-
Exemplo de chamada ao endpoint (GET) usando “Query By Template”
Produção https://platform.nstech.com.br/api/mdm/entities/company/queryByTemplate/queryByDataIdentifier?paramCountryId=76¶mDocumentId=20¶mDocumentData=26051748000107Homologação https://dev.nstech.com.br/platform/api/mdm-stg/entities/company/queryByTemplate/queryByDataIdentifier?paramCountryId=76&DocumentId=20&DocumentData=26051748000107- Exemplo de retorno
Clique em "JSON"{ "statusCode": 200, "success": true, "message": "Success", "document": [ { "_id": "65133f3e7d6ed3cac0f6c1e7", "status": true, "deleted": false, "updatedAt": "2023-11-14T00:13:54.119Z", "userCreator": "mdm-surrogate", "entityType": "company", "revision": 7, "data": { "name": "\nIR MULTI CONFECCOES LTDA", "identificationDocument": { "countryId": 76, "countryName": "Brasil", "documentId": 20, "documentData": "26051748000107", "documentName": "Cadastro nacional de pessoas jurídicas" }, "tradeName": "\nIR MULTI CONFECCOES LTDA", "document": [ { "countryId": 76, "countryName": "Brasil", "documentId": 20, "documentData": "26051748000107", "documentName": "Cadastro nacional de pessoas jurídicas" } ], "address": [ { "countryId": 76, "countryName": "BRASIL", "provinceId": 31, "provinceName": "MINAS GERAIS", "cityId": 3106200, "cityName": "BELO HORIZONTE", "zipcode": "30494460", "community": "ESTORIL", "address": "RUA WILSON ROCHA LIMA", "number": 25, "complement": "" }, { "countryId": 76, "countryName": "BRASIL", "provinceId": 31, "provinceName": "MINAS GERAIS", "cityId": 3106200, "cityName": "BELO HORIZONTE", "zipcode": "30411023", "community": "PRADO", "address": "RUA ITUIUTABA", "number": 401, "complement": "" }, { "countryId": 76, "countryName": "BRASIL", "provinceId": 31, "provinceName": "MINAS GERAIS", "cityId": 3106200, "cityName": "BELO HORIZONTE", "zipcode": "30494460", "community": "ESTORIL", "address": "RUA WILSON ROCHA LIMA" } ], "professionalContact": [{}], "dataIdentifier": { "identificationDocument": { "documentData": "26051748000107", "documentId": 20, "countryId": 76 } } } } ], "page": 1, "limit": 100 }
- Exemplo de retorno
-
Exemplo de chamada ao endpoint (GET) usando “data id”
-
Método post
As APIs do método POST são usadas para escrita de registro(s) na base do MDM e portanto apenas usuários com permissão de escrita poderão acessá-las
Para uso das APIs POST, não informar dataId do(s) novo(s) registro(s) que serão escritos, pois dataId será automaticamente criado pelo banco de dados
Antes de fazer o post de um documento, você deve consulta ultima versão do schema desse documento, conforme descrito aqui-
save record
Quando devo usar esta API: para escrita individual de um registro em alguma entidade do MDM
Endpoint de produção: https://platform.nstech.com.br/api/mdm/entities/{entityType}
Parâmetros de requisição:
Obrigatórios:
nome da entidade “entityType” (string): Ver “Quadro de entidades MDM” (no início deste tutorial) → a ser informado na URI
documento JSON contendo dados a serem escritos no novo registro
ATENÇÃO:
Os campos obrigatórios da entidade (required) não poderão ser nulos
Demais campos poderão ser nulos e, neste caso, os nomes dos campos que ficarão nulos não deverão ser escritos no documento JSON de chamada
Neste JSON de chamada você deverá informar “entityType” e “revision” da entidade.
Os dados a serem escritos no novo registro deverá seguir a estrutura da última versão do schema da entidade (consultado previamente)
Retorno do endpoint:
mensagem de retorno informando sucesso ou erro na tentativa de escrever o registro
objectId (Id único do banco de dados) do novo registro inserido
dataId (Id único dentro da entidade) do novo registro inserido
Exemplo de chamada
Desejo escreve um novo registro dentro da entidade company
request POST
https://platform.nstech.com.br/api/mdm/entities/company
JSON de chamada com dados do novo registro a ser escrito:
Clique em "JSON"“entityType”: “company”, “revision”: 7, “data”{ “name”: “Transportadora XYZ”, “country”: { “countryId”: 76, “countryName”: “Brasil”, } “tradeName”: “Transportadora XYZ Ltda”, “companyClass”: [ { “companyClassId”: 1, “companyClassName”: “Matriz”, } ], “companyActivity”: [ { “companyActivityId”: 7, “companyActivityName”: “Transportes”, }Clique em "JSON"“identificationDocument”: { “documentId”: 20, “documentName”: “Cadastro nacional de pessoas jurídicas”, “documentData”: 99999999999999, “doctIssuerId”: 197, “docIssuerName”: “Receita federal”, “provinceIssuerId”: 11, “provinceIssuerName”: “Rondônia”, “issueDate”: “04/12/2020”, “firstIssueDate”: “04/12/2020”, }Retorno do exemplo:
JSON contendo mensagem de sucesso/erro na escrita, objectId e dataId do novo registro inserido-
post records by bulk insert
Quando devo usar esta API: para escrita em lote de registros em alguma entidade do MDM
Endpoint de produção: https://platform.nstech.com.br/api/mdm/bulk/{entityType}
Parâmetros de requisição:
Obrigatórios:
nome da entidade “entityType” (string): Ver “Quadro de entidades MDM” (no início deste tutorial) → a ser informado na URI
array de documentos JSON (cada documento do array contém dados de um novo registro a ser escrito) → todos os registros do array devem pertencer a mesma entidade e à mesma versão da entidade
ATENÇÃO:
Os campos obrigatórios da entidade (required) não poderão ser nulos
Demais campos poderão ser nulos e, neste caso, os nomes dos campos que ficarão nulos não deverão ser escritos no documento JSON de chamada
Para cada documento do array você deverá informar “entityType” e “revision” da entidade
Cada documento do array deverá seguir a estrutura da última versão do schema da entidade (consultado previamente)
Retorno do endpoint:
array com mensagem de retorno informando sucesso ou erro na tentativa de escrever cada registro
array contendo objectId (Id único do banco de dados) de cada novo registro inserido
array contendo dataId (Id único dentro da entidade) de cada novo registro inserido
Exemplo de chamada
Desejo escreve um lote de 2 novos registros dentro da entidade company
request POST
https://platform.nstech.com.br/api/mdm/bulk/company
Array de JSON de chamada com dados dos novos registros a serem escritos:
Clique em "JSON"“entityType”: “company”, “revision”: 7, “data”{ “name”: “Transportadora XYZ”, “country”: { “countryId”: 76, “countryName”: “Brasil”, } “tradeName”: “Transportadora XYZ Ltda”, “companyClass”: [ { “companyClassId”: 1, “companyClassName”: “Matriz”, } ], “companyActivity”: [ { “companyActivityId”: 7, “companyActivityName”: “Transportes”, } ], “identificationDocument”: { “documentId”: 20, “documentName”: “Cadastro nacional de pessoas jurídicas”, “documentData”: 99999999999999, “doctIssuerId”: 197, “docIssuerName”: “Receita federal”, “provinceIssuerId”: 11, “provinceIssuerName”: “Rondônia”, “issueDate”: “04/12/2020”, “firstIssueDate”: “04/12/2020”, } }Clique em "JSON"“entityType”: “company”, “revision”: 7, “data”{ “name”: “Rastreadora XYZ”, “country”: { “countryId”: 76, “countryName”: “Brasil”, } “tradeName”: “Rastreadora XYZ Ltda”, “companyClass”: [ { “companyClassId”: 1, “companyClassName”: “Matriz”, } ], “companyActivity”: [ { “companyActivityId”: 4, “companyActivityName”: “Empresa de rastreamento”, } ], “identificationDocument”: { “documentId”: 20, “documentName”: “Cadastro nacional de pessoas jurídicas”, “documentData”: 77777777777, “doctIssuerId”: 197, “docIssuerName”: “Receita federal”, “provinceIssuerId”: 23, “provinceIssuerName”: “Ceará”, “issueDate”: “15/07/1988”, “firstIssueDate”: “15/07/1988”, } }Retorno do exemplo:
array de JSON com mensagem de sucesso/erro na escrita, objectId e dataId de cada novo registro inserido
Caso haja erro na escrita de algum registro, o erro será individual e os demais registros poderão ser inseridos -
-
Método patch
As APIs do método PATCH são usadas para edição de registro(s) na base do MDM e portanto apenas usuários com permissão de escrita poderão acessá-las
Quando devo usar esta API: para editar um ou mais registros dentro de uma entidade do MDM
O que você deve saber antes de um PATCH qualquer:
Você deverá consultar o schema da entidade em sua última versão para obter as seguintes informações:-
revision: é o número da última revisão da entidade;
-
nome dos campos existentes na entidade;
-
tipo de cada campo existente na entidade (type);
Estas informações serão utilizadas para montar o JSON (documento contendo os campos a serem atualizados no novo registro)
Esta consulta prévia é feita através do seguinte endpoint, que mostra a estrutura do schema da entidade em sua última revisão:
Ambiente de produção: https://platform.nstech.com.br/api/mdm/schema/latestRevision/{entityType}
entityType é o nome da entidade (string): Ver “Quadro de entidades MDM” (no início deste tutorial)
O retorno da chamada ao endpoint acima é um JSON contendo a estrutura do schema da entidade em sua última versão
-
patch record by entityType and dataId
Quando devo usar esta API: para edição individual de um registro em alguma entidade do MDM, informando nome da entidade e dataId do registro
Endpoint de produção: https://platform.nstech.com.br/api/mdm/entities/dataId/{entityType}/{dataId}
Parâmetros de requisição:
Obrigatórios:
nome da entidade “entityType” (string): Ver “Quadro de entidades MDM” (no início deste tutorial) → a ser informado na URI
dataId do registro (number) → a ser informado na URI
documento JSON contendo apenas os dados a serem atualizados no registro
ATENÇÃO:
Neste JSON de chamada você deverá informar “entityType” e “revision” da entidade.
Os dados a serem atualizados no novo registro deverá seguir a estrutura da última versão do schema da entidade (consultado previamente)
Retorno do endpoint:
mensagem de retorno informando sucesso ou erro na tentativa de atualizar o registro
Exemplo de chamada
Desejo editar o campo “name” do registro cujo dataId = 120 dentro da entidade company
request PATCH
https://platform.nstech.com.br/api/mdm/entities/dataId/company/120
JSON de chamada com dados do registro a ser editado:
Clique em "JSON"“entityType”: “company”, “revision”: 7, “data”{ “name”: “Transportadora XYZ”,Retorno do exemplo:
mensagem de retorno informando sucesso ou erro na tentativa de atualizar o registro-
patch record by entityType and objectId
Quando devo usar esta API: para edição individual de um registro em alguma entidade do MDM, informando nome da entidade e objectId do registro
Endpoint de produção: https://platform.nstech.com.br/api/mdm/entities/{entityType}/{objectId}
Parâmetros de requisição:
Obrigatórios:
nome da entidade “entityType” (string): Ver “Quadro de entidades MDM” (no início deste tutorial) → a ser informado na URI
objectId do registro (number) → a ser informado na URI
documento JSON contendo apenas os dados a serem atualizados no registro
ATENÇÃO:
Neste JSON de chamada você deverá informar “entityType” e “revision” da entidade.
Os dados a serem atualizados no novo registro deverá seguir a estrutura da última versão do schema da entidade (consultado previamente)
Retorno do endpoint:
mensagem de retorno informando sucesso ou erro na tentativa de atualizar o registro
Exemplo de chamada
Desejo editar o campo “name” do registro cujo objectId (_Id) = 63750efecff33738b407fe99 dentro da entidade company
request PATCH
https://platform.nstech.com.br/api/mdm/entities/company/63750efecff33738b407fe99
JSON de chamada com dados do registro a ser editado:
Clique em "JSON"“entityType”: “company”, “revision”: 7, “data”{ “name”: “Transportadora XYZ”,Retorno do exemplo:
mensagem de retorno informando sucesso ou erro na tentativa de atualizar o registro
-
patch records by bulk update
Quando devo usar esta API: para edição em lote de vários registros dentro de uma entidade do MDM
Endpoint de produção: https://platform.nstech.com.br/api/mdm//bulk/{entityType}
Parâmetros de requisição:
Obrigatórios:
nome da entidade “entityType” (string): Ver “Quadro de entidades MDM” (no início deste tutorial) → a ser informado na URI
objectId do registro (number) → a ser informado na URI
array de documento JSON contendo dataId e dados a serem atualizados em cada registro do array
ATENÇÃO:
Para cada documento do array você deverá informar dataId do registro a ser atualizado
Para cada documento do array você deverá informar “entityType” e “revision” da entidade
Cada documento do array deverá seguir a estrutura da última versão do schema da entidade (consultado previamente)
Retorno do endpoint:
mensagem de retorno informando sucesso ou erro na tentativa de atualizar o registro
Se sucesso, será informado o número de documentos encontrados e o número de documentos modificados
Exemplo de chamada
Desejo editar o campo “name” do registro cujo dataId = 120 e o campo “tradeName” do registro cujo dataId = 55, ambos dentro da entidade company
request PATCH
https://platform.nstech.com.br/api/mdm//bulk/company
Array de JSON de chamada com dados dos registros a serem editados:“dataId”: 120,
“entityType”: “company”,
Clique em "JSON"“revision”: 7, “data”{ “name”: “Transportadora XYZ”, }Clique em "JSON"“dataId”: 55, “entityType”: “company”, “revision”: 7, “data”{ “tradeName”: “Transportadora XYZ Ltda”, }Retorno do exemplo:
mensagem de retorno informando sucesso ou erro na tentativa de atualizar o registro
****número de registros encontrados
número de registros alterados -
-
Códigos de retornos
Os possíveis códigos de status das API´s do MDM são:
Nome do Status Código Significado OK 200 Sucesso Created 201 Sucesso. Novo recurso foi criado No content 204 Não há conteúdo para enviar para esta solicitação, mas os cabeçalhos podem ser úteis Multiple response 207 Um ou mais registros possuem retornos diferentes Not modified 304 Uso para propósito de cache Bad request 400 O servidor não pode processar esta requisição. Sintaxe inválida Unauthorized 401 Usuário deve autenticar para proceder com a requisição Not found 404 Recurso não encontrado pelo servidor Not acceptable 406 Conteúdo não encontrado Conflict 409 O servidor não pode processar esta requisição. Conflito com recurso existente no servidor Possivelmente dataId ou dataIdentifier duplicado Gone 410 Os recursos requisitados foram permanentemente removidos do servidor Internal server error 500 Servidor encontrou uma situação a qual não sabe lidar
Insira nos campos param, param2 e param3 as informações relativas as CountryId, DocumentId e DocumentData, respectivamente.