Notas Fiscais

Emitir Nota Fiscal

Emite uma nota fiscal de serviço avulsa, sem vínculo com cobrança ou assinatura.

A emissão é imediata: o invoiceTiming da configuração fiscal vale apenas para as notas geradas a partir de cobranças, não para a avulsa.

Informe em configId qual configuração fiscal usar — uma conta pode ter configurações de mais de uma empresa, e a nota sai no CNPJ da configuração escolhida. Liste as disponíveis em GET /v1/invoices/notas/config.

O ref que você enviar passa a ser o identificador da nota nas demais rotas: consultar, cancelar, reemitir e reenviar. Omitido, a API gera um identificador próprio e o devolve na resposta.

O campo type indica o modelo do documento fiscal. O único valor aceito hoje é NFSE (nota fiscal de serviço), que também é o assumido quando o campo é omitido — qualquer outro valor retorna 400 com o código NOTA_TYPE_NOT_SUPPORTED.

Outros tipos de nota estarão disponíveis em breve. Envie type explicitamente desde já: quando cada modelo for liberado, nenhuma alteração no payload será necessária.

O tomador não precisa estar cadastrado. Se o endereço não trouxer cityCode, o código IBGE do município é resolvido a partir do CEP — assim como logradouro e bairro, quando faltarem.

A resposta volta com status PROCESSING: a prefeitura responde de forma assíncrona. Não há evento de webhook para nota fiscal — acompanhe o desfecho em GET /v1/invoices/notas/{notaId}, que passa a AUTHORIZED ou a ERROR com as mensagens da prefeitura.

Case de uso:

Como prestador, quero emitir uma nota para um serviço cobrado fora da plataforma, informando apenas o tomador, o valor e a descrição.

POST/v1/invoices/notas

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

nota.fiscal/write

Body

application/json

Content-Type:application/json

{
  "configId": "unc_1776888897617_ppwgo7oef",
  "type": "NFSE",
  "amount": 150.00,
  "descricao": "Consultoria em tecnologia da informação",
  "ref": "pedido-2026-0912",
  "customer": {
    "document": "11144477735",
    "name": "Alexandre Souza",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 5",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityCode": "3550308"
    }
  }
}

Schema

configIdstringRequired

Configuração fiscal, de GET /v1/invoices/notas/config

amountnumberRequired

Valor do serviço em reais

descricaostringRequired

Discriminação do serviço na nota

customerobjectRequired

typestringOptional

Modelo do documento fiscal; único valor aceito hoje, outros tipos em breve. Padrão: NFSE

refstringOptional

Vira o identificador da nota nas demais rotas; se omitida, a API gera uma

← Anterior

Consultar Nota Fiscal

Emitir Nota de uma Cobrança

const url = 'https://sandbox.validapay.com.br/v1/invoices/notas';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "configId": "unc_1776888897617_ppwgo7oef",
  "type": "NFSE",
  "amount": 150.00,
  "descricao": "Consultoria em tecnologia da informação",
  "ref": "pedido-2026-0912",
  "customer": {
    "document": "11144477735",
    "name": "Alexandre Souza",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Sala 5",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityCode": "3550308"
    }
  }
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200

{
  "success": true,
  "status": "PROCESSING",
  "ref": "nf_1788101026585_uqaspo7bn",
  "id": "nf_1788101026585_uqaspo7bn",
  "nfStatus": "processando_autorizacao",
  "tipo": "nacional",
  "issuedAt": "2026-08-30T14:43:49.719Z",
  "internalStatus": "PROCESSING"
}

400400 - campos obrigatórios

{
    "error": {
        "message": "customer.document, amount, descricao e configId são obrigatórios",
        "code": "MISSING_FIELDS",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

400400 - configuração inválida

{
    "error": {
        "message": "Configuração não encontrada ou desabilitada",
        "code": "NOTA_CONFIG_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Consultar Nota Fiscal

Emitir Nota de uma Cobrança