Create the NFSe configuration
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs \
--header 'Content-Type: application/json' \
--data '
{
"event": "INVOICE_PAID",
"issWithheldAtSource": false,
"environment": "LIVE",
"competence": "PAID_AT",
"observation": "Serviços prestados conforme contrato.",
"operationNature": "Prestação de Serviços"
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs"
payload = {
"event": "INVOICE_PAID",
"issWithheldAtSource": False,
"environment": "LIVE",
"competence": "PAID_AT",
"observation": "Serviços prestados conforme contrato.",
"operationNature": "Prestação de Serviços"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
event: 'INVOICE_PAID',
issWithheldAtSource: false,
environment: 'LIVE',
competence: 'PAID_AT',
observation: 'Serviços prestados conforme contrato.',
operationNature: 'Prestação de Serviços'
})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'event' => 'INVOICE_PAID',
'issWithheldAtSource' => false,
'environment' => 'LIVE',
'competence' => 'PAID_AT',
'observation' => 'Serviços prestados conforme contrato.',
'operationNature' => 'Prestação de Serviços'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs"
payload := strings.NewReader("{\n \"event\": \"INVOICE_PAID\",\n \"issWithheldAtSource\": false,\n \"environment\": \"LIVE\",\n \"competence\": \"PAID_AT\",\n \"observation\": \"Serviços prestados conforme contrato.\",\n \"operationNature\": \"Prestação de Serviços\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs")
.header("Content-Type", "application/json")
.body("{\n \"event\": \"INVOICE_PAID\",\n \"issWithheldAtSource\": false,\n \"environment\": \"LIVE\",\n \"competence\": \"PAID_AT\",\n \"observation\": \"Serviços prestados conforme contrato.\",\n \"operationNature\": \"Prestação de Serviços\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"event\": \"INVOICE_PAID\",\n \"issWithheldAtSource\": false,\n \"environment\": \"LIVE\",\n \"competence\": \"PAID_AT\",\n \"observation\": \"Serviços prestados conforme contrato.\",\n \"operationNature\": \"Prestação de Serviços\"\n}"
response = http.request(request)
puts response.read_body{
"event": "INVOICE_PAID",
"issWithheldAtSource": false,
"environment": "LIVE",
"createdAt": "2026-08-07T19:45:17.204Z",
"competence": "PAID_AT",
"observation": "Serviços prestados conforme contrato.",
"operationNature": "Prestação de Serviços"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "TAX_ISSUER_NOT_FOUND",
"origin": "BILLING",
"message": "Tax issuer not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "RESOURCE_CONFLICT",
"origin": "BILLING",
"message": "NFSE_CONFIG already exist"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "BILLING",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "event",
"message": "Invalid option: expected one of \"INVOICE_PAID\"|\"INVOICE_CLOSED\"|\"PAYMENT_RECEIVED\"",
"code": "EVENT_ONE_OF",
"values": [
"INVOICE_PAID",
"INVOICE_CLOSED",
"PAYMENT_RECEIVED"
]
}
]
}Create the NFSe configuration
Turns on automatic NFSe issuance for the organization: from now on, each event you choose issues a service invoice (NFSe) through your tax issuer.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
nfse-configs
Create the NFSe configuration
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs \
--header 'Content-Type: application/json' \
--data '
{
"event": "INVOICE_PAID",
"issWithheldAtSource": false,
"environment": "LIVE",
"competence": "PAID_AT",
"observation": "Serviços prestados conforme contrato.",
"operationNature": "Prestação de Serviços"
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs"
payload = {
"event": "INVOICE_PAID",
"issWithheldAtSource": False,
"environment": "LIVE",
"competence": "PAID_AT",
"observation": "Serviços prestados conforme contrato.",
"operationNature": "Prestação de Serviços"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
event: 'INVOICE_PAID',
issWithheldAtSource: false,
environment: 'LIVE',
competence: 'PAID_AT',
observation: 'Serviços prestados conforme contrato.',
operationNature: 'Prestação de Serviços'
})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'event' => 'INVOICE_PAID',
'issWithheldAtSource' => false,
'environment' => 'LIVE',
'competence' => 'PAID_AT',
'observation' => 'Serviços prestados conforme contrato.',
'operationNature' => 'Prestação de Serviços'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs"
payload := strings.NewReader("{\n \"event\": \"INVOICE_PAID\",\n \"issWithheldAtSource\": false,\n \"environment\": \"LIVE\",\n \"competence\": \"PAID_AT\",\n \"observation\": \"Serviços prestados conforme contrato.\",\n \"operationNature\": \"Prestação de Serviços\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs")
.header("Content-Type", "application/json")
.body("{\n \"event\": \"INVOICE_PAID\",\n \"issWithheldAtSource\": false,\n \"environment\": \"LIVE\",\n \"competence\": \"PAID_AT\",\n \"observation\": \"Serviços prestados conforme contrato.\",\n \"operationNature\": \"Prestação de Serviços\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/nfse-configs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"event\": \"INVOICE_PAID\",\n \"issWithheldAtSource\": false,\n \"environment\": \"LIVE\",\n \"competence\": \"PAID_AT\",\n \"observation\": \"Serviços prestados conforme contrato.\",\n \"operationNature\": \"Prestação de Serviços\"\n}"
response = http.request(request)
puts response.read_body{
"event": "INVOICE_PAID",
"issWithheldAtSource": false,
"environment": "LIVE",
"createdAt": "2026-08-07T19:45:17.204Z",
"competence": "PAID_AT",
"observation": "Serviços prestados conforme contrato.",
"operationNature": "Prestação de Serviços"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "TAX_ISSUER_NOT_FOUND",
"origin": "BILLING",
"message": "Tax issuer not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "RESOURCE_CONFLICT",
"origin": "BILLING",
"message": "NFSE_CONFIG already exist"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "BILLING",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "event",
"message": "Invalid option: expected one of \"INVOICE_PAID\"|\"INVOICE_CLOSED\"|\"PAYMENT_RECEIVED\"",
"code": "EVENT_ONE_OF",
"values": [
"INVOICE_PAID",
"INVOICE_CLOSED",
"PAYMENT_RECEIVED"
]
}
]
}Only admins of the organization or of the realm can create it. The organization needs an active tax issuer in the Accounting service first (
POST /realms/{realmId}/organizations/{organizationId}/tax-issuer, with its test and live configurations), and it has at most one NFSe configuration: to change it, delete it and create a new one. The configuration is read when each event is processed, shortly after it happens, so an event processed while the organization has no configuration issues no NFSe, and it is not issued later.
Each NFSe is issued in the background, after its event, and appears in the Accounting service’s tax document list (GET /realms/{realmId}/organizations/{organizationId}/tax-document). It is issued to the invoice’s payer: the CPF or CNPJ comes from the invoice, and the name, e-mail and address from the contract’s buyer when it has them. An invoice whose payer has no CPF or CNPJ issues none. The service data (city, ISS rate, municipal service code, LC 116 item, CNAE) comes from your tax issuer’s live configuration, also when environment is TEST, and the service description is the invoice’s description.
With PAYMENT_RECEIVED, each payment settled on an invoice issues its own NFSe, for the amount of that payment. Payments you record by hand (POST .../invoices/{invoiceId}/statements and POST .../invoices/{invoiceId}/statements/settlement) issue none.
Answers the configuration it created.Path Parameters
ID of your realm.
Format: UUID
ID of the organization that issues the NFSe. It needs an active tax issuer.
Format: UUID
Body
application/json
Which billing event issues an NFSe. INVOICE_CLOSED: one NFSe for the whole invoice, for its amount, when the invoice closes. INVOICE_PAID: one NFSe for the whole invoice, for its amount, when the invoice is paid. PAYMENT_RECEIVED: one NFSe for each payment settled on an invoice, for the amount of that payment.
Available options:
INVOICE_PAID, INVOICE_CLOSED, PAYMENT_RECEIVED Example:
"INVOICE_PAID"
Whether the customer withholds the ISS at source. Sent on every NFSe this configuration issues.
Example:
false
LIVE issues real NFSe. TEST issues homologation documents, which have no fiscal value; they carry the same service data, from your tax issuer's live configuration.
Available options:
TEST, LIVE Example:
"LIVE"
Which date becomes the competence date of each NFSe (the date the service refers to), as a UTC calendar day. EVENT_DATE: the day the event happened. CREATED_AT: the day the invoice was created, or, with PAYMENT_RECEIVED, the day the payment was recorded. CLOSED_AT, DUE_AT, PAID_AT: the invoice's closing, due and payment dates (an invoice with no payment date uses the event date). EFFECTIVE_AT: the day the payment took effect. INVOICE_CLOSED and INVOICE_PAID accept EVENT_DATE, CREATED_AT, CLOSED_AT, DUE_AT and PAID_AT; PAYMENT_RECEIVED accepts EVENT_DATE, CREATED_AT and EFFECTIVE_AT. Any other combination is rejected.
Available options:
EVENT_DATE, CREATED_AT, CLOSED_AT, DUE_AT, PAID_AT, EFFECTIVE_AT Example:
"PAID_AT"
Free text printed on every NFSe this configuration issues. Send an empty string to print none.
Example:
"Serviços prestados conforme contrato."
Nature of the operation, stored with every NFSe this configuration issues but not printed on it. An empty string is accepted.
Example:
"Prestação de Serviços"
Response
Successful response
The organization's NFSe configuration.
Which billing event issues an NFSe: INVOICE_CLOSED (one per invoice, when it closes), INVOICE_PAID (one per invoice, when it is paid) or PAYMENT_RECEIVED (one per payment settled on an invoice).
Available options:
INVOICE_PAID, INVOICE_CLOSED, PAYMENT_RECEIVED Example:
"INVOICE_PAID"
Whether the customer withholds the ISS at source.
Example:
false
LIVE for real NFSe, TEST for homologation documents with no fiscal value.
Available options:
TEST, LIVE Example:
"LIVE"
When the configuration was created.
Example:
"2026-08-07T19:45:17.204Z"
Which date becomes the competence date of each NFSe: EVENT_DATE, CREATED_AT, CLOSED_AT, DUE_AT, PAID_AT or EFFECTIVE_AT. Absent on a configuration created before this field existed: its NFSe take the day the invoice was last updated.
Available options:
EVENT_DATE, CREATED_AT, CLOSED_AT, DUE_AT, PAID_AT, EFFECTIVE_AT Example:
"PAID_AT"
Free text printed on every NFSe. Absent on a configuration created before this field existed, which prints none.
Example:
"Serviços prestados conforme contrato."
Nature of the operation, stored with every NFSe but not printed on it. Absent on a configuration created before this field existed, which stores Prestação de Serviços.
Example:
"Prestação de Serviços"