Ir para o conteúdo

Rock Conecta (API REST)

API oficial de integração de PDV (Frente de Caixa) da Rock Conecta. É uma API REST/JSON que o caixa do varejista consome em três momentos de uma compra: identificar o cliente, autorizar descontos e registrar a venda.

Esta é a integração recomendada

Para novas integrações de PDV, utilize as APIs Rock Conecta desta seção. A integração Bnex (WSDL/SOAP) está depreciada e é mantida apenas para consulta de integrações existentes.

As três operações

O PDV consome três endpoints, um para cada momento da compra:

Ordem Operação Endpoint Quando chamar
1 Identificar cliente POST /api/v1/tenants/{tenantId}/customers/identify Ao informar o CPF/CNPJ no início da compra
2 Autorizar descontos POST /api/v1/tenants/{tenantId}/discounts/authorizations Com o carrinho montado, para obter os descontos exclusivos por item
3 Registrar venda POST /api/v1/tenants/{tenantId}/sales Ao fechar a compra, para registrar a venda finalizada

  • 1. Identificar Cliente

    Confirma o cliente pelo CPF/CNPJ e retorna dados cadastrais, classificação e código de preço diferenciado.

    Ver Identificar Cliente

  • 2. Autorizar Descontos

    Recebe o carrinho + cliente e devolve os descontos exclusivos autorizados por item. Não grava nada — apenas lê ofertas.

    Ver Autorizar Descontos

  • 3. Registrar Venda

    Registra a venda finalizada. Responde 202 Accepted e processa de forma assíncrona.

    Ver Registrar Venda

Pontos que o integrador deve conhecer desde já:

  • As três operações são independentes: o PDV pode chamar apenas a identificação, ou pular direto para registrar a venda (sem cliente identificado). O fluxo completo (1 → 2 → 3) é o caso de uso principal, mas não é obrigatório.
  • Autorizar descontos apenas lê ofertas e devolve o carrinho com descontos — não grava nada.
  • Registrar venda responde 202 Accepted de imediato e processa a venda de forma assíncrona; o PDV não deve esperar processamento síncrono.
  • Todos os valores monetários de desconto no response usam até 8 casas decimais.

Requisitos para integrar

Antes de começar, o parceiro precisa dos itens abaixo — todos fornecidos pela Rock Conecta durante o onboarding:

Requisito Descrição
tenantId UUID público que identifica o varejista. Vai no path de todas as chamadas.
Credenciais clientId + clientSecret para o Basic Auth. O clientSecret é exibido uma única vez na criação — armazene com segurança.
URL base Endereço do ambiente (homologação e produção).

O cliente HTTP do PDV precisa ser capaz de:

  • Enviar requisições POST com Content-Type: application/json.
  • Enviar header Authorization: Basic ... (HTTP Basic Auth).
  • Tratar respostas de erro no formato RFC 9457 (Problem Details).
  • Enviar datas em ISO 8601 com offset de timezone (ex: 2026-05-26T16:00:00.000-03:00).

Onboarding

A criação do tenantId e das credenciais é feita internamente pela Rock Conecta. Solicite o acesso ao time de integração para receber os dados do seu ambiente.

Autenticação

A API usa HTTP Basic Auth, por tenant.

Authorization: Basic base64(clientId:clientSecret)
Content-Type: application/json
  • As credenciais são validadas contra o tenantId do path. O clientId deve pertencer ao tenant da URL — caso contrário a requisição é rejeitada.
  • Credenciais inválidas ou ausentes retornam 401 Unauthorized.
  • O clientSecret é armazenado de forma não recuperável pela plataforma. Se perdido, deve ser rotacionado (nova credencial gerada pela Rock Conecta).

Exemplo de header já codificado em Base64:

Authorization: Basic dmFyZWppc3RhLWEtcG9zOnMzY3VyM1BAc3N3MHJkIQ==
Content-Type: application/json

Headers comuns a todas as operações

Header Obrigatório Descrição
Authorization Sim Basic base64(clientId:clientSecret)
Content-Type Sim application/json
X-Correlation-Id Não UUID para rastreabilidade ponta a ponta (ecoado nas respostas de erro)

Path parameter comum

Parâmetro Tipo Descrição
tenantId UUID Identificador público do varejista (fornecido pela Rock Conecta)

Guia rápido (quickstart)

Sequência das três chamadas com curl. Substitua <BASE_URL>, <TENANT_ID>, <CLIENT_ID> e <CLIENT_SECRET> pelos valores do seu ambiente.

curl -X POST "https://<BASE_URL>/api/v1/tenants/<TENANT_ID>/customers/identify" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "sessionId": "abc-123", "protocol": "ROCK", "customer": { "id": "10098075012", "type": "CPF" } }'

curl -X POST "https://<BASE_URL>/api/v1/tenants/<TENANT_ID>/discounts/authorizations" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "abc-10", "protocol": "ROCK", "customer": { "id": "10098075012", "type": "CPF" }, "sale": { "store": { "id": "LOJA-001" }, "date": "2026-05-26T16:00:00.000-03:00", "items": [ { "id": "1", "gtin": "7891234567890", "unitPrice": 25.00, "unitMeasure": "UN", "quantity": 1 } ] } }'

curl -X POST "https://<BASE_URL>/api/v1/tenants/<TENANT_ID>/sales" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{ "protocol": "ROCK_V1", "customer": { "id": "10098075012", "type": "CPF" }, "sale": { "id": 45821, "store": { "id": "LOJA-001", "posId": "PDV-01" }, "channel": "1", "date": "2024-06-15T14:30:00Z", "amount": 25.00, "amountPayable": 25.00, "items": [ { "id": "1", "gtin": "7891234567890", "description": "Produto", "unitPrice": 25.00, "quantity": 1 } ], "payments": [ { "id": 1, "amount": 25.00, "method": "PIX" } ] } }'

Próximos passos

Boas práticas para o integrador

  • Envie sempre X-Correlation-Id (UUID) para facilitar rastreabilidade e suporte.
  • Use um sessionId único por atendimento/compra nas operações 1 e 2.
  • Armazene o clientSecret de forma segura; nunca versione em código.
  • Envie datas em ISO 8601 com offset explícito de timezone.
  • Trate o 202 Accepted do registro de venda como confirmação de recebimento, não de gravação final.
  • Preserve e reenvie os descontos autorizados (operação 2) ao registrar a venda (operação 3), mantendo o promotionId.
  • Implemente retry com backoff para erros 5xx/503. Não faça retry automático de 400/401/404.