> ## Documentation Index > Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Primeiros passos > Do zero até a primeira nota fiscal emitida em sandbox. Este guia leva você da criação da conta até a emissão da sua primeira nota fiscal em ambiente de testes. Todos os exemplos usam o [ambiente sandbox](/start/ambiente-de-testes), que não tem validade fiscal. O sandbox é uma **conta separada** da de produção. Para testar, faça um **novo cadastro** no [ambiente de sandbox](/start/ambiente-de-testes) e escolha o **Plano Desenvolvedor** — as chaves e empresas de produção **não** funcionam no sandbox. Mesmo que você já assine a Spedy em produção, precisa de uma conta de sandbox à parte para testar. Faça um **novo cadastro no [ambiente de sandbox](/start/ambiente-de-testes)** e escolha o **Plano Desenvolvedor** — é uma conta à parte da de produção. A conta já é criada com uma **empresa titular**, e é a `X-Api-Key` dela que autentica suas requisições de teste (header `X-Api-Key`). Você já pode emitir com essa empresa, sem criar nenhuma outra. **Onde encontrar a chave:** no [dashboard do sandbox](https://sandbox-app.spedy.com.br/), vá em **menu do perfil do usuário → Minha empresa → Credenciais de API**. A chave de **produção não funciona no sandbox**. Mais detalhes em [Autenticação](/start/autenticacao). Se você emite em nome de outras empresas além da titular (por exemplo, um SaaS que emite pelos seus clientes). A chamada de criação da empresa usa a chave da **empresa titular** e retorna o `id` e a `X-Api-Key` da nova empresa. ```bash cURL theme={null} curl -X POST https://sandbox-api.spedy.com.br/v1/companies \ -H "X-Api-Key: chave-da-empresa-titular" \ -H "Content-Type: application/json" \ -d '{ "name": "Loja Exemplo", "legalName": "Loja Exemplo LTDA", "federalTaxNumber": "00000000000000", "stateTaxNumber": "123456789", "cityTaxNumber": "123456", "taxRegime": "simplesNacional", "address": { "street": "Rua Exemplo", "number": "123", "district": "Centro", "postalCode": "00000000" } }' ``` **Inscrições e regime tributário — quando cada um importa:** | Campo | Quando é necessário | | -------------------------------------------------- | ------------------------------------------------------------------------------------ | | `stateTaxNumber` (inscrição estadual) | Para emitir **NF-e/NFC-e**. Empresas isentas usam `ISENTO`. | | `cityTaxNumber` (inscrição municipal) | Para emitir **NFS-e** (exigência da prefeitura). | | `taxRegime` (regime tributário) | Afeta a tributação em **todos os modelos** (ex.: `simplesNacional`, `regimeNormal`). | | `specialTaxRegime` (regime especial de tributação) | **Específico de NFS-e** — informe conforme o enquadramento na prefeitura. | Os valores possíveis de cada regime e como eles afetam a emissão estão em [Regimes e códigos fiscais](/guides/regimes-e-codigos-fiscais). Apenas a chave da **empresa titular** pode gerenciar empresas. A resposta traz a `X-Api-Key` da nova empresa (exibida uma única vez) — use-a para operar e emitir por ela. Para emitir NF-e e NFC-e, a empresa precisa de um certificado digital A1 (`.pfx`) válido. Envie o arquivo e a senha por `multipart/form-data`. Use o `{id}` e a `X-Api-Key` da empresa que vai emitir — a titular (dados no backoffice) ou uma criada no passo anterior. ```bash cURL theme={null} curl -X POST https://sandbox-api.spedy.com.br/v1/companies/{id}/certificates \ -H "X-Api-Key: sua-chave-de-api" \ -F "certificateFile=@/caminho/para/certificado.pfx" \ -F "password=senha-do-certificado" ``` Para NFS-e, a exigência de certificado depende do município — consulte [Emissão de NFS-e](/guides/emissao-nfse). Para emitir, a empresa precisa do **ambiente** e da **numeração** definidos: * **Ambiente** (`environmentType`): configurado por modelo de nota nas [configurações da empresa](/guides/configuracao-inicial) (`PUT /v1/companies/{id}/settings`). No sandbox, o padrão é Simulação (NFS-e) e Homologação (NF-e/NFC-e) — veja [Ambiente de testes](/start/ambiente-de-testes). * **Série e numeração**: decida quem controla a sequência. * **Deixe a Spedy controlar** (recomendado): configure a série e a próxima numeração por modelo nas configurações da empresa. A cada emissão, a Spedy incrementa o número automaticamente. * **Controle você mesmo**: envie a série e o número diretamente no payload da nota, nos campos `series` e `number`. Isso vale para o número da NF-e e da NFC-e e também para o número do DPS/RPS e a série da NFS-e. ```bash cURL theme={null} curl -X PUT https://sandbox-api.spedy.com.br/v1/companies/{id}/settings \ -H "X-Api-Key: sua-chave-de-api" \ -H "Content-Type: application/json" \ -d '{ "productInvoice": { "environmentType": "development", "series": "1", "nextNumber": 1 }, "consumerInvoice": { "environmentType": "development", "series": "1", "nextNumber": 1 }, "serviceInvoice": { "environmentType": "simulation", "issueType": "normal", "nextNumber": 1 } }' ``` **Valores dos principais campos:** | Campo | Valores | Observação | | ------------------- | ---------------------------------------------------------- | --------------------------------- | | `environmentType` | `production`, `development` (Homologação), `simulation` | `simulation` existe só para NFS-e | | `issueType` (NFS-e) | `normal` (provedor municipal), `annfs` (Ambiente Nacional) | define a rota de emissão da NFS-e | O `PUT` **substitui os campos do bloco que você enviar** — um campo de valor omitido volta ao default (e `environmentType`/`issueType` voltam a um valor **inválido**). Para atualizar com segurança: **`GET` das configurações → altere só o que precisa → `PUT` do bloco completo**. Omitir um bloco **inteiro** o mantém inalterado, então envie só os modelos que for usar. Detalhe de cada bloco em [Configuração inicial](/guides/configuracao-inicial) e da emissão de serviço em [Emissão de NFS-e](/guides/emissao-nfse). A maneira mais simples de emitir é criando uma **venda** (order) com os itens e o cliente. **O modelo da nota é definido pelo `invoiceModel` de cada produto** do item — por padrão `serviceInvoice` (**NFS-e**). Para emitir outro modelo pela venda, defina no produto `invoiceModel` como `productInvoice` (**NF-e**) ou `consumerInvoice` (**NFC-e**). Neste exemplo, a emissão dispara automaticamente ao criar a venda (`autoIssueMode: "immediately"`): ```bash cURL theme={null} curl -X POST https://sandbox-api.spedy.com.br/v1/orders \ -H "X-Api-Key: sua-chave-de-api" \ -H "Content-Type: application/json" \ -d '{ "transactionId": "PEDIDO-12345", "date": "2026-07-31T10:00:00Z", "amount": 100.00, "customer": { "name": "Cliente Exemplo", "federalTaxNumber": "00000000000", "email": "cliente@exemplo.com.br", "address": { "street": "Rua Exemplo", "number": "100", "district": "Centro", "postalCode": "01310100", "city": { "name": "São Paulo", "state": "SP" } } }, "items": [ { "quantity": 1, "price": 100.00, "amount": 100.00, "product": { "code": "SKU-001", "name": "Produto de teste", "invoiceModel": "serviceInvoice", "price": 100.00 } } ] }' ``` A venda monta a nota a partir de dados básicos e das configurações da empresa — é o caminho mais rápido para começar. **Precisa de controle total da tributação?** Quando você precisa definir os dados fiscais de forma personalizada (CFOP, CST/CSOSN, alíquotas, etc.), emita direto pelos **endpoints específicos de cada modelo**, seguindo o guia correspondente: [Emissão de NF-e](/guides/emissao-nfe) (`POST /v1/product-invoices`), [Emissão de NFC-e](/guides/emissao-nfce) (`POST /v1/consumer-invoices`) e [Emissão de NFS-e](/guides/emissao-nfse) (`POST /v1/service-invoices`). Veja o passo a passo dos estados da nota em [Fluxo de emissão](/guides/fluxo-de-emissao). A emissão é **assíncrona**: a resposta `2xx` confirma que a solicitação foi aceita, não que a nota foi autorizada. Acompanhe por webhook ( recomendado) ou consultando o status da nota. A resposta da criação da venda traz um array **`invoices`** — uma entrada por nota gerada, cada uma com `id`, `model` e `status`. **Se você não usa webhooks, é daí que sai o `id` para o polling:** pegue o `id` da nota (diferente do `id` da venda/`order`, que é outro identificador) e consulte o endpoint do **modelo correspondente** — abaixo, `service-invoices` (NFS-e); para NF-e/NFC-e, use `product-invoices`/`consumer-invoices`. ```bash cURL theme={null} curl https://sandbox-api.spedy.com.br/v1/service-invoices/{id} \ -H "X-Api-Key: sua-chave-de-api" ``` O campo de status evolui até `authorized` (autorizada) ou `rejected` (rejeitada). Para configurar notificações automáticas, veja [Webhooks: visão geral](/webhooks/visao-geral). Os exemplos acima usam **Simulação** (padrão do sandbox para NFS-e): a Spedy exercita o **fluxo** de emissão, mas **não valida a tributação** contra as regras do município. Antes do go-live, faça uma **emissão de validação em produção** — veja o [checklist de produção](/start/go-live). ## Próximos passos Entenda todos os estados possíveis de uma nota fiscal. O que revisar antes de trocar para o ambiente de produção.