Exemplos de requisição

Esta página resume os padrões que se repetem em toda a API e traz exemplos prontos (happy-path) dos fluxos mais comuns. Cada exemplo aponta para o guia detalhado, que é a fonte completa de campos e regras de cada operação.

Convenções

Requisições e respostas usam JSON (Content-Type: application/json), exceto o upload de certificado digital, que usa multipart/form-data.
Todos os endpoints exigem o header X-Api-Key. Veja Autenticação.
Campos seguem camelCase (federalTaxNumber, unitAmount, autoIssueMode).
Datas e horários seguem ISO-8601 (2026-07-31T10:00:00Z).
IDs de recursos são UUIDs.
Todos os exemplos usam a base URL de sandbox (https://sandbox-api.spedy.com.br/v1).

A emissão é assíncrona: um 2xx confirma que a solicitação foi aceita, não que a nota foi autorizada. Acompanhe o resultado por webhook ou consulta de status. Veja Ciclo de vida da nota.

Fluxos principais

Os exemplos abaixo têm fins didáticos. Os valores de tributação (CFOP, CSOSN/CST, alíquotas etc.) dependem do seu regime, produto e operação — valide com o seu contador ou responsável fiscal antes de emitir em produção.

Criar uma venda

O caminho mais simples: criar uma venda emite uma nota automaticamente (por padrão, uma NFS-e). Detalhes em Primeiros passos e Fluxo de emissão.

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 }
      }
    ]
  }'

Emitir uma NF-e

Nota de produto (modelo 55). Exemplo para o Simples Nacional (tributação por item com csosn/cst). Detalhes em Emissão de NF-e.

cURL

curl -X POST https://sandbox-api.spedy.com.br/v1/product-invoices \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "pedido-12345",
    "effectiveDate": "2026-08-03T10:00:00Z",
    "operationNature": "Venda de mercadoria",
    "isFinalCustomer": true,
    "receiver": {
      "name": "Cliente Exemplo",
      "federalTaxNumber": "11144477735",
      "address": {
        "street": "Rua Exemplo", "number": "100", "district": "Centro",
        "postalCode": "01001000",
        "city": { "name": "São Paulo", "state": "SP" }
      }
    },
    "items": [
      {
        "code": "SKU-001", "description": "Produto Exemplo",
        "ncm": "61091000", "cfop": 5102, "unit": "UN",
        "quantity": 1, "unitAmount": 100.0, "totalAmount": 100.0,
        "unitTax": "UN", "quantityTax": 1, "unitTaxAmount": 100.0,
        "taxes": {
          "icms": { "origin": 0, "csosn": 102 },
          "pis": { "cst": 49 },
          "cofins": { "cst": 49 }
        }
      }
    ]
  }'

Emitir uma NFC-e

Nota ao consumidor (modelo 65), para varejo/PDV. Detalhes em Emissão de NFC-e.

cURL

curl -X POST https://sandbox-api.spedy.com.br/v1/consumer-invoices \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "venda-pdv-98765",
    "effectiveDate": "2026-08-03T10:00:00Z",
    "operationNature": "Venda de mercadoria",
    "isFinalCustomer": true,
    "receiver": { "name": "Consumidor Final", "federalTaxNumber": "11144477735" },
    "items": [
      {
        "code": "SKU-001", "description": "Produto Exemplo",
        "ncm": "61091000", "cfop": 5102, "unit": "UN",
        "quantity": 1, "unitAmount": 100.0, "totalAmount": 100.0,
        "unitTax": "UN", "quantityTax": 1, "unitTaxAmount": 100.0,
        "taxes": {
          "icms": { "origin": 0, "csosn": 102 },
          "pis": { "cst": 49 },
          "cofins": { "cst": 49 }
        }
      }
    ],
    "payments": [ { "method": "creditCard", "amount": 100.0 } ]
  }'

Emitir uma NFS-e

Nota de serviço. Antes, confirme se o município é integrado (veja Emissão de NFS-e).

cURL

curl -X POST https://sandbox-api.spedy.com.br/v1/service-invoices \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "servico-45678",
    "effectiveDate": "2026-07-31T10:00:00Z",
    "description": "Consultoria em tecnologia da informação",
    "receiver": {
      "name": "Cliente Exemplo Ltda",
      "federalTaxNumber": "00000000000191",
      "address": {
        "street": "Rua Exemplo", "number": "100", "district": "Centro",
        "postalCode": "01310100",
        "city": { "name": "São Paulo", "state": "SP" }
      }
    },
    "total": {
      "invoiceAmount": 1000.0, "netAmount": 950.0,
      "issBaseTax": 1000.0, "issRate": 5, "issAmount": 50.0
    }
  }'

Formato de resposta

Respostas de sucesso retornam o objeto criado ou consultado, com id e os campos normalizados. Para o formato de respostas de erro, veja Erros e respostas; para rejeições fiscais, Erros e rejeições SEFAZ.

Paginação e consultas

Endpoints de listagem (ex.: GET /v1/customers) aceitam page e pageSize e retornam um envelope paginado. Veja os parâmetros de filtro de cada endpoint na Referência da API.

Troque a base URL para https://api.spedy.com.br/v1 e use sua chave de produção quando for para o ar — veja o checklist de produção.

​Convenções

​Fluxos principais

​Criar uma venda

​Emitir uma NF-e

​Emitir uma NFC-e

​Emitir uma NFS-e

​Formato de resposta

​Paginação e consultas

Convenções

Fluxos principais

Criar uma venda

Emitir uma NF-e

Emitir uma NFC-e

Emitir uma NFS-e

Formato de resposta

Paginação e consultas