Primeiros passos

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, 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 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.

Crie a conta de sandbox e pegue a chave da titular

Faça um novo cadastro no ambiente de sandbox 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.

(Opcional) Crie empresas adicionais

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.

cURL

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.

Envie o certificado digital A1

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.

cURL

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.

Configure a emissão

Para emitir, a empresa precisa do ambiente e da numeração definidos:

Ambiente (environmentType): configurado por modelo de nota nas configurações da empresa (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.
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.

cURL

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.

Emita uma nota em sandbox

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").

cURL

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 e as particularidades de cada tipo de nota em Emissão de NF-e, Emissão de NFC-e e Emissão de NFS-e.

Acompanhe o status da nota

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.

cURL

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.

Comece aqui

Primeiros passos

Próximos passos

Ciclo de vida da nota

Checklist de produção

​Próximos passos

Ciclo de vida da nota

Checklist de produção

Próximos passos