> ## 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](/pages/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](/pages/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](/pages/start/ambiente-de-testes)** e escolha o **Plano Desenvolvedor** — é uma conta à parte da de produção. Ao criar a conta, a **empresa titular** já vem junto, e a `X-Api-Key` dela fica disponível no **backoffice do sandbox**. É essa chave (de sandbox) que autentica suas requisições de teste (header `X-Api-Key`), e você já pode emitir com essa empresa, sem criar nenhuma outra — a chave de produção **não** funciona aqui. Detalhes em [Autenticação](/pages/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", "address": { "street": "Rua Exemplo", "number": "123", "district": "Centro", "postalCode": "00000000" } }' ``` 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](/pages/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](/pages/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](/pages/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": { "series": "1", "nextNumber": 1 }, "consumerInvoice": { "series": "1", "nextNumber": 1 }, "serviceInvoice": { "nextNumber": 1 } }' ``` Configure apenas os modelos que você vai emitir. Veja o detalhe de cada bloco em [Configuração inicial](/pages/guides/configuracao-inicial). A maneira mais simples de emitir uma nota fiscal é criando uma venda (order) com os itens e o cliente. Por padrão, a venda emite uma **nota fiscal de serviço (NFS-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", "price": 100.00 } } ] }' ``` Veja o fluxo completo em [Fluxo de emissão](/pages/guides/fluxo-de-emissao) e as particularidades de cada tipo de nota em [Emissão de NF-e](/pages/guides/emissao-nfe), [Emissão de NFC-e](/pages/guides/emissao-nfce) e [Emissão de NFS-e](/pages/guides/emissao-nfse). 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. O `{id}` usado aqui é o **da nota fiscal** (obtido no bloco `invoices` da resposta da venda criada no passo anterior), não o `id` da venda (`order`) — são identificadores diferentes. ```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](/pages/webhooks/visao-geral). ## 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.