api.spedy.com.br acompanhado sempre do protocolo seguro https:// como prefixo. As versões da API são agrupadas por diretório, sufixadas ao endereço base (_https://api.spedy.com.br/v1_).\n\n## Integração com IA\n\nSe você está usando um assistente de IA (GitHub Copilot, Cursor, Claude, ChatGPT etc.) para integrar com a API Spedy, disponibilizamos um arquivo `llms.txt` com toda a documentação em formato otimizado para modelos de linguagem — sem HTML, sem overhead de UI.\n\nO arquivo contém todos os endpoints, parâmetros, exemplos de request/response, enums com descrições e fluxos de integração em texto puro.\n\n**Disponível em:** [https://api.spedy.com.br/llms.txt](https://api.spedy.com.br/llms.txt)\n\nCole o conteúdo no contexto da conversa com seu assistente, ou aponte a URL diretamente se a ferramenta suportar.\n\n# Ambiente de testes\n\nA Spedy também oferece um ambiente de testes, que é completamente isolado do ambiente de produção, portanto é necessário criar uma nova conta para utilizá-lo, escolhendo o Plano Desenvolvedor (sem custo). \n\nAs URLs do ambiente de teste estão listadas abaixo:\n\nAPI: https://sandbox-api.spedy.com.br/v1 \nBackoffice: https://sandbox-app.spedy.com.br \n\n# Exemplos de requisição\n\nDisponibilizamos exemplos de requisição em uma Collection do Insominia.\n\nPara baixá-la, clique no botão abaixo\n\n[](https://insomnia.rest/run/?label=Spedy%20API&uri=https%3A%2F%2Fdocs.spedy.com.br%2FInsomnia_2022-03-04.json)\n\n\n# Autenticação\n\nA autenticação na API é realizada por meio de **Chave de API (API Key)**, que deve ser enviada no header `X-Api-Key` em todas as requisições.\n\n## Obtendo a Chave de API\n\n### Na criação da empresa (via API)\n\nA chave de API é retornada **exclusivamente** no momento da criação de uma nova empresa, no campo `apiCredentials` da resposta. **Essa é a única vez em que a chave será exibida por completo** — armazene-a em local seguro.\n\nExemplo de resposta (campos resumidos):\n\n```json\n{\n \"result\": {\n \"id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"name\": \"Minha Empresa LTDA\",\n \"federalTaxNumber\": \"12345678000199\",\n \"apiCredentials\": {\n \"apiKey\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n }\n }\n}\n```\n\n> **Importante:** em consultas posteriores (`GET /v1/companies/{id}`), a chave será retornada ofuscada (ex: `a1b2****-****-****-****-************`).\n\n### Pelo Backoffice\n\nCaso não tenha salvo a chave no momento da criação, você pode:\n\n1. **Visualizar a chave atual** — acesse **Perfil > Minha empresa > Credenciais da API**\n2. **Gerar uma nova chave** — na mesma tela, clique em **Gerar nova chave**. A chave anterior será revogada imediatamente e deixará de funcionar.\n\n## Escopo da Chave\n\nCada empresa cadastrada possui sua própria Chave de API. O escopo de permissões depende do tipo de empresa:\n\n| Tipo | Permissões |\n|---|---|\n| **Empresa principal** (primeira da conta) | Gerenciar empresas (criar, editar, excluir) + operações de nota fiscal |\n| **Demais empresas** | Apenas operações relacionadas a nota fiscal |\n\n## Exemplo de uso\n\n```bash\ncurl -X GET https://api.spedy.com.br/v1/service-invoices \\\n -H \"X-Api-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n```\n\n# Rate Limit\n\nPara garantir a **estabilidade**, **desempenho** e **segurança** dos nossos serviços, a API impõe limites ao número de requisições que podem ser realizadas por usuário ou aplicação em um determinado intervalo de tempo.\n\n#### **Limites padrão**\n- **60 requisições por minuto**\n- **Máximo de 5 requisições por segundo**\n- Aplica-se a todas as operações (leitura e escrita)\n\nSe o cliente exceder esses limites, a API responderá com o **status HTTP 429 (Too Many Requests)**. Neste caso, recomendamos aguardar o tempo indicado no cabeçalho `x-rate-limit-reset` antes de tentar novamente. \n\n#### **Cabeçalhos de Rate Limit**\nA cada requisição, a API retorna os seguintes cabeçalhos:\n\n| Cabeçalho | Descrição |\n|--------------------------|---------------------------------------------------------------------------|\n| `x-rate-limit-limit` | Janela de tempo usada no controle de limite (ex: `1m` para 1 minuto) |\n| `x-rate-limit-remaining` | Número de requisições restantes antes de atingir o limite |\n| `x-rate-limit-reset` | Data/hora (em UTC) em que o limite será reiniciado |\n\n# Fluxo de emissão\n\nA emissão de notas fiscais na Spedy é **assíncrona**: ao receber a requisição, a Spedy valida os dados, **enfileira** a nota para processamento e responde imediatamente com a nota no status `enqueued`. O envio à Prefeitura/SEFAZ e a autorização acontecem em segundo plano — acompanhe o resultado por **webhook** (recomendado) ou consultando a nota pelo endpoint de leitura.\n\n## Formas de emissão\n\nHá duas formas de emitir uma nota, escolhidas conforme o quanto de dado tributário você quer enviar:\n\n| Forma | Endpoint | Quando usar |\n|---|---|---|\n| **Por venda** | `POST /v1/orders` | Forma mais simples: você envia apenas os dados da venda (data, cliente, itens e valor total) e a Spedy resolve a tributação a partir da configuração da empresa. Não é necessário enviar nenhuma informação tributária (códigos, impostos, retenções etc.). Atende cenários mais simples de emissão. |\n| **Nota completa** | `POST /v1/service-invoices` (NFS-e), `POST /v1/product-invoices` (NF-e), `POST /v1/consumer-invoices` (NFC-e) | Você envia os dados tributários completos, conforme o modelo da nota. Indicada para cenários mais complexos ou quando o cliente final não deve acessar o backoffice da Spedy para configurar nada. |\n\nEm ambas as formas a nota entra no mesmo fluxo de processamento assíncrono descrito a seguir.\n\n## Etapas do processamento\n\n| # | Etapa | O que acontece |\n|---|---|---|\n| 1 | **Recebimento** | Você envia a requisição (`/orders` ou `/{modelo}-invoices`). A Spedy valida o payload e cria a nota com status `enqueued`. |\n| 2 | **Enfileiramento** | A emissão é colocada na fila de processamento. |\n| 3 | **Envio à autoridade** | A Spedy transmite a nota à Prefeitura/SEFAZ. |\n| 4 | **Processamento fiscal** | A autoridade processa a nota. |\n| 5 | **Atualização de status** | A Spedy consulta o resultado e atualiza `status` e `processingDetail` da nota (ex.: `authorized`, `rejected`). |\n| 6 | **Notificação** | Havendo webhook configurado, a Spedy notifica o seu sistema com o resultado. |\n\n> **Emissão por venda (`/orders`):** na integração por venda, o enfileiramento da Etapa 1 depende do atributo `autoIssueMode`. A nota só é enfileirada quando o modo permite a emissão: `immediately` (ao criar a venda), `afterPayment` (quando a venda muda para `approved`) ou `afterWarrency` (no dia seguinte ao fim da garantia). Com `disabled`, a venda é registrada mas nenhuma nota é emitida automaticamente.\n\nA autorização depende da disponibilidade e do tempo de processamento da Prefeitura/SEFAZ, que varia conforme a autoridade — mas, em geral, uma nota é autorizada em **menos de 10 segundos** após o envio.\n\n**Acompanhando o resultado:** recomendamos fortemente o uso de **Webhooks** para receber as atualizações de status automaticamente. Se não utilizar webhooks, faça *polling* consultando a nota pelo endpoint de leitura (`GET /v1/{modelo}-invoices/{id}`), que retorna o `status` atual sem acionar a autoridade fiscal.\n\n## Preenchimento de Cidades\n\nTodos os campos de cidade na API (`city` em endereços de receiver, company etc.) aceitam duas formas de preenchimento:\n\n**Por código IBGE (recomendado quando disponível):**\n\n```json\n{ \"city\": { \"code\": \"3550308\" } }\n```\n\nMais assertivo: não depende de matching no nome. Use quando o código IBGE estiver disponível no sistema de origem.\n\n**Por nome e estado:**\n\n```json\n{ \"city\": { \"name\": \"São Paulo\", \"state\": \"SP\" } }\n```\n\nAlternativa quando o código IBGE não está disponível. A Spedy resolve automaticamente o município pelo nome e estado.\n\nNão é necessário enviar os três campos juntos — basta código IBGE **ou** nome + estado.\n\n## Status e Detalhes do Processamento\n\nToda nota fiscal retornada pela API possui dois campos importantes para acompanhar o resultado das operações:\n\n**`status`** — representa o estado atual da nota fiscal. É controlado exclusivamente pela Spedy e **não deve ser enviado** nas requisições de emissão. Use-o para saber se a nota foi autorizada, rejeitada, cancelada etc.\n\n**`processingDetail`** — contém o resultado do **último processamento** executado na nota (emissão, cancelamento, carta de correção etc.). É atualizado a cada operação. Seus campos são:\n\n| Campo | Descrição |\n|---|---|\n| `status` | `success`, `processing` ou `failed` |\n| `message` | Mensagem descritiva do resultado |\n| `code` | Código retornado pela autoridade fiscal |\n\nQuando uma nota é rejeitada (`status: \"rejected\"`), os detalhes da rejeição ficam em `processingDetail.message` e `processingDetail.code`. Rejeições podem vir diretamente da SEFAZ/Prefeitura ou da validação prévia da Spedy — que utiliza o schema fornecido pela autoridade fiscal para validar os dados antes do envio. Quando a rejeição é da Spedy, o código em `processingDetail.code` inicia com o prefixo `SPD`. Em ambos os casos, o formato é idêntico.\n\n> **Nota sobre `processingDetail.status`:** O valor `success` indica que o processamento assíncrono foi executado — **não** que a nota foi autorizada. Uma nota rejeitada terá `processingDetail.status: \"success\"` porque o evento na fila foi processado corretamente. O valor `failed` ocorre apenas em falhas internas de infraestrutura, independentemente do resultado fiscal.\n\n# Contingência\n\nA **contingência** é o mecanismo que mantém a emissão funcionando quando a **SEFAZ está temporariamente indisponível** (instabilidade, sobrecarga em datas de pico ou manutenção programada). Em vez de a nota falhar, a Spedy a emite por um caminho alternativo previsto na legislação, preservando a continuidade da sua operação.\n\n**Você não aciona a contingência.** A Spedy monitora continuamente a disponibilidade da SEFAZ e decide, de forma automática, quando entrar e sair de contingência — não há como forçá-la por requisição, e o gatilho é o mesmo para todas as empresas de uma mesma UF. Sua integração de emissão não muda: você emite normalmente e a Spedy escolhe o caminho correto.\n\n> A contingência se aplica a **NF-e** e **NFC-e** (SEFAZ). Não se aplica a **NFS-e**, cujo processamento é feito pelas prefeituras.\n\n## Ativação automática\n\nA entrada e a saída de contingência são decididas exclusivamente pela Spedy, com base no estado real da SEFAZ. Implicações para a integração:\n\n- **A Spedy decide _quando_ entrar.** O gatilho é sempre automático — não é possível forçar a contingência em uma requisição de emissão nem escolher, por nota, o modo de emissão.\n- **A requisição de emissão não muda.** Você continua emitindo pelos mesmos endpoints (`/orders`, `/product-invoices`, `/consumer-invoices`), com o mesmo payload.\n- **A NFC-e offline exige habilitação prévia** por empresa (`allowOfflineContingency` — ver a seção abaixo). Isso **habilita a capacidade**; _quando_ usá-la continua sendo decidido automaticamente pela Spedy.\n- **O tratamento difere por modelo** — NF-e e NFC-e seguem caminhos distintos, descritos a seguir.\n\n## NF-e em contingência (SVC)\n\nPara a **NF-e**, quando a SEFAZ autorizadora da UF está indisponível, a autorização passa a ser feita por um **ambiente de contingência da própria SEFAZ (SVC — Sistema Virtual de Contingência)**.\n\nNa prática é **transparente para a integração**: a nota continua sendo autorizada de forma síncrona, com validade plena, apenas por um servidor alternativo. O `status` segue normalmente para `authorized` e a DANFE é gerada identificada como emitida em contingência.\n\n## NFC-e em contingência (offline)\n\nPara a **NFC-e**, o caminho de contingência é a **emissão offline**: a nota é **válida no momento da emissão**, sem depender de autorização síncrona da SEFAZ.\n\n> **Pré-requisito:** a emissão offline só é aplicada se a empresa tiver a contingência offline habilitada em suas configurações de NFC-e. O campo **`allowOfflineContingency`** faz parte do bloco `consumerInvoice` do endpoint **[Alterar configurações](#tag/Empresas/paths/~1v1~1companies~1{id}~1settings/put)** (`PUT /v1/companies/{id}/settings`) e exige `tokenId`/`csc` válidos. Sem essa habilitação, a NFC-e segue o fluxo normal de retentativa quando a SEFAZ está indisponível. A habilitação apenas autoriza o uso da contingência offline — _quando_ entrar em contingência continua sendo decidido automaticamente pela Spedy.\n\n| Momento | O que acontece |\n|---|---|\n| **Emissão** | A nota é emitida em contingência e assume o `status` `inContingent`. A **DANFCE e o XML já ficam disponíveis** — a venda se completa imediatamente. |\n| **Regularização** | Quando a SEFAZ volta a operar, a Spedy **transmite a nota automaticamente** para autorização definitiva. Nenhuma ação sua é necessária. |\n| **Conclusão** | Autorizada, a nota passa a `authorized` (dispara `invoice.authorized`). Em rejeição definitiva, passa a `rejected` (dispara `invoice.rejected`). |\n\n> Uma nota em `inContingent` é **juridicamente válida** desde a emissão — a regularização apenas registra a autorização na SEFAZ. Enquanto estiver `inContingent`, o **cancelamento fica indisponível** até a autorização definitiva.\n\n## Status e acompanhamento\n\nDurante a contingência, acompanhe a nota pelos mesmos campos de sempre (`status` e `processingDetail`, descritos em **Fluxo de emissão**):\n\n| `status` | Significado |\n|---|---|\n| `inContingent` | NFC-e emitida offline: válida e pendente de autorização definitiva na SEFAZ. |\n| `authorized` | Autorização concluída (inclui a regularização de uma nota que estava `inContingent`). |\n| `rejected` | Rejeição definitiva na autorização. |\n\nRecomendamos acompanhar a transição por **webhook**. Além dos eventos de autorização e rejeição, a entrada em contingência dispara o evento `invoice.contingency` (ver **Webhooks**).\n\n# Webhooks\n\nA Spedy envia um HTTP POST para a URL configurada sempre que um evento ocorrer nas notas fiscais da sua conta. **O webhook é configurado por conta, não por empresa** — uma única configuração recebe eventos de todas as empresas da conta. Para identificar qual empresa gerou o evento, utilize o objeto `company` presente no payload.\n\n## Eventos disponíveis\n\n| Evento | Descrição |\n| --- | --- |\n| `invoice.status_changed` | Qualquer alteração de status da nota (criação, autorização, rejeição, cancelamento etc.) |\n| `invoice.authorized` | Nota fiscal autorizada |\n| `invoice.rejected` | Nota fiscal rejeitada |\n| `invoice.canceled` | Nota fiscal cancelada |\n| `invoice.contingency` | Nota fiscal emitida em contingência, aguardando autorização definitiva |\n\n> **Dica:** O evento `invoice.status_changed` cobre todo o ciclo de vida da nota. Na maioria dos casos, assinar apenas este evento é suficiente.\n\n## Política de Retry\n\nQuando a entrega de um webhook falha (endpoint indisponível, timeout, HTTP 5xx), o sistema executa até **5 retentativas** com intervalos crescentes:\n\n| Tentativa | Intervalo |\n| --- | --- |\n| 1ª | 5 minutos |\n| 2ª | 30 minutos |\n| 3ª | 1 hora |\n| 4ª | 4 horas |\n| 5ª | 16 horas |\n\nApós 5 falhas consecutivas, o webhook é **desabilitado automaticamente**. Para reativá-lo, utilize o endpoint `PUT /v1/webhooks/{id}/enable`. Eventos perdidos durante o período desabilitado não são reenviados — utilize os endpoints de consulta (`GET /v1/service-invoices`, `GET /v1/product-invoices`) para reconciliar.\n\n## Schema do payload\n\nTodos os eventos seguem a mesma estrutura:\n\n```json\n{\n \"id\": \"uuid-do-evento\",\n \"event\": \"invoice.status_changed\",\n \"data\": { ... }\n}\n```\n\n| Campo | Descrição |\n| --- | --- |\n| `id` | Identificador único do evento |\n| `event` | Tipo do evento |\n| `data` | Dados completos do objeto que gerou o evento |\n\n## Exemplo de payload\n\nO exemplo abaixo é de uma autorização de NFS-e. O campo `data` contém os mesmos dados retornados pelo `GET /v1/service-invoices/{id}` — a estrutura é idêntica para NF-e, usando os campos do `GET /v1/product-invoices/{id}`.\n\n```\n{\n \"id\": \"caaf34ab-6c65-4ca6-b6bf-b2d8f497c721\",\n \"event\": \"invoice.status_changed\",\n \"data\": {\n \"id\": \"833e8e0e-3bda-4394-ab70-5edf4ee70988\",\n \"status\": \"authorized\",\n\t \"rps\": {\n \"number\": 1,\n \"series\": \"1\"\n },\n \"batchNumber\": 1, \n \"model\": \"serviceInvoice\",\n \"environmentType\": \"production\",\n \"issuedOn\": \"2021-11-08T18:35:37.823708\",\n \"receiver\": {\n \"name\": \"EMPRESA LTDA\",\n \"federalTaxNumber\": \"00000571000189\",\n \"municipalTaxNumber\": null,\n \"email\": null,\n \"phoneNumber\": null,\n \"address\": {\n \"street\": \"Estrada da Água Branca\",\n \"district\": \"Padre Miguel\",\n \"postalCode\": \"21720162\",\n \"number\": \"3795\",\n \"additionalInformation\": null,\n \"city\": {\n\t\t\t\"name\": \"Rio de Janeiro\",\n\t\t\t\"state\": \"RJ\"\n\t\t }\n }\n },\n \"company\": {\n \"name\": \"EMPRESA LTDA\",\n \"legalName\": \"EMPRESA LTDA\",\n \"federalTaxNumber\": \"00000571000189\",\n \"stateTaxNumber\": \"634992136797\",\n \"cityTaxNumber\": \"123456\"\n },\n \"order\": {\n \"id\": \"fa15d7af-991d-467d-961a-f564b76d771c\",\n \"date\": \"2021-10-14T09:00:00\",\n \"transactionId\": \"AACcacAD1DB\"\n },\n \"authorization\": {\n\t\t\"date\": \"2021-11-08T18:35:38.443559\",\n\t\t\"protocol\": \"AAAB1245\",\n\t\t\"digestValue\": null\n\t },\n \"amount\": 100,\n \"number\": 0,\n \"processingDetail\": {\n \"status\": \"success\",\n \"message\": \"NFS-e autorizada pelo município.\",\n \"code\": null,\n \"on\": \"2021-11-08T18:35:38.443559\"\n },\n \"totals\": {\n \"invoiceAmount\": 100,\n \"netAmount\": 100,\n \"issBaseTax\": 0,\n \"irRate\": 0,\n \"csllRate\": 0,\n \"pisRate\": 0,\n \"cofinsRate\": 0,\n \"inssRate\": 0,\n \"issRate\": 0,\n \"issAmount\": 0,\n \"discountUnconditionedAmount\": null,\n \"discountConditionedAmount\": null,\n \"irAmount\": 0,\n \"pisAmount\": 0,\n \"cofinsAmount\": 0,\n \"inssAmount\": 0,\n \"csllAmount\": 0,\n \"othersAmount\": null,\n \"deductionsAmount\": null,\n \"irWithheld\": false,\n \"issWithheld\": false,\n \"cofinsWithheld\": false,\n \"inssWithheld\": false,\n \"csllWithheld\": false,\n \"pisWithheld\": false\n } \n }\n }\n\n```\n\nOs demais eventos de nota fiscal possuem exatamente a mesma estrutura.\n\n# Reforma Tributária \n\nA partir de **1º de janeiro de 2026**, entra em vigor uma nova etapa da **Reforma Tributária**, marcada pela ampliação do uso da **NFS-e Nacional** — o modelo unificado do Governo Federal para emissão de Notas Fiscais de Serviço — e pela introdução dos novos tributos **IBS** e **CBS**, aplicáveis tanto às **notas de serviço (NFS-e)** quanto às **notas de produto (NF-e)**.\n\nNa **Spedy**, acompanhamos essa evolução desde as primeiras definições oficiais. Nossa plataforma está sendo continuamente preparada para suportar todas as adequações exigidas pela Reforma, garantindo que nossos clientes estejam em conformidade com as novas regras **desde o primeiro dia de vigência**.\n\n\n## Nota Fiscal de Serviço (NFS-e)\n\nPor se tratar de uma mudança **estrutural em nível nacional**, é importante considerar alguns cenários que podem ocorrer, especialmente neste **período inicial de 2026**, de transição entre modelos municipais e o ambiente nacional.\n\n### Municípios que já aderiram ao Emissor Nacional\n\nPara municípios que **já aderiram ao Emissor Nacional da NFS-e**, o processo de adequação é simples.\n\nBasta **atualizar o método de emissão** no sistema da Spedy para utilizar o **Ambiente Nacional**.\n\n- A lista completa e atualizada dos municípios aderentes pode ser consultada [aqui](https://app.powerbi.com/view?r=eyJrIjoiNGQ4YTcxNmMtMzdhNC00Mzc5LTllM2EtMjY1MTM3NWQyZDgyIiwidCI6IjZmNDlhYTQzLTgyMmEtNGMyMC05NjcwLWRiNzcwMGJmMWViMCJ9&pageName=608609c2e0a53d7a3c6e).\n- Esse ajuste pode ser realizado diretamente pelo **Backoffice**, conforme detalhado [neste artigo](https://ajuda.spedy.com.br/pt-br/article/entenda-como-atualizar-as-configuracoes-de-emissao-de-nfs-e-para-a-reforma-tributaria-2026-1rh3lbp/) da nossa Central de Ajuda: \n \n\nCaso você utilize a API de configurações, utilize o endpoint **[Alterar configurações](#tag/Empresas/paths/~1v1~1companies/post)** da empresa e altere o campo **IssueType** para o valor `annfs` (Ambiente Nacional).\n\n#### Alterações no RPS (DPS)\n\nAo emitir NFS-e no **Ambiente Nacional**, o **RPS passa a ser tratado como DPS (Declaração de Prestação de Serviços)**.\n\nIsso significa que:\n- A numeração e série configuradas deixam de representar o próximo RPS;\n- Passam a representar o **próximo número e série do DPS**.\n\nEssa alteração é fundamental para evitar rejeições no momento da emissão. \n\n\n### Novos campos do Layout Nacional\n\nO layout nacional da NFS-e introduz **novos campos obrigatórios**, que devem ser informados na emissão:\n\n#### Campos gerais\n\n- **Código NBS (`nbsCode`)** \n- **CST PIS/COFINS (`cstPisCofins`)**\n\n#### Campos de Comércio Exterior (`foreignTrade`)\n- **Modo de prestação** *\n- **Vínculo entre as partes** (Padrão: *Sem vínculo com o tomador*)\n- **Fomento utilizado pelo prestador do serviço** (Padrão: *Nenhum*)\n- **Fomento utilizado pelo tomador do serviço** (Padrão: *Nenhum*)\n- **Vínculo da operação à movimentação temporária de bens** (Padrão: *Nenhum*)\n- **Enviar NFS-e ao MDIC** (Padrão: *Não*)\n- **Valor do serviço em moeda estrangeira** *\n- **Código da moeda estrangeira** * (Padrão ISO, ex: `USD`, `BRL`)\n\n\\* Campos obrigatórios quando aplicáveis.\n\n\n\n### Municípios que ainda não aderiram ao Emissor Nacional\n\nPara municípios que ainda utilizam **sistemas próprios**, existem dois cenários possíveis:\n\n#### 1) Prefeituras que já se adaptaram ao novo modelo\n\nAlgumas prefeituras já disponibilizaram **ambientes de teste compatíveis com o novo modelo**, incluindo IBS e CBS.\n\nNesses casos, a Spedy está ajustando as integrações conforme os municípios disponibilizam os novos ambientes.\n\n#### 2) Prefeituras sem informações técnicas ou ambiente de homologação\n\nPara municípios que ainda não divulgaram informações técnicas ou ambientes de homologação, a Spedy segue monitorando os comunicados oficiais.\n\nAssim que os dados forem disponibilizados, a integração será iniciada imediatamente.\n\n\n### Novos impostos: IBS e CBS\n\nAlém das mudanças no layout da NFS-e, a Reforma Tributária altera de forma significativa a **estrutura de tributação sobre o consumo**, introduzindo o conceito de **IVA Dual**, composto pelos tributos **IBS** e **CBS**.\n\nDiferente do modelo anterior — no qual era necessário configurar as alíquotas de diversos impostos, neste novo cenário a **Spedy realiza automaticamente o cálculo dos tributos** com base nas **alíquotas padrão definidas para o período de transição da Reforma Tributária**.\n\nDurante essa fase, são aplicadas as seguintes alíquotas:\n- **IBS:** 0,1%\n- **CBS:** 0,9%\n\n### Campos necessários para o cálculo de IBS e CBS\n\nDurante a fase de transição da Reforma Tributária, a Spedy disponibiliza a **estrutura mínima necessária** para o cálculo e envio dos campos de IBS e CBS nas notas fiscais de serviço.\n\n⚠️ **Importante:** \nNesse período, **os tributos atualmente vigentes (como ISS, PIS e COFINS) continuam obrigatórios** e **devem ser informados normalmente na nota fiscal**, conforme as regras atuais de cada município.\n\nOs valores de **IBS e CBS terão finalidade exclusivamente de teste operacional e adaptação dos sistemas**, permitindo que empresas, prefeituras e plataformas se preparem para o novo modelo tributário. **Não haverá arrecadação efetiva desses tributos durante a fase de transição.**\n\nPara habilitar o envio desses campos na nota fiscal, acesse: \n**Configurações > Geral > Habilitar campos da Reforma Tributária**\n\nPara cada nota, será necessário informar os seguintes campos do grupo IBS/CBS (`ibsCbs`):\n\n- **CST (`cst`)** – Código da Situação Tributária\n- **Código de Classificação Tributária (`classification`)** – Código único que identifica o enquadramento tributário do serviço\n- **Código de Indicador de Operação (`operationIndicatorCode`)** – Código associado à natureza da operação tributária\n- **Uso ou consumo pessoal (`isPersonalUse`)** – Indica se a operação é destinada a uso ou consumo pessoal\n\n> Para consultar a **tabela de correlação entre Item da Lista de Serviço, NBS, Código de Classificação Tributária e Código de Indicador de Operação**, consulte o [material de referência](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/anexovii-indop_ibscbs_v1-00-00.xlsx/view). \n> Esses campos podem ser configurados na Regra de Tributação, caso não sejam informados via API, conforme [artigo](https://ajuda.spedy.com.br/pt-br/article/entenda-como-atualizar-as-configuracoes-de-emissao-de-nfs-e-para-a-reforma-tributaria-2026-1rh3lbp/).\n---\n\n\n[Clique aqui](https://storage.crisp.chat/users/upload/session/-/1/8/1/f/181f0e08f152f400/requestnfseibscbs_1ckgrd7.json) para baixar um modelo de request da NFS-e, destacando os campos de IBS/CBS.\n\n## Nota Fiscal de Produto (NF-e)\n\nA adaptação da **NF-e** ao novo modelo tributário, incluindo IBS e CBS, já está disponível. Consulte a [Documentação de Referência](#tag/NF-e/paths/~1v1~1product-invoices/post).\n\nMais detalhes serão adicionados a esta documentação em breve.\n"
version: v1
x-logo:
url: https://docs.spedy.com.br/logo.svg
altText: Spedy
servers:
- url: https://api.spedy.com.br
description: Produção
- url: https://sandbox-api.spedy.com.br
description: Sandbox
security:
- ApiKey: []
paths:
/v1/service-invoices:
post:
tags:
- NFS-e
summary: Criar NFS-e
description: "Cria uma **NFS-e** (nota de serviço) e a enfileira para emissão junto à prefeitura/provedor\r\nmunicipal. A emissão é **assíncrona**: a resposta `2xx` confirma que a solicitação foi aceita, não\r\nque a nota foi autorizada — acompanhe o resultado por webhook ou consulta.\r\n \r\n**integrationId** — Identificador da nota no seu sistema (máx. 36 caracteres). Recomendado em todas as integrações:\r\n \r\n- **Associação:** vincula a NFS-e gerada pela Spedy a um ID do seu sistema (ex: ID do pedido)\r\n- **Idempotência:** um segundo POST com o mesmo `integrationId` atualiza a nota existente em vez de criar uma nova — protege contra duplicidade em retries e timeouts\r\n- **Correção de rejeitada:** para corrigir uma NFS-e rejeitada, reenvie o POST com os dados corrigidos e o mesmo `integrationId` — sem necessidade de deletar a nota anterior"
requestBody:
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/CreateServiceInvoiceDto'
application/json:
schema:
$ref: '#/components/schemas/CreateServiceInvoiceDto'
text/json:
schema:
$ref: '#/components/schemas/CreateServiceInvoiceDto'
application/*+json:
schema:
$ref: '#/components/schemas/CreateServiceInvoiceDto'
responses:
'200':
description: OK
content:
text/plain:
schema:
$ref: '#/components/schemas/ServiceInvoiceDto'
application/json:
schema:
$ref: '#/components/schemas/ServiceInvoiceDto'
text/json:
schema:
$ref: '#/components/schemas/ServiceInvoiceDto'
'400':
description: Bad Request — Erro de validação ou regra de negócio
'403':
description: Forbidden — Chave de API inválida
'429':
description: Too Many Requests — Limite de requisições atingido
components:
schemas:
CreateServiceInvoiceDto:
required:
- description
- total
type: object
properties:
integrationId:
maxLength: 36
minLength: 0
type: string
description: >-
Identificador único da nota fiscal no sistema do cliente (máx. 36
caracteres).
nullable: true
issuedOn:
type: string
description: Data de emissão [dhEmi]
format: date-time
nullable: true
effectiveDate:
type: string
description: Data de competência [dCompet]
format: date-time
receiver:
$ref: '#/components/schemas/InvoiceReceiverDto'
number:
type: integer
description: Número da NF [nNF]
format: int64
nullable: true
status:
$ref: '#/components/schemas/InvoiceStatus'
additionalInformation:
type: string
description: Informações adicionais [infCpl]
nullable: true
sendEmailToCustomer:
type: boolean
description: Enviar e-mail para o cliente / tomador
description:
minLength: 1
type: string
description: Discriminação dos serviços
batchNumber:
type: integer
description: Número do Lote
format: int32
nullable: true
rpsNumber:
type: integer
description: Número do RPS
format: int64
nullable: true
rpsSeries:
type: string
description: Série do RPS
nullable: true
cnaeCode:
type: string
description: Código CNAE
nullable: true
nbsCode:
type: string
description: Código NBS
nullable: true
federalServiceCode:
type: string
description: Código do Item da Lista de Serviço (LC 116/03)
nullable: true
nationalTaxationCode:
type: string
description: Código de Tributação Nacional
nullable: true
cityServiceCode:
type: string
description: Código do serviço no munícipio
nullable: true
taxationType:
$ref: '#/components/schemas/ServiceInvoiceTaxationType'
intermediary:
$ref: '#/components/schemas/InvoiceIntermediaryDto'
cstPisCofins:
type: string
description: Cod. Situação Tributária de PIS/COFINS (Apenas p/ Ambiente Nacional)
nullable: true
simplesNacionalAnnex:
type: string
description: "Anexo do Simples Nacional.\r\nObrigatório somente para os provedores Conan e Webfisco.\r\nValores aceitos: I, II, III, IV, V."
nullable: true
total:
$ref: '#/components/schemas/ServiceInvoiceTotalDto'
location:
$ref: '#/components/schemas/CitySimpleDto'
taxLocation:
$ref: '#/components/schemas/ServiceInvoiceLocation'
ibsCbs:
$ref: '#/components/schemas/ServiceInvoiceIbsCbsDto'
national:
$ref: '#/components/schemas/ServiceInvoiceNationalDto'
approximateTaxes:
$ref: '#/components/schemas/ServiceInvoiceApproximateTaxRatesDto'
additionalProperties: false
ServiceInvoiceDto:
type: object
properties:
id:
type: string
description: ID da NF
format: uuid
integrationId:
type: string
description: ID de integração
nullable: true
status:
$ref: '#/components/schemas/InvoiceStatus'
model:
$ref: '#/components/schemas/InvoiceModel'
environmentType:
$ref: '#/components/schemas/EnvironmentType'
issuedOn:
type: string
description: Data de emissão
format: date-time
nullable: true
effectiveDate:
type: string
description: Data de competência
format: date-time
nullable: true
receiver:
$ref: '#/components/schemas/InvoiceReceiverDto'
company:
$ref: '#/components/schemas/InvoiceCompanyDto'
order:
$ref: '#/components/schemas/InvoiceOrderDto'
authorization:
$ref: '#/components/schemas/InvoiceAuthorizationDto'
amount:
type: number
description: Valor total da NF
format: double
number:
type: integer
description: Número
format: int64
nullable: true
processingDetail:
$ref: '#/components/schemas/InvoiceProcessingDetailDto'
description:
type: string
nullable: true
totals:
$ref: '#/components/schemas/ServiceInvoiceTotalDto'
rps:
$ref: '#/components/schemas/ServiceInvoiceRpsDto'
location:
$ref: '#/components/schemas/CitySimpleDto'
ibsCbs:
$ref: '#/components/schemas/ServiceInvoiceIbsCbsDto'
nbsCode:
type: string
nullable: true
nationalTaxationCode:
type: string
nullable: true
batchNumber:
type: integer
format: int32
nullable: true
approximateTaxes:
$ref: '#/components/schemas/ServiceInvoiceApproximateTaxesDto'
additionalProperties: false
InvoiceReceiverDto:
type: object
properties:
name:
type: string
description: Nome [xName]
nullable: true
federalTaxNumber:
type: string
description: CPF / CNPJ / Doc Estrangeiro ( [CPF] / [CNPJ] )
nullable: true
stateTaxNumber:
type: string
description: Inscrição estadual [IE]
nullable: true
suframaTaxNumber:
type: string
description: >-
Inscrição na SUFRAMA do destinatário [ISUF] — obrigatória em vendas
com isenção para ZFM/Áreas de Livre Comércio
nullable: true
cityTaxNumber:
type: string
description: Inscrição municipal
nullable: true
email:
type: string
description: E-mail [email]
nullable: true
phoneNumber:
type: string
description: Telefone
nullable: true
address:
$ref: '#/components/schemas/AddressCreateDto'
additionalProperties: false
InvoiceStatus:
enum:
- created
- enqueued
- received
- authorized
- inContingent
- rejected
- canceled
- denied
- removed
- disabled
type: string
description: >
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis:
Valores possíveis: