{ "openapi": "3.0.3", "info": { "title": "Registry", "version": "1.0.0", "description": "Portão 3 registry API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Confidence tiers: generated:typed=37 copied:manual=0 unknown=0." }, "servers": [ { "url": "https://api.registry.v2.portao3.com.br/", "description": "production" }, { "url": "https://api.registry.dev.3pers.com.br/", "description": "development" } ], "x-p3-surface": "public", "tags": [ { "name": "Customers" }, { "name": "Companies" }, { "name": "People" }, { "name": "Products" }, { "name": "Suppliers" } ], "components": {}, "paths": { "/realms/{realmId}/organizations/{organizationId}/customer": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdCustomer", "summary": "List customers", "tags": [ "Customers" ], "x-p3-sidebar-order": 1, "description": "Lists the customers of an organization, 25 per page and oldest first by default.", "x-mint": { "content": "Page with `limit` and `next`: pass the `next` cursor of one page to get the following one; the last page has no `next`. Sort with `order` and `orderBy`.\n\n`search` looks for the text, case-insensitively, anywhere in the customer's name, trade name or document, and in the text values of its custom fields (a number or yes/no value is never matched). A term with at least one letter is searched as typed. A term with no letter keeps only its digits, so a CPF typed as `529.982.247-25` finds the stored `52998224725`, and `10-20` is searched as `1020`.\n\n`documents` looks up up to 100 documents at once, comma-separated: `?documents=52998224725,11144477735` (repeating the parameter works too). A repeated document counts once, more than 100 is rejected and a blank value is ignored. It combines with `search`, `status` and `documentType`, but it answers every match in one response, oldest first and with no `next`: `limit`, `next`, `order` and `orderBy` don't apply." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose customers you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "search", "in": "query", "required": false, "description": "Free-text search over the customer's name, trade name, document and the text values of its custom fields (case-insensitive, any part of the text).", "schema": { "type": "string" }, "example": "souza" }, { "name": "status", "in": "query", "required": false, "description": "Only customers in one of these statuses.\n\n---\n\nExample (comma-separated list): `?status=ACTIVE,DEACTIVATED`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] } }, "style": "form", "explode": false }, { "name": "documentType", "in": "query", "required": false, "description": "Only customers whose document is of one of these kinds: `CPF` (people) or `CNPJ` (companies).\n\n---\n\nExample (comma-separated list): `?documentType=CPF,CNPJ`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "CPF", "CNPJ" ] } }, "style": "form", "explode": false }, { "name": "documents", "in": "query", "required": false, "description": "Only the customers with these documents (exact match, CPF or CNPJ without formatting).\n\n---\n\nExample (comma-separated list): `?documents=52998224725,11144477735`", "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "style": "form", "explode": false }, { "name": "order", "in": "query", "required": false, "description": "Sort direction: `ASC` (oldest first, by default) or `DESC`.", "schema": { "default": "ASC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Name of the customer field to sort by. Defaults to `createdAt`.", "schema": { "default": "createdAt", "type": "string" }, "example": "name" }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 25.", "schema": { "default": 25, "type": "number" }, "example": 25 }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit it to get the first page.", "schema": { "type": "string" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "next": { "type": "string", "description": "Cursor for the next page: pass it as `next` to get it. Absent on the last page, and when the list was filtered by `documents`.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13", "format": "uuid" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number (letters, digits and dashes).", "example": "123" }, "complement": { "type": "string", "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" } }, "description": "Postal address of the customer.", "example": { "street": "Rua das Flores", "number": "123", "complement": "Apto 45", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01000-000" } }, "name": { "type": "string", "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "document": { "type": "string", "description": "Tax ID of the customer, without formatting: a CPF (11 digits) or a CNPJ (14 characters — the first 12 may be uppercase letters, the last 2 are digits).", "example": "52998224725" }, "documentType": { "type": "string", "description": "Kind of `document`: `CPF` for 11 characters, `CNPJ` otherwise.", "example": "CPF" }, "trandingName": { "type": "string", "description": "Trade name of a company customer.", "example": "Souza Studio" }, "email": { "type": "string", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the customer, in international format: `+` followed by digits. A few older records that could not be converted to this format are returned exactly as they were stored.", "example": "+5511999999999" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was created.", "example": "2026-03-14T12:30:00.000Z" }, "createdBy": { "type": "string", "description": "ID of the user or API client that created the customer. The customer list does not include it.", "example": "9b2f4c1e-5d38-4a76-b0e1-3c8a7d2f6e45" }, "hash": { "type": "string", "description": "Token that identifies the customer in the link of their portal page (`customerUrl`).", "example": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "format": "uuid" }, "customerUrl": { "type": "string", "description": "Link to the customer's portal page. It is built from the portal address and `hash`.", "example": "https://portal.example.com/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" }, "status": { "type": "string", "description": "Status of the customer: `ACTIVE` or `DEACTIVATED`.", "example": "ACTIVE" }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by the field's `slug`. Absent, or `null`, when the customer has none.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "id", "documentType", "customerUrl" ], "description": "A customer: the person or company an organization bills." }, "description": "The customers of this page." } }, "required": [ "items" ], "description": "A page of customers." } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `status`, more than 100 `documents` or a `limit` that is not a number; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "documents", "message": "Too big: expected array to have <=100 items", "code": "DOCUMENTS_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.transform(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdCustomer", "summary": "Create a customer", "tags": [ "Customers" ], "x-p3-sidebar-order": 2, "description": "Creates a customer of the organization — a person or a company you bill — and answers it.", "x-mint": { "content": "Every new customer is `ACTIVE`. Its `document` (CPF or CNPJ) can belong to one customer only in the organization.\n\n`customFields` are checked against the organization's active custom fields for customers: every key must be the slug of one of them and every value must fit its type. A custom field marked as required must have a value, even when you send no `customFields` at all." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the customer belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "trandingName": { "description": "Trade name of a company customer.", "example": "Souza Studio", "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "pattern": "^\\+55[0-9]{10,11}$", "description": "Brazilian phone number in international format: `+55`, the area code and the number (10 or 11 digits).", "example": "+5511999999999" }, "document": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$", "description": "CPF (11 digits) or CNPJ (14 characters: the first 12 may be letters, the last 2 are digits) of the customer, with no dots, dashes or slashes. The check digits are verified and letters are stored in uppercase. A document can belong to one customer only in the organization.", "example": "52998224725" }, "address": { "type": "object", "properties": { "city": { "type": "string", "minLength": 1, "maxLength": 50, "description": "City.", "example": "São Paulo" }, "neighborhood": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-zÀ-ú 0-9.,\\-]+$", "description": "Neighborhood. Letters, digits, spaces and the characters `. , -` only.", "example": "Centro" }, "number": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9\\-]+$", "description": "Street number. Letters, digits and dashes only.", "example": "123" }, "state": { "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO", "DF" ], "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "street": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-zÀ-ú 0-9.,\\-]+$", "description": "Street name. Letters, digits, spaces and the characters `. , -` only.", "example": "Rua das Flores" }, "postalCode": { "type": "string", "minLength": 1, "pattern": "^[0-9]{5}-[0-9]{3}$", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" }, "complement": { "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45", "type": "string", "maxLength": 50 } }, "required": [ "city", "neighborhood", "number", "state", "street", "postalCode" ], "description": "Postal address of the customer." }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by each field's `slug`. Every key must be the slug of an active custom field defined for customers, and every value must fit that field's type; a field marked as required must have a value.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } }, "required": [ "name", "email", "phoneNumber", "document", "address" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13", "format": "uuid" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number (letters, digits and dashes).", "example": "123" }, "complement": { "type": "string", "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" } }, "description": "Postal address of the customer.", "example": { "street": "Rua das Flores", "number": "123", "complement": "Apto 45", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01000-000" } }, "name": { "type": "string", "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "document": { "type": "string", "description": "Tax ID of the customer, without formatting: a CPF (11 digits) or a CNPJ (14 characters — the first 12 may be uppercase letters, the last 2 are digits).", "example": "52998224725" }, "documentType": { "type": "string", "description": "Kind of `document`: `CPF` for 11 characters, `CNPJ` otherwise.", "example": "CPF" }, "trandingName": { "type": "string", "description": "Trade name of a company customer.", "example": "Souza Studio" }, "email": { "type": "string", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the customer, in international format: `+` followed by digits.", "example": "+5511999999999" }, "hash": { "type": "string", "description": "Token that identifies the customer in the link of their portal page.", "example": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "format": "uuid" }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by the field's `slug`. Absent, or `null`, when the customer has none.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "id", "hash" ], "description": "The customer a create or an update answers with." } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "409": { "description": "`CUSTOMER_CONFLICT` — The organization already has a customer with this `document`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CUSTOMER_CONFLICT" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CUSTOMER_CONFLICT", "origin": "REGISTRY", "message": "Customer already exists" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter or a body field is invalid or missing, such as a `document` that is not a valid CPF or CNPJ; `fields` lists each one.\n\n`CUSTOM_FIELD_NOT_FOUND` — A key of `customFields` is not the slug of an active custom field defined for customers. The message reads `Custom field \"\" not found`.\n\n`CUSTOM_FIELD_INVALID_VALUE` — A value of `customFields` does not fit its custom field's type or options. The message reads `Invalid value for custom field \"\"`.\n\n`CUSTOM_FIELD_IS_REQUIRED` — A custom field marked as required has no value. The message reads `Custom field \"\" is required`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "CUSTOM_FIELD_NOT_FOUND", "CUSTOM_FIELD_INVALID_VALUE", "CUSTOM_FIELD_IS_REQUIRED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/customers/report": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdCustomersReport", "summary": "Export customers", "tags": [ "Customers" ], "x-p3-sidebar-order": 3, "description": "Exports every customer of the organization as a CSV or XLSX file.", "x-mint": { "content": "The file format goes in the `type` query parameter: `?type=csv` (the default) answers a UTF-8 CSV file, `?type=xlsx` an Excel workbook returned base64-encoded. The file lists every customer of the organization, whatever its status, one per row, with four columns whose headers are in Portuguese: `Nome do cliente` (name), `CPF/CNPJ` (document), `Status` (`Ativo` or `Desativado`) and `Data de Criação` (creation date, as `DD/MM/YYYY`, the UTC date: a customer created at 22:30 in Brasília time on the 13th shows the 14th). The filters of the customer list do not apply." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose customers you want to export.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "type", "in": "query", "required": false, "description": "The file format: `csv` for a UTF-8 CSV file (the default), `xlsx` for an Excel workbook returned base64-encoded.", "schema": { "default": "csv", "type": "string", "enum": [ "csv", "xlsx" ] }, "example": "csv" } ], "responses": { "200": { "description": "`application/csv` — The customers as a UTF-8 CSV file, when `type` is `csv` or omitted (served with that `Content-Type`).\n\n`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — The Excel workbook, base64-encoded, when `type` is `xlsx`.", "content": { "application/csv": { "schema": { "type": "string", "description": "The customers as a UTF-8 CSV file, when `type` is `csv` or omitted (served with that `Content-Type`)." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "byte", "description": "The Excel workbook, base64-encoded, when `type` is `xlsx`." } } } }, "400": { "description": "`INVALID_TYPE` — The `type` query parameter is neither `csv` nor `xlsx`. Omit it to get a CSV file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "INVALID_TYPE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "INVALID_TYPE", "origin": "REGISTRY", "message": "Invalid type" } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is invalid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "type", "message": "Invalid option: expected one of \"csv\"|\"xlsx\"", "code": "TYPE_ONE_OF" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/customer/{customerId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdCustomerByCustomerId", "summary": "Get a customer", "tags": [ "Customers" ], "x-p3-sidebar-order": 4, "description": "Gets one customer of the organization, with its status and the link to its portal page.", "x-mint": { "content": "`createdBy` is the ID of the user or API client that created the customer, and `customerUrl` is the link to the customer's portal page." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the customer belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "customerId", "in": "path", "required": true, "description": "ID of the customer.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13", "format": "uuid" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number (letters, digits and dashes).", "example": "123" }, "complement": { "type": "string", "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" } }, "description": "Postal address of the customer.", "example": { "street": "Rua das Flores", "number": "123", "complement": "Apto 45", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01000-000" } }, "name": { "type": "string", "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "document": { "type": "string", "description": "Tax ID of the customer, without formatting: a CPF (11 digits) or a CNPJ (14 characters — the first 12 may be uppercase letters, the last 2 are digits).", "example": "52998224725" }, "documentType": { "type": "string", "description": "Kind of `document`: `CPF` for 11 characters, `CNPJ` otherwise.", "example": "CPF" }, "trandingName": { "type": "string", "description": "Trade name of a company customer.", "example": "Souza Studio" }, "email": { "type": "string", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the customer, in international format: `+` followed by digits. A few older records that could not be converted to this format are returned exactly as they were stored.", "example": "+5511999999999" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was created.", "example": "2026-03-14T12:30:00.000Z" }, "createdBy": { "type": "string", "description": "ID of the user or API client that created the customer. The customer list does not include it.", "example": "9b2f4c1e-5d38-4a76-b0e1-3c8a7d2f6e45" }, "hash": { "type": "string", "description": "Token that identifies the customer in the link of their portal page (`customerUrl`).", "example": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "format": "uuid" }, "customerUrl": { "type": "string", "description": "Link to the customer's portal page. It is built from the portal address and `hash`.", "example": "https://portal.example.com/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" }, "status": { "type": "string", "description": "Status of the customer: `ACTIVE` or `DEACTIVATED`.", "example": "ACTIVE" }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by the field's `slug`. Absent, or `null`, when the customer has none.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "id", "documentType", "customerUrl" ], "description": "A customer: the person or company an organization bills." } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "404": { "description": "`CUSTOMER_NOT_FOUND` — No customer with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CUSTOMER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CUSTOMER_NOT_FOUND", "origin": "REGISTRY", "message": "Customer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `customerId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "customerId", "message": "Invalid UUID", "code": "CUSTOMERID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdCustomerByCustomerId", "summary": "Update a customer", "tags": [ "Customers" ], "x-p3-sidebar-order": 5, "description": "Updates a customer's name, trade name, e-mail, phone, address or custom-field values, and answers the updated customer with `201`.", "x-mint": { "content": "Send only what changes: a field you leave out keeps its current value, and an address part you leave out stays as it is. A customer's `document` can't be changed, and neither can its status: use the activate and deactivate routes for that.\n\n`customFields`, when sent, replaces the customer's whole map, so send every value you want to keep. Its keys are checked against the organization's active custom fields for customers; unlike a create, a required custom field you leave out is not an error." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the customer belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "customerId", "in": "path", "required": true, "description": "ID of the customer to update.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name of the customer: a person's full name or a company's name. Omit it, or send it empty, to keep the current one.", "example": "Ana Souza", "type": "string", "maxLength": 100 }, "trandingName": { "description": "New trade name of a company customer. Omit it, or send it empty, to keep the current one.", "example": "Souza Studio", "type": "string" }, "email": { "description": "New e-mail address of the customer.", "example": "ana.souza@example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "document": { "description": "A customer's document can't be changed: the value is checked (it must be a valid CPF or CNPJ, with no dots, dashes or slashes) and then ignored.", "example": "52998224725", "type": "string", "pattern": "^[A-Za-z0-9]+$" }, "phoneNumber": { "description": "New Brazilian phone number in international format: `+55`, the area code and the number (10 or 11 digits).", "example": "+5511999999999", "type": "string", "pattern": "^\\+55[0-9]{10,11}$" }, "address": { "default": {}, "description": "Parts of the postal address to change. Each part you send replaces the stored one; the parts you leave out stay as they are.", "type": "object", "properties": { "city": { "description": "City.", "example": "São Paulo", "type": "string", "maxLength": 50 }, "neighborhood": { "description": "Neighborhood. Letters, digits, spaces and the characters `. , -` only.", "example": "Centro", "type": "string", "maxLength": 100, "pattern": "^[A-Za-zÀ-ú 0-9.,\\-]+$" }, "number": { "description": "Street number. Letters, digits and dashes only.", "example": "123", "type": "string", "pattern": "^[A-Za-z0-9\\-]+$" }, "state": { "description": "Two-letter code of the Brazilian state.", "example": "SP", "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO", "DF" ] }, "street": { "description": "Street name. Letters, digits, spaces and the characters `. , -` only.", "example": "Rua das Flores", "type": "string", "maxLength": 100, "pattern": "^[A-Za-zÀ-ú 0-9.,\\-]+$" }, "postalCode": { "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000", "type": "string", "pattern": "^[0-9]{5}-[0-9]{3}$" }, "complement": { "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45", "type": "string", "maxLength": 50 } } }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by each field's `slug`. When sent it replaces the customer's whole map: a field you leave out is removed, and a value sent as `null`, an empty string or an empty list clears that field. Every key must be the slug of an active custom field defined for customers, and every value must fit that field's type. Omit `customFields` to leave the values untouched.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {} } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13", "format": "uuid" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number (letters, digits and dashes).", "example": "123" }, "complement": { "type": "string", "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" } }, "description": "Postal address of the customer.", "example": { "street": "Rua das Flores", "number": "123", "complement": "Apto 45", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01000-000" } }, "name": { "type": "string", "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "document": { "type": "string", "description": "Tax ID of the customer, without formatting: a CPF (11 digits) or a CNPJ (14 characters — the first 12 may be uppercase letters, the last 2 are digits).", "example": "52998224725" }, "documentType": { "type": "string", "description": "Kind of `document`: `CPF` for 11 characters, `CNPJ` otherwise.", "example": "CPF" }, "trandingName": { "type": "string", "description": "Trade name of a company customer.", "example": "Souza Studio" }, "email": { "type": "string", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the customer, in international format: `+` followed by digits.", "example": "+5511999999999" }, "hash": { "type": "string", "description": "Token that identifies the customer in the link of their portal page.", "example": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "format": "uuid" }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by the field's `slug`. Absent, or `null`, when the customer has none.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "hash", "id" ], "description": "The customer an update answers with: the same shape a create answers with." } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "404": { "description": "`CUSTOMER_NOT_FOUND` — No customer with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CUSTOMER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CUSTOMER_NOT_FOUND", "origin": "REGISTRY", "message": "Customer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter or a body field is invalid, such as a `customerId` that is not a UUID (listed in `fields` as `id`); `fields` lists each one.\n\n`CUSTOM_FIELD_NOT_FOUND` — A key of `customFields` is not the slug of an active custom field defined for customers. The message reads `Custom field \"\" not found`.\n\n`CUSTOM_FIELD_INVALID_VALUE` — A value of `customFields` does not fit its custom field's type or options. The message reads `Invalid value for custom field \"\"`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "CUSTOM_FIELD_NOT_FOUND", "CUSTOM_FIELD_INVALID_VALUE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "Too big: expected string to have <=100 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/customer/{customerId}/activate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdCustomerByCustomerIdActivate", "summary": "Activate a customer", "tags": [ "Customers" ], "x-p3-sidebar-order": 6, "description": "Sets a customer's `status` to `ACTIVE`.", "x-mint": { "content": "Only a `DEACTIVATED` customer can be activated: activating one that is already `ACTIVE` is rejected. To deactivate a customer, use `POST /realms/{realmId}/organizations/{organizationId}/customer/{customerId}/deactivate`.\n\nAnswers the customer as it is after the change. The request has no body: if your HTTP client sends `Content-Type: application/json`, send `{}`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the customer belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "customerId", "in": "path", "required": true, "description": "ID of the customer.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13", "format": "uuid" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number (letters, digits and dashes).", "example": "123" }, "complement": { "type": "string", "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" } }, "description": "Postal address of the customer.", "example": { "street": "Rua das Flores", "number": "123", "complement": "Apto 45", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01000-000" } }, "name": { "type": "string", "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "document": { "type": "string", "description": "Tax ID of the customer, without formatting: a CPF (11 digits) or a CNPJ (14 characters — the first 12 may be uppercase letters, the last 2 are digits).", "example": "52998224725" }, "documentType": { "type": "string", "description": "Kind of `document`: `CPF` for 11 characters, `CNPJ` otherwise.", "example": "CPF" }, "trandingName": { "type": "string", "description": "Trade name of a company customer.", "example": "Souza Studio" }, "email": { "type": "string", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the customer, in international format: `+` followed by digits. A few older records that could not be converted to this format are returned exactly as they were stored.", "example": "+5511999999999" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was created.", "example": "2026-03-14T12:30:00.000Z" }, "createdBy": { "type": "string", "description": "ID of the user or API client that created the customer. The customer list does not include it.", "example": "9b2f4c1e-5d38-4a76-b0e1-3c8a7d2f6e45" }, "hash": { "type": "string", "description": "Token that identifies the customer in the link of their portal page (`customerUrl`).", "example": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "format": "uuid" }, "customerUrl": { "type": "string", "description": "Link to the customer's portal page. It is built from the portal address and `hash`.", "example": "https://portal.example.com/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" }, "status": { "type": "string", "description": "Status of the customer: `ACTIVE` or `DEACTIVATED`.", "example": "ACTIVE" }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by the field's `slug`. Absent, or `null`, when the customer has none.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "id", "documentType", "customerUrl" ], "description": "A customer: the person or company an organization bills." } } } }, "400": { "description": "`ACTIVATE_CUSTOMER_BUSINESS_LOGIC` — The customer is already `ACTIVE`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "ACTIVATE_CUSTOMER_BUSINESS_LOGIC" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "ACTIVATE_CUSTOMER_BUSINESS_LOGIC", "origin": "REGISTRY", "message": "This customer is alredy activate." } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "404": { "description": "`CUSTOMER_NOT_FOUND` — No customer with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CUSTOMER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CUSTOMER_NOT_FOUND", "origin": "REGISTRY", "message": "Customer not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `customerId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "customerId", "message": "Invalid UUID", "code": "CUSTOMERID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/customer/{customerId}/deactivate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdCustomerByCustomerIdDeactivate", "summary": "Deactivate a customer", "tags": [ "Customers" ], "x-p3-sidebar-order": 7, "description": "Sets a customer's `status` to `DEACTIVATED`.", "x-mint": { "content": "A customer with an open deal whose end date is today or later can't be deactivated: cancel those deals first, or wait for them to end. An open deal with no end date does not block it. Deactivating a customer that is already `DEACTIVATED` is rejected. To bring a customer back, use `POST /realms/{realmId}/organizations/{organizationId}/customer/{customerId}/activate`.\n\nAnswers the customer as it is after the change. The request has no body: if your HTTP client sends `Content-Type: application/json`, send `{}`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the customer belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "customerId", "in": "path", "required": true, "description": "ID of the customer.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer.", "example": "7f3b1c52-9e4a-4d1b-8a67-2c5d9f0e4b13", "format": "uuid" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number (letters, digits and dashes).", "example": "123" }, "complement": { "type": "string", "description": "Extra address detail, such as an apartment or suite.", "example": "Apto 45" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "São Paulo" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), as `00000-000`.", "example": "01000-000" } }, "description": "Postal address of the customer.", "example": { "street": "Rua das Flores", "number": "123", "complement": "Apto 45", "neighborhood": "Centro", "city": "São Paulo", "state": "SP", "postalCode": "01000-000" } }, "name": { "type": "string", "description": "Name of the customer: a person's full name or a company's name.", "example": "Ana Souza" }, "document": { "type": "string", "description": "Tax ID of the customer, without formatting: a CPF (11 digits) or a CNPJ (14 characters — the first 12 may be uppercase letters, the last 2 are digits).", "example": "52998224725" }, "documentType": { "type": "string", "description": "Kind of `document`: `CPF` for 11 characters, `CNPJ` otherwise.", "example": "CPF" }, "trandingName": { "type": "string", "description": "Trade name of a company customer.", "example": "Souza Studio" }, "email": { "type": "string", "description": "E-mail address of the customer.", "example": "ana.souza@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the customer, in international format: `+` followed by digits. A few older records that could not be converted to this format are returned exactly as they were stored.", "example": "+5511999999999" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the customer was created.", "example": "2026-03-14T12:30:00.000Z" }, "createdBy": { "type": "string", "description": "ID of the user or API client that created the customer. The customer list does not include it.", "example": "9b2f4c1e-5d38-4a76-b0e1-3c8a7d2f6e45" }, "hash": { "type": "string", "description": "Token that identifies the customer in the link of their portal page (`customerUrl`).", "example": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "format": "uuid" }, "customerUrl": { "type": "string", "description": "Link to the customer's portal page. It is built from the portal address and `hash`.", "example": "https://portal.example.com/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" }, "status": { "type": "string", "description": "Status of the customer: `ACTIVE` or `DEACTIVATED`.", "example": "DEACTIVATED" }, "customFields": { "description": "Values of the organization's custom fields for this customer, keyed by the field's `slug`. Absent, or `null`, when the customer has none.\n\n---\n\nExample: `{\"cost-center\":\"CC-1020\"}`", "example": { "cost-center": "CC-1020" }, "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "id", "documentType", "customerUrl" ], "description": "A customer: the person or company an organization bills." } } } }, "400": { "description": "`DEACTIVATE_CUSTOMER_BUSINESS_LOGIC` — The customer is already `DEACTIVATED`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "DEACTIVATE_CUSTOMER_BUSINESS_LOGIC" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "DEACTIVATE_CUSTOMER_BUSINESS_LOGIC", "origin": "REGISTRY", "message": "This customer is alredy deactivated." } } } }, "403": { "description": "`FORBIDDEN_CUSTOMER` — You do not belong to the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_CUSTOMER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_CUSTOMER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on this resource (customer)" } } } }, "404": { "description": "`CUSTOMER_NOT_FOUND` — No customer with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CUSTOMER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CUSTOMER_NOT_FOUND", "origin": "REGISTRY", "message": "Customer not found" } } } }, "409": { "description": "`CUSTOMER_DEACTIVE_DEALS_ACTIVE_BUSINESS_LOGIC` — The customer has an open deal whose end date is today or later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "CUSTOMER_DEACTIVE_DEALS_ACTIVE_BUSINESS_LOGIC" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "CUSTOMER_DEACTIVE_DEALS_ACTIVE_BUSINESS_LOGIC", "origin": "REGISTRY", "message": "This customer has active deals, please cancel them before deactivating the customer." } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `customerId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "customerId", "message": "Invalid UUID", "code": "CUSTOMERID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/companies": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdCompanies", "summary": "Search companies", "tags": [ "Companies" ], "x-p3-sidebar-order": 1, "description": "Searches Brazil's public company registry, one establishment (headquarters or branch) per result, in CNPJ order.", "x-mint": { "content": "The data is Brazil's public company registry, from Receita Federal's monthly open data; a record that was looked up by CNPJ may have been refreshed in real time since. Each result's `refDate` is the month of the registry data it reflects. The search covers the stored records only — it never looks a company up. The data is the same for every organization — nothing in it belongs to yours.\n\nEvery filter is optional and they combine. `legalName` matches the beginning of the legal name only (at least 3 characters), never the middle. `mainActivity` is a CNAE code, matched exactly when it has 7 digits and as a prefix when shorter. `companyDocument` lists every establishment of one company. Page with `limit` (up to 100) and `next`: pass the `next` cursor of one page to get the following one; the last page answers `next` as `null`.\n\nA result carries the registry's codes (`statusReason`, `legalNature`, …); `GET /realms/{realmId}/organizations/{organizationId}/companies/{document}` adds their text." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization making the request.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "mainActivity", "in": "query", "required": false, "description": "Main economic activity (CNAE code). A 7-digit code matches that activity exactly; a shorter code, from 2 to 6 digits, matches every activity that starts with it (`62` is the whole division).", "schema": { "type": "string", "pattern": "^\\d{2,7}$" }, "example": "4712100" }, { "name": "status", "in": "query", "required": false, "description": "Only establishments in one of these registration statuses.\n\n---\n\nExample (comma-separated list): `?status=ACTIVE,SUSPENDED`", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ANNULLED", "ACTIVE", "ACTIVE_IRREGULAR", "SUSPENDED", "INAPT", "CLOSED" ] } }, "style": "form", "explode": false }, { "name": "legalName", "in": "query", "required": false, "description": "Only companies whose legal name starts with this text (case-insensitive, at least 3 characters). It matches the beginning of the name, never the middle.", "schema": { "type": "string", "minLength": 3, "maxLength": 120 }, "example": "exemplo comercio" }, { "name": "legalNature", "in": "query", "required": false, "description": "Only companies of one of these legal natures (4-digit codes of Receita Federal's table).\n\n---\n\nExample (comma-separated list): `?legalNature=2046,2062`", "schema": { "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^\\d{4}$" } }, "style": "form", "explode": false }, { "name": "companyDocument", "in": "query", "required": false, "description": "The first 8 characters of a CNPJ, which identify one company: lists the headquarters and every branch of it.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{8}$" }, "example": "11222333" }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit it to get the first page.", "schema": { "type": "string", "maxLength": 64 }, "example": "MTEyMjIzMzMwMDAxODE" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, from 1 to 100. Defaults to 15.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Same value as `document`.", "example": "11222333000181" }, "document": { "type": "string", "description": "CNPJ of the establishment: 14 characters (the first 12 digits or letters, the last 2 digits), without formatting.", "example": "11222333000181" }, "companyDocument": { "type": "string", "description": "The first 8 characters of the CNPJ, which identify the company: every establishment of one company shares them.", "example": "11222333" }, "branchNumber": { "type": "string", "description": "The 4 characters after the company's 8: `0001` is the headquarters.", "example": "0001" }, "branchType": { "type": "string", "enum": [ "HEADQUARTERS", "BRANCH" ], "description": "`HEADQUARTERS` or `BRANCH`.", "example": "HEADQUARTERS" }, "tradingName": { "type": "string", "description": "Trade name of the establishment.", "example": "EXEMPLO MERCADO" }, "status": { "type": "string", "enum": [ "ANNULLED", "ACTIVE", "ACTIVE_IRREGULAR", "SUSPENDED", "INAPT", "CLOSED" ], "description": "Registration status: `ACTIVE`, `ACTIVE_IRREGULAR` (operating, with a pending irregularity at Receita Federal), `SUSPENDED`, `INAPT` (ineligible), `CLOSED` (deregistered) or `ANNULLED`.", "example": "ACTIVE" }, "statusDate": { "type": "string", "format": "date-time", "description": "When the registration status last changed.", "example": "2015-03-12T00:00:00.000Z" }, "statusReason": { "type": "string", "description": "Code of the reason for the registration status, from Receita Federal's table. The company read adds its text as `statusReasonDescription`.", "example": "00" }, "specialStatus": { "type": "string", "description": "Special situation of the company, as published by Receita Federal.", "example": "RECUPERACAO JUDICIAL" }, "specialStatusDate": { "type": "string", "format": "date-time", "description": "When the special situation began.", "example": "2022-06-01T00:00:00.000Z" }, "foundingDate": { "type": "string", "format": "date-time", "description": "When the establishment started its activities.", "example": "2015-03-12T00:00:00.000Z" }, "mainActivity": { "type": "string", "description": "Main economic activity: a 7-digit CNAE code.", "example": "4712100" }, "secondaryActivities": { "type": "array", "items": { "type": "string", "example": "4721102" }, "description": "Secondary economic activities: 7-digit CNAE codes.\n\n---\n\nExample: `[\"4721102\",\"4722901\"]`" }, "email": { "type": "string", "description": "E-mail address of the establishment, in lower case.", "example": "contato@exemplo.com.br" }, "phoneNumber": { "type": "string", "description": "Main phone number, in international format (`+` followed by digits). Absent when the published number can't be converted to it.", "example": "+551133334444" }, "secondaryPhoneNumber": { "type": "string", "description": "Secondary phone number, in international format.", "example": "+551155556666" }, "fax": { "type": "string", "description": "Fax number, in international format.", "example": "+551177778888" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street, with its type (such as `RUA` or `AVENIDA`).", "example": "AVENIDA PAULISTA" }, "number": { "type": "string", "description": "Street number.", "example": "1578" }, "complement": { "type": "string", "description": "Extra address detail.", "example": "ANDAR 3" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "BELA VISTA" }, "city": { "type": "string", "description": "City name.", "example": "SAO PAULO" }, "cityCode": { "type": "string", "description": "Code of the city in Receita Federal's municipality table.", "example": "7107" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), 8 digits.", "example": "01310200" } }, "description": "Address of the establishment." }, "foreignCity": { "type": "string", "description": "City of an establishment based abroad.", "example": "LISBOA" }, "country": { "type": "string", "description": "Country of an establishment based abroad, as a two-letter ISO 3166-1 code. Absent when the published country has no single ISO equivalent; `countryCode` keeps the published value.", "example": "PT" }, "countryCode": { "type": "string", "description": "Country code of an establishment based abroad, as published by Receita Federal (a 3-digit code of its own country table).", "example": "607" }, "legalName": { "type": "string", "description": "Legal name (razão social) of the company.", "example": "EXEMPLO COMERCIO DE ALIMENTOS LTDA" }, "legalNature": { "type": "string", "description": "Legal nature of the company: a 4-digit code from Receita Federal's table. The company read adds its text as `legalNatureDescription`.", "example": "2062" }, "size": { "type": "string", "enum": [ "NOT_INFORMED", "MICRO", "SMALL", "OTHER" ], "description": "Size of the company: `MICRO`, `SMALL`, `OTHER` (any larger) or `NOT_INFORMED`.", "example": "SMALL" }, "capital": { "type": "number", "description": "Share capital, in cents of BRL.", "example": 50000000 }, "responsibleQualification": { "type": "string", "description": "Qualification code of the person responsible for the company, from Receita Federal's qualification table.", "example": "49" }, "federativeEntity": { "type": "string", "description": "Federative entity responsible for the company. Only public bodies have one.", "example": "UNIAO" }, "shareholders": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "CNPJ", "CPF", "FOREIGN" ], "description": "Kind of partner: `CNPJ` for a company, `CPF` for a person or `FOREIGN` for a foreign partner.", "example": "CPF" }, "name": { "type": "string", "description": "Name of the partner.", "example": "MARIA DA SILVA" }, "document": { "type": "string", "description": "Document of the partner: a CNPJ, or a CPF — in full when the record was refreshed in real time, otherwise partly masked as published in the monthly data (`***123456**`). Absent for a foreign partner.", "example": "***123456**" }, "qualification": { "type": "string", "description": "Qualification code of the partner, from Receita Federal's qualification table (`49` is partner-administrator, `22` partner).", "example": "49" }, "joinedAt": { "type": "string", "format": "date-time", "description": "When the partner joined the company.", "example": "2015-03-12T00:00:00.000Z" }, "country": { "type": "string", "description": "Country of a foreign partner, as a two-letter ISO 3166-1 code. Absent when the published country has no single ISO equivalent; `countryCode` keeps the published value.", "example": "US" }, "countryCode": { "type": "string", "description": "Country code of a foreign partner, as published by Receita Federal (a 3-digit code of its own country table).", "example": "249" }, "ageRange": { "type": "string", "description": "Age range of a person partner, as the code published by Receita Federal: `0` not applicable, `1` up to 12 years, `2` 13 to 20, `3` 21 to 30, `4` 31 to 40, `5` 41 to 50, `6` 51 to 60, `7` 61 to 70, `8` 71 to 80, `9` over 80.", "example": "5" }, "legalRepresentative": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF of the representative: in full when the record was refreshed in real time, otherwise partly masked as published in the monthly data (`***123456**`).", "example": "***123456**" }, "name": { "type": "string", "description": "Name of the representative.", "example": "JOAO PEREIRA DA SILVA" }, "qualification": { "type": "string", "description": "Qualification code of the representative, from Receita Federal's qualification table.", "example": "17" } }, "description": "The partner's legal representative, when it has one." } }, "required": [ "documentType" ], "description": "A partner or shareholder of the company." }, "description": "Partners and shareholders of the company, sorted by name." }, "simples": { "type": "object", "properties": { "optIn": { "type": "boolean", "description": "Whether the company is currently opted in.", "example": true }, "optInDate": { "type": "string", "format": "date-time", "description": "When the company opted in.", "example": "2016-01-01T00:00:00.000Z" }, "optOutDate": { "type": "string", "format": "date-time", "description": "When the company opted out, if it did.", "example": "2020-12-31T00:00:00.000Z" } }, "required": [ "optIn" ], "description": "Whether the company opted into the Simples Nacional tax regime." }, "mei": { "type": "object", "properties": { "optIn": { "type": "boolean", "description": "Whether the company is currently opted in.", "example": true }, "optInDate": { "type": "string", "format": "date-time", "description": "When the company opted in.", "example": "2016-01-01T00:00:00.000Z" }, "optOutDate": { "type": "string", "format": "date-time", "description": "When the company opted out, if it did.", "example": "2020-12-31T00:00:00.000Z" } }, "required": [ "optIn" ], "description": "Whether the company is registered as an individual microentrepreneur (MEI)." }, "refDate": { "type": "string", "description": "Month of the registry data this record reflects, as `YYYY-MM`: the monthly release that last updated it, or the month it was refreshed in real time.", "example": "2026-08" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this record was first added to the registry.", "example": "2026-07-14T09:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this record last changed.", "example": "2026-08-18T09:00:00.000Z" } }, "required": [ "_id", "document", "companyDocument", "branchNumber", "branchType", "status", "refDate" ], "description": "One establishment (headquarters or branch) of a company, as listed by the company search." }, "description": "The establishments of this page, in CNPJ order." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page: pass it as `next` to get it. `null` on the last page.", "example": "MTEyMjIzMzMwMDAxODE" } }, "required": [ "items", "next" ], "description": "A page of establishments." } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `status`, a `legalName` shorter than 3 characters or a `limit` above 100; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "legalName", "message": "Too big: expected string to have <=120 characters", "code": "LEGALNAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/companies/{document}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdCompaniesByDocument", "summary": "Get a company by CNPJ", "tags": [ "Companies" ], "x-p3-sidebar-order": 2, "description": "Gets one establishment of Brazil's public company registry by its full CNPJ.", "x-mint": { "content": "The data is Brazil's public company registry. Most of it comes from Receita Federal's monthly open data; when the stored record is missing, out of date or has no partners, it may be refreshed from the registry in real time before the answer is sent, so a company opened after the last monthly release can be found too. `refDate` is the month of the registry data the record reflects. The data is the same for every organization — nothing in it belongs to yours.\n\nBesides the registry's codes, the answer carries the text of two of them: `statusReasonDescription` and `legalNatureDescription`. A document that is not a valid CNPJ is answered as not found, like one the registry doesn't have." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization making the request.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "document", "in": "path", "required": true, "description": "CNPJ of the establishment: 14 characters, the first 12 digits or letters and the last 2 digits. Dots, dashes and spaces are ignored. A path can't carry the `/` of a formatted CNPJ, so send the 14 characters alone or the mask without the slash.", "schema": { "type": "string" }, "example": "11222333000181" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "description": "Same value as `document`.", "example": "11222333000181" }, "document": { "type": "string", "description": "CNPJ of the establishment: 14 characters (the first 12 digits or letters, the last 2 digits), without formatting.", "example": "11222333000181" }, "companyDocument": { "type": "string", "description": "The first 8 characters of the CNPJ, which identify the company: every establishment of one company shares them.", "example": "11222333" }, "branchNumber": { "type": "string", "description": "The 4 characters after the company's 8: `0001` is the headquarters.", "example": "0001" }, "branchType": { "type": "string", "enum": [ "HEADQUARTERS", "BRANCH" ], "description": "`HEADQUARTERS` or `BRANCH`.", "example": "HEADQUARTERS" }, "tradingName": { "type": "string", "description": "Trade name of the establishment.", "example": "EXEMPLO MERCADO" }, "status": { "type": "string", "enum": [ "ANNULLED", "ACTIVE", "ACTIVE_IRREGULAR", "SUSPENDED", "INAPT", "CLOSED" ], "description": "Registration status: `ACTIVE`, `ACTIVE_IRREGULAR` (operating, with a pending irregularity at Receita Federal), `SUSPENDED`, `INAPT` (ineligible), `CLOSED` (deregistered) or `ANNULLED`.", "example": "ACTIVE" }, "statusDate": { "type": "string", "format": "date-time", "description": "When the registration status last changed.", "example": "2015-03-12T00:00:00.000Z" }, "statusReason": { "type": "string", "description": "Code of the reason for the registration status, from Receita Federal's table. The company read adds its text as `statusReasonDescription`.", "example": "00" }, "specialStatus": { "type": "string", "description": "Special situation of the company, as published by Receita Federal.", "example": "RECUPERACAO JUDICIAL" }, "specialStatusDate": { "type": "string", "format": "date-time", "description": "When the special situation began.", "example": "2022-06-01T00:00:00.000Z" }, "foundingDate": { "type": "string", "format": "date-time", "description": "When the establishment started its activities.", "example": "2015-03-12T00:00:00.000Z" }, "mainActivity": { "type": "string", "description": "Main economic activity: a 7-digit CNAE code.", "example": "4712100" }, "secondaryActivities": { "type": "array", "items": { "type": "string", "example": "4721102" }, "description": "Secondary economic activities: 7-digit CNAE codes.\n\n---\n\nExample: `[\"4721102\",\"4722901\"]`" }, "email": { "type": "string", "description": "E-mail address of the establishment, in lower case.", "example": "contato@exemplo.com.br" }, "phoneNumber": { "type": "string", "description": "Main phone number, in international format (`+` followed by digits). Absent when the published number can't be converted to it.", "example": "+551133334444" }, "secondaryPhoneNumber": { "type": "string", "description": "Secondary phone number, in international format.", "example": "+551155556666" }, "fax": { "type": "string", "description": "Fax number, in international format.", "example": "+551177778888" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street, with its type (such as `RUA` or `AVENIDA`).", "example": "AVENIDA PAULISTA" }, "number": { "type": "string", "description": "Street number.", "example": "1578" }, "complement": { "type": "string", "description": "Extra address detail.", "example": "ANDAR 3" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "BELA VISTA" }, "city": { "type": "string", "description": "City name.", "example": "SAO PAULO" }, "cityCode": { "type": "string", "description": "Code of the city in Receita Federal's municipality table.", "example": "7107" }, "state": { "type": "string", "description": "Two-letter code of the Brazilian state.", "example": "SP" }, "postalCode": { "type": "string", "description": "Postal code (CEP), 8 digits.", "example": "01310200" } }, "description": "Address of the establishment." }, "foreignCity": { "type": "string", "description": "City of an establishment based abroad.", "example": "LISBOA" }, "country": { "type": "string", "description": "Country of an establishment based abroad, as a two-letter ISO 3166-1 code. Absent when the published country has no single ISO equivalent; `countryCode` keeps the published value.", "example": "PT" }, "countryCode": { "type": "string", "description": "Country code of an establishment based abroad, as published by Receita Federal (a 3-digit code of its own country table).", "example": "607" }, "legalName": { "type": "string", "description": "Legal name (razão social) of the company.", "example": "EXEMPLO COMERCIO DE ALIMENTOS LTDA" }, "legalNature": { "type": "string", "description": "Legal nature of the company: a 4-digit code from Receita Federal's table. The company read adds its text as `legalNatureDescription`.", "example": "2062" }, "size": { "type": "string", "enum": [ "NOT_INFORMED", "MICRO", "SMALL", "OTHER" ], "description": "Size of the company: `MICRO`, `SMALL`, `OTHER` (any larger) or `NOT_INFORMED`.", "example": "SMALL" }, "capital": { "type": "number", "description": "Share capital, in cents of BRL.", "example": 50000000 }, "responsibleQualification": { "type": "string", "description": "Qualification code of the person responsible for the company, from Receita Federal's qualification table.", "example": "49" }, "federativeEntity": { "type": "string", "description": "Federative entity responsible for the company. Only public bodies have one.", "example": "UNIAO" }, "shareholders": { "type": "array", "items": { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "CNPJ", "CPF", "FOREIGN" ], "description": "Kind of partner: `CNPJ` for a company, `CPF` for a person or `FOREIGN` for a foreign partner.", "example": "CPF" }, "name": { "type": "string", "description": "Name of the partner.", "example": "MARIA DA SILVA" }, "document": { "type": "string", "description": "Document of the partner: a CNPJ, or a CPF — in full when the record was refreshed in real time, otherwise partly masked as published in the monthly data (`***123456**`). Absent for a foreign partner.", "example": "***123456**" }, "qualification": { "type": "string", "description": "Qualification code of the partner, from Receita Federal's qualification table (`49` is partner-administrator, `22` partner).", "example": "49" }, "joinedAt": { "type": "string", "format": "date-time", "description": "When the partner joined the company.", "example": "2015-03-12T00:00:00.000Z" }, "country": { "type": "string", "description": "Country of a foreign partner, as a two-letter ISO 3166-1 code. Absent when the published country has no single ISO equivalent; `countryCode` keeps the published value.", "example": "US" }, "countryCode": { "type": "string", "description": "Country code of a foreign partner, as published by Receita Federal (a 3-digit code of its own country table).", "example": "249" }, "ageRange": { "type": "string", "description": "Age range of a person partner, as the code published by Receita Federal: `0` not applicable, `1` up to 12 years, `2` 13 to 20, `3` 21 to 30, `4` 31 to 40, `5` 41 to 50, `6` 51 to 60, `7` 61 to 70, `8` 71 to 80, `9` over 80.", "example": "5" }, "legalRepresentative": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF of the representative: in full when the record was refreshed in real time, otherwise partly masked as published in the monthly data (`***123456**`).", "example": "***123456**" }, "name": { "type": "string", "description": "Name of the representative.", "example": "JOAO PEREIRA DA SILVA" }, "qualification": { "type": "string", "description": "Qualification code of the representative, from Receita Federal's qualification table.", "example": "17" } }, "description": "The partner's legal representative, when it has one." } }, "required": [ "documentType" ], "description": "A partner or shareholder of the company." }, "description": "Partners and shareholders of the company, sorted by name." }, "simples": { "type": "object", "properties": { "optIn": { "type": "boolean", "description": "Whether the company is currently opted in.", "example": true }, "optInDate": { "type": "string", "format": "date-time", "description": "When the company opted in.", "example": "2016-01-01T00:00:00.000Z" }, "optOutDate": { "type": "string", "format": "date-time", "description": "When the company opted out, if it did.", "example": "2020-12-31T00:00:00.000Z" } }, "required": [ "optIn" ], "description": "Whether the company opted into the Simples Nacional tax regime." }, "mei": { "type": "object", "properties": { "optIn": { "type": "boolean", "description": "Whether the company is currently opted in.", "example": true }, "optInDate": { "type": "string", "format": "date-time", "description": "When the company opted in.", "example": "2016-01-01T00:00:00.000Z" }, "optOutDate": { "type": "string", "format": "date-time", "description": "When the company opted out, if it did.", "example": "2020-12-31T00:00:00.000Z" } }, "required": [ "optIn" ], "description": "Whether the company is registered as an individual microentrepreneur (MEI)." }, "refDate": { "type": "string", "description": "Month of the registry data this record reflects, as `YYYY-MM`: the monthly release that last updated it, or the month it was refreshed in real time.", "example": "2026-08" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this record was first added to the registry.", "example": "2026-07-14T09:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this record last changed.", "example": "2026-08-18T09:00:00.000Z" }, "statusReasonDescription": { "type": "string", "description": "Text of `statusReason`.", "example": "SEM MOTIVO" }, "legalNatureDescription": { "type": "string", "description": "Text of `legalNature`.", "example": "Sociedade Empresária Limitada" } }, "required": [ "_id", "branchNumber", "branchType", "companyDocument", "document", "refDate", "status" ], "description": "One establishment of a company, with the text of its coded fields." } } } }, "404": { "description": "`COMPANY_NOT_FOUND` — The registry has no establishment with this CNPJ, or the document is not a valid CNPJ.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "COMPANY_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "COMPANY_NOT_FOUND", "origin": "REGISTRY", "message": "Company not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`COMPANY_LOOKUP_UNAVAILABLE` — The establishment is not stored yet and the real-time registry could not be reached. Try again later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "COMPANY_LOOKUP_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "COMPANY_LOOKUP_UNAVAILABLE", "origin": "REGISTRY", "message": "Company lookup unavailable" } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/people/{document}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdPeopleByDocument", "summary": "Get a person by CPF", "tags": [ "People" ], "x-p3-sidebar-order": 1, "description": "Gets a person by CPF.", "x-mint": { "content": "The data comes from Brazil's public registries, looked up in real time: a person read in the last 7 days is answered from the registry's copy, otherwise it is looked up again before the answer is sent. It is the same for every organization — nothing in it belongs to yours.\n\nA document that is not a valid CPF is answered as not found, like one the registry doesn't have. When the source refuses to answer for a CPF, the answer is `PERSON_LOOKUP_RESTRICTED`, without a reason." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization making the request.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "document", "in": "path", "required": true, "description": "CPF of the person: 11 digits. Dots, dashes and spaces are ignored.", "schema": { "type": "string" }, "example": "52998224725" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "type": "string", "description": "CPF of the person, 11 digits.", "example": "52998224725" }, "name": { "type": "string", "description": "Full name.", "example": "MARIA EXEMPLO DA SILVA" }, "socialName": { "type": "string", "description": "Social name, when the person registered one.", "example": "MARIA EXEMPLO" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE" ], "description": "`MALE` or `FEMALE`.", "example": "FEMALE" }, "birthDate": { "type": "string", "format": "date-time", "description": "Date of birth.", "example": "1984-09-17T00:00:00.000Z" }, "nationality": { "type": "string", "description": "Nationality, as published.", "example": "BRASILEIRA" }, "motherName": { "type": "string", "description": "Mother's name.", "example": "ANA EXEMPLO DA SILVA" }, "fatherName": { "type": "string", "description": "Father's name.", "example": "JOSE EXEMPLO DA SILVA" }, "maritalStatus": { "type": "string", "description": "Marital status, as published.", "example": "CASADO" }, "maritalStatusUpdatedAt": { "type": "string", "format": "date-time", "description": "When the marital status was last updated at the source.", "example": "2019-05-02T00:00:00.000Z" }, "taxIdStatus": { "type": "string", "enum": [ "REGULAR", "PENDING_REGULARIZATION", "SUSPENDED", "CANCELED", "ANNULLED", "HOLDER_DECEASED", "INCOMPLETE_DATA" ], "description": "Status of the CPF at Receita Federal: `REGULAR`, `PENDING_REGULARIZATION`, `SUSPENDED`, `CANCELED`, `ANNULLED`, `HOLDER_DECEASED` or `INCOMPLETE_DATA`.", "example": "REGULAR" }, "taxIdStatusDate": { "type": "string", "format": "date-time", "description": "When the CPF status was last checked at Receita Federal.", "example": "2026-10-01T00:00:00.000Z" }, "taxIdRegistrationDate": { "type": "string", "format": "date-time", "description": "When the CPF was registered.", "example": "2001-03-15T00:00:00.000Z" }, "taxIdFiscalRegion": { "type": "string", "description": "Receita Federal fiscal region of the CPF.", "example": "SP" }, "deceased": { "type": "boolean", "description": "Whether there is a record of the person's death.", "example": false }, "deathYear": { "type": "string", "description": "Year of death, when `deceased` is true.", "example": "2021" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this person was first added to the registry.", "example": "2026-10-29T15:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this record last changed.", "example": "2026-10-29T15:00:00.000Z" } }, "required": [ "document" ], "description": "A person, by CPF. Text comes in upper case, as the registry publishes it." } } } }, "404": { "description": "`PERSON_NOT_FOUND` — The registry has no person with this CPF, or the document is not a valid CPF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PERSON_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PERSON_NOT_FOUND", "origin": "REGISTRY", "message": "Person not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid; `fields` lists each one.\n\n`PERSON_LOOKUP_RESTRICTED` — The source refuses to answer for this CPF.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "PERSON_LOOKUP_RESTRICTED" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "organizationId", "message": "Invalid UUID", "code": "ORGANIZATIONID_UUID" } ] } } } }, "503": { "description": "`PERSON_LOOKUP_UNAVAILABLE` — The person is not stored yet and the registry could not be reached. Try again later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PERSON_LOOKUP_UNAVAILABLE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PERSON_LOOKUP_UNAVAILABLE", "origin": "REGISTRY", "message": "Person lookup unavailable" } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/products": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdProducts", "summary": "List products", "tags": [ "Products" ], "x-p3-sidebar-order": 1, "description": "Lists the organization's products and services, newest first.", "x-mint": { "content": "Any member of the organization can list products. Narrow the list with `name`, `skuCode`, `status`, `type` and a creation date range (`startDate`, `endDate`), sort it with `orderBy` and `order`, and page through it with `limit` and `next`: each page answers the cursor of the following one as `next`, which is `null` on the last page.\n\n`name` matches the products whose name or SKU code contains the text, ignoring case, while `skuCode` and `type` match by contained text too. The date range is on the creation date and both ends are inclusive; a date with no time means 00:00 UTC of that day." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose products you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "name", "in": "query", "required": false, "description": "Only products whose name or SKU code contains this text (case-insensitive).", "schema": { "type": "string", "minLength": 1, "maxLength": 56 }, "example": "consultoria" }, { "name": "skuCode", "in": "query", "required": false, "description": "Only products whose SKU code contains this text (case-insensitive).", "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "example": "CONS-LOG" }, { "name": "status", "in": "query", "required": false, "description": "Only products in this status.", "schema": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] }, "example": "ACTIVE" }, { "name": "type", "in": "query", "required": false, "description": "Only products whose type contains this text (case-insensitive): `PRODUCT` or `SERVICE`.", "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "example": "SERVICE" }, { "name": "startDate", "in": "query", "required": false, "description": "Only products created at or after this moment, in ISO 8601. A date with no time means 00:00 UTC of that day. It can't be after `endDate`.", "schema": { "type": "string" }, "example": "2026-10-01T00:00:00.000Z" }, { "name": "endDate", "in": "query", "required": false, "description": "Only products created at or before this moment, in ISO 8601. A date with no time means 00:00 UTC of that day, so `2026-10-31` leaves out products created later on the 31st: send `2026-10-31T23:59:59.999Z` to include the whole day.", "schema": { "type": "string" }, "example": "2026-10-31T23:59:59.999Z" }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 15.", "schema": { "default": 15, "type": "integer" }, "example": 15 }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit it for the first page.", "schema": { "type": "string" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction. Defaults to `DESC`: newest first when sorting by `createdAt`.", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by. Defaults to `createdAt`.", "schema": { "default": "createdAt", "type": "string", "enum": [ "name", "value", "createdAt" ] }, "example": "createdAt" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product.", "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" }, "realmId": { "type": "string", "description": "ID of the realm the product belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the product belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the product or service.", "example": "Consultoria em logística" }, "description": { "type": "string", "description": "Free-text description. Empty when none was given.", "example": "Hora técnica de consultoria em logística e roteirização." }, "value": { "type": "number", "description": "Price in centavos: `15000` is R$ 150,00.", "example": 15000 }, "skuCode": { "type": "string", "nullable": true, "description": "Your own stock-keeping code. Absent, or `null`, when none was given.", "example": "CONS-LOG-001" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text a client stored is kept as sent.", "example": "SERVICE" }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the product was retired.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the product was created.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the product was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "description", "value", "type", "status" ], "description": "A product or service of the organization's catalog." }, "description": "Products, in the order you asked for (newest first by default)." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of products." } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as a `startDate` that is not a date or comes after `endDate`; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "Too big: expected string to have <=56 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.refine(…)` constraint not represented (runtime-dependent value); `.transform(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdProducts", "summary": "Create a product", "tags": [ "Products" ], "x-p3-sidebar-order": 2, "description": "Creates a product or service in the organization's catalog.", "x-mint": { "content": "Any member of the organization can create products. The product is always created `ACTIVE`, whatever `status` you send. `value` is the price in centavos, so `15000` is R$ 150,00, and must be greater than zero. `type` is `PRODUCT` for a physical good or `SERVICE` for a service. Answers the product that was created, with its new `id`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose catalog the product joins.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 56, "description": "Name of the product or service, 2 to 56 characters.", "example": "Consultoria em logística" }, "description": { "description": "Free-text description, up to 250 characters.", "example": "Hora técnica de consultoria em logística e roteirização.", "type": "string", "maxLength": 250 }, "value": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Price in centavos: `15000` is R$ 150,00. Must be greater than zero.", "example": 15000 }, "skuCode": { "description": "Your own stock-keeping code for the product. Free text; the `name` and `skuCode` list filters search it.", "example": "CONS-LOG-001", "type": "string" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text is stored as sent, and the exports show it as a service.", "example": "SERVICE" }, "status": { "description": "Accepted but ignored: a new product is always created `ACTIVE`. To retire a product, deactivate it.", "example": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] } }, "required": [ "name", "value", "type" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product.", "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" }, "realmId": { "type": "string", "description": "ID of the realm the product belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the product belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the product or service.", "example": "Consultoria em logística" }, "description": { "type": "string", "description": "Free-text description. Empty when none was given.", "example": "Hora técnica de consultoria em logística e roteirização." }, "value": { "type": "number", "description": "Price in centavos: `15000` is R$ 150,00.", "example": 15000 }, "skuCode": { "type": "string", "nullable": true, "description": "Your own stock-keeping code. Absent, or `null`, when none was given.", "example": "CONS-LOG-001" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text a client stored is kept as sent.", "example": "SERVICE" }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the product was retired.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the product was created.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the product was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "description", "value", "type", "status" ], "description": "A product or service of the organization's catalog." } } } }, "422": { "description": "`BAD_REQUEST` — The body is invalid, such as a missing `name`, `value` or `type`, a `name` outside 2 to 56 characters or a `value` that is not greater than zero; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/products/report": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdProductsReport", "summary": "Export products", "tags": [ "Products" ], "x-p3-sidebar-order": 3, "description": "Exports the organization's products as a CSV or XLSX file.", "x-mint": { "content": "Any member of the organization can export. Choose the file format with the required `type` query parameter: `?type=csv` answers a UTF-8 CSV file, `?type=xlsx` an Excel workbook returned base64-encoded. The file lists every product of the organization, with no filters, and has one row per product with its name, description, value, SKU code, type, status and creation and last update dates. The headers and the type and status values are in Portuguese (`Produto` or `Serviço`, `Ativo` or `Desativado`). The `Valor` column is the price in reais, not in centavos like the `value` of the API, written the Brazilian way as text: a product whose `value` is `2500` shows `25,00` and one whose `value` is `150000` shows `1.500,00`. The dates are `DD/MM/YYYY HH:mm` in Brasília time. An organization with no products gets a file with the header row and one blank row, whose `Valor` reads `0,00`.\n\nThe file is sent as an attachment named `products-report-.csv` or `.xlsx`. A file of more than 50,000 rows or 4 MiB is refused." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose products you want to export.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "type", "in": "query", "required": true, "description": "The file format: `csv` for a UTF-8 CSV file, `xlsx` for an Excel workbook returned base64-encoded.", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "example": "csv" } ], "responses": { "200": { "description": "`application/csv` — The products as a UTF-8 CSV file, when `?type=csv`.\n\n`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — The Excel workbook, base64-encoded, when `?type=xlsx`. It is always base64: this export has no switch for raw bytes.", "content": { "application/csv": { "schema": { "type": "string", "description": "The products as a UTF-8 CSV file, when `?type=csv`." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "byte", "description": "The Excel workbook, base64-encoded, when `?type=xlsx`. It is always base64: this export has no switch for raw bytes." } } } }, "400": { "description": "`INVALID_TYPE` — The `type` query parameter is missing or is neither `csv` nor `xlsx`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "INVALID_TYPE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "INVALID_TYPE", "origin": "REGISTRY", "message": "Invalid type" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is invalid; `fields` lists each one.\n\n`EXPORT_TOO_LARGE` — The catalog is too big for one file: more than 50,000 products, or a file over 4 MiB. The export has no filters to narrow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "EXPORT_TOO_LARGE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "type", "message": "Invalid option: expected one of \"csv\"|\"xlsx\"", "code": "TYPE_ONE_OF", "values": [ "csv", "xlsx" ] } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/products/{productId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdProductsByProductId", "summary": "Get a product", "tags": [ "Products" ], "x-p3-sidebar-order": 4, "description": "Gets one product of the organization's catalog.", "x-mint": { "content": "Any member of the organization can read a product. A product that belongs to another organization is not found." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the product belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "productId", "in": "path", "required": true, "description": "ID of the product (`id` in the product list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product.", "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" }, "realmId": { "type": "string", "description": "ID of the realm the product belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the product belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the product or service.", "example": "Consultoria em logística" }, "description": { "type": "string", "description": "Free-text description. Empty when none was given.", "example": "Hora técnica de consultoria em logística e roteirização." }, "value": { "type": "number", "description": "Price in centavos: `15000` is R$ 150,00.", "example": 15000 }, "skuCode": { "type": "string", "nullable": true, "description": "Your own stock-keeping code. Absent, or `null`, when none was given.", "example": "CONS-LOG-001" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text a client stored is kept as sent.", "example": "SERVICE" }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the product was retired.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the product was created.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the product was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "description", "value", "type", "status" ], "description": "A product or service of the organization's catalog." } } } }, "404": { "description": "`PRODUCT_NOT_FOUND` — No product with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_NOT_FOUND", "origin": "REGISTRY", "message": "Product not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `productId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "productId", "message": "Invalid UUID", "code": "PRODUCTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdProductsByProductId", "summary": "Update a product", "tags": [ "Products" ], "x-p3-sidebar-order": 5, "description": "Updates a product.", "x-mint": { "content": "Any member of the organization can update a product. Send only the fields you want to change: the ones you omit keep their current value. `value` is the price in centavos, so `15000` is R$ 150,00. Answers the product as it is after the change.\n\n`status` changes the product's status too: `ACTIVE` brings a deactivated product back, and `DEACTIVATED` retires an active one. A product that still has active payment links can't be deactivated: end those links first. Setting a status the product already has changes nothing." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the product belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "productId", "in": "path", "required": true, "description": "ID of the product (`id` in the product list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name, 2 to 56 characters. Omit it to keep the current one.", "example": "Consultoria em logística", "type": "string", "minLength": 2, "maxLength": 56 }, "description": { "description": "New description, up to 250 characters. Omit it to keep the current one; send an empty string to clear it.", "example": "Hora técnica de consultoria em logística e roteirização.", "type": "string", "maxLength": 250 }, "value": { "description": "New price in centavos: `15000` is R$ 150,00. Must be greater than zero. Omit it to keep the current one.", "example": 15000, "type": "number", "minimum": 0, "exclusiveMinimum": true }, "skuCode": { "description": "New stock-keeping code. Omit it to keep the current one.", "example": "CONS-LOG-001", "type": "string" }, "type": { "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text is stored as sent, and the exports show it as a service. Omit it to keep the current one.", "example": "SERVICE", "type": "string" }, "status": { "description": "`ACTIVE` or `DEACTIVATED`. Omit it to keep the current status. Setting `DEACTIVATED` on an active product is refused while it still has active payment links.", "example": "DEACTIVATED", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product.", "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" }, "realmId": { "type": "string", "description": "ID of the realm the product belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the product belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the product or service.", "example": "Consultoria em logística" }, "description": { "type": "string", "description": "Free-text description. Empty when none was given.", "example": "Hora técnica de consultoria em logística e roteirização." }, "value": { "type": "number", "description": "Price in centavos: `15000` is R$ 150,00.", "example": 15000 }, "skuCode": { "type": "string", "nullable": true, "description": "Your own stock-keeping code. Absent, or `null`, when none was given.", "example": "CONS-LOG-001" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text a client stored is kept as sent.", "example": "SERVICE" }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the product was retired.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the product was created.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the product was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "description", "value", "type", "status" ], "description": "A product or service of the organization's catalog." } } } }, "400": { "description": "`PRODUCT_HAS_ACTIVE_PAYMENT_LINKS` — You set `status` to `DEACTIVATED` on an active product that still has active payment links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_HAS_ACTIVE_PAYMENT_LINKS" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_HAS_ACTIVE_PAYMENT_LINKS", "origin": "REGISTRY", "message": "Product has active payment links" } } } }, "404": { "description": "`PRODUCT_NOT_FOUND` — No product with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_NOT_FOUND", "origin": "REGISTRY", "message": "Product not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter or a body field is invalid, such as a `productId` that is not a UUID or a `value` that is not greater than zero; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "Too big: expected string to have <=56 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/products/{productId}/activate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdProductsByProductIdActivate", "summary": "Activate a product", "tags": [ "Products" ], "x-p3-sidebar-order": 6, "description": "Sets a product's `status` to `ACTIVE`.", "x-mint": { "content": "Only organization admins can activate a product, and only a `DEACTIVATED` one: activating a product that is already `ACTIVE` is rejected. To retire a product, use `POST /realms/{realmId}/organizations/{organizationId}/products/{productId}/deactivate`.\n\nAnswers the product as it is after the change. The request has no body: if your HTTP client sends `Content-Type: application/json`, send `{}`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the product belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "productId", "in": "path", "required": true, "description": "ID of the product (`id` in the product list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product.", "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" }, "realmId": { "type": "string", "description": "ID of the realm the product belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the product belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the product or service.", "example": "Consultoria em logística" }, "description": { "type": "string", "description": "Free-text description. Empty when none was given.", "example": "Hora técnica de consultoria em logística e roteirização." }, "value": { "type": "number", "description": "Price in centavos: `15000` is R$ 150,00.", "example": 15000 }, "skuCode": { "type": "string", "nullable": true, "description": "Your own stock-keeping code. Absent, or `null`, when none was given.", "example": "CONS-LOG-001" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text a client stored is kept as sent.", "example": "SERVICE" }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the product was retired.", "example": "ACTIVE" }, "createdAt": { "type": "string", "description": "When the product was created.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the product was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "description", "value", "type", "status" ], "description": "A product or service of the organization's catalog." } } } }, "400": { "description": "`PRODUCT_INVALID_STATUS_FOR_ACTIVATION` — The product is already `ACTIVE`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_INVALID_STATUS_FOR_ACTIVATION" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_INVALID_STATUS_FOR_ACTIVATION", "origin": "REGISTRY", "message": "Product is already active" } } } }, "403": { "description": "`FORBIDDEN_PRODUCT` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_PRODUCT" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_PRODUCT", "origin": "REGISTRY", "message": "Forbidden" } } } }, "404": { "description": "`PRODUCT_NOT_FOUND` — No product with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_NOT_FOUND", "origin": "REGISTRY", "message": "Product not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `productId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "productId", "message": "Invalid UUID", "code": "PRODUCTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/products/{productId}/deactivate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdProductsByProductIdDeactivate", "summary": "Deactivate a product", "tags": [ "Products" ], "x-p3-sidebar-order": 7, "description": "Sets a product's `status` to `DEACTIVATED`.", "x-mint": { "content": "Only organization admins can deactivate a product, and only an `ACTIVE` one: deactivating a product that is already `DEACTIVATED` is rejected. A product that still has active payment links can't be deactivated: end those links first. This is how a product is retired, since products can't be deleted. To bring one back, use `POST /realms/{realmId}/organizations/{organizationId}/products/{productId}/activate`.\n\nAnswers the product as it is after the change. The request has no body: if your HTTP client sends `Content-Type: application/json`, send `{}`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the product belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "productId", "in": "path", "required": true, "description": "ID of the product (`id` in the product list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product.", "example": "9b2f6c1e-3d4a-4f7b-8e21-5a6c7d8e9f01" }, "realmId": { "type": "string", "description": "ID of the realm the product belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organizationId": { "type": "string", "description": "ID of the organization the product belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the product or service.", "example": "Consultoria em logística" }, "description": { "type": "string", "description": "Free-text description. Empty when none was given.", "example": "Hora técnica de consultoria em logística e roteirização." }, "value": { "type": "number", "description": "Price in centavos: `15000` is R$ 150,00.", "example": 15000 }, "skuCode": { "type": "string", "nullable": true, "description": "Your own stock-keeping code. Absent, or `null`, when none was given.", "example": "CONS-LOG-001" }, "type": { "type": "string", "description": "`PRODUCT` for a physical good or `SERVICE` for a service. Any other text a client stored is kept as sent.", "example": "SERVICE" }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the product was retired.", "example": "DEACTIVATED" }, "createdAt": { "type": "string", "description": "When the product was created.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the product was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realmId", "organizationId", "name", "description", "value", "type", "status" ], "description": "A product or service of the organization's catalog." } } } }, "400": { "description": "`PRODUCT_INVALID_STATUS_FOR_DEACTIVATION` — The product is already `DEACTIVATED`.\n\n`PRODUCT_HAS_ACTIVE_PAYMENT_LINKS` — The product still has active payment links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_INVALID_STATUS_FOR_DEACTIVATION", "PRODUCT_HAS_ACTIVE_PAYMENT_LINKS" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_INVALID_STATUS_FOR_DEACTIVATION", "origin": "REGISTRY", "message": "Product is already deactivated" } } } }, "403": { "description": "`FORBIDDEN_PRODUCT` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_PRODUCT" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_PRODUCT", "origin": "REGISTRY", "message": "Forbidden" } } } }, "404": { "description": "`PRODUCT_NOT_FOUND` — No product with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "PRODUCT_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "PRODUCT_NOT_FOUND", "origin": "REGISTRY", "message": "Product not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `productId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "productId", "message": "Invalid UUID", "code": "PRODUCTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/suppliers": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdSuppliers", "summary": "List suppliers", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 1, "description": "Lists the organization's suppliers, newest first.", "x-mint": { "content": "Only organization admins can list suppliers. Narrow the list with `name`, `document` and `status`, sort it with `orderBy` and `order`, and page through it with `limit` (25 by default) and `next`: each page answers the cursor of the following one as `next`, which is `null` on the last page.\n\n`name` matches the suppliers whose name or trade name contains the text, ignoring case, and `document` those whose document contains the characters. `status` is an exact match." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose suppliers you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "name", "in": "query", "required": false, "description": "Only suppliers whose name or trade name contains this text (case-insensitive).", "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "example": "boa viagem" }, { "name": "document", "in": "query", "required": false, "description": "Only suppliers whose document contains these letters and digits (case-insensitive). Send it with no dots, slashes or hyphens.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]+$" }, "example": "112223" }, { "name": "status", "in": "query", "required": false, "description": "Only suppliers in this status.", "schema": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] }, "example": "ACTIVE" }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 25.", "schema": { "default": 25, "type": "integer" }, "example": 25 }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit it for the first page.", "schema": { "type": "string" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction. Defaults to `DESC`: newest first when sorting by `createdAt`.", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field to sort by. Defaults to `createdAt`.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "updatedAt", "name", "tradingName", "document" ] }, "example": "createdAt" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the supplier.", "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" }, "realm": { "type": "string", "description": "ID of the realm the supplier belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the supplier belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the supplier.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "type": "string", "description": "Trade name of the supplier. Absent when none was given.", "example": "Boa Viagem Transportes" }, "document": { "type": "string", "description": "CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company.", "example": "CNPJ" }, "email": { "type": "string", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the supplier in international format.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number.", "example": "100" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "state": { "type": "string", "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "description": "Postal code (CEP) as `00000-000`.", "example": "38400-000" }, "complement": { "type": "string", "description": "Complement such as a suite or a floor. Absent when none was given.", "example": "Sala 2" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the supplier was deactivated.", "example": "ACTIVE" }, "pixKey": { "type": "string", "description": "PIX key to pay the supplier. Absent when none was given.", "example": "financeiro@boaviagem.example.com" }, "pixKeyType": { "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ], "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Absent when there is no PIX key.", "example": "EMAIL" }, "createdBy": { "type": "string", "description": "ID of the user who registered the supplier.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the supplier was registered.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the supplier was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "name", "document", "documentType", "email", "phoneNumber", "status" ], "description": "A supplier of the organization: someone you pay." }, "description": "Suppliers, in the order you asked for (newest first by default)." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of suppliers." } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `status` or `orderBy`; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "Too big: expected string to have <=50 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed", "note": "`.transform(…)` constraint not represented (runtime-dependent value)" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdSuppliers", "summary": "Create a supplier", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 2, "description": "Registers a supplier in the organization.", "x-mint": { "content": "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`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the supplier is registered in.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the supplier, up to 100 characters.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "description": "Trade name of the supplier, up to 100 characters.", "example": "Boa Viagem Transportes", "type": "string", "maxLength": 100 }, "document": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$", "description": "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.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company. It must match `document`.", "example": "CNPJ" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "pattern": "^\\+55[0-9]{10,11}$", "description": "Phone number of the supplier in international format: `+55`, the area code and the number, with no spaces or punctuation.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "maxLength": 100, "description": "Street name, up to 100 characters.", "example": "Rua das Flores" }, "number": { "type": "string", "maxLength": 20, "description": "Street number, up to 20 characters.", "example": "100" }, "neighborhood": { "type": "string", "maxLength": 100, "description": "Neighborhood, up to 100 characters.", "example": "Centro" }, "city": { "type": "string", "maxLength": 50, "description": "City, up to 50 characters.", "example": "Uberlândia" }, "state": { "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO", "DF" ], "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "pattern": "^\\d{5}-\\d{3}$", "description": "Postal code (CEP) as `00000-000`, with the hyphen.", "example": "38400-000" }, "complement": { "description": "Complement such as a suite or a floor, up to 50 characters.", "example": "Sala 2", "type": "string", "maxLength": 50 } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "pixKey": { "description": "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.", "example": "financeiro@boaviagem.example.com", "type": "string", "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}$" }, "pixKeyType": { "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Required when you send `pixKey`, and not allowed without it.", "example": "EMAIL", "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ] } }, "required": [ "name", "document", "documentType", "email", "phoneNumber", "address" ] } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the supplier.", "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" }, "realm": { "type": "string", "description": "ID of the realm the supplier belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the supplier belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the supplier.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "type": "string", "description": "Trade name of the supplier. Absent when none was given.", "example": "Boa Viagem Transportes" }, "document": { "type": "string", "description": "CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company.", "example": "CNPJ" }, "email": { "type": "string", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the supplier in international format.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number.", "example": "100" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "state": { "type": "string", "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "description": "Postal code (CEP) as `00000-000`.", "example": "38400-000" }, "complement": { "type": "string", "description": "Complement such as a suite or a floor. Absent when none was given.", "example": "Sala 2" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the supplier was deactivated.", "example": "ACTIVE" }, "pixKey": { "type": "string", "description": "PIX key to pay the supplier. Absent when none was given.", "example": "financeiro@boaviagem.example.com" }, "pixKeyType": { "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ], "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Absent when there is no PIX key.", "example": "EMAIL" }, "createdBy": { "type": "string", "description": "ID of the user who registered the supplier.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the supplier was registered.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the supplier was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "name", "document", "documentType", "email", "phoneNumber", "status" ], "description": "A supplier of the organization: someone you pay." } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "409": { "description": "`SUPPLIER_CONFLICT` — The organization already has a supplier with this `document`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SUPPLIER_CONFLICT" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SUPPLIER_CONFLICT", "origin": "REGISTRY", "message": "Supplier already exists with this document in this real/company/document" } } } }, "422": { "description": "`BAD_REQUEST` — The body is invalid, such as a document that is not a valid CPF or CNPJ, a `documentType` that does not match it, a phone number outside the `+55` format or a `pixKey` without its `pixKeyType`; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/suppliers/suppliers/report": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdSuppliersSuppliersReport", "summary": "Export suppliers", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 3, "description": "Exports the organization's suppliers as a CSV or XLSX file.", "x-mint": { "content": "Only organization admins can export. Choose the file format with the required `type` query parameter: `?type=csv` answers a UTF-8 CSV file, `?type=xlsx` an Excel workbook, returned base64-encoded unless you ask for `encoding=binary`. The supplier list's filters apply here too (`name`, `document`, `status`), and `orderBy` and `order` sort the rows. The file has one row per supplier with its name, trade name, document and document type, phone, e-mail, the address in seven columns, PIX key and key type, status and creation and last update dates. The headers are in Portuguese, while the values are as the API gives them: `Tipo de Documento` is `CPF` or `CNPJ`, `Pix - Tipo` the `pixKeyType` and `Status` is `ACTIVE` or `DEACTIVATED`. The dates are `DD/MM/YYYY HH:mm` in Brasília time. A search that finds nothing gets a file with the header row and one empty row.\n\nThe file is sent as an attachment named `fornecedores_.csv` or `.xlsx`. A file of more than 50,000 rows or 4 MiB is refused." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose suppliers you want to export.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "type", "in": "query", "required": true, "description": "The file format: `csv` for a UTF-8 CSV file, `xlsx` for an Excel workbook.", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "example": "csv" }, { "name": "encoding", "in": "query", "required": false, "description": "How an `xlsx` file is returned: `base64` (the default) as base64 text, or `binary` as the raw bytes. Ignored for `csv`.", "schema": { "default": "base64", "type": "string", "enum": [ "base64", "binary" ] }, "example": "base64" }, { "name": "name", "in": "query", "required": false, "description": "Only suppliers whose name or trade name contains this text (case-insensitive).", "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "example": "boa viagem" }, { "name": "document", "in": "query", "required": false, "description": "Only suppliers whose document contains these letters and digits (case-insensitive). Send it with no dots, slashes or hyphens.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]+$" }, "example": "112223" }, { "name": "status", "in": "query", "required": false, "description": "Only suppliers in this status.", "schema": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] }, "example": "ACTIVE" }, { "name": "order", "in": "query", "required": false, "description": "Sort direction of the rows. Defaults to `DESC`: newest first when sorting by `createdAt`.", "schema": { "default": "DESC", "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "DESC" }, { "name": "orderBy", "in": "query", "required": false, "description": "Field the rows are sorted by. Defaults to `createdAt`.", "schema": { "default": "createdAt", "type": "string", "enum": [ "createdAt", "updatedAt", "name", "tradingName", "document" ] }, "example": "createdAt" } ], "responses": { "200": { "description": "`application/csv` — The suppliers as a UTF-8 CSV file, when `?type=csv`.\n\n`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` — The Excel workbook, base64-encoded, when `?type=xlsx` (the default `encoding=base64`). With `encoding=binary` the body is the raw workbook bytes instead of base64 text, but the platform returns those bytes as text, so the workbook usually can't be opened from it: prefer the default.", "content": { "application/csv": { "schema": { "type": "string", "description": "The suppliers as a UTF-8 CSV file, when `?type=csv`." } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "byte", "description": "The Excel workbook, base64-encoded, when `?type=xlsx` (the default `encoding=base64`). With `encoding=binary` the body is the raw workbook bytes instead of base64 text, but the platform returns those bytes as text, so the workbook usually can't be opened from it: prefer the default." } } } }, "400": { "description": "`INVALID_TYPE` — The `type` query parameter is missing or is neither `csv` nor `xlsx`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "INVALID_TYPE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "INVALID_TYPE", "origin": "REGISTRY", "message": "Invalid type" } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid, such as an unknown `encoding` or `status`; `fields` lists each one.\n\n`EXPORT_TOO_LARGE` — The result is too big for one file: more than 50,000 suppliers, or a file over 4 MiB. Narrow it with `name`, `document` or `status`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "EXPORT_TOO_LARGE" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "type", "message": "Invalid option: expected one of \"csv\"|\"xlsx\"", "code": "TYPE_ONE_OF", "values": [ "csv", "xlsx" ] } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/suppliers/{supplierId}": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdSuppliersBySupplierId", "summary": "Get a supplier", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 4, "description": "Gets one supplier of the organization.", "x-mint": { "content": "Only organization admins can read a supplier. A supplier that belongs to another organization is not found." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the supplier belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "supplierId", "in": "path", "required": true, "description": "ID of the supplier (`id` in the supplier list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the supplier.", "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" }, "realm": { "type": "string", "description": "ID of the realm the supplier belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the supplier belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the supplier.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "type": "string", "description": "Trade name of the supplier. Absent when none was given.", "example": "Boa Viagem Transportes" }, "document": { "type": "string", "description": "CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company.", "example": "CNPJ" }, "email": { "type": "string", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the supplier in international format.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number.", "example": "100" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "state": { "type": "string", "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "description": "Postal code (CEP) as `00000-000`.", "example": "38400-000" }, "complement": { "type": "string", "description": "Complement such as a suite or a floor. Absent when none was given.", "example": "Sala 2" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the supplier was deactivated.", "example": "ACTIVE" }, "pixKey": { "type": "string", "description": "PIX key to pay the supplier. Absent when none was given.", "example": "financeiro@boaviagem.example.com" }, "pixKeyType": { "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ], "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Absent when there is no PIX key.", "example": "EMAIL" }, "createdBy": { "type": "string", "description": "ID of the user who registered the supplier.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the supplier was registered.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the supplier was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "name", "document", "documentType", "email", "phoneNumber", "status" ], "description": "A supplier of the organization: someone you pay." } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "404": { "description": "`SUPPLIER_NOT_FOUND` — No supplier with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SUPPLIER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SUPPLIER_NOT_FOUND", "origin": "REGISTRY", "message": "Supplier not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `supplierId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "supplierId", "message": "Invalid UUID", "code": "SUPPLIERID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } }, "put": { "operationId": "putRealmsByRealmIdOrganizationsByOrganizationIdSuppliersBySupplierId", "summary": "Update a supplier", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 5, "description": "Updates a supplier.", "x-mint": { "content": "Only organization admins can update a supplier. Send only the fields you want to change: the ones you omit keep their current value, and in `address` too, so you can change the city alone. A CNPJ with letters is stored in upper case, like on creation, and a `pixKey` always comes with its `pixKeyType`. The supplier's `status` can't be changed here: use the activate and deactivate routes. Answers the supplier as it is after the change." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the supplier belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "supplierId", "in": "path", "required": true, "description": "ID of the supplier (`id` in the supplier list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "New name, up to 100 characters. Omit it to keep the current one.", "example": "Transportadora Boa Viagem Ltda", "type": "string", "minLength": 1, "maxLength": 100 }, "tradingName": { "description": "New trade name, up to 100 characters. Omit it to keep the current one.", "example": "Boa Viagem Transportes", "type": "string", "maxLength": 100 }, "document": { "description": "New CPF or CNPJ: letters and digits only, with no dots, slashes or hyphens (a CNPJ can contain letters). It must be valid and agree with `documentType`. Omit it to keep the current one.", "example": "11222333000181", "type": "string", "minLength": 1, "pattern": "^[A-Za-z0-9]+$" }, "documentType": { "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company. When you also send `document`, it must match it. Omit it to keep the current one.", "example": "CNPJ", "type": "string", "enum": [ "CPF", "CNPJ" ] }, "email": { "description": "New e-mail address. Omit it to keep the current one.", "example": "financeiro@boaviagem.example.com", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phoneNumber": { "description": "New phone number in international format: `+55`, the area code and the number, with no spaces or punctuation. Omit it to keep the current one.", "example": "+5534984325252", "type": "string", "pattern": "^\\+55[0-9]{10,11}$" }, "address": { "description": "The address fields to change. Send only the ones that change: the others keep their current value.", "type": "object", "properties": { "street": { "description": "Street name, up to 100 characters.", "example": "Rua das Flores", "type": "string", "maxLength": 100 }, "number": { "description": "Street number, up to 20 characters.", "example": "100", "type": "string", "maxLength": 20 }, "neighborhood": { "description": "Neighborhood, up to 100 characters.", "example": "Centro", "type": "string", "maxLength": 100 }, "city": { "description": "City, up to 50 characters.", "example": "Uberlândia", "type": "string", "maxLength": 50 }, "state": { "description": "State, as its two-letter abbreviation.", "example": "MG", "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO", "DF" ] }, "postalCode": { "description": "Postal code (CEP) as `00000-000`, with the hyphen.", "example": "38400-000", "type": "string", "pattern": "^\\d{5}-\\d{3}$" }, "complement": { "description": "Complement such as a suite or a floor, up to 50 characters.", "example": "Sala 2", "type": "string", "maxLength": 50 } } }, "pixKey": { "description": "New PIX key: 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.", "example": "financeiro@boaviagem.example.com", "type": "string", "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}$" }, "pixKeyType": { "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Required when you send `pixKey`, and not allowed without it.", "example": "EMAIL", "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the supplier.", "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" }, "realm": { "type": "string", "description": "ID of the realm the supplier belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the supplier belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the supplier.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "type": "string", "description": "Trade name of the supplier. Absent when none was given.", "example": "Boa Viagem Transportes" }, "document": { "type": "string", "description": "CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company.", "example": "CNPJ" }, "email": { "type": "string", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the supplier in international format.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number.", "example": "100" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "state": { "type": "string", "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "description": "Postal code (CEP) as `00000-000`.", "example": "38400-000" }, "complement": { "type": "string", "description": "Complement such as a suite or a floor. Absent when none was given.", "example": "Sala 2" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the supplier was deactivated.", "example": "ACTIVE" }, "pixKey": { "type": "string", "description": "PIX key to pay the supplier. Absent when none was given.", "example": "financeiro@boaviagem.example.com" }, "pixKeyType": { "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ], "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Absent when there is no PIX key.", "example": "EMAIL" }, "createdBy": { "type": "string", "description": "ID of the user who registered the supplier.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the supplier was registered.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the supplier was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "name", "document", "documentType", "email", "phoneNumber", "status" ], "description": "A supplier of the organization: someone you pay." } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "404": { "description": "`SUPPLIER_NOT_FOUND` — No supplier with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SUPPLIER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SUPPLIER_NOT_FOUND", "origin": "REGISTRY", "message": "Supplier not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter or a body field is invalid, such as a `supplierId` that is not a UUID, a document that is not a valid CPF or CNPJ or a phone number outside the `+55` format; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "Too big: expected string to have <=100 characters", "code": "NAME_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value); `.refine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/suppliers/{supplierId}/activate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdSuppliersBySupplierIdActivate", "summary": "Activate a supplier", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 6, "description": "Sets a supplier's `status` to `ACTIVE`.", "x-mint": { "content": "Only organization admins can activate a supplier, and only a `DEACTIVATED` one: activating a supplier that is already `ACTIVE` is rejected. To deactivate a supplier, use `POST /realms/{realmId}/organizations/{organizationId}/suppliers/{supplierId}/deactivate`.\n\nAnswers the supplier as it is after the change. The request has no body: if your HTTP client sends `Content-Type: application/json`, send `{}`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the supplier belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "supplierId", "in": "path", "required": true, "description": "ID of the supplier (`id` in the supplier list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the supplier.", "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" }, "realm": { "type": "string", "description": "ID of the realm the supplier belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the supplier belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the supplier.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "type": "string", "description": "Trade name of the supplier. Absent when none was given.", "example": "Boa Viagem Transportes" }, "document": { "type": "string", "description": "CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company.", "example": "CNPJ" }, "email": { "type": "string", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the supplier in international format.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number.", "example": "100" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "state": { "type": "string", "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "description": "Postal code (CEP) as `00000-000`.", "example": "38400-000" }, "complement": { "type": "string", "description": "Complement such as a suite or a floor. Absent when none was given.", "example": "Sala 2" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the supplier was deactivated.", "example": "ACTIVE" }, "pixKey": { "type": "string", "description": "PIX key to pay the supplier. Absent when none was given.", "example": "financeiro@boaviagem.example.com" }, "pixKeyType": { "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ], "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Absent when there is no PIX key.", "example": "EMAIL" }, "createdBy": { "type": "string", "description": "ID of the user who registered the supplier.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the supplier was registered.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the supplier was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "name", "document", "documentType", "email", "phoneNumber", "status" ], "description": "A supplier of the organization: someone you pay." } } } }, "400": { "description": "`SUPPLIER_INVALID_STATUS_FOR_ACTIVATION` — The supplier is already `ACTIVE`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SUPPLIER_INVALID_STATUS_FOR_ACTIVATION" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SUPPLIER_INVALID_STATUS_FOR_ACTIVATION", "origin": "REGISTRY", "message": "This supplier is already active." } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "404": { "description": "`SUPPLIER_NOT_FOUND` — No supplier with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SUPPLIER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SUPPLIER_NOT_FOUND", "origin": "REGISTRY", "message": "Supplier not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `supplierId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "supplierId", "message": "Invalid UUID", "code": "SUPPLIERID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/suppliers/{supplierId}/deactivate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdSuppliersBySupplierIdDeactivate", "summary": "Deactivate a supplier", "tags": [ "Suppliers" ], "x-p3-sidebar-order": 7, "description": "Sets a supplier's `status` to `DEACTIVATED`.", "x-mint": { "content": "Only organization admins can deactivate a supplier. Deactivating a supplier that is already `DEACTIVATED` succeeds and changes nothing. To bring a supplier back, use `POST /realms/{realmId}/organizations/{organizationId}/suppliers/{supplierId}/activate`.\n\nAnswers the supplier as it is after the change. The request has no body: if your HTTP client sends `Content-Type: application/json`, send `{}`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the supplier belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "supplierId", "in": "path", "required": true, "description": "ID of the supplier (`id` in the supplier list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the supplier.", "example": "5f0c7d2a-91b4-4e6f-8a13-c2d4e6f80b17" }, "realm": { "type": "string", "description": "ID of the realm the supplier belongs to.", "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b", "format": "uuid" }, "organization": { "type": "string", "description": "ID of the organization the supplier belongs to.", "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410", "format": "uuid" }, "name": { "type": "string", "description": "Name of the supplier.", "example": "Transportadora Boa Viagem Ltda" }, "tradingName": { "type": "string", "description": "Trade name of the supplier. Absent when none was given.", "example": "Boa Viagem Transportes" }, "document": { "type": "string", "description": "CPF or CNPJ of the supplier, with no punctuation. A CNPJ with letters is returned in upper case.", "example": "11222333000181" }, "documentType": { "type": "string", "enum": [ "CPF", "CNPJ" ], "description": "`CPF` when the supplier is a person, `CNPJ` when it is a company.", "example": "CNPJ" }, "email": { "type": "string", "description": "E-mail address of the supplier.", "example": "financeiro@boaviagem.example.com" }, "phoneNumber": { "type": "string", "description": "Phone number of the supplier in international format.", "example": "+5534984325252" }, "address": { "type": "object", "properties": { "street": { "type": "string", "description": "Street name.", "example": "Rua das Flores" }, "number": { "type": "string", "description": "Street number.", "example": "100" }, "neighborhood": { "type": "string", "description": "Neighborhood.", "example": "Centro" }, "city": { "type": "string", "description": "City.", "example": "Uberlândia" }, "state": { "type": "string", "description": "State, as its two-letter abbreviation.", "example": "MG" }, "postalCode": { "type": "string", "description": "Postal code (CEP) as `00000-000`.", "example": "38400-000" }, "complement": { "type": "string", "description": "Complement such as a suite or a floor. Absent when none was given.", "example": "Sala 2" } }, "required": [ "street", "number", "neighborhood", "city", "state", "postalCode" ], "description": "Address of the supplier." }, "status": { "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ], "description": "`ACTIVE`, or `DEACTIVATED` once the supplier was deactivated.", "example": "DEACTIVATED" }, "pixKey": { "type": "string", "description": "PIX key to pay the supplier. Absent when none was given.", "example": "financeiro@boaviagem.example.com" }, "pixKeyType": { "type": "string", "enum": [ "PHONE", "EMAIL", "CPF", "CNPJ", "EVP" ], "description": "Type of `pixKey`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (a random key). Absent when there is no PIX key.", "example": "EMAIL" }, "createdBy": { "type": "string", "description": "ID of the user who registered the supplier.", "example": "e3553bc1-5e20-4e17-b22a-a796fda0aa99", "format": "uuid" }, "createdAt": { "type": "string", "description": "When the supplier was registered.", "example": "2026-10-02T14:03:11.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the supplier was last changed.", "example": "2026-10-05T09:30:00.000Z", "format": "date-time" } }, "required": [ "id", "realm", "organization", "name", "document", "documentType", "email", "phoneNumber", "status" ], "description": "A supplier of the organization: someone you pay." } } } }, "403": { "description": "`FORBIDDEN_SUPPLIER` — You are not an admin of the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "FORBIDDEN_SUPPLIER" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "FORBIDDEN_SUPPLIER", "origin": "REGISTRY", "message": "You do not have permission to perform this action on supplier" } } } }, "404": { "description": "`SUPPLIER_NOT_FOUND` — No supplier with this ID exists in the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "SUPPLIER_NOT_FOUND" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b", "code": "SUPPLIER_NOT_FOUND", "origin": "REGISTRY", "message": "Supplier not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not valid, such as a `supplierId` that is not a UUID; `fields` lists each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "traceId": { "type": "string", "description": "Identifier of the request that failed. Quote it when contacting support.", "example": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b" }, "code": { "type": "string", "enum": [ "BAD_REQUEST" ], "description": "Stable, machine-readable error code. Branch on this, never on `message`." }, "origin": { "type": "string", "enum": [ "REGISTRY" ], "description": "Service that produced the error." }, "message": { "type": "string", "description": "Human-readable explanation. Its wording may change without notice." }, "fields": { "type": "array", "description": "One entry per invalid request field (validation errors only).", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Path of the invalid field, e.g. `label` or `values[0].value`.", "example": "label" }, "message": { "type": "string", "description": "Why the field was rejected.", "example": "label is required" }, "code": { "type": "string", "description": "`_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`.", "example": "LABEL_REQUIRED" }, "values": { "type": "array", "items": { "type": "string" }, "description": "The accepted values, when the field is an enumeration." } }, "required": [ "field", "message", "code" ] } } }, "required": [ "traceId", "code", "origin", "message" ] }, "example": { "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": "supplierId", "message": "Invalid UUID", "code": "SUPPLIERID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }