Nimbus Rodizio API - Documentação

Este documento apresenta um catálogo de endpoints disponíveis para integração com o Nimbus Rodízio, permitindo a troca de dados entre sistemas parceiros, podendo ser utilizado para consultar, enviar ou receber informações conforme necessidade.

URL:

Diferente para cada cliente, pois depende do IP do servidor local.

Endpoints:

• Catálogo
• Imagem do Produto
• Criar Faturamento
• Consultar Faturamento
• Consultar Nota Fiscal do Faturamento
• Formas de Recebimento

Todas as requisições autenticadas devem enviar o header HTTP Authorization no formato Basic Auth.

Header obrigatório

Authorization: Basic <base64(username:password)>

Como montar o token Basic

1. Concatenar usuário e senha no formato: usuario:senha
2. Converter para Base64
3. Enviar no header Authorization com prefixo Basic

Exemplo

Authorization: Basic dXN1YXJpbzpwYXNzMTIz

O valor Base64 acima representa usuario:pass123.

Regras de validação de autenticação

A API retorna 401 Unauthorized quando:

• o header Authorization não é enviado;
• o formato não é Basic <token>;
• o token Base64 é inválido ou não representa usuario:senha;
• usuário ou senha estão vazios;
• usuário/senha não são validados com sucesso.

Descrição

Retorna uma estrutura hierárquica contendo subgrupos (categorias), produtos e seus respectivos grupos de opções.

Tipo de Retorno de Sucesso

application/json

Modelo

SubGroup

Product

ProductOptionsGroup

OptionGroup

Option

Answer

ProductOption

Exemplo de Response

statusCode 200

{
  "data": [
    {
      "id": 10,
      "index": 1,
      "description": "Bebidas",
      "products": [
        {
          "id": 101,
          "name": "Refrigerante Lata",
          "image": "/products/101/image",
          "price": 8.5,
          "description": "Coca-Cola lata 350ml",
          "productOptionsGroups": [
            {
              "id": 9001,
              "charge": true,
              "required": true,
              "numberOfAnswers": 1,
              "optionGroup": {
                "id": 500,
                "type": "R",
                "description": "Escolha o sabor",
                "options": [
                  {
                    "id": 1,
                    "answer": {
                      "id": 11,
                      "description": "Uva"
                    },
                    "product": null
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Parâmetros da URI

Descrição

Retorna a imagem do produto informado pelo id.

• Quando existir imagem para o produto, retorna o arquivo no content-type image/jpeg.
• Quando o produto não possuir imagem, retorna 204 No Content.

Descrição

Cria um faturamento com base em uma venda feita.

Regras de Negócio

• FaturamentoStatus sempre inicia como 4 (ABERTO).
• Deve existir ao menos 1 item e 1 receivingMethod.
• fulfillmentType é opcional na criação do faturamento. Quando não informado, o sistema assume DINE_IN.
• fulfillmentType aceita apenas: PICKUP, DINE_IN e TAKEOUT.
• total deve ser igual a subtotal - discount + fees.
• subtotal deve ser igual a soma de items.totalPrice.
• Soma de receivingMethods.amount deve ser igual a total.
• Cada receivingMethod.amount deve ser maior que zero.
• Cada receivingMethod.change não pode ser negativo.
• Se customer.name ou customer.document não forem enviados, usa o cliente padrão CONSUMIDOR (id 2).
• Documento é normalizado e validado por tamanho: 11 dígitos (CPF) ou 14 dígitos (CNPJ).
• No CNPJ, os dados são enriquecidos via https://publica.cnpj.ws/cnpj/{cnpj}, com fallback de fantasia para razão social.
• Complementos devem respeitar grupos obrigatórios, limite de respostas e consistência de option/answer/product.
• quantity do complemento é obrigatória (> 0), inclusive para complemento de resposta.
• unitPrice e totalPrice do complemento não podem ser negativos.
• Quando productId for informado, unitPrice deve ser igual ao preço do produto no catálogo e totalPrice deve ser igual a unitPrice * quantity.
• Quando productId for informado, o produto adicional precisa estar disponível no catálogo do estabelecimento.
• Quando for complemento de resposta (answerId), unitPrice e totalPrice devem ser 0.
• O backend recalcula o totalPrice do item e rejeita se divergir do valor enviado.

Modelo de Requisição

ReceivingMethodInput

ItemInput

ItemComplementInput

CustomerInput

FulfillmentType

No momento, o endpoint de criação de faturamento não aceita DELIVERY.

Exemplo de Request

statusCode 200

{
  "total": 47,
  "subtotal": 47,
  "discount": 0,
  "fees": 0,
  "fulfillmentType": "PICKUP",
  "observation": "Venda realizada no totem",
  "receivingMethods": [
    {
      "receivingMethodId": 1,
      "amount": 47,
      "change": 0
    }
  ],
  "customer": {
    "name": "Empresa Exemplo LTDA",
    "document": "11222333000181"
  },
  "items": [
    {
      "productId": 101,
      "quantity": 2,
      "unitPrice": 8.5,
      "totalPrice": 19,
      "complements": [
        {
          "optionId": 100,
          "optionGroupId": 20,
          "productId": 1700,
          "quantity": 1,
          "charge": true,
          "unitPrice": 2,
          "totalPrice": 2
        },
        {
          "optionId": 101,
          "optionGroupId": 21,
          "answerId": 13,
          "quantity": 1,
          "unitPrice": 0,
          "totalPrice": 0
        }
      ]
    }
  ]
}

Exemplo de Response

statusCode 200

{
  "data": {
    "id": 12345
  }
}

Parâmetros da URI

Modelo de Resposta

Exemplo de Response

statusCode 200

{
  "data": {
    "id": 12345,
    "total": 47,
    "subtotal": 47,
    "discount": 0,
    "fees": 0,
    "observation": "Venda realizada no totem",
    "invoiceStatus": "SOLICITADO",
    "orderPassword": "42",
    "createdAt": "2026-04-14T16:25:30",
    "type": "BALCAO",
    "fulfillmentType": "PICKUP",
    "status": {
      "id": 4,
      "description": "ABERTO"
    },
    "customer": {
      "id": 2,
      "name": "CONSUMIDOR",
      "document": null
    },
    "receivingMethods": [
      {
        "id": 77,
        "name": "PIX",
        "alias": "PIX",
        "amount": 47,
        "change": 0,
        "receivingMethodId": 1
      }
    ],
    "items": [
      {
        "id": 9876,
        "quantity": 2,
        "unitPrice": 8.5,
        "totalPrice": 19,
        "observation": "Sem cebola",
        "productId": 101,
        "complements": [
          {
            "id": 1,
            "optionId": 100,
            "answerId": null,
            "productId": 1700,
            "quantity": 1,
            "charge": true
          },
          {
            "id": 2,
            "optionId": 101,
            "answerId": 13,
            "productId": null,
            "quantity": 1,
            "charge": false
          }
        ]
      }
    ]
  }
}

Retorna o status fiscal atual vinculado ao faturamento informado.

Este endpoint deve ser utilizado como polling para acompanhar a emissão.

Quando ainda não existir status fiscal salvo, o backend inicializa com SOLICITADO.

Recomendação: realizar polling a cada 3 segundos.

Valores de status

Modelo de Resposta

Regras de retorno

• O campo xml só é preenchido quando o status for FINALIZADO e houver XML da NFe/NFCe associado ao faturamento.
• Em qualquer outro caso, xml será null.

Exemplo de Response

statusCode 200

{
  "data": {
    "status": "FINALIZADO",
    "xml": "<xml da nota fiscal>"
  }
}

Descrição

Retorna a lista de formas de recebimento aceitas pelo sistema.

Modelo de Resposta

Exemplo de Response

statusCode 200

{
  "data": [
    {
      "id": 1,
      "name": "Cartao de Credito",
      "alias": "CARTAO CREDITO"
    },
    {
      "id": 2,
      "name": "PIX",
      "alias": "PIX"
    },
    {
      "id": 3,
      "name": "Dinheiro",
      "alias": "DIN"
    }
  ]
}