{
  "openapi": "3.1.0",
  "info": {
    "title": "VatBR API",
    "version": "1.0.0",
    "description": "Cálculo de IBS (estadual e municipal) e CBS da Reforma Tributária (LC 214/2025) para SaaS e bens digitais. Alíquotas de referência estimadas."
  },
  "servers": [
    {
      "url": "https://vatbr.com/api/public/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {}
  ],
  "paths": {
    "/calculations": {
      "post": {
        "operationId": "createCalculation",
        "summary": "Calcular IBS e CBS de uma operação",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalculationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cálculo realizado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Calculation"
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Chave inválida ou revogada",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "sk_live_ exige plano pago",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Limite mensal do plano excedido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/calculations/batch": {
      "post": {
        "operationId": "createCalculationBatch",
        "summary": "Calcular um carrinho ou fatura (até 100 itens)",
        "description": "Cada item calculado com sucesso conta como 1 cálculo. customer, nbs e regime no topo valem para todos os itens.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lote processado (pode conter itens com erro)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "400": {
            "description": "Envelope inválido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Chave inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "sk_live_ exige plano pago",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Nenhum item pôde ser calculado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                }
              }
            }
          },
          "429": {
            "description": "Lote excede o limite mensal",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Chave sk_test_… ou sk_live_… gerada no Painel. Opcional no sandbox."
      }
    },
    "schemas": {
      "CalculationRequest": {
        "type": "object",
        "required": [
          "amount",
          "nbs",
          "customer"
        ],
        "properties": {
          "amount": {
            "type": "number",
            "minimum": 0,
            "examples": [
              1000
            ]
          },
          "currency": {
            "type": "string",
            "const": "BRL"
          },
          "customer": {
            "type": "object",
            "description": "Destino da operação. Informe cep ou ibge.",
            "properties": {
              "cep": {
                "type": "string",
                "pattern": "^\\d{5}-?\\d{3}$",
                "examples": [
                  "01310-100"
                ]
              },
              "ibge": {
                "type": "string",
                "pattern": "^\\d{7}$",
                "examples": [
                  "3550308"
                ]
              }
            }
          },
          "nbs": {
            "type": "string",
            "enum": [
              "1.1502.10.00",
              "1.1503.10.00",
              "1.1401.10.00",
              "1.1201.10.00",
              "1.1202.10.00",
              "1.2301.10.00",
              "1.2302.10.00",
              "CBN.01",
              "MED.01",
              "DMA.01"
            ],
            "description": "Código NBS ou categoria. 1.1502.10.00: Licenciamento de software (SaaS); 1.1503.10.00: Hospedagem e infraestrutura em nuvem; 1.1401.10.00: Streaming de conteúdo digital; 1.1201.10.00: Cursos online e educação; 1.1202.10.00: Ensino superior (bolsas ProUni); 1.2301.10.00: Telessaúde / saúde digital; 1.2302.10.00: Serviços de saúde humana; CBN.01: Cesta Básica Nacional de Alimentos; MED.01: Medicamentos da lista de alíquota zero; DMA.01: Dispositivos médicos e de acessibilidade"
          },
          "regime": {
            "type": "string",
            "enum": [
              "standard",
              "reduced_60",
              "zero_rate"
            ],
            "description": "Opcional. Deve ser elegível para o item; padrão = regime do item."
          }
        }
      },
      "BatchItem": {
        "type": "object",
        "required": [
          "amount"
        ],
        "properties": {
          "id": {
            "type": [
              "string",
              "number"
            ],
            "description": "Sua referência, devolvida na resposta"
          },
          "amount": {
            "type": "number",
            "minimum": 0
          },
          "customer": {
            "type": "object",
            "description": "Destino da operação. Informe cep ou ibge.",
            "properties": {
              "cep": {
                "type": "string",
                "pattern": "^\\d{5}-?\\d{3}$",
                "examples": [
                  "01310-100"
                ]
              },
              "ibge": {
                "type": "string",
                "pattern": "^\\d{7}$",
                "examples": [
                  "3550308"
                ]
              }
            }
          },
          "nbs": {
            "type": "string",
            "enum": [
              "1.1502.10.00",
              "1.1503.10.00",
              "1.1401.10.00",
              "1.1201.10.00",
              "1.1202.10.00",
              "1.2301.10.00",
              "1.2302.10.00",
              "CBN.01",
              "MED.01",
              "DMA.01"
            ],
            "description": "Código NBS ou categoria. 1.1502.10.00: Licenciamento de software (SaaS); 1.1503.10.00: Hospedagem e infraestrutura em nuvem; 1.1401.10.00: Streaming de conteúdo digital; 1.1201.10.00: Cursos online e educação; 1.1202.10.00: Ensino superior (bolsas ProUni); 1.2301.10.00: Telessaúde / saúde digital; 1.2302.10.00: Serviços de saúde humana; CBN.01: Cesta Básica Nacional de Alimentos; MED.01: Medicamentos da lista de alíquota zero; DMA.01: Dispositivos médicos e de acessibilidade"
          },
          "regime": {
            "type": "string",
            "enum": [
              "standard",
              "reduced_60",
              "zero_rate"
            ],
            "description": "Opcional. Deve ser elegível para o item; padrão = regime do item."
          }
        }
      },
      "BatchRequest": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "customer": {
            "type": "object",
            "description": "Destino da operação. Informe cep ou ibge.",
            "properties": {
              "cep": {
                "type": "string",
                "pattern": "^\\d{5}-?\\d{3}$",
                "examples": [
                  "01310-100"
                ]
              },
              "ibge": {
                "type": "string",
                "pattern": "^\\d{7}$",
                "examples": [
                  "3550308"
                ]
              }
            }
          },
          "nbs": {
            "type": "string",
            "enum": [
              "1.1502.10.00",
              "1.1503.10.00",
              "1.1401.10.00",
              "1.1201.10.00",
              "1.1202.10.00",
              "1.2301.10.00",
              "1.2302.10.00",
              "CBN.01",
              "MED.01",
              "DMA.01"
            ],
            "description": "Código NBS ou categoria. 1.1502.10.00: Licenciamento de software (SaaS); 1.1503.10.00: Hospedagem e infraestrutura em nuvem; 1.1401.10.00: Streaming de conteúdo digital; 1.1201.10.00: Cursos online e educação; 1.1202.10.00: Ensino superior (bolsas ProUni); 1.2301.10.00: Telessaúde / saúde digital; 1.2302.10.00: Serviços de saúde humana; CBN.01: Cesta Básica Nacional de Alimentos; MED.01: Medicamentos da lista de alíquota zero; DMA.01: Dispositivos médicos e de acessibilidade"
          },
          "regime": {
            "type": "string",
            "enum": [
              "standard",
              "reduced_60",
              "zero_rate"
            ],
            "description": "Opcional. Deve ser elegível para o item; padrão = regime do item."
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/BatchItem"
            }
          }
        }
      },
      "TaxLine": {
        "type": "object",
        "required": [
          "tax",
          "jurisdiction",
          "rate",
          "amount"
        ],
        "properties": {
          "tax": {
            "type": "string",
            "enum": [
              "CBS",
              "IBS"
            ]
          },
          "jurisdiction": {
            "type": "string",
            "examples": [
              "federal",
              "uf:SP",
              "mun:3550308"
            ]
          },
          "rate": {
            "type": "number"
          },
          "amount": {
            "type": "number"
          }
        }
      },
      "Calculation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "calculation"
          },
          "amount": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "destination": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              },
              "uf": {
                "type": "string"
              },
              "ibge": {
                "type": "string"
              }
            }
          },
          "nbs": {
            "type": "string"
          },
          "regime": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "enum": [
                  "standard",
                  "reduced_60",
                  "zero_rate"
                ],
                "description": "Opcional. Deve ser elegível para o item; padrão = regime do item."
              },
              "reduction": {
                "type": "number"
              },
              "basis": {
                "type": "string"
              }
            }
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxLine"
            }
          },
          "total_tax": {
            "type": "number"
          },
          "livemode": {
            "type": "boolean"
          }
        }
      },
      "Batch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "calculation_batch"
          },
          "livemode": {
            "type": "boolean"
          },
          "item_count": {
            "type": "integer"
          },
          "succeeded": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "succeeded",
                    "failed"
                  ]
                },
                "error": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "number"
              },
              "cbs": {
                "type": "number"
              },
              "ibs_uf": {
                "type": "number"
              },
              "ibs_mun": {
                "type": "number"
              },
              "ibs": {
                "type": "number"
              },
              "total_tax": {
                "type": "number"
              }
            }
          }
        }
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          }
        }
      }
    }
  }
}