Existem várias formas de usar nossa API. Aqui você encontrará alguns exemplos de como utilizá-las para conectar com seus negócios conosco. Como nossas APIs você poderá recuperar dados, criar, editar e remover documentos do Nimbi.
Recursos são grupos de informações importantes como por exemplo PurchaseOrder, Requisition, ASN e outros. Vamos ver mais abaixo.
A maioria das operações disponíveis nas nossas APIs são o que chamamos de de CRUD. Que é um acrônimo para Criar, Ler (Read do inglês), Editar (Update do inglês) e Remover (Delete do inglês). Cada operação tem um método HTTP associado. POST, GET, PUT e DELETE.
| Criar | POST |
| Ler | GET |
| Editar | PUT |
| Remover | DELETE |
Autenticação é a primeira coisa que você deve fazer para utilizar nossas APIs. Se você já leu nossa página Sobre nossa API, você já sabe que uma requisição HTTP utiliza Cabeçalhos (Headers do inglês) e a Nimbi utiliza dois cabeçalhos específicos para autenticar você. Toda requisição que você fará nas nossas APIs DEVEM informá-las. Veja os cabeçalhos ClientAPI_ID e ClientAPI_Key no exemplo abaixo:
curl --request GET \
--url 'https://api001.nimbi.com.br/API/rest/ConnectivityTest/v1/TestConnectivity \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]'
Para ter essas informações, por favor, entre em contato.
A paginação baseada em offset e limit é utilizada para realizar um deslocamento de registros.
Em outras palavras, você especifica no offset a partir de qual registro você quer os dados, e no limit você especifica o limite de registros a serem retornados.
• Paginação sequencial
Paginação onde o offset inicial será 0 ou 1 e as próximas páginas serão o offset + 1
Exemplo de paginação iniciada em 0:
Se uma consulta retorna 25 registros, a primeira página offset=0, segunda página offset=1, terceira página offset=2...
Exemplo de paginação iniciada em 1:
Se uma consulta retorna 25 registros, a primeira página offset=1, segunda página offset=2, terceira página offset=3...
• Paginação baseada no limit
Paginação onde a página inicial é 0 e a próxima página será a soma do offset + limit
Exemplo:
Se uma consulta retorna 25 registros e o limit configurado é = 5, a primeira página offset=0, segunda página offset=5, terceira página offset=10, quarta página offset=15 ...
Nós oferecemos duas opções para recuperar dados do Nimbi. Você pode recuperar uma lista de recursos usando filtros ou você pode recuperar um recurso diretamente utilizando seu Identificado Único (ID). Nós recomendamos que você sempre priorize recuperar recursos pelo seu ID para uma melhor performance. Para recuperar dados você sempre irá utilizar o método HTTP chamado GET. Por exemplo:
curl --request GET \
--url 'https://api001.nimbi.com.br/API/rest/PurchaseOrder/v2/{PurchaseOrderId}' \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]'
Se você desejar listar alguns recursos você deve utilizar os filtros disponíveis para cada API. Por exemplo:
curl --request GET \
--url 'https://api001.nimbi.com.br/API/rest/PurchaseOrder/v2?OrderStatusId=3&InitialDate=2018-01-15T14:30:00Z&FinalDate=2018-01-15T14:39:59Z' \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]' \
--header 'QueryLimit: 20'
Criar um recurso é muito simples quando você está usando nossa API. Você sempre irá utilizar o método HTTP chamado POST para criar novos recursos no Nimbi. Por exemplo:
curl --request POST \
--url 'https://api001.nimbi.com.br/API/rest/PurchaseOrder/v2' \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"PurchaseOrder": {
"Title": "PEDIDO DE COMPRA",
"PriorityCode": "Normal",
"IsAddressByOrder": true,
"OrderStatusCode": "Draft",
"DeliveryAddressExternalId": "02",
"PaymentAddressExternalId": "01",
"SupplierCompanyTaxNumber": "55875685000101",
"SupplierCountryCode": "BR",
"TotalPrice": 0,
"TotalQtdItems": "1",
"CreatedBy": "usuarioimplantacao@nimbi.com.br",
"CreatedDate": "2018-03-08T14:54:58Z",
"UpdatedBy": " usuarioimplantacao@nimbi.com.br",
"UpdatedDate": "2018-03-26T17:57:04Z",
"PaymentTypeCode": "15DD",
"DocumentFormCode": "PEDIDO_2",
"IncotermCode": "CIF",
"IncotermExtraInfoCode": "N/A",
"FilialCode": "03",
"PurchasingOrganizationCode": "01",
"CurrencyCode": "",
"BuyerContact": " usuarioimplantacao@nimbi.com.br",
"CodeERP": "14",
"Attachs": [
{
"FileName": "anexo pedido",
"Attach": "UEsDBBQABgAIAAAAIQB8bJgWbAEAAKAFAAATAAgCW0NvbnRlbnRfVHlwZXNdLnhtbCCiBAIooAAC"
}
]
},
"ListOrderItems": [
{
"Code": "12345",
"ShortDescription": "Serviço de Taxi",
"LongDescription": "Serviço de motorista de Taxi / Uber",
"Quantity": 1,
"UnitPrice": 1000,
"TotalPrice": 0,
"DeliveryDeadline": 5,
"UnitOfMeasureCode": "SV",
"CatalogItemId": 118937,
"CategoryId": "C3002",
"NatureOfOperationCode": "S02",
"ItemClassificationId": "2",
"PER": "1"
}
]
}'
Assim como na criação, editar um recurso também utilizar um método HTTP só que um conhecido como PUT. Alguns recursos podem ser editados mas há regras de negócios, esteja atento. Antes de começar, você deve saber se o recurso que está tentando editar tem essa opção. Pedidos de Compras (PurchaseOrder) são editáveis apenas se estiverem no estado "Em Composição". Vamos ver um exemplo:
curl --request PUT \
--url 'https://api001.nimbi.com.br/API/rest/PurchaseOrder/v1/{PurchaseOrderId}' \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"PurchaseOrder": {
"Id": 33338,
"Title": "Pedido de Compra ",
"PriorityCode": "Normal",
"IsAddressByOrder": true,
"OrderStatusCode": "Approved",
"DeliveryAddressExternalId": "02",
"DeliveryAddressDescription": "ALAMEDA VICENTE PINZON, 51 - 6° ANDAR| ALAMEDA VICENTE PINZON, 51 - 6° ANDAR - VILA OLIMPIA - São Paulo, - VILA OLIMPIA - São Paulo| SP| 04547130| CNPJ:62829178000105",
"PaymentAddressExternalId": "01",
"PaymentAddressDescription": "RUA DO PASSEIO 62A, 10° ANDAR| RUA DO PASSEIO 62A, 10° ANDAR - VILA SAN MARTIN - Rio de Janeiro, - VILA SAN MARTIN - Rio de Janeiro| RJ| 20021290| CNPJ:13432689000175",
"SupplierCompanyTaxNumber": "79197257000135",
"TotalPrice": 100,
"TotalQtdItems": "1",
"CreatedBy": "usuarioimplantacao@nimbi.com.br",
"CreatedDate": "2018-05-07T16:39:51Z",
"UpdatedBy": "usuarioimplantacao@nimbi.com.br",
"UpdatedDate": "2018-05-07T16:42:39Z",
"PaymentTypeCode": "30DD",
"PaymentTypeDescription": "Pagamento em 30 dias após a entrega da NF",
"DocumentFormCode": "PEDIDOSEMWF",
"CodeERP": "12345",
"CreatedDateERP": "1900-01-01",
"CompanyCurrencyISO": "BRL",
"BuyerCountryCode": "BR",
"BuyerTaxNumber": "49317000000109",
"BuyerContact": "usuarioimplantacao@nimbi.com.br",
"SupplierCompanyName": "Mailinator 01",
"ListComment": [
{
"Id": 140653,
"Comment": "TESTEEEEEEE",
"IsPublic": true
}
],
"ListAttribute": [
{
"Code": "2",
"Name": "CAMPO FLEXIVEL NO HEADER(CABEÇALHO)"
}
]
},
"ListOrderItems": [
{
"Id": 219112,
"Code": "12345678",
"ShortDescription": "Serviço de Taxi",
"LongDescription": "Serviço de motorista de Taxi / Uber",
"Quantity": 100,
"UnitPrice": 1,
"TotalPrice": 100,
"DeliveryDeadline": 1,
"PaymentTypeCode": "30DD",
"PaymentTypeDescription": "Pagamento em 30 dias após a entrega da NF",
"UnitOfMeasureCode": "SV",
"UnitOfMeasureDescription": "Serviço",
"CatalogItemId": 119371,
"NatureOfOperationCode": "S02",
"NatureOfOperationDescription": "S02 - S02 - Uso e Consumo",
"ItemClassificationId": 2,
"CompanyCurrencyId": 540,
"DeliveryDate": "2018-05-08",
"ItemStatus": "Active",
"PER": "1",
"RequisitionNumber": "174612",
"RequesterName": "setupimplantacao@nimbi.com.br",
"RequesterContact": "setupimplantacao@nimbi.com.br",
"TaxesOrdemItem": {
"TaxReplacementCode": "Not informed"
},
"Origin": {
"originType": "COMPRA_REQUEST_ITEM",
"originId": "182854",
"originCodeERP": "18"
},
"OriginRequisition": {
"RequisitionId": 174612,
"CodeERP": "18"
}
}
]
}'
O exemplo acima edita todos os campos de um recurso. O método PUT também pode alterar o estado de um recurso. Por exemplo:
curl --request PUT \
--url 'https://api001.nimbi.com.br/API/rest/PurchaseOrder/v1/{PurchaseOrderId}/Accepted' \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]' \
--header 'Content-Type: application/json' \
--data '{
"Comment": "Aprovado pelo setor responsável",
"Username": "fulano@empresa.com.br",
"ReferenceCodeSupplier": "450012335"
}'
Para essa operação, você irá utilizar o métdo DELETE. Assim como a operação Editar você deve saber se as regras negócios permitem apagar um recurso. Normalmente os recursos não apagados, mas há exceções. Por exemplo:
curl --request DELETE \
--url 'https://api001.nimbi.com.br/API/rest/PurchaseOrder/v1/Items/{PurchaseOrderId}' \
--header 'ClientAPI_ID: [YOUR_ID]' \
--header 'ClientAPI_Key: [YOUR_KEY]' \
--header 'Content-Type: application/json' \
--data '[
{
"ItemId": 8242
}
]'
Nós oferecemos uma documentação completa para cada API que nós temos. Veja mais na sessão
API Explorer e divirta-se.