Princípios da API

REST + JSON

Cada recurso tem endpoint próprio. Exemplos conceituais: - POST /api/v1/calculate para cálculo síncrono. - POST /api/v1/classifications para classificação NCM. - GET /api/v1/audit para consulta de auditoria.

Request e response em JSON. Sem XML, sem SOAP.

Exemplo simplificado de chamada:

POST /api/v1/calculate
Content-Type: application/json
Authorization: Bearer <SEU_TOKEN>

{
  "items": [ ... ],
  "origin_uf": "SP",
  "destination_uf": "MG"
}

Resposta simplificada:

HTTP 200 OK
Content-Type: application/json

{
  "request_id": "req_<id>",
  "status": "completed",
  "total_value": <valor>,
  "breakdown": { ... }
}

Autenticação por token

Token gerado no dashboard. Header padrão:

Authorization: Bearer <token>

Política de rotação e validade segue documentação oficial. Não exponha token em código-fonte; use variável de ambiente.

Idempotência

Requests síncronas suportam chave de idempotência. Em caso de timeout ou erro de rede, o reenvio com mesma chave evita duplicação.

Idempotency-Key: <chave-única-da-operação>

Webhooks de auditoria

Operações relevantes geram eventos que podem ser entregues via webhook ao endpoint do cliente, com payload contendo identificador da requisição, timestamp e dados da operação. Útil para rastro fiscal.

Endpoints principais (conceituais)

POST /api/v1/calculate (cálculo síncrono)

Exemplo simplificado de payload:

{
  "items": [
    {
      "sku": "<id-do-sku>",
      "ncm": "<NCM 8 dígitos>",
      "value": 1000,
      "quantity": 100,
      "description": "<descrição livre>"
    }
  ],
  "origin_uf": "SP",
  "destination_uf": "MG",
  "destination_cnae": "<CNAE do comprador>",
  "operation_type": "venda",
  "buyer_type": "empresa",
  "buyer_tax_regime": "<regime>"
}

A resposta traz breakdown por tributo (ICMS, ICMS-ST quando aplicável, DIFAL conforme operação, IPI conforme TIPI vigente, PIS/COFINS) e detalhes por item. Schema oficial e nomes exatos dos campos constam na documentação da API.

Target de latência: abaixo de 100ms em condições otimizadas. Os valores reais dependem do plano contratado, da região da chamada e do volume.

POST /api/v1/classifications (classificação NCM)

Exemplo simplificado:

{
  "sku": "<id-do-sku>",
  "description": "<descrição do produto>",
  "image_url": "<URL da imagem do produto>",
  "category": "<categoria do produto>",
  "confidence_threshold": 0.90
}

A resposta traz lista de NCMs candidatas com confiança associada, raciocínio resumido e recomendação principal. Schema oficial e campos exatos constam na documentação.

O tempo de resposta varia conforme tamanho e complexidade da imagem.

GET /api/v1/audit (consulta auditoria)

Permite recuperar entradas de auditoria filtradas por período, paginadas. Útil para reconciliação e auditoria fiscal. Schema oficial na documentação.

Tratamento de erros

Códigos HTTP típicos

Estrutura de erro (simplificada)

HTTP 400 Bad Request

{
  "error": {
    "code": "<código>",
    "message": "<mensagem>",
    "request_id": "<id>",
    "details": { ... }
  }
}

A estrutura exata pode evoluir entre versões. Documentação oficial é a fonte de verdade.

Retry policy

Em respostas 5xx ou erros transitórios, retry com backoff exponencial. Recomendação geral: limitar tentativas e usar Idempotency-Key em toda retentativa.

Performance e confiabilidade

Latência

Target de latência abaixo de 100ms em condições otimizadas para cálculo síncrono. Classificação NCM varia conforme imagem. Valores específicos por plano e região constam em SLA contratual.

Disponibilidade

A Mastery monitora disponibilidade internamente e expõe SLA conforme plano. Status page e métricas de uptime constam na área de cliente.

Rate limit

Os limites variam por plano. Respostas 429 incluem cabeçalho indicando o tempo recomendado de espera.

Taxa de erro

A Mastery monitora taxa de erro internamente. Valores específicos são compartilhados sob acordo de confidencialidade e podem variar por endpoint, região e plano.

Como começar

1. Crie API key No dashboard, gere o token e armazene em variável de ambiente segura.

2. Teste em ambiente de homologação Use a Postman collection oficial (link na documentação) e faça uma primeira chamada com payload mínimo.

3. Integre com seu checkout Para plataformas suportadas (por exemplo, VTEX), há apps oficiais. Para integrações custom, chame o endpoint antes de exibir o preço final no carrinho.

4. Monitore Dashboard mostra volume de chamadas, latência observada e taxa de erro. Configure alertas para anomalias.

FAQ

1. Como autenticar na API Mastery? Gere API token no dashboard e use em header Authorization: Bearer <token>. Política de rotação consta na documentação oficial.

2. Qual o tempo médio de resposta da API? Target de latência abaixo de 100ms para cálculo síncrono em condições otimizadas. Classificação NCM varia conforme imagem. Valores específicos por plano e região constam em SLA.

3. A API suporta idempotência? Sim, via cabeçalho Idempotency-Key. Reenvios com a mesma chave não duplicam operação.

4. Como tratar erros de cálculo fiscal via API? Validar o código HTTP. 400: corrigir o request. 401: renovar token. 429: aguardar conforme cabeçalho. 5xx: retry com backoff exponencial, sempre com Idempotency-Key.

5. Quanto tempo leva para integrar? Depende do escopo. Uma chamada básica no checkout costuma ser rápida (algumas horas). Integração completa, com webhooks, auditoria e reconciliação, demanda mais. O tempo real depende da arquitetura existente e do fluxo de pedido da loja.

Este conteúdo tem caráter informativo e não substitui orientação contábil, fiscal ou jurídica especializada. Regras tributárias podem variar conforme UF, regime tributário, operação, produto, NCM, CNAE e perfil do comprador. Valide seu cenário com profissional habilitado.