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.
Operações CRUD
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 API Key
A autenticação é o primeiro passo fundamental para utilizar nossas APIs. Todas as requisições HTTP devem incluir cabeçalhos específicos para sua autenticação na Nimbi. É mandatório que estas informações estejam presentes em cada chamada à API. Consulte 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]'
Autenticação OAuth 2.0
O OAuth 2.0 Client Credentials Grant permite que um aplicativo se autentique diretamente (com client_id e client_secret) para acessar APIs, sem envolver um usuário, comunicação de máquina para máquina.
Disponível somente para APIs do comprador no Private Documentação A requisição para obtenção do access_token deve ser enviada via HTTPS POST para o endpoint /oauth/rest/token/v1
https://api001.nimbi.com.br/oauth/rest/token/v1
A autenticação do cliente é realizada via HTTP Basic Authentication. O client_id e o client_secret devem ser concatenados com dois-pontos (:) e o resultado codificado em Base64. Esta string codificada deve ser incluída no cabeçalho Authorization, precedida pelo esquema Basic. Authorization: Basic <Base64(client_id:client_secret)>
Corpo da Requisição
O corpo da requisição deve ser enviado no formato application/x-www-form-urlencoded e conter os seguintes parâmetros:
grant_type:
Define o fluxo de concessão de autorização a ser utilizado. Para acesso direto da aplicação sem envolvimento do usuário, client_credentials é mandatório. Valor Obrigatório: client_credentials
scope:
Especifica as permissões requeridas pela aplicação. Valores Aceitos: read, write (ou uma combinação de ambos, separada por espaço) read: Concede permissão para operações de leitura (e.g., requisições GET a recursos da API). write: Concede permissão para operações de escrita (e.g., requisições POST, PUT, DELETE a recursos da API). Exemplo de Corpo da Requisição:
grant_type=client_credentials&scope=read write
Exemplo obtenção token:
curl --location 'https://api001.nimbi.com.br/oauth/rest/token/v1' \
--header 'Authorization: Basic c2V1X2NsaWVudF9pZDpzZXVfY2xpZW50ZV9zZWNyZXQ=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=read write'
Resposta do Token de Acesso:
Em caso de sucesso, o servidor responderá com um objeto JSON contendo o access_token e metadados relacionados. Código de Status HTTP: 200 OK Corpo da Resposta (JSON):
{
"access_token": "c2b2b4fe-890f-4b54-b2b4-2b809c91a19c",
"token_type": "Bearer",
"scope": "read write",
"expires_in": 86400
}
Descrição dos Campos da Resposta
access_token:
O token de acesso que deve ser utilizado para autenticar requisições subsequentes aos recursos protegidos da API. Este é um token opaco e deve ser incluído no cabeçalho Authorization (precedido por Bearer) em todas as chamadas à APIs que exijam essa autenticação. Ex: (Authorization:Bearer c2b2b4fe-890f-4b54-b2b4-2b809c91a19c)
token_type:
Indica o tipo de token emitido. O esquema Bearer é o padrão para OAuth 2.0, indicando que o token confere acesso a quem o "portar", valor fixo Bearer
scope:
Os scopos efetivamente concedidos à aplicação. Este valor reflete as permissões concedidas pelo servidor, que podem ser iguais ou um subconjunto dos scopes solicitados na requisição.
expires_in:
A duração, em segundos, após a qual o access_token expirará e se tornará inválido. Após este período, um novo access_token deve ser obtido. Validade default 3600 segundos
Exemplo utilização API com token:
curl --location 'https://api001.nimbi.com.br/NimbiShopAPI/rest/privatePurchaseOrders/v1' \
--header 'storeCode: Lojinha' \
--header 'Authorization: Bearer c2b2b4fe-890f-4b54-b2b4-2b809c91a19c'
Revogação de token
Esta API permite a invalidação imediata de tokens de acesso que foram previamente emitidos. É um endpoint de segurança para revogar o acesso antes do vencimento natural do token, sendo essencial em casos de comprometimento de credenciais, garantindo controle e segurança proativos.
https://api001.nimbi.com.br/oauth/rest/token/v1/revoke
A autenticação do cliente é realizada via HTTP Basic Authentication. O client_id e o client_secret devem ser concatenados com dois-pontos (:) e o resultado codificado em Base64. Esta string codificada deve ser incluída no cabeçalho Authorization, precedida pelo esquema Basic. Authorization: Basic <Base64(client_id:client_secret)>
Corpo da Requisição
O corpo da requisição deve ser enviado no formato application/x-www-form-urlencoded e conter os seguintes parâmetros:
token:
O token de acesso a ser revogado.
Exemplo utilização API revoke:
curl --location 'https://api001.nimbi.com.br/oauth/rest/token/v1/revoke' \
--header 'Authorization: Basic c2V1X2NsaWVudF9pZDpzZXVfY2xpZW50ZV9zZWNyZXQ=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=c2b2b4fe-890f-4b54-b2b4-2b809c91a19c'
Para obter as credenciais de acesso às APIs, no Eprocurement vá em configurações / configurações gerais / configurações avançadas.
Atenção: Mantenha suas credenciais de API seguras! Evite compartilhá-las e armazene-as de forma segura. Não exponha suas chaves de API desnecessariamente. Lembre-se de monitorar e rotacionar suas chaves regularmente.
O que é offset e limit em paginação?
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.
Tipos de paginação
• 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 ...
Recuperando Dados
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
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"
}
]
}'
Editar um Recurso
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"
}'
Remover um Recurso
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
}
]'
Explore!
Nós oferecemos uma documentação completa para cada API que nós temos. Veja mais na sessão
API Explorer e divirta-se.