{ "openapi": "3.1.1", "info": { "title": "emitza API", "version": "0.10.2", "description": "API da emitza para emitir NF-e e NFS-e e calcular impostos, incluindo o IBS/CBS da Reforma Tributária.\n\n**Autenticação.** Envie `Authorization: Bearer `. Chaves `fsk_test_` funcionam só em `api-sandbox.emitza.com.br` e emitem só em homologação, sem valor fiscal; chaves `fsk_live_` funcionam só em `api.emitza.com.br`. Comece pelo sandbox e confira a chave com `GET /v1/me`.\n\n**Emissão assíncrona.** `POST /v1/nfe` e `POST /v1/nfse` respondem 202 na hora, com a nota na fila. O resultado chega pelo webhook (`nfe.authorized`, `nfse.rejected`...) ou consultando `GET /v1/nfe/{id}`.\n\n**Idempotência.** O `externalId` do pedido é a chave: repetir o mesmo pedido devolve a mesma nota (200), nunca uma segunda. Uma nota rejeitada é corrigida reenviando o pedido corrigido com o mesmo `externalId`.\n\n**Valores.** Decimais vão em texto com ponto (`\"1500.00\"`), para não perder precisão.\n\n**Erros.** Sempre `{ \"error\": { \"code\", \"message\", \"details\" } }`. Em `validation_failed` (422), `details` lista `{ path, message }` com o caminho do campo, ex.: `items[2].ncm`. Campos desconhecidos são recusados.", "contact": { "name": "emitza", "url": "https://emitza.com.br" }, "license": { "name": "Uso conforme contrato com a emitza", "url": "https://emitza.com.br" } }, "servers": [ { "url": "https://api-sandbox.emitza.com.br", "description": "Sandbox: chave fsk_test_, só homologação (sem valor fiscal)." }, { "url": "https://api.emitza.com.br", "description": "Produção: chave fsk_live_." } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Sistema", "description": "Saúde do serviço, conferência da chave e esta especificação." }, { "name": "Empresas", "description": "Empresas emitentes: cadastro, certificado A1, séries e configuração da NFS-e." }, { "name": "Classes de imposto", "description": "Regras de impostos por tipo de produto, para o item da nota só informar a classe." }, { "name": "NF-e", "description": "Nota fiscal eletrônica (modelo 55): emissão assíncrona, consulta, XML, DANFE, eventos e inutilização." }, { "name": "NFS-e", "description": "NFS-e no padrão nacional (Sefin): emissão assíncrona, consulta, XML, DANFSe e cancelamento." }, { "name": "Impostos", "description": "Cálculo sem emissão e tabelas da Reforma Tributária (IBS/CBS)." }, { "name": "Webhooks", "description": "Avisos de resultado enviados ao seu sistema." }, { "name": "Cobertura", "description": "O que a emitza atende em cada município, por tipo de documento e regime." }, { "name": "MCP", "description": "Servidor MCP para assistentes de IA emitirem notas com a sua chave." } ], "paths": { "/health": { "get": { "tags": [ "Sistema" ], "summary": "Saúde do serviço", "description": "Sem autenticação. Versão publicada e conexão com o banco.", "operationId": "getHealth", "responses": { "200": { "description": "No ar.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "db": { "type": "string", "enum": [ "ok", "unreachable" ] }, "version": { "type": "string", "maxLength": 60 }, "commit": { "type": "string", "maxLength": 60 }, "sefaz": { "type": "string", "enum": [ "simulada" ] } }, "required": [ "status", "db", "version" ], "additionalProperties": false } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/openapi.json": { "get": { "tags": [ "Sistema" ], "summary": "Esta especificação (OpenAPI 3.1)", "description": "Sem autenticação. Use para gerar um cliente ou para dar à IA o contrato da API.", "operationId": "getV1Openapi.json", "responses": { "200": { "description": "Documento OpenAPI 3.1.", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/me": { "get": { "tags": [ "Sistema" ], "summary": "Quem sou eu", "description": "Confere a chave: cliente, plano e modo (live ou test). Bom primeiro teste da integração.", "operationId": "getV1Me", "responses": { "200": { "description": "Cliente da chave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "name": { "type": "string", "maxLength": 100000 }, "plan": { "type": [ "string", "null" ], "maxLength": 60 }, "keyPrefix": { "type": "string", "maxLength": 60 }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live: chave fsk_live_ (produção). test: chave fsk_test_ (sandbox, só homologação)." } }, "required": [ "clientId", "name", "plan", "keyPrefix", "mode" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies": { "post": { "tags": [ "Empresas" ], "summary": "Cadastrar empresa emitente", "description": "Cadastra a empresa que vai emitir. Depois envie o certificado A1 (PUT /v1/companies/{id}/certificate). Com chave de teste (fsk_test_) a empresa fica só em homologação.", "operationId": "postV1Companies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreate" }, "example": { "cnpj": "11222333000181", "ie": "110042490114", "crt": 1, "legalName": "Calçados Exemplo Indústria Ltda", "tradeName": "Exemplo", "email": "fiscal@exemplo.com.br", "address": { "street": "Rua das Indústrias", "number": "100", "district": "Distrito Industrial", "cityName": "Franca", "cityCode": "3516200", "uf": "SP", "zip": "14406000", "phone": "1637001000" } } } } }, "responses": { "201": { "description": "Empresa cadastrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CNPJ já cadastrado por este cliente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos; em sandbox, sandbox_homologation_only ao pedir produção; UF ainda não atendida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Empresas" ], "summary": "Listar empresas", "operationId": "getV1Companies", "responses": { "200": { "description": "Empresas do cliente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "maxItems": 100000 } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}": { "get": { "tags": [ "Empresas" ], "summary": "Consultar empresa", "operationId": "getV1CompaniesById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Empresas" ], "summary": "Alterar empresa", "operationId": "patchV1CompaniesById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdate" } } } }, "responses": { "200": { "description": "Empresa alterada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos; certificate_required ao pedir produção sem certificado; em sandbox, sandbox_homologation_only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/nfe-series": { "post": { "tags": [ "Empresas" ], "summary": "Cadastrar série da NF-e", "description": "Inclui uma série com o próximo número. Útil para continuar a numeração de outro emissor.", "operationId": "postV1CompaniesByIdNfeSeries", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "maximum": 889, "description": "Série (0 a 889; 890 em diante são reservadas ao Fisco)." }, "next": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "Próximo número a usar." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente da série (padrão: o atual da empresa)." } }, "required": [ "number", "next" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Série incluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Série já cadastrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos (validation_failed), com a lista de campos em details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/nfse-series": { "post": { "tags": [ "Empresas" ], "summary": "Cadastrar série da DPS (NFS-e)", "operationId": "postV1CompaniesByIdNfseSeries", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 1, "maximum": 49999, "description": "Série da DPS (1 a 49999)." }, "next": { "type": "integer", "minimum": 1, "maximum": 999999999999999 }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "homologation: testes, sem valor fiscal. production: notas com valor fiscal." } }, "required": [ "number", "next" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Série incluída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Série já cadastrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos (validation_failed), com a lista de campos em details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/nfse-settings": { "put": { "tags": [ "Empresas" ], "summary": "Configurar a NFS-e da empresa", "description": "Regime de apuração do Simples, regime especial municipal, atividade do Simples (cAtvSN) e total aproximado dos tributos padrão.", "operationId": "putV1CompaniesByIdNfseSettings", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseSettings" } } } }, "responses": { "200": { "description": "Configuração salva.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos (validation_failed), com a lista de campos em details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/certificate": { "put": { "tags": [ "Empresas" ], "summary": "Enviar certificado digital A1", "description": "Envia o .pfx (e-CNPJ A1) em base64 com a senha. O certificado é conferido (CNPJ da empresa, validade, cadeia ICP-Brasil) e guardado cifrado. Substitui o anterior.", "operationId": "putV1CompaniesByIdCertificate", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pfxBase64": { "type": "string", "minLength": 100, "maxLength": 700000, "pattern": "^[A-Za-z0-9+/=\\s]+$", "description": "Arquivo .pfx (certificado A1 e-CNPJ) em base64." }, "password": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Senha do .pfx. Não é guardada em texto: o certificado é cifrado no cofre.", "writeOnly": true } }, "required": [ "pfxBase64", "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Certificado aceito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "certificate_*: senha errada, certificado vencido, de outro CNPJ ou fora da ICP-Brasil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/status": { "get": { "tags": [ "Empresas" ], "summary": "Situação da empresa", "description": "Ambiente atual e situação do certificado.", "operationId": "getV1CompaniesByIdStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Situação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente: homologation (sem valor fiscal) ou production." }, "certificate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "missing", "valid", "expiring", "expired" ], "description": "expiring: vence em até 30 dias." }, "daysLeft": { "type": [ "integer", "null" ] }, "notAfter": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "status", "daysLeft", "notAfter" ], "additionalProperties": false }, "sefaz": { "type": [ "null" ], "description": "Reservado (situação da SEFAZ)." } }, "required": [ "id", "environment", "certificate", "sefaz" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada (ou de outro cliente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/tax-classes": { "post": { "tags": [ "Classes de imposto" ], "summary": "Criar classe de imposto", "description": "Uma classe guarda as regras de CFOP, ICMS, IPI, PIS e COFINS de um tipo de produto, escolhidas por operação, destino e tipo de destinatário. O item da nota só informa taxClass.", "operationId": "postV1CompaniesByIdTaxClasses", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxClassInput" } } } }, "responses": { "201": { "description": "Classe criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxClass" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa ou classe não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Já existe uma classe com este código.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos (validation_failed), com a lista de campos em details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Classes de imposto" ], "summary": "Listar classes de imposto", "operationId": "getV1CompaniesByIdTaxClasses", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Classes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxClass" }, "maxItems": 100000 } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa ou classe não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{id}/tax-classes/{code}": { "get": { "tags": [ "Classes de imposto" ], "summary": "Consultar classe de imposto", "operationId": "getV1CompaniesByIdTaxClassesByCode", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Código da classe.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Classe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxClass" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa ou classe não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Classes de imposto" ], "summary": "Substituir classe de imposto", "description": "Troca a classe inteira (o code do corpo é ignorado; vale o da URL).", "operationId": "putV1CompaniesByIdTaxClassesByCode", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Código da classe.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxClassInput" } } } }, "responses": { "200": { "description": "Classe substituída.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxClass" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa ou classe não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos (validation_failed), com a lista de campos em details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Classes de imposto" ], "summary": "Apagar classe de imposto", "operationId": "deleteV1CompaniesByIdTaxClassesByCode", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da empresa.", "schema": { "type": "string" } }, { "name": "code", "in": "path", "required": true, "description": "Código da classe.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Apagada." }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa ou classe não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Cadastrar webhook", "description": "Os eventos chegam por POST com JSON, assinados com HMAC-SHA256 no cabeçalho X-Fiscal-Signature (t=,v1=.\")>). Responda 2xx em até 10 s; sem isso, novas tentativas por cerca de 24 h. Até 5 webhooks ativos.", "operationId": "postV1Webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 500, "description": "URL HTTPS que recebe os eventos (POST com JSON assinado).", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "nfe.authorized", "nfe.rejected", "nfe.denied", "nfe.failed", "nfe.event_rejected", "nfe.cancelled", "nfe.correction_registered", "nfe.disabled", "nfse.authorized", "nfse.rejected", "nfse.failed", "nfse.cancelled", "nfse.event_rejected", "certificate.expiring", "certificate.expired", "sefaz.contingency_started", "sefaz.contingency_ended", "webhook.test" ] }, "minItems": 1, "maxItems": 19, "description": "Eventos assinados; \"*\" (padrão) recebe todos." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://seu-sistema.com.br/webhooks/emitza", "events": [ "nfe.authorized", "nfe.rejected", "nfse.authorized", "nfse.rejected" ] } } } }, "responses": { "201": { "description": "Webhook criado; o secret só aparece aqui.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24 }, "url": { "type": "string", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "nfe.authorized", "nfe.rejected", "nfe.denied", "nfe.failed", "nfe.event_rejected", "nfe.cancelled", "nfe.correction_registered", "nfe.disabled", "nfse.authorized", "nfse.rejected", "nfse.failed", "nfse.cancelled", "nfse.event_rejected", "certificate.expiring", "certificate.expired", "sefaz.contingency_started", "sefaz.contingency_ended", "webhook.test" ] }, "maxItems": 100 }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "maxLength": 200, "description": "Segredo do HMAC. Aparece só nesta resposta: guarde para conferir a assinatura (cabeçalho X-Fiscal-Signature)." } }, "required": [ "id", "url", "events", "active", "createdAt", "secret" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "URL repetida ou limite de 5 webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "URL recusada (precisa ser HTTPS e pública).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "Listar webhooks", "operationId": "getV1Webhooks", "responses": { "200": { "description": "Webhooks ativos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "maxItems": 100000 } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Remover webhook", "operationId": "deleteV1WebhooksById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id do webhook.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removido." }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Enviar evento de teste", "description": "Dispara um webhook.test para conferir a URL e a assinatura.", "operationId": "postV1WebhooksByIdTest", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id do webhook.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Entrega na fila.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveryId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "deliveryId", "status" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/export": { "get": { "tags": [ "NF-e" ], "summary": "Exportar o mês (zip para o contador)", "description": "Zip com os XMLs do mês (notas, eventos e inutilizações), um resumo.csv e, com danfe=1, os DANFEs. Sai em streaming.", "operationId": "getV1NfeExport", "parameters": [ { "name": "companyId", "in": "query", "required": true, "description": "id da empresa.", "schema": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$" } }, { "name": "month", "in": "query", "required": true, "description": "Mês AAAA-MM.", "schema": { "type": "string", "minLength": 7, "maxLength": 7, "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "environment", "in": "query", "required": false, "description": "Padrão: o ambiente atual da empresa.", "schema": { "type": "string", "enum": [ "production", "homologation" ] } }, { "name": "danfe", "in": "query", "required": false, "description": "1 inclui os DANFEs em PDF.", "schema": { "type": "string", "enum": [ "0", "1" ] } } ], "responses": { "200": { "description": "Arquivo zip.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Parâmetros inválidos; too_many_danfes quando o mês tem notas demais para incluir os DANFEs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/disable-range": { "post": { "tags": [ "NF-e" ], "summary": "Inutilizar faixa de números", "description": "Inutiliza números pulados ou de notas que não foram autorizadas (veja GET /v1/nfe/gaps). Assíncrono: o resultado chega pelo webhook nfe.disabled ou em GET /v1/nfe/disablements/{id}.", "operationId": "postV1NfeDisableRange", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "id da empresa emitente (devolvido em POST /v1/companies)." }, "series": { "type": "integer", "minimum": 0, "maximum": 889 }, "from": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "to": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "justification": { "type": "string", "minLength": 15, "maxLength": 255 } }, "required": [ "companyId", "series", "from", "to", "justification" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "O mesmo pedido já existia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disablement" } } } }, "202": { "description": "Pedido aceito e na fila.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disablement" } } } }, "400": { "description": "companyId inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Faixa sobreposta a outra inutilização ou com notas em uso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "series_missing, range_invalid, range_too_large, range_not_reserved, certificate_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/gaps": { "get": { "tags": [ "NF-e" ], "summary": "Números pulados da série", "description": "Faixas que não viraram nota autorizada nem foram inutilizadas. O Fisco exige inutilizar esses números.", "operationId": "getV1NfeGaps", "parameters": [ { "name": "companyId", "in": "query", "required": true, "description": "id da empresa.", "schema": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$" } }, { "name": "series", "in": "query", "required": true, "description": "Série.", "schema": { "type": "integer", "minimum": 0, "maximum": 889 } } ], "responses": { "200": { "description": "Faixas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente: homologation (sem valor fiscal) ou production." }, "series": { "type": "integer" }, "next": { "type": "integer", "description": "Próximo número da série." }, "gaps": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "reason": { "type": "string", "maxLength": 30, "description": "unused: número pulado; rejected ou failed: nota que não foi autorizada; disabling: inutilização em andamento." }, "documentIds": { "type": "array", "items": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "maxItems": 100000, "description": "Notas da faixa que não foram autorizadas." } }, "required": [ "from", "to", "reason", "documentIds" ], "additionalProperties": false }, "maxItems": 100000, "description": "Faixas sem nota autorizada nem inutilizada. Inutilize com POST /v1/nfe/disable-range." }, "truncated": { "type": "boolean", "description": "true: a busca parou em 100 mil números." } }, "required": [ "companyId", "environment", "series", "next", "gaps", "truncated" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "series_missing ou parâmetros inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/disablements/{id}": { "get": { "tags": [ "NF-e" ], "summary": "Consultar inutilização", "operationId": "getV1NfeDisablementsById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da inutilização.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inutilização.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disablement" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inutilização não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/disablements/{id}/xml": { "get": { "tags": [ "NF-e" ], "summary": "XML da inutilização", "operationId": "getV1NfeDisablementsByIdXml", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da inutilização.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "procInutNFe.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inutilização não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Inutilização ainda não registrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/disablements/{id}/retry": { "post": { "tags": [ "NF-e" ], "summary": "Reenviar inutilização com falha", "operationId": "postV1NfeDisablementsByIdRetry", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da inutilização.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "De volta à fila.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disablement" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Inutilização não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Só inutilizações com falha podem ser reenviadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe": { "post": { "tags": [ "NF-e" ], "summary": "Emitir NF-e", "description": "Calcula os impostos (IBS/CBS incluídos), monta, assina e envia a NF-e (modelo 55) em segundo plano. Responde 202 na hora; o resultado chega pelo webhook (nfe.authorized, nfe.rejected...) ou em GET /v1/nfe/{id}. O externalId é a chave de idempotência: repetir o pedido devolve a mesma nota com 200; reenviar uma nota rejeitada com o mesmo externalId e o pedido corrigido tenta de novo com o mesmo número.", "operationId": "postV1Nfe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeCreate" }, "example": { "externalId": "pedido-1234", "companyId": "6710a1b2c3d4e5f601234567", "operation": "sale", "natureOfOperation": "Venda de produção do estabelecimento", "recipient": { "cnpj": "11444777000161", "name": "Loja Exemplo Comércio de Calçados Ltda", "ieIndicator": "1", "ie": "123456785004", "email": "fiscal@lojaexemplo.com.br", "address": { "street": "Avenida Paulista", "number": "1000", "district": "Bela Vista", "cityName": "São Paulo", "cityCode": "3550308", "uf": "SP", "zip": "01310100" } }, "items": [ { "code": "BOT-COURO-38", "description": "Bota de couro cano médio nº 38", "ncm": "64039190", "origin": "0", "cfop": "5101", "unit": "PAR", "quantity": "10", "unitPrice": "129.90", "taxes": { "icms": { "csosn": "101", "creditRate": "1.25" }, "pis": { "cst": "49" }, "cofins": { "cst": "49" } } } ], "transport": { "mode": "0" }, "payments": [ { "method": "15" } ], "billing": { "installments": [ { "dueDate": "2026-11-30" } ] } } } } }, "responses": { "200": { "description": "Pedido repetido: a nota que já existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfe" } } } }, "202": { "description": "Aceita e na fila. Header Location com o endereço da nota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfe" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "externalId já usado com outro conteúdo, ou nota em situação que não aceita reenvio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos; series_missing, certificate_unavailable, model_invalid, sandbox_homologation_only, total diferente de expectedTotal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "NF-e" ], "summary": "Buscar NF-e pelo externalId", "operationId": "getV1Nfe", "parameters": [ { "name": "externalId", "in": "query", "required": true, "description": "O seu identificador do pedido.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "NF-e.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfe" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}": { "get": { "tags": [ "NF-e" ], "summary": "Consultar NF-e", "operationId": "getV1NfeById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "NF-e.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfe" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/xml": { "get": { "tags": [ "NF-e" ], "summary": "XML autorizado (procNFe)", "description": "Disponível para nota autorizada, denegada ou cancelada. É o arquivo que o emitente deve guardar por 5 anos.", "operationId": "getV1NfeByIdXml", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "XML.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "XML ainda não disponível para a situação atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/danfe": { "get": { "tags": [ "NF-e" ], "summary": "DANFE em PDF", "description": "Montado do XML autorizado. Nota cancelada sai com marca d'água.", "operationId": "getV1NfeByIdDanfe", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } }, { "name": "download", "in": "query", "required": false, "description": "1 para baixar (attachment) em vez de abrir no navegador.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Nota sem DANFE (não autorizada).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/cancel": { "post": { "tags": [ "NF-e" ], "summary": "Cancelar NF-e", "description": "Pede o cancelamento (evento 110111) de uma nota autorizada, dentro do prazo da SEFAZ. Assíncrono: resultado pelo webhook nfe.cancelled ou nfe.event_rejected.", "operationId": "postV1NfeByIdCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "justification": { "type": "string", "minLength": 15, "maxLength": 255, "description": "Motivo do cancelamento (15 a 255 caracteres)." } }, "required": [ "justification" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "O mesmo pedido já existia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeEvent" } } } }, "202": { "description": "Pedido aceito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeEvent" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Nota não autorizada ou cancelamento já em andamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "certificate_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/correction": { "post": { "tags": [ "NF-e" ], "summary": "Carta de correção", "description": "Registra uma carta de correção (evento 110110). Não corrige valores, impostos, dados do emitente ou do destinatário que mudem quem é ele, nem a data. Até 20 por nota.", "operationId": "postV1NfeByIdCorrection", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 15, "maxLength": 1000, "description": "Texto da correção. Cada carta substitui a anterior, então repita as correções anteriores que ainda valem." } }, "required": [ "text" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "O mesmo pedido já existia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeEvent" } } } }, "202": { "description": "Pedido aceito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeEvent" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Nota não autorizada ou outra carta em andamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "correction_limit ou certificate_unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/events": { "get": { "tags": [ "NF-e" ], "summary": "Eventos da NF-e", "description": "Cancelamentos e cartas de correção da nota.", "operationId": "getV1NfeByIdEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Eventos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NfeEvent" }, "maxItems": 100000 } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/events/{eventId}/xml": { "get": { "tags": [ "NF-e" ], "summary": "XML do evento", "operationId": "getV1NfeByIdEventsByEventIdXml", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "description": "id do evento.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "procEventoNFe.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e ou evento não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Evento ainda não registrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfe/{id}/retry": { "post": { "tags": [ "NF-e" ], "summary": "Tentar de novo", "description": "Para nota com falha (failed) ou parada pedindo atenção, depois de corrigir a causa (ex.: certificado novo). Rejeitada não usa esta rota: reenvie o pedido corrigido em POST /v1/nfe.", "operationId": "postV1NfeByIdRetry", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NF-e.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "De volta à fila.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfe" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NF-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A nota não pode ser reenviada na situação atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/municipalities/{cityCode}": { "get": { "tags": [ "NFS-e" ], "summary": "Município no Sistema Nacional da NFS-e", "description": "Diz se o município é conveniado e se aceita os emissores nacionais (a NFS-e pela API do Sefin). Consulta o ADN com o certificado da empresa; resultado guardado por 24 h.", "operationId": "getV1NfseMunicipalitiesByCityCode", "parameters": [ { "name": "cityCode", "in": "path", "required": true, "description": "Código IBGE do município (7 dígitos).", "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": true, "description": "Empresa cujo certificado é usado na consulta.", "schema": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Situação do município.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cityCode": { "type": "string", "maxLength": 7 }, "name": { "type": [ "string", "null" ], "maxLength": 100000 }, "uf": { "type": [ "string", "null" ], "maxLength": 2 }, "agreement": { "type": [ "boolean", "null" ], "description": "Município conveniado ao Sistema Nacional da NFS-e." }, "nationalIssuer": { "type": [ "boolean", "null" ], "description": "Aceita os emissores nacionais (API do Sefin). false: a NFS-e sai pelo sistema da prefeitura." }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "string", "maxLength": 60, "description": "adn (consultado agora), cache (até 24 h), indisponível ou sem certificado para consultar." } }, "required": [ "cityCode", "name", "uf", "agreement", "nationalIssuer", "checkedAt", "source" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Código IBGE ou companyId inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse": { "post": { "tags": [ "NFS-e" ], "summary": "Emitir NFS-e (padrão nacional)", "description": "Monta e assina a DPS e envia ao Sistema Nacional da NFS-e (Sefin) em segundo plano. Responde 202 na hora; o resultado chega pelo webhook (nfse.authorized, nfse.rejected...) ou em GET /v1/nfse/{id}. MEI e Simples Nacional emitem pelo padrão nacional em todos os municípios a partir de 01/11/2026 (antes, só onde a prefeitura já aceita); os demais regimes, só onde o município aceita o emissor nacional (veja GET /v1/nfse/municipalities/{cityCode}). O externalId é a chave de idempotência.", "operationId": "postV1Nfse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseCreate" }, "example": { "externalId": "os-2026-1001", "companyId": "6710a1b2c3d4e5f601234567", "service": { "nationalCode": "01.07.01", "description": "Suporte técnico em informática - outubro/2026", "simplesActivity": "07" }, "recipient": { "cnpj": "11444777000161", "name": "Cliente Exemplo Ltda", "email": "fiscal@cliente.com.br", "address": { "street": "Avenida Paulista", "number": "1000", "district": "Bela Vista", "cityCode": "3550308", "zip": "01310100" } }, "amount": "1500.00", "approximateTaxes": { "simplesRate": "6.00" } } } } }, "responses": { "200": { "description": "Pedido repetido: a NFS-e que já existe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfse" } } } }, "202": { "description": "Aceita e na fila.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfse" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "externalId já usado com outro conteúdo, ou documento em situação que não aceita reenvio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos; nfse_series_missing, certificate_unavailable, model_invalid, municipality_not_supported, sandbox_homologation_only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "NFS-e" ], "summary": "Buscar NFS-e pelo externalId", "operationId": "getV1Nfse", "parameters": [ { "name": "externalId", "in": "query", "required": true, "description": "O seu identificador do pedido.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "NFS-e.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfse" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}": { "get": { "tags": [ "NFS-e" ], "summary": "Consultar NFS-e", "operationId": "getV1NfseById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "NFS-e.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfse" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}/xml": { "get": { "tags": [ "NFS-e" ], "summary": "XML da NFS-e", "description": "XML gerado pelo Sistema Nacional, com a DPS assinada dentro.", "operationId": "getV1NfseByIdXml", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "XML.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "XML ainda não disponível.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}/danfse": { "get": { "tags": [ "NFS-e" ], "summary": "DANFSe em PDF", "description": "Documento auxiliar da NFS-e (NT 008), com QR Code. Cancelada sai com marca d'água.", "operationId": "getV1NfseByIdDanfse", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } }, { "name": "download", "in": "query", "required": false, "description": "1 para baixar em vez de abrir.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "NFS-e não autorizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}/cancel": { "post": { "tags": [ "NFS-e" ], "summary": "Cancelar NFS-e", "description": "Registra o evento de cancelamento (101101). Assíncrono: resultado pelo webhook nfse.cancelled ou nfse.event_rejected.", "operationId": "postV1NfseByIdCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Motivo: 1 erro na emissão, 2 serviço não prestado, 9 outros." }, "justification": { "type": "string", "minLength": 15, "maxLength": 255, "description": "Justificativa (15 a 255 caracteres)." } }, "required": [ "reason", "justification" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "O mesmo pedido já existia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseEvent" } } } }, "202": { "description": "Pedido aceito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseEvent" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "NFS-e não autorizada ou cancelamento já pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos (validation_failed), com a lista de campos em details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}/events": { "get": { "tags": [ "NFS-e" ], "summary": "Eventos da NFS-e", "operationId": "getV1NfseByIdEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Eventos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NfseEvent" }, "maxItems": 100000 } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}/events/{eventId}/xml": { "get": { "tags": [ "NFS-e" ], "summary": "XML do evento da NFS-e", "operationId": "getV1NfseByIdEventsByEventIdXml", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "description": "id do evento.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "XML do evento.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Evento não registrado ou inexistente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/nfse/{id}/retry": { "post": { "tags": [ "NFS-e" ], "summary": "Tentar de novo", "description": "Para NFS-e com falha ou parada pedindo atenção, depois de corrigir a causa. Rejeitada: reenvie o pedido corrigido em POST /v1/nfse com o mesmo externalId.", "operationId": "postV1NfseByIdRetry", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "id da NFS-e.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "De volta à fila.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Nfse" } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NFS-e não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A NFS-e não pode ser reenviada na situação atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax/calculate": { "post": { "tags": [ "Impostos" ], "summary": "Calcular impostos (sem emitir)", "description": "Calcula ICMS, IPI, PIS, COFINS e IBS/CBS de um pedido como sairia na NF-e, sem criar documento nem reservar número. Serve para orçamento e carrinho. Use companyId (empresa cadastrada, com classes de imposto) ou issuer (só regime e UF).", "operationId": "postV1TaxCalculate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCalculate" }, "example": { "issuer": { "crt": 3, "uf": "SP" }, "operation": "sale", "recipient": { "cnpj": "11444777000161", "ieIndicator": "1", "uf": "MG" }, "items": [ { "code": "TEN-ESP-42", "description": "Tênis esportivo nº 42", "ncm": "64041100", "origin": "0", "cfop": "6101", "unit": "PAR", "quantity": "20", "unitPrice": "75.00", "taxes": { "icms": { "cst": "00", "rate": "12" }, "ipi": { "cst": "50", "rate": "10" }, "pis": { "cst": "01", "rate": "1.65" }, "cofins": { "cst": "01", "rate": "7.6" } } } ] } } } }, "responses": { "200": { "description": "Cálculo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "maxLength": 20 }, "year": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "description": "Item calculado: CFOP, valores, impostos (icms, ipi, pis, cofins, ibsCbs), decisões do motor e sugestões de redução pelo NCM." }, "maxItems": 990, "description": "Itens na ordem do pedido." }, "totals": { "type": "object", "description": "Totais como sairiam na NF-e, em texto decimal." }, "invoiceMessages": { "type": [ "string", "null" ], "maxLength": 100000 }, "warnings": { "type": "array", "items": { "type": "string", "maxLength": 100000 }, "maxItems": 1000 }, "basis": { "type": "object", "description": "Bases legais e alíquotas usadas no cálculo." } }, "required": [ "operation", "year", "items", "totals", "invoiceMessages", "warnings", "basis" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Empresa não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Dados inválidos ou regras do ano ainda não publicadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax/classifications": { "get": { "tags": [ "Impostos" ], "summary": "Tabela de classificação do IBS/CBS", "description": "CST e cClassTrib oficiais, com as reduções de cada classificação.", "operationId": "getV1TaxClassifications", "parameters": [ { "name": "cst", "in": "query", "required": false, "description": "Filtra por CST.", "schema": { "type": "string", "pattern": "^[0-9]{3}$" } }, { "name": "q", "in": "query", "required": false, "description": "Busca no nome ou no código.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "responses": { "200": { "description": "Classificações.", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "object", "description": "Tabela oficial usada (versão e data)." }, "data": { "type": "array", "items": { "type": "object", "properties": { "cst": { "type": "string", "maxLength": 3 }, "classTrib": { "type": "string", "maxLength": 6 }, "description": { "type": "string", "maxLength": 100000 }, "taxed": { "description": "Tributação (texto da tabela oficial)." }, "ibsReduction": { "description": "Percentual de redução do IBS." }, "cbsReduction": { "description": "Percentual de redução da CBS." }, "supported": { "type": "boolean", "description": "true: a emitza já emite com este CST." } }, "required": [ "cst", "classTrib", "description", "taxed", "ibsReduction", "cbsReduction", "supported" ], "additionalProperties": false }, "maxItems": 10000 } }, "required": [ "source", "data" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "CST inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax/ncm/{ncm}": { "get": { "tags": [ "Impostos" ], "summary": "Reduções possíveis para um NCM", "description": "Itens dos anexos da LC 214/2025 que citam o NCM (redução do IBS/CBS) e o Imposto Seletivo. A redução só vale se o produto corresponder à descrição legal.", "operationId": "getV1TaxNcmByNcm", "parameters": [ { "name": "ncm", "in": "path", "required": true, "description": "NCM com 8 dígitos (pontuação aceita).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reduções.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ncm": { "type": "string", "maxLength": 8 }, "reductions": { "type": "array", "items": { "type": "object", "properties": { "annex": { "type": "string", "maxLength": 10 }, "item": { "type": [ "string", "integer" ] }, "description": { "type": "string", "maxLength": 100000 }, "classTrib": { "type": [ "string", "null" ], "maxLength": 6 }, "publicBuyerClassTrib": { "type": [ "string", "null" ], "maxLength": 6 }, "reduction": { "type": [ "string", "number", "null" ] }, "legalBasis": { "type": "string", "maxLength": 100000 } }, "required": [ "annex", "item", "description", "classTrib", "publicBuyerClassTrib", "reduction", "legalBasis" ], "additionalProperties": false }, "maxItems": 200 }, "selectiveTax": { "anyOf": [ { "description": "Imposto Seletivo possível para o NCM, ou null." }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 100000 }, "source": { "type": "object", "description": "Fonte das listas de NCM." } }, "required": [ "ncm", "reductions", "selectiveTax", "note", "source" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "NCM inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax/rules": { "get": { "tags": [ "Impostos" ], "summary": "Regras do IBS/CBS de um ano", "description": "Alíquotas do ano e o que ainda falta ser publicado pelo governo.", "operationId": "getV1TaxRules", "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Ano (padrão: o atual).", "schema": { "type": "integer", "minimum": 2026, "maximum": 2033 } }, { "name": "crt", "in": "query", "required": false, "description": "Regime (padrão: 3).", "schema": { "type": "integer", "enum": [ 1, 2, 3, 4 ] } } ], "responses": { "200": { "description": "Regras.", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "rates": { "type": [ "object", "null" ], "description": "Alíquotas do IBS (UF e município) e da CBS no ano." }, "source": { "anyOf": [ { "description": "Base legal das alíquotas." }, { "type": "null" } ] }, "pending": { "type": "array", "items": { "type": "object", "description": "O que ainda falta ser publicado para o ano (code, what, expected)." }, "maxItems": 100, "description": "Regras ainda não publicadas." }, "available": { "type": "boolean", "description": "true: tudo publicado; dá para emitir com as regras do ano." }, "knownYears": { "type": "array", "items": { "type": "integer" }, "maxItems": 20 } }, "required": [ "year", "rates", "source", "pending", "available", "knownYears" ], "additionalProperties": false } } } }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Ano ou crt inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/coverage": { "get": { "tags": [ "Cobertura" ], "summary": "Cobertura por município", "description": "O que a emitza atende em cada município de SP: NF-e (todos, pela SEFAZ-SP) e NFS-e por regime, conforme a adesão do município ao emissor nacional, conferida todo mês no Sistema Nacional. Sem chave.", "operationId": "getV1Coverage", "parameters": [ { "name": "uf", "in": "query", "required": false, "description": "UF (por enquanto, só SP).", "schema": { "type": "string", "enum": [ "SP" ] } } ], "responses": { "200": { "description": "Municípios da UF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uf": { "type": "string", "maxLength": 2 }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Fim da última conferência completa (mensal)." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coverage" }, "maxItems": 1000 } }, "required": [ "uf", "updatedAt", "data" ], "additionalProperties": false } } } }, "422": { "description": "UF não atendida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/coverage/{cityCode}": { "get": { "tags": [ "Cobertura" ], "summary": "Cobertura de um município", "operationId": "getV1CoverageByCityCode", "parameters": [ { "name": "cityCode", "in": "path", "required": true, "description": "Código IBGE do município (7 dígitos).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Município.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" } } } }, "404": { "description": "Município fora de SP ou inexistente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Código IBGE inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/mcp": { "post": { "tags": [ "MCP" ], "summary": "Servidor MCP (para IA)", "description": "Model Context Protocol no transporte Streamable HTTP, sem sessão e com respostas em JSON. Configure no cliente de IA a URL https://api-sandbox.emitza.com.br/mcp (ou api.emitza.com.br/mcp) com o cabeçalho Authorization: Bearer . Tools: consultar_conta, listar_empresas, cadastrar_empresa, calcular_impostos, emitir_nfe, emitir_nfse, consultar_nota, cancelar_nota, baixar_documento.", "operationId": "postMcp", "responses": { "200": { "description": "Resposta JSON-RPC 2.0.", "content": { "application/json": { "schema": { "type": [ "object", "array" ], "description": "Mensagem (ou lista de mensagens) JSON-RPC 2.0." } } } }, "202": { "description": "Só notificações: nada a responder." }, "401": { "description": "Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Origin não permitido (navegador de outro site).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de requisições; espere o tempo de Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "nfe.authorized": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.authorized", "description": "NF-e autorizada pela SEFAZ. O XML e o DANFE já podem ser baixados.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeAuthorized", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.authorized" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NF-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "series": { "type": "integer" }, "number": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 44 }, "protocol": { "type": "string", "maxLength": 20 }, "authorizedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "companyId", "environment", "series", "number", "accessKey", "protocol", "authorizedAt" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.rejected": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.rejected", "description": "NF-e rejeitada (cStat e motivo da SEFAZ). Corrija o pedido e reenvie com o mesmo externalId.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeRejected", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.rejected" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NF-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "series": { "type": "integer" }, "number": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 44 }, "cStat": { "type": "string", "maxLength": 10 }, "reason": { "type": "string", "maxLength": 100000 } }, "required": [ "id", "externalId", "companyId", "environment", "series", "number", "accessKey", "cStat", "reason" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.denied": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.denied", "description": "Uso denegado: a SEFAZ registrou a nota, mas ela não vale (irregularidade do emitente ou destinatário). O número fica consumido.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeDenied", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.denied" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NF-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "series": { "type": "integer" }, "number": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 44 }, "cStat": { "type": [ "string", "null" ], "maxLength": 10 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "id", "externalId", "companyId", "environment", "series", "number", "accessKey", "cStat", "reason" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.failed": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.failed", "description": "A emissão parou sem resposta da SEFAZ (ex.: certificado vencido). Corrija e chame POST /v1/nfe/{id}/retry.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeFailed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NF-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "series": { "type": "integer" }, "number": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 44 }, "failure": { "type": "string", "maxLength": 60 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "id", "externalId", "companyId", "environment", "series", "number", "accessKey", "failure", "reason" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.cancelled": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.cancelled", "description": "Cancelamento registrado na SEFAZ.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeCancelled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NF-e." }, "externalId": { "type": "string", "maxLength": 100 }, "accessKey": { "type": "string", "maxLength": 44 }, "event": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24 }, "type": { "type": "string", "enum": [ "cancel", "correction" ] }, "sequence": { "type": "integer" } }, "required": [ "id", "type", "sequence" ], "additionalProperties": false }, "protocol": { "type": "string", "maxLength": 20 }, "cStat": { "type": "string", "maxLength": 10 } }, "required": [ "id", "externalId", "accessKey", "event", "protocol", "cStat" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.correction_registered": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.correction_registered", "description": "Carta de correção registrada.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeCorrectionRegistered", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.correction_registered" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NF-e." }, "externalId": { "type": "string", "maxLength": 100 }, "accessKey": { "type": "string", "maxLength": 44 }, "event": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24 }, "type": { "type": "string", "enum": [ "cancel", "correction" ] }, "sequence": { "type": "integer" } }, "required": [ "id", "type", "sequence" ], "additionalProperties": false }, "protocol": { "type": "string", "maxLength": 20 }, "text": { "type": "string", "maxLength": 100000 } }, "required": [ "id", "externalId", "accessKey", "event", "protocol", "text" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.event_rejected": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.event_rejected", "description": "Cancelamento, carta de correção (com \"event\") ou inutilização (kind \"disable\") rejeitado ou com falha.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeEventRejected", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.event_rejected" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24 }, "externalId": { "type": "string", "maxLength": 100 }, "accessKey": { "type": "string", "maxLength": 44 }, "event": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24 }, "type": { "type": "string", "enum": [ "cancel", "correction" ] }, "sequence": { "type": "integer" } }, "required": [ "id", "type", "sequence" ], "additionalProperties": false }, "kind": { "type": "string", "enum": [ "disable" ] }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "series": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "cStat": { "type": "string", "maxLength": 10 }, "failure": { "type": "string", "maxLength": 60 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfe.disabled": { "post": { "tags": [ "Webhooks" ], "summary": "nfe.disabled", "description": "Faixa de numeração inutilizada.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfeDisabled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfe.disabled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da inutilização." }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "series": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "protocol": { "type": [ "string", "null" ], "maxLength": 20 }, "cStat": { "type": "string", "maxLength": 10 } }, "required": [ "id", "companyId", "environment", "series", "from", "to", "protocol", "cStat" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfse.authorized": { "post": { "tags": [ "Webhooks" ], "summary": "nfse.authorized", "description": "NFS-e gerada pelo Sistema Nacional. XML e DANFSe disponíveis.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfseAuthorized", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfse.authorized" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NFS-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "dpsSeries": { "type": "integer" }, "dpsNumber": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 50 }, "number": { "type": [ "string", "null" ], "maxLength": 20 }, "authorizedAt": { "type": "string", "format": "date-time" }, "values": { "type": "object", "description": "Valores da NFS-e gerada." } }, "required": [ "id", "externalId", "companyId", "environment", "dpsSeries", "dpsNumber", "accessKey", "number", "authorizedAt", "values" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfse.rejected": { "post": { "tags": [ "Webhooks" ], "summary": "nfse.rejected", "description": "DPS rejeitada pelo Sefin (lista de erros com código). Corrija e reenvie com o mesmo externalId.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfseRejected", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfse.rejected" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NFS-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "dpsSeries": { "type": "integer" }, "dpsNumber": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 50 }, "number": { "type": [ "string", "null" ], "maxLength": 20 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "maxLength": 20 }, "message": { "type": [ "string", "null" ], "maxLength": 100000 }, "complement": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code", "message", "complement" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "id", "externalId", "companyId", "environment", "dpsSeries", "dpsNumber", "accessKey", "number", "errors" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfse.failed": { "post": { "tags": [ "Webhooks" ], "summary": "nfse.failed", "description": "A emissão parou sem resposta do Sefin. Corrija e chame POST /v1/nfse/{id}/retry.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfseFailed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfse.failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NFS-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "environment": { "type": "string", "enum": [ "homologation", "production" ] }, "dpsSeries": { "type": "integer" }, "dpsNumber": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 50 }, "number": { "type": [ "string", "null" ], "maxLength": 20 }, "failure": { "type": "string", "maxLength": 60 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "id", "externalId", "companyId", "environment", "dpsSeries", "dpsNumber", "accessKey", "number", "failure", "reason" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfse.cancelled": { "post": { "tags": [ "Webhooks" ], "summary": "nfse.cancelled", "description": "Cancelamento da NFS-e registrado.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfseCancelled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfse.cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NFS-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "accessKey": { "type": "string", "maxLength": 50 }, "eventId": { "type": "string", "maxLength": 24 }, "type": { "type": "string", "enum": [ "cancel" ] }, "cancelledAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "companyId", "accessKey", "eventId", "type", "cancelledAt" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "nfse.event_rejected": { "post": { "tags": [ "Webhooks" ], "summary": "nfse.event_rejected", "description": "Cancelamento da NFS-e rejeitado.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookNfseEventRejected", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "nfse.event_rejected" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da NFS-e." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "maxLength": 24 }, "accessKey": { "type": "string", "maxLength": 50 }, "eventId": { "type": "string", "maxLength": 24 }, "type": { "type": "string", "enum": [ "cancel" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "maxLength": 20 }, "message": { "type": [ "string", "null" ], "maxLength": 100000 }, "complement": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code", "message", "complement" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "id", "externalId", "companyId", "accessKey", "eventId", "type", "errors" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "certificate.expiring": { "post": { "tags": [ "Webhooks" ], "summary": "certificate.expiring", "description": "O certificado da empresa vence em breve (avisos a 30, 15 e 7 dias).\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookCertificateExpiring", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "certificate.expiring" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "companyId": { "type": "string", "maxLength": 24 }, "cnpj": { "type": "string", "maxLength": 14 }, "notAfter": { "type": "string", "format": "date-time" }, "daysLeft": { "type": "integer" } }, "required": [ "companyId", "cnpj", "notAfter", "daysLeft" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "certificate.expired": { "post": { "tags": [ "Webhooks" ], "summary": "certificate.expired", "description": "O certificado da empresa venceu; as emissões param até o envio de um novo.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookCertificateExpired", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "certificate.expired" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "companyId": { "type": "string", "maxLength": 24 }, "cnpj": { "type": "string", "maxLength": 14 }, "notAfter": { "type": "string", "format": "date-time" }, "daysLeft": { "type": "integer" } }, "required": [ "companyId", "cnpj", "notAfter", "daysLeft" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "sefaz.contingency_started": { "post": { "tags": [ "Webhooks" ], "summary": "sefaz.contingency_started", "description": "Reservado: contingência da SEFAZ (ainda não enviado).\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookSefazContingencyStarted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "sefaz.contingency_started" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "sefaz.contingency_ended": { "post": { "tags": [ "Webhooks" ], "summary": "sefaz.contingency_ended", "description": "Reservado: fim da contingência (ainda não enviado).\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookSefazContingencyEnded", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "sefaz.contingency_ended" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } }, "webhook.test": { "post": { "tags": [ "Webhooks" ], "summary": "webhook.test", "description": "Disparado por POST /v1/webhooks/{id}/test.\n\nCabeçalhos: X-Fiscal-Event, X-Fiscal-Delivery e X-Fiscal-Signature (HMAC-SHA256). Responda 2xx; sem isso, novas tentativas por cerca de 24 h.", "operationId": "webhookWebhookTest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24, "description": "id da entrega. A mesma entrega pode chegar mais de uma vez: use o id para ignorar repetições." }, "event": { "type": "string", "enum": [ "webhook.test" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 100000 } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "id", "event", "createdAt", "data" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Chave da API: fsk_test_... (sandbox) ou fsk_live_... (produção)." } }, "schemas": { "Address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 2, "maxLength": 60 }, "number": { "type": "string", "minLength": 1, "maxLength": 60 }, "complement": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "district": { "type": "string", "minLength": 2, "maxLength": 60 }, "cityName": { "type": "string", "minLength": 2, "maxLength": 60 }, "cityCode": { "type": "string", "pattern": "^[0-9]{7}$" }, "uf": { "type": "string", "enum": [ "RO", "AC", "AM", "RR", "PA", "AP", "TO", "MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA", "MG", "ES", "RJ", "SP", "PR", "SC", "RS", "MS", "MT", "GO", "DF" ] }, "zip": { "type": "string", "pattern": "^[0-9]{8}$" }, "phone": { "type": [ "string", "null" ], "pattern": "^[0-9]{6,14}$" } }, "required": [ "street", "number", "district", "cityName", "cityCode", "uf", "zip" ], "additionalProperties": false, "description": "Endereço da empresa. cityCode é o código IBGE do município (7 dígitos)." }, "ApproximateTaxes": { "type": "object", "properties": { "simplesRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 99.99)." }, "rates": { "type": "object", "properties": { "federal": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 100)." }, "state": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 100)." }, "municipal": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 100)." } }, "required": [ "federal", "state", "municipal" ], "additionalProperties": false }, "amounts": { "type": "object", "properties": { "federal": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "state": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "municipal": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "required": [ "federal", "state", "municipal" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Total aproximado dos tributos (Lei 12.741/2012). Informe só um: simplesRate, rates ou amounts." }, "Company": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "cnpj": { "type": "string", "maxLength": 14 }, "ie": { "type": "string", "maxLength": 20 }, "im": { "type": [ "string", "null" ], "maxLength": 15 }, "crt": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "legalName": { "type": "string", "maxLength": 100000 }, "tradeName": { "type": [ "string", "null" ], "maxLength": 100000 }, "email": { "type": [ "string", "null" ], "maxLength": 100000 }, "address": { "type": "object", "description": "Endereço, como cadastrado." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente: homologation (sem valor fiscal) ou production." }, "sandbox": { "type": "boolean", "description": "true: empresa criada com chave de teste (fsk_test_); só emite em homologação." }, "nfe": { "type": "object", "properties": { "homologation": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "next": { "type": "integer" } }, "required": [ "number", "next" ], "additionalProperties": false }, "maxItems": 1000 }, "defaultSeries": { "type": [ "integer", "null" ] } }, "required": [ "series", "defaultSeries" ], "additionalProperties": false }, "production": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "next": { "type": "integer" } }, "required": [ "number", "next" ], "additionalProperties": false }, "maxItems": 1000 }, "defaultSeries": { "type": [ "integer", "null" ] } }, "required": [ "series", "defaultSeries" ], "additionalProperties": false } }, "required": [ "homologation", "production" ], "additionalProperties": false, "description": "Séries e próximos números da NF-e, separados por ambiente." }, "nfse": { "type": "object", "properties": { "settings": { "type": "object", "description": "Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null." }, "homologation": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "next": { "type": "integer" } }, "required": [ "number", "next" ], "additionalProperties": false }, "maxItems": 1000 }, "defaultSeries": { "type": [ "integer", "null" ] } }, "required": [ "series", "defaultSeries" ], "additionalProperties": false }, "production": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "next": { "type": "integer" } }, "required": [ "number", "next" ], "additionalProperties": false }, "maxItems": 1000 }, "defaultSeries": { "type": [ "integer", "null" ] } }, "required": [ "series", "defaultSeries" ], "additionalProperties": false } }, "required": [ "settings", "homologation", "production" ], "additionalProperties": false, "description": "Configuração e séries da DPS (NFS-e nacional)." }, "certificate": { "type": [ "object", "null" ], "properties": { "cnpj": { "type": [ "string", "null" ], "maxLength": 14 }, "subjectName": { "type": [ "string", "null" ], "maxLength": 100000 }, "issuer": { "type": [ "string", "null" ], "maxLength": 100000 }, "serialNumber": { "type": [ "string", "null" ], "maxLength": 100000 }, "notBefore": { "type": "string", "format": "date-time" }, "notAfter": { "type": "string", "format": "date-time" }, "uploadedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "valid", "expiring", "expired" ] }, "daysLeft": { "type": "integer" } }, "required": [ "cnpj", "subjectName", "issuer", "serialNumber", "notBefore", "notAfter", "uploadedAt", "status", "daysLeft" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "cnpj", "ie", "im", "crt", "legalName", "tradeName", "email", "address", "environment", "sandbox", "nfe", "nfse", "certificate", "createdAt", "updatedAt" ], "additionalProperties": false }, "CompanyCreate": { "type": "object", "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 18, "description": "CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico).", "examples": [ "11222333000181" ] }, "ie": { "type": "string", "minLength": 2, "maxLength": 20, "description": "Inscrição estadual (dígitos, com ou sem pontuação) ou \"ISENTO\"." }, "im": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 15, "description": "Inscrição municipal (necessária para NFS-e em alguns municípios)." }, "crt": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Regime tributário (CRT): 1 Simples Nacional, 2 Simples com excesso de sublimite, 3 regime normal (Presumido ou Real), 4 MEI." }, "legalName": { "type": "string", "minLength": 2, "maxLength": 60 }, "tradeName": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "address": { "$ref": "#/components/schemas/Address" }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "homologation: testes, sem valor fiscal. production: notas com valor fiscal." }, "nfeSeries": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer", "minimum": 0, "maximum": 889, "description": "Série da NF-e (0 a 889)." }, "next": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "Próximo número a usar nesta série." } }, "required": [ "number", "next" ], "additionalProperties": false }, "maxItems": 10, "description": "Séries da NF-e já usadas pela empresa, com o próximo número (para continuar a numeração de outro sistema)." } }, "required": [ "cnpj", "ie", "crt", "legalName", "address" ], "additionalProperties": false }, "CompanyUpdate": { "type": "object", "properties": { "ie": { "type": "string", "minLength": 2, "maxLength": 20, "description": "Inscrição estadual (dígitos, com ou sem pontuação) ou \"ISENTO\"." }, "im": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 15 }, "crt": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Regime tributário (CRT): 1 Simples Nacional, 2 Simples com excesso de sublimite, 3 regime normal (Presumido ou Real), 4 MEI." }, "legalName": { "type": "string", "minLength": 2, "maxLength": 60 }, "tradeName": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "address": { "$ref": "#/components/schemas/Address" }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "homologation: testes, sem valor fiscal. production: notas com valor fiscal." } }, "additionalProperties": false, "description": "Só os campos enviados mudam. O CNPJ não muda." }, "Coverage": { "type": "object", "properties": { "cityCode": { "type": "string", "maxLength": 7 }, "name": { "type": "string", "maxLength": 100000 }, "uf": { "type": "string", "maxLength": 2 }, "nfe": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available" ] }, "via": { "type": "string", "enum": [ "SEFAZ-SP" ] } }, "required": [ "status", "via" ], "additionalProperties": false, "description": "NF-e: todos os municípios de SP, pela SEFAZ-SP." }, "nfse": { "type": "object", "properties": { "agreement": { "type": [ "boolean", "null" ], "description": "Município conveniado ao Sistema Nacional da NFS-e." }, "nationalIssuer": { "type": [ "boolean", "null" ], "description": "Aceita os emissores nacionais. null: ainda não conferido." }, "simplesMei": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "available_from", "planned", "unknown" ], "description": "MEI e Simples Nacional. available: emite pelo padrão nacional; available_from: a partir de \"from\" (obrigatoriedade nacional); unknown: não conferido." }, "via": { "type": "string", "enum": [ "national" ] }, "from": { "type": "string", "maxLength": 10 } }, "required": [ "status", "via" ], "additionalProperties": false, "description": "MEI e Simples Nacional." }, "otherRegimes": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "available_from", "planned", "unknown" ], "description": "Lucro Presumido e Real. available: pelo padrão nacional; planned: pelo sistema da prefeitura, ainda não atendido; unknown: não conferido." }, "via": { "type": "string", "enum": [ "national", "municipal" ] } }, "required": [ "status", "via" ], "additionalProperties": false, "description": "Lucro Presumido e Lucro Real." } }, "required": [ "agreement", "nationalIssuer", "simplesMei", "otherRegimes" ], "additionalProperties": false, "description": "NFS-e por regime." }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando a adesão foi conferida no Sistema Nacional (ADN)." } }, "required": [ "cityCode", "name", "uf", "nfe", "nfse", "checkedAt" ], "additionalProperties": false }, "Disablement": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente: homologation (sem valor fiscal) ou production." }, "series": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "justification": { "type": "string", "maxLength": 100000 }, "status": { "type": "string", "enum": [ "queued", "sending", "unknown", "disabled", "rejected", "failed" ] }, "protocol": { "type": [ "string", "null" ], "maxLength": 20 }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "rejection": { "type": [ "object", "null" ], "properties": { "cStat": { "type": "string", "maxLength": 10 }, "reason": { "type": "string", "maxLength": 100000 }, "at": { "type": "string", "format": "date-time" } }, "required": [ "cStat", "reason", "at" ], "additionalProperties": false }, "failure": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "maxLength": 60 } }, "required": [ "code" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "companyId", "environment", "series", "from", "to", "justification", "status", "protocol", "disabledAt", "rejection", "failure", "createdAt", "updatedAt" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 60, "description": "Código estável para tratar no seu sistema (ex.: validation_failed, not_found, conflict, sandbox_homologation_only)." }, "message": { "type": "string", "maxLength": 100000, "description": "Mensagem em português." }, "details": { "type": "array", "items": { "type": "object" }, "maxItems": 1000, "description": "Em validation_failed: lista de { path, message }, com o caminho do campo (ex.: items[2].ncm)." } }, "required": [ "code", "message", "details" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "IbsCbsTax": { "type": "object", "properties": { "cst": { "type": "string", "pattern": "^[0-9]{3}$", "description": "CST do IBS/CBS (tabela da Reforma Tributária; veja GET /v1/tax/classifications)." }, "classTrib": { "type": "string", "pattern": "^[0-9]{6}$", "description": "cClassTrib: classificação tributária do IBS/CBS (veja GET /v1/tax/classifications)." }, "ibsUfRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "ibsMunRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "cbsRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "donation": { "type": "boolean" }, "ibsValue": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "cbsValue": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "required": [ "cst", "classTrib" ], "additionalProperties": false, "description": "IBS/CBS informado à mão (modo avançado). Ausente, o motor decide." }, "IcmsTax": { "type": "object", "properties": { "cst": { "type": "string", "enum": [ "00", "20", "40", "41", "50", "51", "90" ], "description": "CST do ICMS (regime normal)." }, "csosn": { "type": "string", "enum": [ "101", "102", "103", "300", "400", "900" ], "description": "CSOSN (Simples Nacional)." }, "rate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "baseReduction": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "deferral": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 100)." }, "creditRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota do crédito do Simples (CSOSN 101 e 900)." }, "value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "additionalProperties": false, "description": "ICMS do item. Informe cst (regime normal) ou csosn (Simples), um dos dois." }, "IpiTax": { "type": "object", "properties": { "cst": { "type": "string", "enum": [ "00", "01", "02", "03", "04", "05", "49", "50", "51", "52", "53", "54", "55", "99" ] }, "enquadramento": { "type": "string", "pattern": "^[0-9]{3}$", "description": "Código de enquadramento legal do IPI (padrão 999)." }, "rate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "required": [ "cst" ], "additionalProperties": false }, "Nfe": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente: homologation (sem valor fiscal) ou production." }, "status": { "type": "string", "enum": [ "queued", "sending", "pending", "unknown", "authorized", "rejected", "denied", "failed", "cancelled", "disabled" ], "description": "queued/sending/pending: em andamento. unknown: resposta perdida, em conferência com a SEFAZ. authorized, rejected, denied, failed: resultado. cancelled e disabled: depois de um evento." }, "series": { "type": "integer" }, "number": { "type": [ "integer", "null" ] }, "accessKey": { "type": [ "string", "null" ], "maxLength": 50, "description": "Chave de acesso (44 caracteres na NF-e; 50 na NFS-e)." }, "protocol": { "type": [ "string", "null" ], "maxLength": 20 }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rejection": { "type": [ "object", "null" ], "properties": { "cStat": { "type": "string", "maxLength": 10 }, "reason": { "type": "string", "maxLength": 100000 }, "at": { "type": "string", "format": "date-time" } }, "required": [ "cStat", "reason", "at" ], "additionalProperties": false, "description": "Última rejeição da SEFAZ (status rejected). Corrija e reenvie com o mesmo externalId." }, "denial": { "type": [ "object", "null" ], "properties": { "cStat": { "type": [ "string", "null" ], "maxLength": 10 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "cStat", "reason" ], "additionalProperties": false }, "failure": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "maxLength": 60 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code" ], "additionalProperties": false }, "attention": { "type": [ "string", "null" ], "maxLength": 60, "description": "Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired." }, "totals": { "type": [ "object", "null" ], "description": "Totais calculados (produtos, impostos, total da nota), em texto decimal." }, "warnings": { "type": "array", "items": { "type": "string", "maxLength": 100000 }, "maxItems": 1000, "description": "Avisos do cálculo; não impedem a emissão." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "companyId", "environment", "status", "series", "number", "accessKey", "protocol", "authorizedAt", "rejection", "denial", "failure", "attention", "totals", "warnings", "createdAt", "updatedAt" ], "additionalProperties": false }, "NfeCreate": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Seu identificador do pedido. Também é a chave de idempotência: repetir o mesmo externalId devolve a mesma nota (200), nunca uma segunda." }, "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "id da empresa emitente (devolvido em POST /v1/companies)." }, "operation": { "type": "string", "enum": [ "sale", "return", "bonus", "transfer" ], "description": "sale venda, return devolução, bonus bonificação, transfer transferência." }, "direction": { "type": "string", "enum": [ "out", "in" ], "description": "Só em devolução: out nota de saída (padrão), in nota de entrada." }, "series": { "type": "integer", "minimum": 0, "maximum": 889, "description": "Série (padrão: a série padrão da empresa no ambiente)." }, "natureOfOperation": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Natureza da operação impressa na nota (ex.: \"Venda de mercadoria\")." }, "presence": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "9" ], "description": "Indicador de presença do comprador (indPres): 0 não se aplica, 1 presencial, 2 internet, 3 teleatendimento, 4 entrega a domicílio, 5 presencial fora do estabelecimento, 9 outros." }, "finalConsumer": { "type": "boolean", "description": "Venda a consumidor final (indFinal)." }, "recipient": { "$ref": "#/components/schemas/NfeRecipient" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NfeItem" }, "minItems": 1, "maxItems": 990 }, "charges": { "type": "object", "properties": { "freight": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "insurance": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "otherExpenses": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "discount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "additionalProperties": false }, "transport": { "$ref": "#/components/schemas/Transport" }, "payments": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "pattern": "^[0-9]{2}$", "description": "Meio de pagamento (tPag): 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 15 boleto, 17 PIX, 90 sem pagamento, 99 outros." }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "description": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Descrição do meio quando method é 99." }, "term": { "type": "string", "enum": [ "cash", "installments" ], "description": "cash à vista, installments a prazo." } }, "required": [ "method" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "billing": { "type": [ "object", "null" ], "properties": { "number": { "type": "string", "minLength": 1, "maxLength": 60 }, "installments": { "type": "array", "items": { "type": "object", "properties": { "dueDate": { "type": "string", "minLength": 10, "maxLength": 10, "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "format": "date" }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "required": [ "dueDate" ], "additionalProperties": false }, "minItems": 1, "maxItems": 120 } }, "required": [ "installments" ], "additionalProperties": false, "description": "Fatura e duplicatas (vendas a prazo)." }, "purchaseOrder": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "additionalInfo": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 4000, "description": "Informações complementares de interesse do contribuinte." }, "fiscalInfo": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000, "description": "Informações de interesse do Fisco." }, "expectedTotal": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Total que você espera. Se o calculado for diferente, a nota é recusada antes de ir à SEFAZ." } }, "required": [ "externalId", "companyId", "operation", "natureOfOperation", "recipient", "items", "transport", "payments" ], "additionalProperties": false }, "NfeEvent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "nfeId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "type": { "type": "string", "enum": [ "cancel", "correction" ], "description": "cancel cancelamento (110111), correction carta de correção (110110)." }, "sequence": { "type": "integer" }, "text": { "type": "string", "maxLength": 100000 }, "status": { "type": "string", "enum": [ "queued", "sending", "unknown", "registered", "rejected", "failed" ] }, "protocol": { "type": [ "string", "null" ], "maxLength": 20 }, "registeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "rejection": { "type": [ "object", "null" ], "properties": { "cStat": { "type": "string", "maxLength": 10 }, "reason": { "type": "string", "maxLength": 100000 }, "at": { "type": "string", "format": "date-time" } }, "required": [ "cStat", "reason", "at" ], "additionalProperties": false }, "failure": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "maxLength": 60 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code" ], "additionalProperties": false }, "attention": { "type": [ "string", "null" ], "maxLength": 60, "description": "Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "nfeId", "type", "sequence", "text", "status", "protocol", "registeredAt", "rejection", "failure", "attention", "createdAt", "updatedAt" ], "additionalProperties": false }, "NfeItem": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Código do produto no seu sistema." }, "description": { "type": "string", "minLength": 1, "maxLength": 120 }, "ncm": { "type": "string", "pattern": "^[0-9]{8}$", "description": "NCM do produto (8 dígitos)." }, "cest": { "type": [ "string", "null" ], "pattern": "^[0-9]{7}$" }, "gtin": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 14, "pattern": "^(SEM GTIN|\\d{8}|\\d{12,14})$", "description": "Código de barras (GTIN) ou \"SEM GTIN\"." }, "origin": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8" ], "description": "Origem da mercadoria: 0 nacional; 1 a 8 importada ou com conteúdo importado (tabela do ICMS)." }, "cfop": { "type": "string", "pattern": "^[0-9]{4}$", "description": "CFOP. Obrigatório sem taxClass; com taxClass, vem da classe." }, "taxClass": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[A-Za-z0-9_.-]+$", "description": "Código de uma classe de imposto da empresa (POST /v1/companies/{id}/tax-classes): CFOP, ICMS, IPI, PIS e COFINS saem dela." }, "unit": { "type": "string", "minLength": 1, "maxLength": 6, "description": "Unidade comercial (ex.: UN, KG, PAR)." }, "quantity": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Decimal em texto, com ponto e até 4 casas (mínimo 0.0001)." }, "unitPrice": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,10})?$", "description": "Preço unitário bruto." }, "netUnitPrice": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,10})?$", "description": "Preço unitário líquido, quando a empresa calcula pelo líquido." }, "discount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "freight": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "insurance": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "otherExpenses": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "approxTaxes": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "purchaseOrder": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 15 }, "purchaseOrderItem": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,6}$" }, "additionalInfo": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "reference": { "type": "object", "properties": { "accessKey": { "type": "string", "minLength": 44, "maxLength": 44, "pattern": "^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$", "description": "Chave de acesso de 44 caracteres." }, "item": { "type": "integer", "minimum": 1, "maximum": 990 } }, "required": [ "accessKey" ], "additionalProperties": false, "description": "Só em devolução: a NF-e original e o número do item nela." }, "returnedIpi": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "percent": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (mínimo 0.01, máximo 100)." } }, "required": [ "value" ], "additionalProperties": false, "description": "Só em devolução: IPI devolvido." }, "taxes": { "type": "object", "properties": { "icms": { "$ref": "#/components/schemas/IcmsTax" }, "ipi": { "anyOf": [ { "$ref": "#/components/schemas/IpiTax" }, { "type": "null" } ] }, "pis": { "$ref": "#/components/schemas/PisCofinsTax" }, "cofins": { "$ref": "#/components/schemas/PisCofinsTax" }, "ibsCbs": { "anyOf": [ { "$ref": "#/components/schemas/IbsCbsTax", "description": "Ausente: o motor decide o IBS/CBS. null: nota sem o grupo do IBS/CBS." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Impostos do item. Sem taxClass, informe icms, pis e cofins. Com taxClass, o que vier aqui prevalece sobre a classe." } }, "required": [ "code", "description", "ncm", "origin", "unit", "quantity", "unitPrice" ], "additionalProperties": false }, "NfeRecipient": { "type": "object", "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 18, "description": "CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico).", "examples": [ "11222333000181" ] }, "cpf": { "type": "string", "pattern": "^[0-9]{11}$", "description": "CPF, 11 dígitos." }, "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "ieIndicator": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Indicador da IE do destinatário: 1 contribuinte do ICMS (informe ie), 2 isento, 9 não contribuinte." }, "ie": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 20, "description": "Inscrição estadual (dígitos, com ou sem pontuação) ou \"ISENTO\"." }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254, "description": "Recebe o XML e o DANFE, se a empresa enviar." }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 2, "maxLength": 60 }, "number": { "type": "string", "minLength": 1, "maxLength": 60 }, "complement": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "district": { "type": "string", "minLength": 2, "maxLength": 60 }, "cityName": { "type": "string", "minLength": 2, "maxLength": 60 }, "cityCode": { "type": "string", "pattern": "^[0-9]{7}$" }, "uf": { "type": "string", "enum": [ "RO", "AC", "AM", "RR", "PA", "AP", "TO", "MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA", "MG", "ES", "RJ", "SP", "PR", "SC", "RS", "MS", "MT", "GO", "DF" ] }, "zip": { "type": [ "string", "null" ], "pattern": "^[0-9]{8}$" }, "phone": { "type": [ "string", "null" ], "pattern": "^[0-9]{6,14}$" } }, "required": [ "street", "number", "district", "cityName", "cityCode", "uf" ], "additionalProperties": false } }, "required": [ "name", "ieIndicator", "address" ], "additionalProperties": false, "description": "Destinatário. Informe cnpj ou cpf (um dos dois)." }, "Nfse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "externalId": { "type": "string", "maxLength": 100 }, "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "environment": { "type": "string", "enum": [ "homologation", "production" ], "description": "Ambiente: homologation (sem valor fiscal) ou production." }, "status": { "type": "string", "enum": [ "queued", "sending", "unknown", "authorized", "rejected", "failed", "cancelled" ], "description": "queued/sending: em andamento. unknown: resposta perdida, em conferência com o Sefin. authorized, rejected, failed: resultado. cancelled: cancelada." }, "dps": { "type": "object", "properties": { "series": { "type": "integer" }, "number": { "type": [ "integer", "null" ] }, "id": { "type": [ "string", "null" ], "maxLength": 45 } }, "required": [ "series", "number", "id" ], "additionalProperties": false, "description": "Declaração de Prestação de Serviço enviada (série, número e Id)." }, "number": { "type": [ "string", "null" ], "maxLength": 20, "description": "Número da NFS-e, dado pelo Sistema Nacional." }, "accessKey": { "type": [ "string", "null" ], "maxLength": 50, "description": "Chave de acesso (44 caracteres na NF-e; 50 na NFS-e)." }, "authorizedAt": { "type": [ "string", "null" ], "format": "date-time" }, "values": { "type": [ "object", "null" ], "description": "Valores da NFS-e gerada (base, ISSQN, líquido...), lidos do XML." }, "incidence": { "type": [ "object", "null" ], "description": "Município de incidência do ISSQN (código e nome)." }, "rejection": { "type": [ "object", "null" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "maxLength": 20 }, "message": { "type": [ "string", "null" ], "maxLength": 100000 }, "complement": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code", "message", "complement" ], "additionalProperties": false }, "maxItems": 100 }, "at": { "type": "string", "format": "date-time" } }, "required": [ "errors", "at" ], "additionalProperties": false }, "failure": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "maxLength": 60 }, "reason": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code" ], "additionalProperties": false }, "attention": { "type": [ "string", "null" ], "maxLength": 60, "description": "Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired." }, "cancellation": { "type": [ "object", "null" ], "properties": { "eventId": { "type": "string", "maxLength": 24 }, "reason": { "type": "string", "maxLength": 2 }, "at": { "type": "string", "format": "date-time" } }, "required": [ "eventId", "reason", "at" ], "additionalProperties": false }, "summary": { "type": [ "object", "null" ], "description": "Resumo do pedido calculado antes do envio." }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 60 }, "message": { "type": "string", "maxLength": 100000 } }, "required": [ "code", "message" ], "additionalProperties": false }, "maxItems": 1000, "description": "Avisos do cálculo; não impedem a emissão." }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "maxLength": 20 }, "message": { "type": [ "string", "null" ], "maxLength": 100000 }, "complement": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code", "message", "complement" ], "additionalProperties": false }, "maxItems": 20, "description": "Alertas devolvidos pelo Sefin junto com a NFS-e." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "companyId", "environment", "status", "dps", "number", "accessKey", "authorizedAt", "values", "incidence", "rejection", "failure", "attention", "cancellation", "summary", "warnings", "alerts", "createdAt", "updatedAt" ], "additionalProperties": false }, "NfseAddress": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 255 }, "number": { "type": "string", "minLength": 1, "maxLength": 60 }, "complement": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 156 }, "district": { "type": "string", "minLength": 1, "maxLength": 60 }, "cityCode": { "type": "string", "pattern": "^[0-9]{7}$" }, "zip": { "type": "string", "pattern": "^[0-9]{8}$" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "cityName": { "type": "string", "minLength": 1, "maxLength": 60 }, "state": { "type": "string", "minLength": 1, "maxLength": 60 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 11 } }, "required": [ "street", "number", "district" ], "additionalProperties": false, "description": "No Brasil: cityCode (IBGE) e zip. No exterior: country, cityName, state e postalCode." }, "NfseCreate": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Seu identificador do pedido. Também é a chave de idempotência: repetir o mesmo externalId devolve a mesma nota (200), nunca uma segunda." }, "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "id da empresa emitente (devolvido em POST /v1/companies)." }, "series": { "type": "integer", "minimum": 1, "maximum": 49999, "description": "Série da DPS (padrão: a série padrão da empresa no ambiente)." }, "competenceDate": { "type": "string", "minLength": 10, "maxLength": 10, "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "format": "date", "description": "Data de competência (padrão: hoje)." }, "service": { "type": "object", "properties": { "nationalCode": { "type": "string", "minLength": 6, "maxLength": 10, "pattern": "^[0-9.\\s-]{6,10}$", "description": "Código de tributação nacional (cTribNac, lista da LC 116), com ou sem pontos: \"01.07.01\" ou \"010701\"." }, "municipalCode": { "type": [ "string", "null" ], "pattern": "^[0-9]{3}$", "description": "Código de tributação municipal, quando o município exige." }, "nbs": { "type": [ "string", "null" ], "minLength": 9, "maxLength": 13, "pattern": "^[0-9.\\s-]{9,13}$", "description": "Código NBS (9 dígitos). Obrigatório quando a nota leva o grupo do IBS/CBS." }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Discriminação do serviço." }, "internalCode": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9]+$" }, "simplesActivity": { "type": [ "string", "null" ], "enum": [ "07", "08", "09", "10", "11", "12", "13", "14", "90", null ], "description": "Atividade do Simples Nacional (cAtvSN), só para ME/EPP; MEI e não optante não informam. Ex.: 10 para 16.01, 12 e 13 para 7.02 e 7.05." }, "location": { "type": [ "object", "null" ], "properties": { "cityCode": { "type": "string", "pattern": "^[0-9]{7}$" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false, "description": "Local da prestação. Padrão: o município da empresa." } }, "required": [ "nationalCode", "description" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "$ref": "#/components/schemas/NfseRecipient" }, { "type": "null" } ] }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Valor do serviço." }, "discounts": { "type": [ "object", "null" ], "properties": { "unconditional": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "conditional": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "additionalProperties": false }, "iss": { "type": [ "object", "null" ], "properties": { "taxation": { "type": "string", "enum": [ "taxable", "immune", "export", "not_levied" ], "description": "taxable tributável (padrão), immune imunidade, export exportação de serviço, not_levied não incidência." }, "withheld": { "type": "boolean", "description": "ISS retido pelo tomador." }, "rate": { "type": [ "string", "null" ], "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Alíquota do ISS em %. Ausente: a do município no Sistema Nacional." }, "immunityType": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ] }, "resultCountry": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" } }, "additionalProperties": false, "description": "ISSQN." }, "federal": { "type": [ "object", "null" ], "properties": { "pisCofins": { "type": "object", "properties": { "cst": { "type": "string", "enum": [ "00", "01", "02", "03", "04", "05", "06", "07", "08", "09" ] }, "base": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "pisRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 99.99)." }, "cofinsRate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas (máximo 99.99)." }, "withholding": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ] } }, "required": [ "cst" ], "additionalProperties": false }, "inss": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "irrf": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "csll": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "additionalProperties": false }, "approximateTaxes": { "anyOf": [ { "$ref": "#/components/schemas/ApproximateTaxes" }, { "type": "null" } ] }, "ibsCbs": { "type": [ "object", "null" ], "properties": { "cst": { "type": "string", "pattern": "^[0-9]{3}$" }, "classTrib": { "type": "string", "pattern": "^[0-9]{6}$" }, "operationIndicator": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Indicador da operação (cIndOp, Anexo VII da NT)." }, "finalConsumer": { "type": "boolean" } }, "required": [ "cst", "classTrib", "operationIndicator" ], "additionalProperties": false, "description": "Grupo do IBS/CBS da NFS-e." }, "orderNumber": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60, "description": "Número do pedido, impresso no DANFSe." }, "reference": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 }, "additionalInfo": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000 } }, "required": [ "externalId", "companyId", "service", "amount" ], "additionalProperties": false }, "NfseEvent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "Identificador (24 caracteres hexadecimais)." }, "type": { "type": "string", "enum": [ "cancel" ] }, "status": { "type": "string", "enum": [ "queued", "sending", "unknown", "registered", "rejected" ] }, "reason": { "type": "string", "maxLength": 2 }, "justification": { "type": "string", "maxLength": 100000 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "maxLength": 20 }, "message": { "type": [ "string", "null" ], "maxLength": 100000 }, "complement": { "type": [ "string", "null" ], "maxLength": 100000 } }, "required": [ "code", "message", "complement" ], "additionalProperties": false }, "maxItems": 100 }, "attention": { "type": [ "string", "null" ], "maxLength": 60, "description": "Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired." }, "registeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "status", "reason", "justification", "errors", "attention", "registeredAt", "createdAt" ], "additionalProperties": false }, "NfseRecipient": { "type": "object", "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 18, "description": "CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico).", "examples": [ "11222333000181" ] }, "cpf": { "type": "string", "pattern": "^[0-9]{11}$", "description": "CPF, 11 dígitos." }, "nif": { "type": "string", "minLength": 1, "maxLength": 40 }, "noNifReason": { "type": "integer", "enum": [ 0, 1, 2 ] }, "im": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 15 }, "name": { "type": "string", "minLength": 1, "maxLength": 150 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "phone": { "type": [ "string", "null" ], "pattern": "^[0-9]{6,20}$" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/NfseAddress" }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false, "description": "Tomador do serviço. Informe exatamente um: cnpj, cpf, nif (estrangeiro) ou noNifReason." }, "NfseSettings": { "type": "object", "properties": { "simplesTaxRegime": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "ME/EPP do Simples: regime de apuração (regApTribSN): 1 tributos federais e municipal pelo Simples, 2 federais pelo Simples e ISS pela NFS-e, 3 federais e municipal pela NFS-e." }, "ibsCbsSimplesRegime": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "ME/EPP do Simples: apuração do IBS/CBS (regApIBSCBSSN, NT 009)." }, "specialRegime": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 9 ], "description": "Regime especial de tributação municipal (regEspTrib); 0 nenhum." }, "simplesActivity": { "type": [ "string", "null" ], "enum": [ "07", "08", "09", "10", "11", "12", "13", "14", "90", null ], "description": "Atividade do Simples padrão da empresa (cAtvSN)." }, "approximateTaxes": { "anyOf": [ { "$ref": "#/components/schemas/ApproximateTaxes", "description": "Total aproximado dos tributos padrão das notas." }, { "type": "null" } ] } }, "additionalProperties": false }, "PisCofinsTax": { "type": "object", "properties": { "cst": { "type": "string", "enum": [ "01", "02", "04", "05", "06", "07", "08", "09", "49", "50", "51", "52", "53", "54", "55", "56", "60", "61", "62", "63", "64", "65", "66", "67", "70", "71", "72", "73", "74", "75", "98", "99" ] }, "rate": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,4})?$", "description": "Alíquota em percentual, texto com até 4 casas (ex.: \"18.00\")." }, "base": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "value": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "required": [ "cst" ], "additionalProperties": false }, "TaxCalculate": { "type": "object", "properties": { "companyId": { "type": "string", "minLength": 24, "maxLength": 24, "pattern": "^[0-9a-f]{24}$", "description": "id da empresa emitente (devolvido em POST /v1/companies)." }, "issuer": { "type": "object", "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 18, "description": "CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico).", "examples": [ "11222333000181" ] }, "crt": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "uf": { "type": "string", "enum": [ "RO", "AC", "AM", "RR", "PA", "AP", "TO", "MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA", "MG", "ES", "RJ", "SP", "PR", "SC", "RS", "MS", "MT", "GO", "DF" ] }, "cityCode": { "type": "string", "pattern": "^[0-9]{7}$" } }, "required": [ "crt", "uf" ], "additionalProperties": false, "description": "Emitente sem cadastro (só regime e UF). Use companyId ou issuer, um dos dois." }, "issueDate": { "type": "string", "minLength": 10, "maxLength": 10, "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "format": "date", "description": "Simula as regras de outra data (ex.: 2027-01-01)." }, "operation": { "type": "string", "enum": [ "sale", "return", "bonus", "transfer" ], "description": "sale venda, return devolução, bonus bonificação, transfer transferência." }, "direction": { "type": "string", "enum": [ "out", "in" ], "description": "Só em devolução: out nota de saída (padrão), in nota de entrada." }, "natureOfOperation": { "type": "string", "minLength": 1, "maxLength": 60 }, "presence": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "9" ], "description": "Indicador de presença do comprador (indPres): 0 não se aplica, 1 presencial, 2 internet, 3 teleatendimento, 4 entrega a domicílio, 5 presencial fora do estabelecimento, 9 outros." }, "finalConsumer": { "type": "boolean" }, "recipient": { "type": "object", "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 18, "description": "CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico).", "examples": [ "11222333000181" ] }, "cpf": { "type": "string", "pattern": "^[0-9]{11}$", "description": "CPF, 11 dígitos." }, "ieIndicator": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Indicador da IE do destinatário: 1 contribuinte do ICMS (informe ie), 2 isento, 9 não contribuinte." }, "uf": { "type": "string", "enum": [ "RO", "AC", "AM", "RR", "PA", "AP", "TO", "MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA", "MG", "ES", "RJ", "SP", "PR", "SC", "RS", "MS", "MT", "GO", "DF" ] }, "cityCode": { "type": "string", "pattern": "^[0-9]{7}$" } }, "required": [ "ieIndicator", "uf" ], "additionalProperties": false }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NfeItem" }, "minItems": 1, "maxItems": 990 }, "charges": { "type": "object", "properties": { "freight": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "insurance": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "otherExpenses": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "discount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "additionalProperties": false }, "payments": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "pattern": "^[0-9]{2}$", "description": "Meio de pagamento (tPag): 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 15 boleto, 17 PIX, 90 sem pagamento, 99 outros." }, "amount": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." }, "description": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Descrição do meio quando method é 99." }, "term": { "type": "string", "enum": [ "cash", "installments" ], "description": "cash à vista, installments a prazo." } }, "required": [ "method" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "expectedTotal": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,2})?$", "description": "Decimal em texto, com ponto e até 2 casas." } }, "required": [ "operation", "recipient", "items" ], "additionalProperties": false }, "TaxClass": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 30 }, "name": { "type": "string", "maxLength": 100000 }, "ibsCbs": { "type": [ "object", "null" ], "description": "Classificação do IBS/CBS fixa da classe; null: sem o grupo. Ausente: o motor decide." }, "rules": { "type": "array", "items": { "type": "object", "description": "Regra, como cadastrada." }, "maxItems": 50 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "code", "name", "rules", "createdAt", "updatedAt" ], "additionalProperties": false }, "TaxClassInput": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[A-Za-z0-9_.-]+$", "description": "Código da classe, usado em items[].taxClass." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "ibsCbs": { "type": [ "object", "null" ], "properties": { "cst": { "type": "string", "pattern": "^[0-9]{3}$" }, "classTrib": { "type": "string", "pattern": "^[0-9]{6}$" } }, "required": [ "cst", "classTrib" ], "additionalProperties": false, "description": "Classificação do IBS/CBS fixa para a classe. Ausente: o motor decide; null: sem o grupo." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/TaxClassRule" }, "minItems": 1, "maxItems": 50 } }, "required": [ "code", "name", "rules" ], "additionalProperties": false }, "TaxClassRule": { "type": "object", "properties": { "when": { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "string", "enum": [ "sale", "return", "bonus", "transfer" ] }, "minItems": 1, "maxItems": 4 }, "destination": { "type": "string", "enum": [ "internal", "interstate" ], "description": "internal dentro do estado, interstate para outro estado." }, "recipient": { "type": "string", "enum": [ "contributor", "exempt", "nonContributor" ], "description": "Tipo de destinatário (pelo ieIndicator 1, 2 ou 9)." } }, "additionalProperties": false, "description": "Quando a regra vale. Ausente: vale sempre. Vence a primeira regra que casar." }, "cfop": { "type": "string", "pattern": "^[0-9]{4}$" }, "icms": { "$ref": "#/components/schemas/IcmsTax" }, "ipi": { "anyOf": [ { "$ref": "#/components/schemas/IpiTax" }, { "type": "null" } ] }, "pis": { "$ref": "#/components/schemas/PisCofinsTax" }, "cofins": { "$ref": "#/components/schemas/PisCofinsTax" } }, "required": [ "cfop", "icms", "pis", "cofins" ], "additionalProperties": false }, "Transport": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "9" ], "description": "Modalidade do frete: 0 por conta do emitente, 1 do destinatário, 2 de terceiros, 3 próprio do emitente, 4 próprio do destinatário, 9 sem frete." }, "carrier": { "type": [ "object", "null" ], "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 18, "description": "CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico).", "examples": [ "11222333000181" ] }, "cpf": { "type": "string", "pattern": "^[0-9]{11}$", "description": "CPF, 11 dígitos." }, "name": { "type": "string", "minLength": 2, "maxLength": 60 }, "ie": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 20, "description": "Inscrição estadual (dígitos, com ou sem pontuação) ou \"ISENTO\"." }, "address": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "city": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "uf": { "type": [ "string", "null" ], "enum": [ "RO", "AC", "AM", "RR", "PA", "AP", "TO", "MA", "PI", "CE", "RN", "PB", "PE", "AL", "SE", "BA", "MG", "ES", "RJ", "SP", "PR", "SC", "RS", "MS", "MT", "GO", "DF", null ] } }, "required": [ "name" ], "additionalProperties": false }, "volumes": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 0, "maximum": 999999999999999 }, "species": { "type": "string", "minLength": 1, "maxLength": 60 }, "brand": { "type": "string", "minLength": 1, "maxLength": 60 }, "numbering": { "type": "string", "minLength": 1, "maxLength": 60 }, "netWeight": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,3})?$", "description": "Decimal em texto, com ponto e até 3 casas." }, "grossWeight": { "type": "string", "pattern": "^[0-9]{1,15}(\\.[0-9]{1,3})?$", "description": "Decimal em texto, com ponto e até 3 casas." } }, "additionalProperties": false }, "maxItems": 50 } }, "required": [ "mode" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 24 }, "url": { "type": "string", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "nfe.authorized", "nfe.rejected", "nfe.denied", "nfe.failed", "nfe.event_rejected", "nfe.cancelled", "nfe.correction_registered", "nfe.disabled", "nfse.authorized", "nfse.rejected", "nfse.failed", "nfse.cancelled", "nfse.event_rejected", "certificate.expiring", "certificate.expired", "sefaz.contingency_started", "sefaz.contingency_ended", "webhook.test" ] }, "maxItems": 100 }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "active", "createdAt" ], "additionalProperties": false } } } }