API atual/Referência completa/Métodos de envio

Impostos de importação

Lê e substitui a tabela de imposto de importação e taxa de manuseio por país e por código HS, usada nas vendas internacionais.

Quando a loja vende para fora do Brasil, o preço final para o cliente inclui o imposto de importação do país de destino e, às vezes, uma taxa de manuseio. Esta tabela guarda esses percentuais. Cada linha vale para um país (country_code) e, opcionalmente, para uma família de produtos, identificada pelo prefixo do código HS (Sistema Harmonizado, o código aduaneiro de classificação de mercadorias) do produto. Linha com hs_prefix vazio vale para o país inteiro.

A tabela é administrada como um conjunto: o PUT envia a lista completa e o que não estiver nela é apagado.

Listar as taxas

GET/api/v1/admin/shipping/duty-ratesAdmin

Lista os impostos de importação

Exige view_shipping ou manage_shipping. Ordenado por país e prefixo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/duty-rates" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Taxas retornadas

json

{
  "items": [
    {
      "country_code": "AR",
      "hs_prefix": "",
      "duty_pct": 30,
      "handling_cents": 1500
    },
    {
      "country_code": "AR",
      "hs_prefix": "6109",
      "duty_pct": 35,
      "handling_cents": 1500
    }
  ]
}

Campos da resposta

itemsarray

Linhas da tabela.

country_codestring

País de destino, código de 2 letras em maiúsculas.

hs_prefixstring

Prefixo do código HS. Vazio = país inteiro.

duty_pctnumber

Imposto de importação em percentual (30 = 30%).

handling_centsinteger

Taxa de manuseio em centavos.

Substituir a tabela

Em uma única transação: cada linha enviada é inserida ou atualizada (chave: país e prefixo) e todas as demais são apagadas. Enviar uma lista vazia apaga a tabela inteira.

PUT/api/v1/admin/shipping/duty-ratesAdmin

Substitui a tabela de impostos de importação

Exige manage_shipping.

Corpo da requisição

ratesarrayobrigatório

A tabela completa. Linhas existentes que não estiverem aqui são apagadas.

country_codestringobrigatório

País de destino. Convertido para maiúsculas. Linha sem país é ignorada.

hs_prefixstring

Prefixo do código HS. Omita para o país inteiro.

duty_pctnumber

Imposto em percentual.

handling_centsinteger

Taxa de manuseio em centavos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/shipping/duty-rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "country_code": "AR",
        "duty_pct": 30,
        "handling_cents": 1500
      },
      {
        "country_code": "AR",
        "hs_prefix": "6109",
        "duty_pct": 35,
        "handling_cents": 1500
      }
    ]
  }'

Resposta

200Tabela substituída

json

{
  "updated": 2
}

Campos da resposta

updatedinteger

Quantas linhas foram gravadas (as ignoradas por falta de país não contam).

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `manage_shipping`	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
400	Corpo que não é JSON	`{"error":"bad_request","detail":"..."}`
500	Falha ao ler ou gravar	`{"error":"upsert_failed","detail":"..."}` / `{"error":"list_failed","detail":"..."}`
501	Frete internacional não configurado nesta instalação	`{"error":"not_configured","detail":"international shipping unavailable"}`

Veja também

Impostos de importação

Lê e substitui a tabela de imposto de importação e taxa de manuseio por país e por código HS, usada nas vendas internacionais.

A tabela é administrada como um conjunto: o PUT envia a lista completa e o que não estiver nela é apagado.

Listar as taxas

GET/api/v1/admin/shipping/duty-ratesAdmin

Lista os impostos de importação

Exige view_shipping ou manage_shipping. Ordenado por país e prefixo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping/duty-rates" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Taxas retornadas

json

{
  "items": [
    {
      "country_code": "AR",
      "hs_prefix": "",
      "duty_pct": 30,
      "handling_cents": 1500
    },
    {
      "country_code": "AR",
      "hs_prefix": "6109",
      "duty_pct": 35,
      "handling_cents": 1500
    }
  ]
}

Campos da resposta

itemsarray

Linhas da tabela.

country_codestring

País de destino, código de 2 letras em maiúsculas.

hs_prefixstring

Prefixo do código HS. Vazio = país inteiro.

duty_pctnumber

Imposto de importação em percentual (30 = 30%).

handling_centsinteger

Taxa de manuseio em centavos.

Substituir a tabela

Em uma única transação: cada linha enviada é inserida ou atualizada (chave: país e prefixo) e todas as demais são apagadas. Enviar uma lista vazia apaga a tabela inteira.

PUT/api/v1/admin/shipping/duty-ratesAdmin

Substitui a tabela de impostos de importação

Exige manage_shipping.

Corpo da requisição

ratesarrayobrigatório

A tabela completa. Linhas existentes que não estiverem aqui são apagadas.

country_codestringobrigatório

País de destino. Convertido para maiúsculas. Linha sem país é ignorada.

hs_prefixstring

Prefixo do código HS. Omita para o país inteiro.

duty_pctnumber

Imposto em percentual.

handling_centsinteger

Taxa de manuseio em centavos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/shipping/duty-rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "country_code": "AR",
        "duty_pct": 30,
        "handling_cents": 1500
      },
      {
        "country_code": "AR",
        "hs_prefix": "6109",
        "duty_pct": 35,
        "handling_cents": 1500
      }
    ]
  }'

Resposta

200Tabela substituída

json

{
  "updated": 2
}

Campos da resposta

updatedinteger

Quantas linhas foram gravadas (as ignoradas por falta de país não contam).

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `manage_shipping`	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
400	Corpo que não é JSON	`{"error":"bad_request","detail":"..."}`
500	Falha ao ler ou gravar	`{"error":"upsert_failed","detail":"..."}` / `{"error":"list_failed","detail":"..."}`
501	Frete internacional não configurado nesta instalação	`{"error":"not_configured","detail":"international shipping unavailable"}`