Pular para o conteúdo
platform
PT EN

Webhooks e eventos · Callback síncrono

Callback de cálculo de impostos

Quando dispara

Quando o cálculo de impostos pelo ERP está ativo na loja, a CWS Platform chama o seu endpoint de tributos antes de fechar o pedido, com o cliente, a empresa, a UF e os itens, e usa os valores devolvidos no pedido.

O cálculo de impostos pela API do cliente depende de ativação. Sem ele, este callback não é chamado.

Payload de exemplo

Exemplo da coleção pública. A URL é a do seu sistema: o endereço abaixo é só ilustrativo.

POST https://api.exemplo-cliente.com.br/wscwstax/calcular
tenantId: 01,04160001
Content-Type: application/json

{
    "cliente": "03.558.351/0001-00",
    "empresa": "12.377.080/0001-88",
    "finalidade": 4,
    "itens": [
        {
            "item": "123456",
            "partner_part_code": "FO0002248281",
            "pre_unit": "451.99",
            "qtde": "45"
        },
        {
            "item": "7891011",
            "partner_part_code": "FO0002248279",
            "pre_unit": "654.99",
            "qtde": "5"
        }
    ],
    "num_pedido": "0",
    "uf": "ES",
    "valor_frete": 0,
    "valor_pedido": 23664.05
}

Como responder

É uma comunicação síncrona: a plataforma faz a chamada e aguarda a resposta imediata para continuar o processo. O seu endpoint responde 200 OK com os tributos de cada item, na estrutura mostrada abaixo.

Como a jornada de compra espera esta resposta, o tempo do seu endpoint entra no tempo do carrinho. Em carrinhos com muitos itens o cálculo pode atrasar a jornada, e a plataforma tem um limitador configurável de itens distintos para esse cenário.

A coleção não publica tempo limite para esta chamada. Confirme o valor com o time de integração ao dimensionar o seu serviço.

O que a coleção documenta

Descrição

Este é um exemplo completo da requisição que a CWS enviará para o seu endpoint de Cálculo de Impostos.

Estrutura da Resposta Esperada

Seu sistema deve retornar uma resposta 200 OK com o seguinte corpo:

{
    "empresa": "12.377.080/0001-88",
    "num_pedido": "0",
    "cliente": "03.558.351/0001-00",
    "mensagem": "sucesso",
    "status": "ok",
    "itens": [
        {
            "item": "123456",
            "st": "0.000000",
            "ipi": "11.120000",
            "icms": 0,
            "pis": 0,
            "cofins": 0
        },
        {
            "item": "7891011",
            "st": "0.000000",
            "ipi": "0.000000",
            "icms": 0,
            "pis": 0,
            "cofins": 0
        }
    ]
}

Autenticação do seu endpoint

Visão Geral da Autenticação

Para proteger seu endpoint de cálculo de impostos, a CWS utilizará um token de acesso obtido do seu sistema. Antes de chamar seu endpoint de impostos, faremos uma requisição ao seu endpoint de autenticação para obter um access_token.

Você deve fornecer à equipe CWS as informações necessárias para que possamos nos autenticar no seu sistema (URL do endpoint de token, credenciais, etc.).

A resposta do seu endpoint de token deve seguir o padrão OAuth2:

{
    "access_token": "SEU_TOKEN_GERADO",
    "expires_in": 3600
}

Abaixo estão três exemplos reais de como seu endpoint de token pode ser configurado.

Exemplo 1: Fluxo client_credentials com Basic Auth

Como funciona: Suas credenciais (clientId e clientSecret) são combinadas, codificadas em Base64 e enviadas no Header Authorization.

Requisição que a CWS fará para seu endpoint de token:

curl --location 'https://api.exemplo-cliente.com/oauth/access-token' \
--header 'Authorization: Basic [SUAS_CREDENCIAS_EM_BASE64]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Exemplo 2: Fluxo com clientId e clientSecret no Body

Como funciona: Suas credenciais são enviadas diretamente no corpo (body) da requisição em formato JSON.

Requisição que a CWS fará para seu endpoint de token:

curl --location 'https://api.exemplo-cliente.com/v1/token' \
--header 'User-Agent: CWS Digital' \
--header 'Content-Type: application/json' \
--data '{
    "clientId": "SEU_CLIENT_ID",
    "clientSecret": "SEU_CLIENT_SECRET"
}'

Exemplo 3: Autenticação com Token Estático no Corpo

Este método mais simples não requer um endpoint de token. Um token fixo (API Key) pré-combinado é enviado diretamente no corpo de cada requisição principal.

Requisição que a CWS fará para seu endpoint de Cálculo de Impostos:

curl --location 'https://api.exemplo-cliente.com/wscwstax/calcular' \
--header 'Content-Type: application/json' \
--data '{
    "cliente": "03.558.351/0001-00",
    "itens": [...],
    "token": "SEU_TOKEN_ESTATICO_PRE_ACORDADO",
    ...
}'

Webhooks e eventos

Gerado a partir da coleção pública da API, publicada em 04/09/2026: api-docs.cws.digital.