Integração para plataformas e checkouts

Este guia é para plataformas de pagamento, checkouts, plataformas de infoprodutos, marketplaces e afins que querem oferecer a Spedy como o sistema de emissão de notas fiscais dos seus clientes. Esse tipo de integração é diferente de um ERP ou SaaS que emite as próprias notas pela API. Aqui, a plataforma não monta a nota fiscal: ela envia a venda para a Spedy e mantém o status dela atualizado a cada mudança. A Spedy decide quando emitir, monta a nota com a configuração fiscal do cliente e cancela a nota quando a venda é reembolsada.

	ERP / SaaS emissor	Plataforma ou checkout
Quem integra	O sistema que emite as próprias notas (ou as dos seus clientes)	A plataforma, em nome de cada vendedor que habilita a integração
O que envia	A nota fiscal completa, ou a venda	Sempre a venda (`/v1/orders`)
Tributação	Enviada pela API ou configurada na Spedy	Configurada pelo vendedor no painel da Spedy
Depois do envio	Acompanha a nota	Atualiza o status da venda a cada evento de pagamento

Como funciona

O vendedor habilita a integração na sua plataforma

Na tela de integrações da plataforma, o vendedor informa a chave de API da Spedy da empresa dele. A chave fica no painel da Spedy, em menu do perfil do usuário → Minha empresa → Credenciais de API.

A plataforma envia cada venda

A cada pedido, a plataforma cria a venda com POST /v1/orders, usando a chave do vendedor no header X-Api-Key.

A plataforma atualiza o status da venda

A cada evento de pagamento (aprovação, recusa, reembolso, chargeback), a plataforma atualiza a venda com PUT /v1/orders/{id}/status.

A Spedy emite e cancela as notas

Conforme o autoIssueMode e o status da venda, a Spedy emite a nota no momento certo — e cancela as notas autorizadas quando a venda é reembolsada, sofre chargeback ou é cancelada.

Sandbox e produção

A Spedy tem dois ambientes, com contas e chaves separadas:

Ambiente	Base URL	Quem usa nesta integração
Sandbox	`https://sandbox-api.spedy.com.br/v1`	Só a sua plataforma, durante o desenvolvimento, com uma conta de testes própria.
Produção	`https://api.spedy.com.br/v1`	Os seus clientes. A chave que o vendedor informa na sua plataforma é sempre de produção.

Desenvolva e homologue no sandbox. Crie uma conta no ambiente de testes e use a chave dela para percorrer todo o fluxo deste guia.
Em produção, use https://api.spedy.com.br/v1. Deixe a base URL em configuração, nunca fixa no código: uma chave de produção enviada ao sandbox (ou o contrário) recebe 401.
Não ofereça o sandbox aos seus clientes. A integração que o vendedor habilita deve apontar sempre para produção.

O sandbox pode emitir notas com validade fiscal: isso acontece quando o ambiente de emissão de um modelo de nota está configurado como Produção na conta de testes. Mantenha a conta de sandbox em Simulação (NFS-e) ou Homologação (NF-e e NFC-e). Veja Ambiente de testes.

Os exemplos deste guia usam o sandbox. Ao levar a integração para produção, troque https://sandbox-api.spedy.com.br por https://api.spedy.com.br.

Habilitando a integração

A chave de API identifica uma empresa (CNPJ) e só opera em nome dela. Na sua tela de integração, guarde a chave por conta (ou loja) do vendedor. Se o vendedor vende por mais de um CNPJ, ele precisa informar a chave de cada empresa. Algumas recomendações para a tela de integração:

Valide a chave ao salvar. Uma chamada simples, como GET /v1/orders?transactionId=teste, devolve 401 quando a chave é inválida.
Guarde a chave como segredo. Ela permite emitir e cancelar notas em nome do vendedor — trate-a como uma senha.
Valide contra produção. A chave do vendedor é de produção: valide-a em https://api.spedy.com.br. Veja Sandbox e produção.

A tributação da nota (códigos de serviço, NCM, CFOP, alíquotas e retenções) não é enviada pela plataforma. O vendedor configura isso no painel da Spedy, por produto e por empresa. Veja Configuração inicial.

Criando a venda

Crie a venda com POST /v1/orders. O exemplo abaixo é um pedido de um curso pago por Pix, ainda aguardando o pagamento:

cURL (sandbox)

curl -X POST https://sandbox-api.spedy.com.br/v1/orders \
  -H "X-Api-Key: sua-chave-de-sandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "PED-2026-000123",
    "date": "2026-11-05T14:30:00-03:00",
    "status": "awaitingPayment",
    "autoIssueMode": "afterPayment",
    "paymentMethod": "pix",
    "amount": 297.00,
    "sendEmailToCustomer": true,
    "customer": {
      "name": "Maria Souza",
      "federalTaxNumber": "12345678909",
      "email": "maria@exemplo.com.br",
      "address": {
        "street": "Rua das Flores",
        "number": "100",
        "district": "Centro",
        "postalCode": "01310100",
        "city": { "name": "São Paulo", "state": "SP" }
      }
    },
    "items": [
      {
        "quantity": 1,
        "price": 297.00,
        "amount": 297.00,
        "product": {
          "code": "CURSO-FOTOGRAFIA",
          "name": "Curso de Fotografia",
          "price": 297.00
        }
      }
    ]
  }'

A resposta traz o id da venda na Spedy. Guarde esse id junto do pedido na sua plataforma: ele é usado em todas as atualizações seguintes. Os campos que mais importam para uma plataforma:

Campo	Descrição
`transactionId`	Código do pedido na sua plataforma. Único por empresa: uma segunda venda com o mesmo `transactionId` é recusada com o erro `Já existe venda com o código de transação informado.` — o que protege contra vendas duplicadas em retentativas.
`date`	Data da venda.
`status`	Status da venda no momento do envio (padrão: `created`). Veja os status.
`autoIssueMode`	Quando a nota deve ser emitida. Veja Quando a nota é emitida.
`warrantyDate`	Último dia da garantia (prazo de reembolso). Usado com `autoIssueMode: "afterWarrency"`.
`paymentMethod`	Forma de pagamento: `creditCard`, `debitCard`, `pix`, `billetBank`, `bankTransfer`, `paypal`, `balanceWallets`, `cash` ou `other`.
`amount`	Valor total da venda.
`sendEmailToCustomer`	Envia a nota por e-mail ao comprador quando autorizada (padrão: `false`).
`customer`	Comprador (tomador ou destinatário da nota). Envie CPF/CNPJ, e-mail e endereço sempre que tiver.
`items[].product.code`	Código do produto na sua plataforma. A Spedy cadastra o produto na primeira venda e o reconhece pelo código nas seguintes — é nesse cadastro que o vendedor configura a tributação.
`items[].product.invoiceModel`	Modelo da nota do produto: `serviceInvoice` (NFS-e, padrão), `productInvoice` (NF-e) ou `consumerInvoice` (NFC-e).

A referência completa dos campos está em Criar Venda.

Envie a venda assim que o pedido existir

Recomendamos criar a venda assim que o pedido é gerado — inclusive Pix e boleto ainda não pagos, com status: "awaitingPayment" — e depois só atualizar o status. Assim a venda na Spedy acompanha a vida do pedido, e o vendedor vê no painel também as vendas recusadas e expiradas. Se a sua plataforma preferir enviar apenas pedidos pagos, crie a venda já com status: "approved". Nesse caso, o restante do fluxo (reembolso, chargeback, cancelamento) continua igual.

Mapeando os eventos da plataforma

Cada mudança no pedido vira uma atualização de status da venda:

cURL (sandbox)

curl -X PUT https://sandbox-api.spedy.com.br/v1/orders/{id}/status \
  -H "X-Api-Key: sua-chave-de-sandbox" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }'

Evento na plataforma	Chamada na Spedy	Efeito na nota
Pedido criado, Pix ou boleto gerado	`POST /v1/orders` com `status: "awaitingPayment"`	Nenhum, com `afterPayment` ou `afterWarrency`.
Pagamento aprovado	`status: "approved"`	Dispara a emissão com `afterPayment`; inicia a espera da garantia com `afterWarrency`.
Pagamento recusado	`status: "refused"`	Nenhuma nota é emitida, com `afterPayment` ou `afterWarrency`.
Pix ou boleto expirado	`status: "expired"`	Nenhuma nota é emitida, com `afterPayment` ou `afterWarrency`.
Reembolso solicitado	`status: "refundRequested"`	Suspende a emissão por garantia enquanto o pedido estiver nesse status.
Reembolso negado	`status: "approved"` se a venda ainda não tem nota; `status: "completed"` se a nota já foi autorizada	Retoma o fluxo normal.
Reembolso efetuado	`status: "refunded"`	A Spedy cancela as notas autorizadas da venda.
Chargeback	`status: "chargeback"`	A Spedy cancela as notas autorizadas da venda.
Pedido cancelado	`status: "canceled"`	A Spedy cancela as notas autorizadas da venda.

O cancelamento de uma nota autorizada segue as regras e prazos fiscais de cada modelo e município. Fora do prazo, a nota não pode mais ser cancelada pelo fisco, e o vendedor precisa tratar a devolução pelo caminho fiscal adequado. Veja Cancelamento, correção e inutilização.

Os status refused e expired não cancelam notas. Com autoIssueMode: "immediately", a nota é emitida na criação da venda e continua válida mesmo que o pagamento seja recusado ou expire.

A Spedy conclui a venda

Quando a nota é autorizada, a Spedy muda a venda para completed automaticamente. A sua plataforma não precisa enviar completed. Depois disso, a venda só aceita os status de reembolso, chargeback e cancelamento.

Regras da mudança de status

A Spedy recusa algumas mudanças de status. Trate essas respostas de erro sem retentar:

Mesmo status: enviar o status que a venda já tem retorna A venda já está com status desejado. Pode ser tratado como sucesso (por exemplo, quando a sua plataforma reenvia um evento).
completed sem nota autorizada: não é permitido. Para “pagamento aprovado”, use sempre approved.
Voltar para awaitingPayment ou approved depois da nota autorizada: não é permitido. Um approved que chegue atrasado, depois que a Spedy já concluiu a venda, é recusado — trate como sucesso.

Já o erro A nota fiscal dessa venda está em processamento. é temporário: a nota está sendo transmitida ao fisco. Aguarde alguns segundos e reenvie a mesma atualização.

Corrigindo dados da venda

Para corrigir dados da venda antes da emissão (por exemplo, o endereço do comprador), use PUT /v1/orders/{id}. Notas já autorizadas não são alteradas por essa chamada.

O PUT /v1/orders/{id} substitui a venda inteira: envie o payload completo, com todos os campos e itens, e não só o que quer alterar. Um campo que fica de fora pode ser gravado vazio ou com o valor padrão, inclusive o autoIssueMode e o warrantyDate. Monte o corpo a partir da venda que você enviou na criação e altere apenas os campos necessários.

Para mudar só o status, use sempre PUT /v1/orders/{id}/status.

Quando a nota é emitida

O campo autoIssueMode, enviado na criação da venda, define em que momento a Spedy emite a nota:

`autoIssueMode`	Quando a nota é emitida	Indicado para
`afterPayment`	Quando a venda chega a `approved` (ou já é criada aprovada).	A maioria das plataformas e checkouts.
`afterWarrency`	No dia seguinte ao fim da garantia (`warrantyDate`), se a venda continuar aprovada.	Produtos com prazo de reembolso, como infoprodutos.
`immediately` (padrão)	Assim que a venda é criada, qualquer que seja o status.	Plataformas que só enviam vendas já pagas.
`disabled`	Nunca automaticamente. A emissão é feita pelo vendedor no painel ou por `POST /v1/orders/{id}/invoices/issue`.	Vendedores que preferem revisar cada venda antes de emitir.

Sempre envie o autoIssueMode. Se ele for omitido, a venda usa immediately e a nota é emitida na criação — mesmo que o pedido ainda esteja aguardando pagamento. Em plataformas que enviam o pedido antes do pagamento, use afterPayment ou afterWarrency.

O ideal é deixar o vendedor escolher o modo de emissão na tela de integração da sua plataforma (por exemplo: “Emitir após o pagamento” ou “Emitir após a garantia”) e enviar a escolha em cada venda.

Emissão após a garantia

Com autoIssueMode: "afterWarrency", a nota só é emitida depois que o prazo de reembolso termina. Isso evita emitir e depois ter de cancelar a nota de uma venda que foi reembolsada durante a garantia. Informe em warrantyDate o último dia da garantia. Por exemplo, para uma garantia de 7 dias de uma venda aprovada em 05/11:

{
  "transactionId": "PED-2026-000124",
  "date": "2026-11-05T14:30:00-03:00",
  "status": "approved",
  "autoIssueMode": "afterWarrency",
  "warrantyDate": "2026-11-12",
  "...": "demais campos da venda"
}

Nesse caso:

A venda fica aprovada, sem nota, até o fim da garantia (12/11).
No dia seguinte (13/11), a Spedy emite a nota, com data de competência 13/11.
Se, até lá, a venda mudar para refundRequested, refunded, chargeback ou for cancelada, a nota não é emitida. Se o reembolso for negado e a venda voltar para approved, a emissão segue para o dia seguinte ao fim da garantia.

A emissão após a garantia depende do warrantyDate. Sem ele, a nota da venda aprovada é emitida imediatamente, como no afterPayment.

A emissão automática após a garantia vale para garantias de até 90 dias, contados da aprovação da venda. Para prazos maiores, a nota é emitida pelo painel ou por POST /v1/orders/{id}/invoices/issue.

Emissão manual e vendas de meses anteriores

A emissão automática acontece dentro do mês de competência da nota. Se a venda chegar à Spedy depois da virada do mês (por exemplo, um pedido aprovado em 31/10 enviado em 02/11), a nota não é emitida automaticamente — o vendedor emite pelo painel, ou a plataforma dispara a emissão informando a data de competência:

cURL (sandbox)

curl -X POST https://sandbox-api.spedy.com.br/v1/orders/{id}/invoices/issue \
  -H "X-Api-Key: sua-chave-de-sandbox" \
  -H "Content-Type: application/json" \
  -d '{ "effectiveDate": "2026-11-02" }'

Sem effectiveDate, a nota usa a data original da venda. A mesma chamada serve para vendas com autoIssueMode: "disabled".

Acompanhando a nota

A plataforma não precisa acompanhar a nota para a integração funcionar. Se quiser exibir a nota dentro da plataforma (por exemplo, o link do PDF na página do pedido), há dois caminhos:

Consulta: GET /v1/orders/{id} traz as notas da venda no campo invoices.
Webhook: o evento invoice.status_changed envia a nota em data. Veja Webhooks: visão geral.

Ligando a nota ao pedido

Toda nota gerada a partir de uma venda traz o objeto order, com os dados da venda de origem. Ele vem em data.order no payload do webhook e em order no GET da nota:

{
  "id": "caaf34ab-6c65-4ca6-b6bf-b2d8f497c721",
  "event": "invoice.status_changed",
  "data": {
    "id": "833e8e0e-3bda-4394-ab70-5edf4ee70988",
    "status": "authorized",
    "order": {
      "id": "fa15d7af-991d-467d-961a-f564b76d771c",
      "date": "2026-11-05T14:30:00",
      "transactionId": "PED-2026-000123"
    },
    "...": "demais campos da nota"
  }
}

Campo	Descrição
`data.order.id`	`id` da venda na Spedy — o mesmo devolvido pelo `POST /v1/orders`.
`data.order.transactionId`	O `transactionId` que a sua plataforma enviou ao criar a venda — o código do pedido.
`data.order.date`	Data da venda.

Use data.order.id (ou data.order.transactionId) para localizar o pedido na sua plataforma. O transactionId é único por empresa: se o vendedor tiver mais de um CNPJ na mesma conta, combine-o com data.company para identificar a empresa.

Webhooks são configurados por conta: um webhook criado com a chave do vendedor recebe as notas de toda a conta dele, inclusive as emitidas manualmente no painel ou vindas de outras integrações. Descarte os eventos cujo data.order não corresponda a uma venda enviada pela sua plataforma, e também os eventos sem order.

Boas práticas

Um pedido, uma venda. Use sempre o mesmo transactionId para o mesmo pedido.
Respeite a ordem dos eventos. Atualize o status na ordem em que os eventos acontecem na sua plataforma, e só depois que a venda tiver sido criada.
Trate erros de validação como definitivos. Respostas 4xx com mensagem de validação não mudam com retentativa — registre e, se for o caso, mostre ao vendedor. Retente apenas falhas de rede, 429 e 5xx. Veja Erros e respostas e Rate limit.
Envie os dados do comprador. CPF/CNPJ, e-mail e endereço completos evitam rejeições, principalmente em NF-e e em municípios que exigem endereço do tomador.
Teste em sandbox. Crie uma conta no ambiente de testes e percorra todos os eventos da tabela acima antes de liberar a integração aos seus clientes.

Sua plataforma dentro da Spedy

Quando a sua integração tiver 3 clientes ativos emitindo pela Spedy, você pode solicitar a inclusão do App da sua plataforma na Spedy. Com o App, os vendedores encontram a sua plataforma na lista de integrações da Spedy e a ativam a partir de lá. Para solicitar, escreva para suporte@spedy.com.br com o nome da plataforma e os clientes que já usam a integração. A equipe da Spedy avalia a solicitação e informa os próximos passos.

Fundamentos

Plataformas e checkouts

Emissão

Operações fiscais

NF-e recebidas

NFS-e tomadas

Integração para plataformas e checkouts

Como funciona

Sandbox e produção

Habilitando a integração

Criando a venda

Envie a venda assim que o pedido existir

Mapeando os eventos da plataforma

A Spedy conclui a venda

Regras da mudança de status

Corrigindo dados da venda

Quando a nota é emitida

Emissão após a garantia

Emissão manual e vendas de meses anteriores

Acompanhando a nota

Ligando a nota ao pedido

Boas práticas

Sua plataforma dentro da Spedy

Relacionado

​Como funciona

​Sandbox e produção

​Habilitando a integração

​Criando a venda

​Envie a venda assim que o pedido existir

​Mapeando os eventos da plataforma

​A Spedy conclui a venda

​Regras da mudança de status

​Corrigindo dados da venda

​Quando a nota é emitida

​Emissão após a garantia

​Emissão manual e vendas de meses anteriores

​Acompanhando a nota

​Ligando a nota ao pedido

​Boas práticas

​Sua plataforma dentro da Spedy

​Relacionado

Como funciona

Sandbox e produção

Habilitando a integração

Criando a venda

Envie a venda assim que o pedido existir

Mapeando os eventos da plataforma

A Spedy conclui a venda

Regras da mudança de status

Corrigindo dados da venda

Quando a nota é emitida

Emissão após a garantia

Emissão manual e vendas de meses anteriores

Acompanhando a nota

Ligando a nota ao pedido

Boas práticas

Sua plataforma dentro da Spedy

Relacionado