Configurando a emissão de nota fiscal via API

Este documento irá ajudá-lo a configurar, via API, a emissão de nota fiscal eletrônica de serviço (NFS-e) de uma conta, do cadastro da integração até a emissão da nota de teste que valida tudo.

info

Todos os endpoints deste documento operam sobre a conta que está no token, sem nenhum parâmetro de conta no corpo da requisição. O fluxo é o mesmo para qualquer conta.

A única diferença no modo BaaS é como você obtém o appId: em vez de criar a API pela plataforma, você gera o appId da conta a partir da sua API mestre. Veja Controlando as contas no modo BAAS.

caution

Esta documentação espera que:

• a feature de nota fiscal esteja habilitada para a sua empresa (disponível apenas por solicitação via chat);
• a conta já esteja com o cadastro aprovado — a identidade fiscal da nota é a da própria conta;
• você tenha em mãos o certificado digital A1 (arquivo .pfx/.p12) e a senha dele.

Autenticação

Todas as requisições usam o padrão da API REST da Woovi: o appId vai no header Authorization.

Authorization: <appId>
Content-Type: application/json

O escopo é definido pelo próprio token: a integração criada, o certificado enviado e a nota de teste emitida pertencem à conta do appId utilizado.

Fluxo da configuração

A integração só fica pronta para emitir notas reais quando o provedor de nota fiscal confirma a nota de teste por webhook. É por isso que a emissão de teste é o último passo: ela é o que fecha a configuração.

1. Criando a integração

O primeiro passo cria a integração de nota fiscal da conta e grava as informações fiscais dela. Essas informações garantem a conformidade tributária e podem ser obtidas com o auxílio do contador do titular da conta.

POST /api/v1/invoice/integration

Todos os campos do corpo são opcionais — envie os que se aplicam ao município e ao regime tributário da conta:

Campo	Tipo	Descrição
cityServiceCode	string	Código de serviço municipal, conforme a lista de serviços da prefeitura
municipalSubscription	string	Inscrição/assinatura municipal do prestador de serviço
rpsNumber	string	Número do RPS (Recibo Provisório de Serviços)
specialTax	string	Regime de imposto especial
taxRegime	string	Regime tributário da empresa
federalTaxDetermination	string	Determinação de tributos federais
municipalTaxDetermination	string	Determinação de tributos municipais
isPortalNacional	boolean	Indica se o município emite pelo Portal Nacional da NFS-e
isActive	boolean	Ativa a integração (só é permitido depois de configurada)

Valores aceitos

Os campos fiscais são enviados ao provedor de nota fiscal exatamente como chegam. Use só os valores abaixo, com a mesma grafia (maiúsculas e minúsculas, sem espaços nem acentos). A API só valida federalTaxDetermination e municipalTaxDetermination; nos demais, um valor fora da lista é gravado, mas faz o envio do certificado falhar no passo 2.

Campo	Valores aceitos
taxRegime	SimplesNacional, SimplesNacionalExcessoSublimite, LucroPresumido, LucroReal, Isento, MicroempreendedorIndividual
specialTax	Nenhum, Automatico, MicroempresaMunicipal, Estimativa, SociedadeDeProfissionais, Cooperativa, MicroempreendedorIndividual, MicroempresarioEmpresaPequenoPorte
federalTaxDetermination e municipalTaxDetermination	SimplesNacional, Default, NotInformed
cityServiceCode	Um único código de serviço; não envie uma lista. No Portal Nacional, é o código de 6 dígitos da lista nacional de serviços (ex.: 040101), com o complemento municipal quando o município exige (ex.: 170202.004)
municipalSubscription e rpsNumber	Só números

caution

Textos livres como simples nacional, Lucro presumido, não possui ou None não são aceitos. Qual valor se aplica à conta (regime, regime especial e código de serviço) é uma definição fiscal: confirme com o contador do titular da conta.

curl 'https://api.woovi.com/api/v1/invoice/integration' -X POST \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "cityServiceCode": "2690",
    "municipalSubscription": "123456",
    "rpsNumber": "1",
    "taxRegime": "SimplesNacional",
    "specialTax": "Nenhum",
    "isPortalNacional": false
  }'

Resposta 201:

{
  "integration": {
    "id": "67001bbf0b0621890af7dc28",
    "type": "NFEIO",
    "status": "CONFIGURING",
    "isActive": false,
    "companyBankAccount": "66f8c1a20b0621890af7aa11",
    "metadata": {
      "nfeio": {
        "cityServiceCode": "2690",
        "municipalSubscription": "123456",
        "rpsNumber": "1",
        "taxRegime": "SimplesNacional",
        "specialTax": "Nenhum",
        "isPortalNacional": false
      }
    }
  }
}

info

O campo companyBankAccount na resposta confirma a qual conta a integração ficou vinculada. O status CONFIGURING indica que a integração existe, mas ainda não está apta a emitir notas.

Corrigindo as informações fiscais

Para alterar as informações fiscais de uma integração que já existe, use o PUT com os mesmos campos (todos opcionais; só os enviados são alterados). Ele também aceita legalNature, a natureza jurídica da empresa (ex.: SociedadeEmpresariaLimitada, Empresario, EireliNaturezaEmpresaria).

PUT /api/v1/invoice/integration

curl 'https://api.woovi.com/api/v1/invoice/integration' -X PUT \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "taxRegime": "SimplesNacional",
    "specialTax": "Nenhum",
    "cityServiceCode": "040101"
  }'

A resposta 200 devolve a integração atualizada, no mesmo formato da criação. Se o envio do certificado falhou por causa das informações fiscais, corrija aqui e envie o certificado de novo.

2. Enviando o certificado digital A1

Com a integração criada, envie o certificado A1 da conta. O arquivo .pfx/.p12 deve ser convertido para base64 e enviado no corpo em JSON.

POST /api/v1/invoice/integration/certificate

Campo	Tipo	Obrigatório	Descrição
pcks12	string	Sim	Certificado A1 (pkcs12) codificado em base64
passphrase	string	Sim	Senha do certificado
test	boolean	Não	Quando true, o certificado não é enviado ao provedor (validação é ignorada)

Para gerar o base64 do certificado:

base64 -w 0 certificado.pfx > certificado.base64

curl 'https://api.woovi.com/api/v1/invoice/integration/certificate' -X POST \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json' \
  --data-raw "{
    \"pcks12\": \"$(cat certificado.base64)\",
    \"passphrase\": \"senha-do-certificado\"
  }"

Resposta 200:

{
  "integration": {
    "status": "CONFIGURING"
  }
}

info

A resposta devolve apenas o status resultante da integração. O certificado, a senha e as credenciais nunca são retornados pela API.

Antes de enviar o certificado, a Woovi cadastra a empresa no provedor de nota fiscal usando as informações fiscais do passo 1. Por isso, um erro neste passo nem sempre é do certificado.

Erros possíveis:

• 400 Error creating company on provider — o provedor recusou o cadastro da empresa. Quase sempre é um campo fiscal fora dos valores aceitos. Corrija com o PUT e envie o certificado de novo.
• 400 Error uploading certificate, check if the password or the certificate is correct — o arquivo não é um A1 válido ou a senha está errada.
• 404 You need to configure the invoice integration — a conta do token ainda não tem integração criada (passo 1).

3. Emitindo a nota fiscal de teste

Este é o passo que fecha a configuração. A emissão de teste leva a integração para VALIDATING e, quando o provedor confirma a nota por webhook, a integração passa para CONFIGURED e isActive: true — é isso que libera a emissão de notas reais.

POST /api/v1/invoice/integration/test

Não há corpo a ser enviado: a conta e a integração são resolvidas pelo token.

curl 'https://api.woovi.com/api/v1/invoice/integration/test' -X POST \
  -H 'Authorization: <appId>' \
  -H 'Content-Type: application/json'

Resposta 200:

{
  "invoice": {
    "id": "67001c5b0b0621890af7dc44"
  },
  "integration": {
    "id": "67001bbf0b0621890af7dc28"
  }
}

Guarde o invoice.id: é o identificador da nota de teste gerada, que você pode consultar depois pelos endpoints de nota fiscal.

4. Confirmando que a integração está configurada

A confirmação da nota de teste chega por webhook do provedor, então o status muda de forma assíncrona. Consulte a integração da conta para acompanhar:

GET /api/v1/invoice/integration

curl 'https://api.woovi.com/api/v1/invoice/integration' -X GET \
  -H 'Authorization: <appId>'

Resposta 200 com a configuração concluída:

{
  "integration": {
    "id": "67001bbf0b0621890af7dc28",
    "type": "NFEIO",
    "status": "CONFIGURED",
    "isActive": true,
    "companyBankAccount": "66f8c1a20b0621890af7aa11",
    "metadata": {
      "nfeio": {
        "nfeioCompanyId": "9f1c4b2e5a7d",
        "cityServiceCode": "2690",
        "municipalSubscription": "123456",
        "rpsNumber": "1",
        "taxRegime": "SimplesNacional",
        "specialTax": "Nenhum",
        "isPortalNacional": false
      }
    }
  }
}

info

Com status: "CONFIGURED" e isActive: true, a conta está pronta para emitir notas fiscais. Vale validar o documento da nota de teste com o contador do titular da conta antes de começar a emitir notas reais.

Próximos passos

Agora que a integração da conta está configurada, o próximo passo é emitir notas fiscais de verdade pela API:

• Criar Nota Fiscal de serviço via API
• Baixar PDF e XML da nota via API
• Cancelar uma nota emitida via API