Skip to main content

Criar Nota Fiscal de serviço via API

caution

A emissão exige que a integração de nota fiscal da conta já esteja configurada e ativa. Veja Configurando a emissão de nota fiscal via API ou Como ativar a emissão pela plataforma.

Endpoint​

POST /api/v1/invoice

Autentique com o header Authorization: SEU_APPID_AQUI. Você encontra a documentação detalhada desse endpoint nas documentações de api.

A API aceita dois formatos de payload, sempre exigindo dados de cobrança ou valor, e um cliente (via customerId ou objeto customer).

Formato 1 – com valor​

{
  "correlationID": "nfse-assinatura-pro-2025-08",
  "description": "Assinatura Pro - Agosto/2025",
  "billingDate": "2025-08-31T23:59:59.000Z",
  "value": 12990,
  "customerId": "cus_123"
}

Formato 2 – com cobrança​

{
  "correlationID": "nfse-mensalidade-premium-2025-08",
  "description": "Mensalidade Premium",
  "billingDate": "2025-08-31T23:59:59.000Z",
  "charge": "ch_abc",
  "customer": {
    "taxID": "12345678909",
    "name": "Maria Souza",
    "email": "[email protected]",
    "phone": "+55 48 99999-0000",
    "address": {
      "country": "BR",
      "zipcode": "88000-000",
      "street": "Rua das Flores",
      "number": "100",
      "state": "SC"
    }
  }
}

Campos do corpo da requisição​

CampoTipoObrigatórioDescrição
correlationIDstringSimSeu identificador único da nota fiscal. Não pode repetir dentro da mesma conta.
billingDatestringSimData de competência/vencimento da nota, no formato YYYY-MM-DD ou ISO 8601.
chargestringSim, se value não for enviadocorrelationID de uma cobrança existente. O valor e o cliente da nota são obtidos da cobrança.
valuenumberSim, se charge não for enviadoValor da nota em centavos (ex.: 12990 equivale a R$ 129,90).
customerobjectSim, quando emitir por value sem customerIdDados do tomador do serviço, detalhados nas linhas seguintes.
customerIdstringNãocorrelationID de um cliente já cadastrado, como alternativa a enviar o objeto customer.
descriptionstringNãoDescrição do serviço que aparece na NFS-e.
customer.taxIDstringSim (dentro de customer)CPF ou CNPJ do tomador, somente números.
customer.namestringSim (dentro de customer)Nome ou razão social do tomador.
customer.emailstringSim (dentro de customer)E-mail válido do tomador.
customer.phonestringSim (dentro de customer)Telefone do tomador.
customer.addressobjectSim (dentro de customer)Endereço do tomador.
customer.address.countrystringSim (dentro de address)País do endereço.
customer.address.zipcodestringSim (dentro de address)CEP do endereço.
customer.address.streetstringSim (dentro de address)Logradouro.
customer.address.numberstringSim (dentro de address)Número do endereço.
customer.address.statestringSim (dentro de address)Sigla do estado brasileiro (ex.: SP).
info

O correlationID é único por conta: cada conta tem o seu próprio espaço de identificadores, então o mesmo correlationID pode existir em contas diferentes.

Resposta​

Sucesso (201)​

{
  "invoice": {
    "id": "6a5f62d35ab4cd72544b1a48",
    "correlationID": "nfse-mensalidade-premium-2025-08",
    "value": 12990,
    "description": "Mensalidade Premium",
    "date": "2025-08-31T23:59:59.000Z",
    "billingDate": "2025-08-31T23:59:59.000Z",
    "status": "PENDING",
    "statusRaw": null,
    "customer": {
      "correlationID": "cus_123",
      "name": "Maria Souza"
    },
    "charge": {
      "correlationID": "ch_abc",
      "value": 12990,
      "status": "ACTIVE",
      "paidAt": null,
      "date": "2025-08-01T12:00:00.000Z"
    }
  }
}

A emissão é assíncrona. A resposta confirma que a nota foi registrada, não que ela já foi autorizada pela prefeitura — por isso o status volta como PENDING.

Fluxo de status​

PENDING  →  PROCESSING  →  CONFIRMED

O PDF e o XML só ficam disponíveis depois que a nota atinge CONFIRMED.

Erros (400)​

  • You need to configure the invoice integration
  • Customer not found
  • Customer is required
  • Charge not found
  • Customer address is invalid

Exemplos em código​

curl --request POST \
  --url https://api.openpix.com.br/api/v1/invoice \
  --header 'Authorization: {AUTHORIZATION TOKEN}' \
  --header 'content-type: application/json' \
  -d '{
    "correlationID": "nfse-mensalidade-premium-2025-08",
    "description": "Mensalidade Premium",
    "billingDate": "2025-08-31T23:59:59.000Z",
    "charge": "ch_abc",
    "customerId": "cus_123"
  }'

Consultando as notas emitidas​

Use o endpoint de listagem para acompanhar o status da emissão:

GET /api/v1/invoice

Parâmetros de query aceitos: start e end (filtro por data da nota), skip e limit (paginação).

curl --request GET \
  --url 'https://api.openpix.com.br/api/v1/invoice?start=2025-08-01&end=2025-08-31&skip=0&limit=100' \
  --header 'Authorization: {AUTHORIZATION TOKEN}'

Cada item da lista tem o mesmo formato do objeto invoice devolvido na criação.

Próximos passos​