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 empresa titular

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

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

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": { "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 e da emissão de serviço em Emissão de NFS-e.

Emita uma nota em sandbox

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

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",
          "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 (POST /v1/product-invoices), Emissão de NFC-e (POST /v1/consumer-invoices) e Emissão de NFS-e (POST /v1/service-invoices).

Veja o passo a passo dos estados da nota em Fluxo de emissão.

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

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.

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.

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