Skip to content
platform
EN PT

Webhooks and events · Synchronous callback

Tax calculation callback

When it fires

When tax calculation by the ERP is active for the store, CWS Platform calls your tax endpoint before closing the order, with the customer, the company, the state and the items, and uses the returned values in the order.

Tax calculation through the customer's API depends on activation. Without it, this callback is not called.

Example payload

Example from the public collection. The URL is your system's: the address below is only illustrative.

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
}

How to respond

This is synchronous communication: the platform makes the call and waits for the immediate response to continue the process. Your endpoint responds 200 OK with the taxes for each item, in the structure shown below.

Because the purchase journey waits for this response, your endpoint's time becomes part of the cart's time. On carts with many items the calculation can slow the journey, and the platform has a configurable limiter of distinct items for that scenario.

The collection does not publish a timeout for this call. Confirm the value with the integration team when sizing your service.

What the collection documents

Description

This is a complete example of the request that CWS will send to your Tax Calculation endpoint.

Expected Response Structure

Your system must return a 200 OK response with the following body:

{
    "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
        }
    ]
}

Authentication of your endpoint

Authentication Overview

To protect your tax calculation endpoint, CWS will use an access token obtained from your system. Before calling your tax endpoint, we will make a request to your authentication endpoint to obtain an access_token.

You must provide the CWS team with the information we need to authenticate against your system (token endpoint URL, credentials, etc.).

The response from your token endpoint must follow the OAuth2 standard:

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

Below are three real examples of how your token endpoint can be configured.

Example 1: client_credentials Flow with Basic Auth

How it works: Your credentials (clientId and clientSecret) are combined, Base64-encoded and sent in the Authorization header.

Request that CWS will make to your token endpoint:

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'

Example 2: Flow with clientId and clientSecret in the Body

How it works: Your credentials are sent directly in the request body in JSON format.

Request that CWS will make to your token endpoint:

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"
}'

Example 3: Authentication with a Static Token in the Body

This simpler method does not require a token endpoint. A pre-agreed fixed token (API Key) is sent directly in the body of each main request.

Request that CWS will make to your Tax Calculation endpoint:

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 and events

Generated from the public API collection, published on 2026-09-04: api-docs.cws.digital.