Create a supplier
curl --request POST \
--url https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers \
--header 'Content-Type: application/json' \
--data '
{
"name": "Transportadora Boa Viagem Ltda",
"document": "11222333000181",
"documentType": "CNPJ",
"email": "financeiro@boaviagem.example.com",
"phoneNumber": "+5534984325252",
"address": {
"street": "Rua das Flores",
"number": "100",
"neighborhood": "Centro",
"city": "Uberlândia",
"state": "MG",
"postalCode": "38400-000",
"complement": "Sala 2"
},
"tradingName": "Boa Viagem Transportes",
"pixKey": "financeiro@boaviagem.example.com",
"pixKeyType": "EMAIL"
}
'import requests
url = "https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers"
payload = {
"name": "Transportadora Boa Viagem Ltda",
"document": "11222333000181",
"documentType": "CNPJ",
"email": "financeiro@boaviagem.example.com",
"phoneNumber": "+5534984325252",
"address": {
"street": "Rua das Flores",
"number": "100",
"neighborhood": "Centro",
"city": "Uberlândia",
"state": "MG",
"postalCode": "38400-000",
"complement": "Sala 2"
},
"tradingName": "Boa Viagem Transportes",
"pixKey": "financeiro@boaviagem.example.com",
"pixKeyType": "EMAIL"
}
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({
name: 'Transportadora Boa Viagem Ltda',
document: '11222333000181',
documentType: 'CNPJ',
email: 'financeiro@boaviagem.example.com',
phoneNumber: '+5534984325252',
address: {
street: 'Rua das Flores',
number: '100',
neighborhood: 'Centro',
city: 'Uberlândia',
state: 'MG',
postalCode: '38400-000',
complement: 'Sala 2'
},
tradingName: 'Boa Viagem Transportes',
pixKey: 'financeiro@boaviagem.example.com',
pixKeyType: 'EMAIL'
})
};
fetch('https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers', 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.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers",
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([
'name' => 'Transportadora Boa Viagem Ltda',
'document' => '11222333000181',
'documentType' => 'CNPJ',
'email' => 'financeiro@boaviagem.example.com',
'phoneNumber' => '+5534984325252',
'address' => [
'street' => 'Rua das Flores',
'number' => '100',
'neighborhood' => 'Centro',
'city' => 'Uberlândia',
'state' => 'MG',
'postalCode' => '38400-000',
'complement' => 'Sala 2'
],
'tradingName' => 'Boa Viagem Transportes',
'pixKey' => 'financeiro@boaviagem.example.com',
'pixKeyType' => 'EMAIL'
]),
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.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers"
payload := strings.NewReader("{\n \"name\": \"Transportadora Boa Viagem Ltda\",\n \"document\": \"11222333000181\",\n \"documentType\": \"CNPJ\",\n \"email\": \"financeiro@boaviagem.example.com\",\n \"phoneNumber\": \"+5534984325252\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"100\",\n \"neighborhood\": \"Centro\",\n \"city\": \"Uberlândia\",\n \"state\": \"MG\",\n \"postalCode\": \"38400-000\",\n \"complement\": \"Sala 2\"\n },\n \"tradingName\": \"Boa Viagem Transportes\",\n \"pixKey\": \"financeiro@boaviagem.example.com\",\n \"pixKeyType\": \"EMAIL\"\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.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Transportadora Boa Viagem Ltda\",\n \"document\": \"11222333000181\",\n \"documentType\": \"CNPJ\",\n \"email\": \"financeiro@boaviagem.example.com\",\n \"phoneNumber\": \"+5534984325252\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"100\",\n \"neighborhood\": \"Centro\",\n \"city\": \"Uberlândia\",\n \"state\": \"MG\",\n \"postalCode\": \"38400-000\",\n \"complement\": \"Sala 2\"\n },\n \"tradingName\": \"Boa Viagem Transportes\",\n \"pixKey\": \"financeiro@boaviagem.example.com\",\n \"pixKeyType\": \"EMAIL\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers")
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 \"name\": \"Transportadora Boa Viagem Ltda\",\n \"document\": \"11222333000181\",\n \"documentType\": \"CNPJ\",\n \"email\": \"financeiro@boaviagem.example.com\",\n \"phoneNumber\": \"+5534984325252\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"100\",\n \"neighborhood\": \"Centro\",\n \"city\": \"Uberlândia\",\n \"state\": \"MG\",\n \"postalCode\": \"38400-000\",\n \"complement\": \"Sala 2\"\n },\n \"tradingName\": \"Boa Viagem Transportes\",\n \"pixKey\": \"financeiro@boaviagem.example.com\",\n \"pixKeyType\": \"EMAIL\"\n}"
response = http.request(request)
puts response.read_body{
"id": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17",
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"name": "Transportadora Boa Viagem Ltda",
"document": "11222333000181",
"documentType": "CNPJ",
"email": "financeiro@boaviagem.example.com",
"phoneNumber": "+5534984325252",
"status": "ACTIVE",
"tradingName": "Boa Viagem Transportes",
"address": {
"street": "Rua das Flores",
"number": "100",
"neighborhood": "Centro",
"city": "Uberlândia",
"state": "MG",
"postalCode": "38400-000",
"complement": "Sala 2"
},
"pixKey": "financeiro@boaviagem.example.com",
"pixKeyType": "EMAIL",
"createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"createdAt": "2026-10-02T14:03:11.000Z",
"updatedAt": "2026-10-05T09:30:00.000Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "FORBIDDEN_SUPPLIER",
"origin": "REGISTRY",
"message": "You do not have permission to perform this action on supplier"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "SUPPLIER_CONFLICT",
"origin": "REGISTRY",
"message": "Supplier already exists with this document in this real/company/document"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "REGISTRY",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "name",
"message": "Invalid input: expected string, received undefined",
"code": "NAME_REQUIRED"
}
]
}Create a supplier
Registers a supplier in the organization.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
suppliers
Create a supplier
curl --request POST \
--url https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers \
--header 'Content-Type: application/json' \
--data '
{
"name": "Transportadora Boa Viagem Ltda",
"document": "11222333000181",
"documentType": "CNPJ",
"email": "financeiro@boaviagem.example.com",
"phoneNumber": "+5534984325252",
"address": {
"street": "Rua das Flores",
"number": "100",
"neighborhood": "Centro",
"city": "Uberlândia",
"state": "MG",
"postalCode": "38400-000",
"complement": "Sala 2"
},
"tradingName": "Boa Viagem Transportes",
"pixKey": "financeiro@boaviagem.example.com",
"pixKeyType": "EMAIL"
}
'import requests
url = "https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers"
payload = {
"name": "Transportadora Boa Viagem Ltda",
"document": "11222333000181",
"documentType": "CNPJ",
"email": "financeiro@boaviagem.example.com",
"phoneNumber": "+5534984325252",
"address": {
"street": "Rua das Flores",
"number": "100",
"neighborhood": "Centro",
"city": "Uberlândia",
"state": "MG",
"postalCode": "38400-000",
"complement": "Sala 2"
},
"tradingName": "Boa Viagem Transportes",
"pixKey": "financeiro@boaviagem.example.com",
"pixKeyType": "EMAIL"
}
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({
name: 'Transportadora Boa Viagem Ltda',
document: '11222333000181',
documentType: 'CNPJ',
email: 'financeiro@boaviagem.example.com',
phoneNumber: '+5534984325252',
address: {
street: 'Rua das Flores',
number: '100',
neighborhood: 'Centro',
city: 'Uberlândia',
state: 'MG',
postalCode: '38400-000',
complement: 'Sala 2'
},
tradingName: 'Boa Viagem Transportes',
pixKey: 'financeiro@boaviagem.example.com',
pixKeyType: 'EMAIL'
})
};
fetch('https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers', 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.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers",
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([
'name' => 'Transportadora Boa Viagem Ltda',
'document' => '11222333000181',
'documentType' => 'CNPJ',
'email' => 'financeiro@boaviagem.example.com',
'phoneNumber' => '+5534984325252',
'address' => [
'street' => 'Rua das Flores',
'number' => '100',
'neighborhood' => 'Centro',
'city' => 'Uberlândia',
'state' => 'MG',
'postalCode' => '38400-000',
'complement' => 'Sala 2'
],
'tradingName' => 'Boa Viagem Transportes',
'pixKey' => 'financeiro@boaviagem.example.com',
'pixKeyType' => 'EMAIL'
]),
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.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers"
payload := strings.NewReader("{\n \"name\": \"Transportadora Boa Viagem Ltda\",\n \"document\": \"11222333000181\",\n \"documentType\": \"CNPJ\",\n \"email\": \"financeiro@boaviagem.example.com\",\n \"phoneNumber\": \"+5534984325252\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"100\",\n \"neighborhood\": \"Centro\",\n \"city\": \"Uberlândia\",\n \"state\": \"MG\",\n \"postalCode\": \"38400-000\",\n \"complement\": \"Sala 2\"\n },\n \"tradingName\": \"Boa Viagem Transportes\",\n \"pixKey\": \"financeiro@boaviagem.example.com\",\n \"pixKeyType\": \"EMAIL\"\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.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Transportadora Boa Viagem Ltda\",\n \"document\": \"11222333000181\",\n \"documentType\": \"CNPJ\",\n \"email\": \"financeiro@boaviagem.example.com\",\n \"phoneNumber\": \"+5534984325252\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"100\",\n \"neighborhood\": \"Centro\",\n \"city\": \"Uberlândia\",\n \"state\": \"MG\",\n \"postalCode\": \"38400-000\",\n \"complement\": \"Sala 2\"\n },\n \"tradingName\": \"Boa Viagem Transportes\",\n \"pixKey\": \"financeiro@boaviagem.example.com\",\n \"pixKeyType\": \"EMAIL\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.registry.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/suppliers")
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 \"name\": \"Transportadora Boa Viagem Ltda\",\n \"document\": \"11222333000181\",\n \"documentType\": \"CNPJ\",\n \"email\": \"financeiro@boaviagem.example.com\",\n \"phoneNumber\": \"+5534984325252\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"100\",\n \"neighborhood\": \"Centro\",\n \"city\": \"Uberlândia\",\n \"state\": \"MG\",\n \"postalCode\": \"38400-000\",\n \"complement\": \"Sala 2\"\n },\n \"tradingName\": \"Boa Viagem Transportes\",\n \"pixKey\": \"financeiro@boaviagem.example.com\",\n \"pixKeyType\": \"EMAIL\"\n}"
response = http.request(request)
puts response.read_body{
"id": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17",
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"name": "Transportadora Boa Viagem Ltda",
"document": "11222333000181",
"documentType": "CNPJ",
"email": "financeiro@boaviagem.example.com",
"phoneNumber": "+5534984325252",
"status": "ACTIVE",
"tradingName": "Boa Viagem Transportes",
"address": {
"street": "Rua das Flores",
"number": "100",
"neighborhood": "Centro",
"city": "Uberlândia",
"state": "MG",
"postalCode": "38400-000",
"complement": "Sala 2"
},
"pixKey": "financeiro@boaviagem.example.com",
"pixKeyType": "EMAIL",
"createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
"createdAt": "2026-10-02T14:03:11.000Z",
"updatedAt": "2026-10-05T09:30:00.000Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "FORBIDDEN_SUPPLIER",
"origin": "REGISTRY",
"message": "You do not have permission to perform this action on supplier"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "SUPPLIER_CONFLICT",
"origin": "REGISTRY",
"message": "Supplier already exists with this document in this real/company/document"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "REGISTRY",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "name",
"message": "Invalid input: expected string, received undefined",
"code": "NAME_REQUIRED"
}
]
}Only organization admins can register suppliers. The supplier is always created
ACTIVE. A CNPJ with letters is stored in upper case, whatever case you send, and each organization can register a document only once. documentType must match the document, and a pixKey always comes with its pixKeyType. Answers the supplier that was created, with its new id.Path Parameters
ID of your realm.
Format: UUID
ID of the organization the supplier is registered in.
Format: UUID
Body
application/json
Name of the supplier, up to 100 characters.
Required string length:
1 - 100Example:
"Transportadora Boa Viagem Ltda"
CPF or CNPJ of the supplier: letters and digits only, with no dots, slashes or hyphens (a CNPJ can contain letters). It must be valid and agree with documentType. A supplier's document is unique in the organization.
Minimum string length:
1Pattern:
^[A-Za-z0-9]+$Example:
"11222333000181"
CPF when the supplier is a person, CNPJ when it is a company. It must match document.
Available options:
CPF, CNPJ Example:
"CNPJ"
E-mail address of the supplier.
Pattern:
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Example:
"financeiro@boaviagem.example.com"
Phone number of the supplier in international format: +55, the area code and the number, with no spaces or punctuation.
Pattern:
^\+55[0-9]{10,11}$Example:
"+5534984325252"
Address of the supplier.
Show child attributes
Show child attributes
Trade name of the supplier, up to 100 characters.
Maximum string length:
100Example:
"Boa Viagem Transportes"
PIX key to pay the supplier: an e-mail address, 11 digits (a CPF or a phone number), a CNPJ, a random key of 32 letters and digits, or 8 digits. Send pixKeyType with it.
Pattern:
^[0-9a-zA-Z._-]+@[0-9a-zA-Z._-]+$|^[0-9]{11}$|^[A-Za-z0-9]{12}[0-9]{2}$|^[a-zA-Z0-9]{32}$|^[0-9]{8}$Example:
"financeiro@boaviagem.example.com"
Type of pixKey: PHONE, EMAIL, CPF, CNPJ or EVP (a random key). Required when you send pixKey, and not allowed without it.
Available options:
PHONE, EMAIL, CPF, CNPJ, EVP Example:
"EMAIL"
Response
Successful response
A supplier of the organization: someone you pay.
ID of the supplier.
Example:
"5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17"
ID of the realm the supplier belongs to.
Example:
"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"
ID of the organization the supplier belongs to.
Example:
"c4bd3f21-dfbd-44e8-8055-68ba15bed410"
Name of the supplier.
Example:
"Transportadora Boa Viagem Ltda"
CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.
Example:
"11222333000181"
CPF when the supplier is a person, CNPJ when it is a company.
Available options:
CPF, CNPJ Example:
"CNPJ"
E-mail address of the supplier.
Example:
"financeiro@boaviagem.example.com"
Phone number of the supplier in international format.
Example:
"+5534984325252"
ACTIVE, or DEACTIVATED once the supplier was deactivated.
Available options:
ACTIVE, DEACTIVATED Example:
"ACTIVE"
Trade name of the supplier. Absent when none was given.
Example:
"Boa Viagem Transportes"
Address of the supplier.
Show child attributes
Show child attributes
PIX key to pay the supplier. Absent when none was given.
Example:
"financeiro@boaviagem.example.com"
Type of pixKey: PHONE, EMAIL, CPF, CNPJ or EVP (a random key). Absent when there is no PIX key.
Available options:
PHONE, EMAIL, CPF, CNPJ, EVP Example:
"EMAIL"
ID of the user who registered the supplier.
Example:
"e3553bc1-5e20-4e17-b22a-a796fda0aa99"
When the supplier was registered.
Example:
"2026-10-02T14:03:11.000Z"
When the supplier was last changed.
Example:
"2026-10-05T09:30:00.000Z"