Configuração inicial

Quando você assina a Spedy, a empresa titular da conta já é criada — então você pode configurar e emitir com ela sem precisar criar nenhuma empresa. Para emitir, uma empresa precisa de duas coisas: um certificado digital A1 e as configurações de emissão. Se você emite em nome de outras empresas (por exemplo, um SaaS que emite pelos seus clientes), pode criar empresas adicionais — mas isso é opcional.

A empresa titular é a que foi criada no ato da assinatura. A chave de API dela fica no backoffice e é a única autorizada a gerenciar empresas (/v1/companies). Cada empresa — a titular ou uma criada — opera e emite com a sua própria chave. Veja Autenticação.

Este guia cobre os três passos abaixo (o primeiro é opcional). Para o caminho mais curto até a primeira nota, veja Primeiros passos.

(Opcional) Crie empresas adicionais

Só é necessário se você emite em nome de outras empresas além da titular. Cadastre a empresa com CNPJ (federalTaxNumber), razão social (legalName), nome fantasia (name) e endereço (address) — campos obrigatórios de CompanyEditingDto. A resposta traz o id da nova empresa e a X-Api-Key dela no campo apiCredentials.apiKey.

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

POST /v1/companies exige a X-Api-Key da empresa titular — é a única chave autorizada a gerenciar empresas. A resposta traz a X-Api-Key da nova empresa, usada para operá-la e emitir por ela; guarde-a imediatamente, pois consultas posteriores a retornam ofuscada.

Envie o certificado digital A1

Envie o arquivo .pfx e a senha por multipart/form-data. O certificado é obrigatório para NF-e e NFC-e, e para NFS-e em municípios que exigem assinatura digital.

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"

Detalhes sobre validade, expiração e renovação em Certificado digital.

Defina as configurações de emissão

As configurações (CompanySettingsDto) controlam como a empresa emite cada modelo de nota. Elas são organizadas em quatro blocos, todos definidos em uma única chamada a PUT /v1/companies/{id}/settings:

Bloco	Controla
`general`	Comportamento geral da empresa: permitir CPF/CNPJ duplicado entre clientes (`allowDuplicateFederalTaxNumbers`), permitir múltiplos modelos de nota por venda (`allowMultipleInvoiceModelsPerOrder`), casas decimais em valores monetários (`decimalPrecision`), campos da Reforma Tributária (`taxReformFieldsEnabled`) e responsável técnico (`technicalResponsible`).
`productInvoice`	Emissão de NF-e: série (`series`), ambiente (`environmentType`), próxima numeração (`nextNumber`) e layout de impressão do DANFE (`danfePrintLayout`).
`consumerInvoice`	Emissão de NFC-e: série, ambiente, próxima numeração, `tokenId` e `csc` (Código de Segurança do Contribuinte, exigido para o QR Code) e contingência offline (`allowOfflineContingency`).
`serviceInvoice`	Emissão de NFS-e: série, ambiente, tipo de emissão (`issueType`), credenciais do provedor municipal (`userName`, `password`, `authNumber`), próximo lote (`nextBatchNumber`) e próximo RPS/DPS (`nextNumber`).

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 '{
    "general": {
      "allowDuplicateFederalTaxNumbers": false,
      "allowMultipleInvoiceModelsPerOrder": false,
      "decimalPrecision": 2
    },
    "productInvoice": {
      "series": "1",
      "nextNumber": 1
    },
    "consumerInvoice": {
      "series": "1",
      "nextNumber": 1,
      "tokenId": "000001",
      "csc": "seu-csc"
    },
    "serviceInvoice": {
      "series": "1",
      "nextNumber": 1
    }
  }'

Se você emite NFC-e, tokenId e csc são obrigatórios para gerar o QR Code de consulta — sem eles a nota não pode ser autorizada. Se emite NFC-e em contingência offline, allowOfflineContingency também depende desses dois campos.

Você só precisa configurar os blocos correspondentes aos modelos de nota que sua empresa realmente emite.

Responsável técnico

Se você é um SaaS ou software que emite notas em nome de outras empresas, deve configurar o responsável técnico — os dados são enviados no grupo infRespTec da NF-e e da NFC-e.

O responsável técnico não se aplica à NFS-e.

Configure-o no bloco general.technicalResponsible das configurações (PUT /v1/companies/{id}/settings), com os campos:

Campo	Descrição
`federalTaxNumber`	CNPJ do responsável técnico, sem máscara (dígitos verificadores válidos)
`contactName`	Nome do contato
`email`	E-mail do responsável técnico
`phone`	Telefone com DDD, somente dígitos (10 ou 11)
`csrts`	Lista de CSRT por UF e ambiente (`state`, `environmentType`, `idCsrt`, `csrt`), exigida apenas onde a SEFAZ pede — hoje, o Paraná (PR). O `csrt` é somente escrita (nunca retornado).

cURL

curl -X PUT https://sandbox-api.spedy.com.br/v1/companies/{id}/settings \
  -H "X-Api-Key: chave-da-empresa-titular" \
  -H "Content-Type: application/json" \
  -d '{
    "general": {
      "technicalResponsible": {
        "federalTaxNumber": "00000000000000",
        "contactName": "Equipe Técnica",
        "email": "tech@seudominio.com.br",
        "phone": "11999998888"
      }
    }
  }'

Ao atualizar as configurações gerais, reenvie o technicalResponsible para mantê-lo — se ele for omitido ou enviado nulo, o responsável cadastrado é removido.

Herança: configure na titular, aplique em todas

Configure o responsável técnico na empresa titular e ele vale para todas as empresas da conta.
Você pode sobrescrever em uma empresa específica, definindo o technicalResponsible dela — nesse caso, o dela prevalece.
Se nenhum responsável for configurado (nem na empresa, nem na titular), a Spedy atua como responsável técnico.

Autorização de uso na SEFAZ

Algumas SEFAZ exigem que o contribuinte solicite a autorização de uso do software emissor, informando o CNPJ do fornecedor (o responsável técnico). Se a empresa titular for o responsável técnico, é ela quem deve receber e autorizar essas solicitações.

Quando a Spedy é o responsável técnico (nenhum responsável configurado), informe o CNPJ da Spedy na autorização de uso: 47332178000101 — SPEDY DESENVOLVIMENTO DE SOFTWARE LTDA.

Paraná (PR) — passo a passo

Acesse o Portal Receita/PR

Entre com o seu certificado digital (A1 ou A3).

Abra a opção UPD

No menu lateral esquerdo, clique em UPD.

Vá em Autorização de Uso

Acesse Autorização de Uso e depois Cadastro de Autorização de Uso.

Informe o CNPJ do fornecedor

Informe o CNPJ do sistema/fornecedor do software emissor e os dados da sua empresa (CAD/ICMS ou CNPJ) para concluir o pedido.

Próximos passos

Conceitos e modelo de dados

Veja como empresa, certificado, configurações, clientes, produtos e vendas se relacionam.

Fluxo de emissão

Do payload da venda até a nota autorizada.

Fundamentos

Emissão

Operações fiscais

Configuração inicial

Responsável técnico

Herança: configure na titular, aplique em todas

Autorização de uso na SEFAZ

Paraná (PR) — passo a passo

Próximos passos

Conceitos e modelo de dados

Fluxo de emissão

​Responsável técnico

​Herança: configure na titular, aplique em todas

​Autorização de uso na SEFAZ

​Paraná (PR) — passo a passo

​Próximos passos

Conceitos e modelo de dados

Fluxo de emissão

Responsável técnico

Herança: configure na titular, aplique em todas

Autorização de uso na SEFAZ

Paraná (PR) — passo a passo

Próximos passos