{ "openapi": "3.1.0", "info": { "title": "PerfectPay API", "version": "0.0.1", "description": "API de integra\u00e7\u00e3o para produtores e afiliados: consulta de vendas, assinaturas, tracking e invoice.\n\n**Autentica\u00e7\u00e3o**\n\nTodas as requisi\u00e7\u00f5es usam o header `Authorization: Bearer `. S\u00e3o aceitos dois tipos de token:\n\n- **Token de integra\u00e7\u00e3o** \u2014 gerado no painel em *Ferramentas > API*.\n- **Token pessoal** \u2014 obtido via `POST \/api\/auth\/login`.\n\n**PostBack (webhook de sa\u00edda)**\n\nVeja a se\u00e7\u00e3o *Webhooks* no menu para o payload e os eventos do webhook enviado \u00e0 sua URL cadastrada.\n\n**Integra\u00e7\u00e3o com IA (llms.txt)**\n\nEsta API exp\u00f5e arquivos em texto plano seguindo o padr\u00e3o [llms.txt](https:\/\/llmstxt.org) \u2014 uma conven\u00e7\u00e3o para publicar documenta\u00e7\u00e3o em markdown limpo, otimizado para leitura por modelos de linguagem e agentes.\n\n- [\/llms.txt](https:\/\/app.perfectpay.com.br\/llms.txt) \u2014 \u00edndice curado e leve: vis\u00e3o geral, autentica\u00e7\u00e3o e a lista dos 7 endpoints com links. Bom como contexto inicial de um agente ou ponto de entrada para navega\u00e7\u00e3o sob demanda.\n- [\/llms-full.txt](https:\/\/app.perfectpay.com.br\/llms-full.txt) \u2014 vers\u00e3o expandida gerada do OpenAPI, com par\u00e2metros e respostas de cada endpoint inline. Use quando a IA precisar do contexto completo em uma \u00fanica leitura, como em RAG ou gera\u00e7\u00e3o de c\u00f3digo de integra\u00e7\u00e3o.\n- [\/docs\/api.json](https:\/\/app.perfectpay.com.br\/docs\/api.json) \u2014 OpenAPI 3.1 can\u00f4nico e machine-readable, para gerar clients\/SDKs, importar em ferramentas ou alimentar pipelines automatizados.\n\nNa pr\u00e1tica: comece pelo [\/llms.txt](https:\/\/app.perfectpay.com.br\/llms.txt) para orientar o agente, recorra ao [\/llms-full.txt](https:\/\/app.perfectpay.com.br\/llms-full.txt) quando precisar dos detalhes de cada rota e use o [\/docs\/api.json](https:\/\/app.perfectpay.com.br\/docs\/api.json) para tooling e gera\u00e7\u00e3o de SDK." }, "servers": [ { "url": "https:\/\/app.perfectpay.com.br\/api" } ], "security": [ { "http": [] } ], "paths": { "\/auth\/login": { "post": { "operationId": "apiAuth.login", "description": "Autentica com e-mail e senha e retorna um `access_token` (token pessoal, scope `personal_access`, validade ~1 m\u00eas).\nUse o token no header `Authorization: Bearer ` nas demais chamadas.", "summary": "Login (token pessoal)", "tags": [ "ApiAuth" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/LoginRequest" } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Error trying to login to API." } }, "required": [ "message" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token de acesso pessoal (Bearer), scope personal_access, validade ~1 m\u00eas. Envie em Authorization: Bearer ." }, "email": { "type": "string", "description": "Endere\u00e7o de e-mail." }, "name": { "type": "string", "description": "Nome." }, "avatar": { "type": "string", "description": "URL da imagem de perfil." }, "uuid": { "type": "string", "description": "Identificador \u00fanico (UUID) do usu\u00e1rio." } }, "required": [ "access_token", "email", "name", "avatar", "uuid" ] }, "example": { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.exemplo.token", "email": "produtor@example.com", "name": "Produtor Exemplo", "avatar": "https:\/\/ppay.storage.example.com\/avatars\/exemplo.png", "uuid": "9b1c7e2a-4f3d-4a1b-8c2e-0a1b2c3d4e5f" } } } }, "401": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Unauthorized" } }, "required": [ "message" ] } } } }, "429": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Acesso bloqueado por excesso de tentativas, entre em contato com suporte." ] } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [] } }, "\/v1\/sales\/get": { "post": { "operationId": "integration.sales", "description": "Lista vendas do produtor com filtros por data (venda\/aprova\u00e7\u00e3o\/atualiza\u00e7\u00e3o), status, c\u00f3digo do produto,\ne-mail do comprador ou c\u00f3digo da transa\u00e7\u00e3o.\n\n**Variante afilia\u00e7\u00e3o premium:** quando o token pertence a uma afilia\u00e7\u00e3o premium, cada item de `sales.data` vem em formato reduzido \u2014 apenas `transaction_token`, `sale_status`, `payment_type`, `date_created`, `date_approved`, `currency_enum`, `currency_enum_key` e `commissions` (neste caso um objeto `{value, affiliation_type}`, e n\u00e3o a lista de comiss\u00f5es do produtor).", "summary": "Buscar vendas", "tags": [ "Integration" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SalesIntegrationRequest" } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Ocorreu um erro durante a busca." } }, "required": [ "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "sales": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "product_code": { "type": "string", "description": "C\u00f3digo do produto." }, "product_name": { "type": "string", "description": "Nome do produto." }, "transaction_token": { "type": "string", "description": "C\u00f3digo da transa\u00e7\u00e3o\/venda (identificador \u00fanico)." }, "value": { "type": "string", "description": "Valor." }, "unit_value": { "type": "string", "description": "Valor unit\u00e1rio." }, "shipping_value": { "type": "string", "description": "Valor do frete." }, "plan": { "type": "array", "items": { "type": "object", "properties": { "plan_name": { "type": "string", "description": "Nome do plano." }, "plan_code": { "type": "string", "description": "C\u00f3digo do plano." }, "offer_name": { "type": [ "string", "null" ], "description": "Nome interno da oferta do plano, definido pelo produtor. N\u00e3o \u00e9 exibido no checkout. Nulo quando n\u00e3o preenchido." }, "quantity": { "type": "integer", "description": "Quantidade." } }, "required": [ "plan_name", "plan_code", "offer_name", "quantity" ] } }, "customer": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": "string", "description": "Nome completo." }, "email": { "type": "string", "description": "Endere\u00e7o de e-mail." }, "identification_type": { "type": "string", "description": "Tipo de documento (CPF ou CNPJ)." }, "identification_number": { "type": "string", "description": "N\u00famero do documento." }, "phone": { "type": "string", "description": "Telefone do comprador." }, "zip_code": { "type": "string", "description": "CEP." }, "street_name": { "type": "string", "description": "Logradouro." }, "street_number": { "type": "string", "description": "N\u00famero do endere\u00e7o." }, "complement": { "type": "string", "description": "Complemento do endere\u00e7o." }, "district": { "type": "string", "description": "Bairro." }, "city": { "type": "string", "description": "Cidade." }, "state": { "type": "string", "description": "UF." }, "country": { "type": "string", "description": "Pa\u00eds." } }, "required": [ "full_name", "email", "identification_type", "identification_number", "phone", "zip_code", "street_name", "street_number", "complement", "district", "city", "state", "country" ] } }, "commissions": { "type": "array", "items": { "type": "object", "properties": { "affiliation_name": { "type": "string", "description": "Nome de quem recebe a comiss\u00e3o." }, "affiliation_email": { "type": "string", "description": "E-mail de quem recebe a comiss\u00e3o." }, "affiliation_type": { "type": "integer", "description": "Papel na venda de quem recebe a comiss\u00e3o. Valores: 0 = plataforma, 1 = produtor, 2 = coprodutor, 3 = gestor de afiliados, 4 = parceiro, 5 = afiliado, 6 = premium, 7 = fornecedor, 8 = cpa." }, "identification": { "type": "string", "description": "Documento de quem recebe a comiss\u00e3o." }, "value": { "type": "number", "description": "Valor." }, "commission": { "type": "number", "description": "Valor da comiss\u00e3o." }, "commission_type": { "type": "integer", "description": "Tipo de comiss\u00e3o." } }, "required": [ "affiliation_name", "affiliation_email", "affiliation_type", "identification", "value", "commission", "commission_type" ] } }, "metadata": { "type": "object", "properties": { "src": { "type": "string", "description": "Origem\/source de rastreio." }, "utm_source": { "type": "string", "description": "UTM source." }, "utm_medium": { "type": "string", "description": "UTM medium." }, "utm_campaign": { "type": "string", "description": "UTM campaign." }, "utm_term": { "type": "string", "description": "UTM term." }, "utm_content": { "type": "string", "description": "UTM content." }, "utm_perfect": { "type": "string", "description": "Par\u00e2metro de rastreio interno da plataforma." } }, "required": [ "src", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_perfect" ] }, "total_invoices": { "type": "integer", "description": "Quantidade de notas fiscais da venda." }, "invoices": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ], "description": "Identificador externo da nota fiscal." }, "logistic_id": { "type": [ "string", "null" ], "description": "Identificador de log\u00edstica\/envio." }, "fiscal_number": { "type": "string", "description": "N\u00famero da nota fiscal." }, "fiscal_access_key": { "type": "string", "description": "Chave de acesso da nota fiscal." }, "fiscal_pdf": { "type": "string", "description": "URL do PDF da nota fiscal." }, "fiscal_xml": { "type": [ "string", "null" ], "description": "URL do XML da nota fiscal." }, "fiscal_status": { "type": "string", "description": "Status da nota fiscal." }, "fiscal_date_emission": { "type": "string", "description": "Data de emiss\u00e3o da nota fiscal." } }, "required": [ "external_id", "logistic_id", "fiscal_number", "fiscal_access_key", "fiscal_pdf", "fiscal_xml", "fiscal_status", "fiscal_date_emission" ] } }, "sale_status": { "type": "string", "description": "Chave textual do status da venda. Ex.: pending (aguardando pagamento), approved (aprovado), cancelled (cancelado), refunded (devolvido), charged_back (chargeback), expired (expirado)." }, "payment_type": { "type": "integer", "description": "Tipo de pagamento. Valores: 1 = credit_card, 2 = billet (boleto), 3 = paypal, 4 = credit_card_recurrent, 5 = free_price, 6 = credit_card_upsell, 7 = pix, 8 = billet_installments, 9 = open_finance, 10 = google_pay, 11 = apple_pay, 12 = picpay, 16 = amazon_pay." }, "date_created": { "type": "string", "description": "Data de cria\u00e7\u00e3o da venda." }, "date_approved": { "type": "string", "description": "Data de aprova\u00e7\u00e3o da venda." }, "currency_enum": { "type": "integer", "description": "Moeda. Valores: 1 = BRL (Real), 2 = USD (D\u00f3lar), 3 = EUR (Euro)." }, "currency_enum_key": { "type": "string", "description": "Chave textual da moeda (ex.: BRL)." } }, "required": [ "product_code", "product_name", "transaction_token", "value", "unit_value", "shipping_value", "plan", "customer", "commissions", "metadata", "total_invoices", "sale_status", "payment_type", "date_created", "date_approved", "currency_enum", "currency_enum_key" ] } }, "current_page": { "type": "integer", "description": "P\u00e1gina atual retornada." }, "current_items_count": { "type": "integer", "description": "Quantidade de itens nesta p\u00e1gina." }, "total_pages": { "type": "integer", "description": "Total de p\u00e1ginas dispon\u00edveis para o filtro." }, "total_items": { "type": "integer", "description": "Total de itens encontrados no filtro." } }, "required": [ "data", "current_page", "current_items_count", "total_pages", "total_items" ] } }, "required": [ "sales" ] }, "example": { "sales": { "data": [ { "product_code": "PPPBEXEMPLO", "product_name": "Curso de Marketing Digital", "transaction_token": "PPCPMT000000000", "value": "197.90", "unit_value": "197.90", "shipping_value": "0.00", "plan": [ { "plan_name": "Plano \u00danico", "plan_code": "PPLQEXEMPLO", "offer_name": "Curso de Exemplo: [Afiliados] [Funil 269] [\u00danico]", "quantity": 1 } ], "customer": [ { "full_name": "Maria Compradora", "email": "maria@example.com", "identification_type": "CPF", "identification_number": "00000000000", "phone": "11988887777", "zip_code": "01001000", "street_name": "Pra\u00e7a da S\u00e9", "street_number": "100", "complement": "", "district": "S\u00e9", "city": "S\u00e3o Paulo", "state": "SP", "country": "BR" } ], "commissions": [ { "affiliation_name": "Produtor Exemplo", "affiliation_email": "produtor@example.com", "affiliation_type": 1, "identification": "00000000000", "value": 197.9, "commission": 178.11, "commission_type": 1 } ], "metadata": { "src": "organic", "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "lancamento", "utm_term": "marketing-digital", "utm_content": "anuncio-01", "utm_perfect": null }, "total_invoices": 0, "invoices": [], "sale_status": "approved", "payment_type": 7, "date_created": "2026-07-20 14:32:10", "date_approved": "2026-07-20 14:32:15", "currency_enum": 1, "currency_enum_key": "BRL" } ], "current_page": 1, "current_items_count": 1, "total_pages": 1, "total_items": 1 } } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/v1\/tracking\/create": { "post": { "operationId": "integration.createTracking", "description": "Registra o c\u00f3digo e URL de rastreio de uma venda, identificada pelo transaction_token.", "summary": "Criar tracking", "tags": [ "Integration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/TrackingIntegrationRequest" } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Erro ao salvar" } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Save Success." } } } } } } }, "\/v1\/tracking\/get": { "post": { "operationId": "integration.getTracking", "description": "Consulta o rastreio de envio de uma venda, identificada pelo transaction_token.", "summary": "Buscar tracking", "tags": [ "Integration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/GetTrackingIntegrationRequest" } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Ocorreu um erro durante a busca." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "tracking": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Nome do produto." }, "product_quantity": { "type": "integer", "description": "Quantidade do produto." }, "total_tracking": { "type": "integer", "description": "Total de c\u00f3digos de rastreio cadastrados." }, "last_tracking_code": { "type": "string", "description": "\u00daltimo c\u00f3digo de rastreio cadastrado." }, "last_tracking_url": { "type": "string", "description": "URL do \u00faltimo rastreio." }, "data": { "type": "array", "items": { "type": "object", "properties": { "tracking_code": { "type": "string", "description": "C\u00f3digo de rastreio." }, "tracking_url": { "type": "string", "description": "URL de rastreio." }, "tracking_status": { "type": "integer", "description": "Status do rastreio (log\u00edstica)." }, "updated_at": { "type": "string", "description": "Data da \u00faltima atualiza\u00e7\u00e3o." } }, "required": [ "tracking_code", "tracking_url", "tracking_status", "updated_at" ] } } }, "required": [ "product_name", "product_quantity", "total_tracking", "data" ] } }, "required": [ "tracking" ] }, "example": { "tracking": { "product_name": "Produto F\u00edsico Exemplo", "product_quantity": 1, "total_tracking": 1, "last_tracking_code": "BR123456789XY", "last_tracking_url": "https:\/\/rastreamento.correios.com.br\/BR123456789XY", "data": [ { "tracking_code": "BR123456789XY", "tracking_url": "https:\/\/rastreamento.correios.com.br\/BR123456789XY", "tracking_status": 1, "updated_at": "2026-07-21 09:15:00" } ] } } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/v1\/invoice\/create": { "post": { "operationId": "integration.createInvoice", "description": "Registra a nota fiscal (invoice) de uma venda, identificada pelo transaction_token.", "summary": "Criar invoice (nota fiscal)", "tags": [ "Integration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/InvoiceIntegrationRequest" } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Erro ao salvar" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "example": { "message": "Invoice inserida com sucesso" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/v1\/invoice\/get": { "post": { "operationId": "integration.getInvoice", "description": "Lista as notas fiscais (invoices) do produtor, com filtro opcional por transaction_token e per\u00edodo.", "summary": "Buscar invoice", "tags": [ "Integration" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/GetInvoiceIntegrationRequest" } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Ocorreu um erro durante a busca." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ], "description": "Identificador externo da nota fiscal." }, "logistic_id": { "type": [ "string", "null" ], "description": "Identificador de log\u00edstica\/envio." }, "fiscal_number": { "type": "string", "description": "N\u00famero da nota fiscal." }, "fiscal_access_key": { "type": "string", "description": "Chave de acesso da nota fiscal." }, "fiscal_pdf": { "type": "string", "description": "URL do PDF da nota fiscal." }, "fiscal_xml": { "type": [ "string", "null" ], "description": "URL do XML da nota fiscal." }, "fiscal_status": { "type": "string", "description": "Status da nota fiscal." }, "fiscal_date_emission": { "type": "string", "description": "Data de emiss\u00e3o da nota fiscal." } }, "required": [ "external_id", "logistic_id", "fiscal_number", "fiscal_access_key", "fiscal_pdf", "fiscal_xml", "fiscal_status", "fiscal_date_emission" ] } }, "current_page": { "type": "integer", "description": "P\u00e1gina atual retornada." }, "current_items_count": { "type": "integer", "description": "Quantidade de itens nesta p\u00e1gina." }, "total_pages": { "type": "integer", "description": "Total de p\u00e1ginas dispon\u00edveis para o filtro." }, "total_items": { "type": "integer", "description": "Total de itens encontrados no filtro." } }, "required": [ "data", "current_page", "current_items_count", "total_pages", "total_items" ] } }, "required": [ "invoices" ] }, "example": { "invoices": { "data": [ { "external_id": "NF-000123", "logistic_id": "LOG-000123", "fiscal_number": "000000123", "fiscal_access_key": "00000000000000000000000000000000000000000000", "fiscal_pdf": "https:\/\/nfe.example.com\/000123.pdf", "fiscal_xml": "https:\/\/nfe.example.com\/000123.xml", "fiscal_status": "emitida", "fiscal_date_emission": "2026-07-20 15:00:00" } ], "current_page": 1, "current_items_count": 1, "total_pages": 1, "total_items": 1 } } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/v1\/subscriptions\/get": { "post": { "operationId": "integration.subscriptions", "description": "Lista assinaturas do produtor com filtros por status, e-mail ou CPF\/CNPJ do cliente.\nA resposta inclui currency_enum, subscription_amount_float e o detalhamento de status\n(subscription_status_enum, subscription_status_detail, subscription_detail_enum).", "summary": "Buscar assinaturas", "tags": [ "Integration" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "subscription_status_enum": { "type": "integer", "description": "Filtro de status da assinatura (1-7, ver SubscriptionStatusEnum). Valores: 1 = trial, 2 = active (ativa), 3 = cancelled (cancelada), 4 = awaiting_payment (aguardando pagamento), 5 = expired (expirada), 6 = in_mediation (em disputa), 7 = finished (finalizada)." }, "recurrent_type_enum": { "type": "integer", "description": "Filtro de tipo de recorr\u00eancia (1-7, ver RecurrentTypeEnum). Observa\u00e7\u00e3o: atualmente este filtro n\u00e3o \u00e9 aplicado na busca (no-op) \u2014 os resultados n\u00e3o s\u00e3o filtrados por tipo de recorr\u00eancia. Valores: 1 = 7 dias, 2 = 15 dias, 3 = mensal, 4 = trimestral, 5 = semestral, 6 = anual, 7 = vital\u00edcio." }, "customer_email": { "type": "string", "description": "Filtro por e-mail do cliente." }, "identification_number": { "type": "string", "description": "Filtro por CPF\/CNPJ do cliente." }, "page": { "type": "integer", "description": "P\u00e1gina da pagina\u00e7\u00e3o." } } } } } }, "responses": { "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Ocorreu um erro durante a busca." } }, "required": [ "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "C\u00f3digo identificador." }, "recurrent_type_enum": { "type": "string", "description": "Periodicidade da recorr\u00eancia. Valores: 1 = 7 dias, 2 = 15 dias, 3 = mensal, 4 = trimestral, 5 = semestral, 6 = anual, 7 = vital\u00edcio." }, "installments": { "type": "integer", "description": "N\u00famero de parcelas." }, "start_date_recurrent": { "type": "string", "description": "Data de in\u00edcio da recorr\u00eancia." }, "end_date_recurrent": { "type": "string", "description": "Data de t\u00e9rmino da recorr\u00eancia." }, "next_date_recurrent": { "type": "string", "description": "Data da pr\u00f3xima cobran\u00e7a." }, "canceled_date": { "type": "string", "description": "Data de cancelamento da assinatura." }, "charges_made": { "type": "integer", "description": "Quantidade de cobran\u00e7as j\u00e1 realizadas." }, "subscription_status_enum": { "type": "string", "description": "Status da assinatura. Valores: 1 = trial, 2 = active (ativa), 3 = cancelled (cancelada), 4 = awaiting_payment (aguardando pagamento), 5 = expired (expirada), 6 = in_mediation (em disputa), 7 = finished (finalizada)." }, "subscription_status_detail": { "type": "string", "description": "Detalhe textual do status da assinatura." }, "subscription_detail_enum": { "type": "string", "description": "Detalhe do status da assinatura. Valores: 1 = canceled_by_billing_error, 2 = canceled_by_customer, 3 = canceled_by_producer, 4 = active_started_recurrence, 5 = active_renewed_recurrence, 6 = trial, 7 = expired, 8 = error_charge, 9 = awaiting_payment, 10 = card_changed_payment, 11 = finished_smart_installment, 12 = blocked_to_sales, 13 = no_sale, 14 = canceled_by_platform." }, "payment_type_enum": { "type": "integer", "description": "Tipo de pagamento. Valores: 1 = credit_card, 2 = billet (boleto), 3 = paypal, 4 = credit_card_recurrent, 5 = free_price, 6 = credit_card_upsell, 7 = pix, 8 = billet_installments, 9 = open_finance, 10 = google_pay, 11 = apple_pay, 12 = picpay, 13 = mercado_pago_brick, 16 = amazon_pay. Carteiras digitais (Apple\/Google Pay) podem chegar normalizadas como cart\u00e3o (1)." }, "payment_type_enum_description": { "type": "string", "description": "Descri\u00e7\u00e3o textual do tipo de pagamento." }, "currency_enum": { "type": "integer", "description": "Moeda. Valores: 1 = BRL (Real), 2 = USD (D\u00f3lar), 3 = EUR (Euro)." }, "customer": { "type": "object", "properties": { "email": { "type": "string", "description": "Endere\u00e7o de e-mail." }, "full_name": { "type": "string", "description": "Nome completo." }, "phone_area_code": { "type": "string", "description": "DDD do telefone." }, "phone_number": { "type": "string", "description": "N\u00famero do telefone." } }, "required": [ "email", "full_name", "phone_area_code", "phone_number" ] }, "product": { "type": "object", "properties": { "code": { "type": "string", "description": "C\u00f3digo identificador." }, "name": { "type": "string", "description": "Nome." } }, "required": [ "code", "name" ] }, "plan": { "type": "object", "properties": { "code": { "type": "string", "description": "C\u00f3digo identificador." }, "name": { "type": "string", "description": "Nome." } }, "required": [ "code", "name" ] }, "subscription_amount": { "type": "string", "description": "Valor da assinatura (string formatada)." }, "subscription_amount_float": { "type": "number", "description": "Valor da assinatura (num\u00e9rico)." }, "sales": { "type": "array", "items": { "type": "object", "properties": { "transaction_token": { "type": "string", "description": "C\u00f3digo da transa\u00e7\u00e3o\/venda (identificador \u00fanico)." }, "sale_status_enum": { "type": "integer", "description": "Status da venda. Valores: 1 = pending (aguardando pagamento), 2 = approved (aprovado), 3 = in_process (em an\u00e1lise), 4 = in_mediation (em disputa), 5 = rejected (rejeitado), 6 = cancelled (cancelado), 7 = refunded (devolvido), 8 = authorized (autorizado), 9 = charged_back (chargeback), 10 = completed (completo), 11 = checkout_error (dados incorretos), 12 = precheckout, 13 = expired (expirado), 15 = cancelled_regenerated, 16 = in_review (revis\u00e3o antifraude), 17 = pre_chargeback, 18 = pre_refunded, 19 = med, 20 = pre_med. No PostBack alguns status s\u00e3o normalizados (8\/10\/16 -> 2; 11 -> 6; 17 -> 9; 18\/19\/20 -> 7)." }, "sale_status_enum_description": { "type": "string", "description": "Descri\u00e7\u00e3o textual do status da venda." }, "date_created": { "type": "string", "description": "Data de cria\u00e7\u00e3o da venda." }, "date_approved": { "type": "string", "description": "Data de aprova\u00e7\u00e3o da venda." }, "sale_amount": { "type": "number", "description": "Valor da venda." }, "payment_type_enum": { "type": "integer", "description": "Tipo de pagamento. Valores: 1 = credit_card, 2 = billet (boleto), 3 = paypal, 4 = credit_card_recurrent, 5 = free_price, 6 = credit_card_upsell, 7 = pix, 8 = billet_installments, 9 = open_finance, 10 = google_pay, 11 = apple_pay, 12 = picpay, 13 = mercado_pago_brick, 16 = amazon_pay. Carteiras digitais (Apple\/Google Pay) podem chegar normalizadas como cart\u00e3o (1)." }, "payment_type_enum_description": { "type": "string", "description": "Descri\u00e7\u00e3o textual do tipo de pagamento." } }, "required": [ "transaction_token", "sale_status_enum", "sale_status_enum_description", "date_created", "date_approved", "sale_amount", "payment_type_enum", "payment_type_enum_description" ] } } }, "required": [ "code", "recurrent_type_enum", "installments", "start_date_recurrent", "end_date_recurrent", "next_date_recurrent", "canceled_date", "charges_made", "subscription_status_enum", "subscription_status_detail", "subscription_detail_enum", "payment_type_enum", "payment_type_enum_description", "currency_enum", "customer", "product", "plan", "subscription_amount", "subscription_amount_float", "sales" ] } }, "current_page": { "type": "integer", "description": "P\u00e1gina atual retornada." }, "current_items_count": { "type": "integer", "description": "Quantidade de itens nesta p\u00e1gina." }, "total_pages": { "type": "integer", "description": "Total de p\u00e1ginas dispon\u00edveis para o filtro." }, "total_items": { "type": "integer", "description": "Total de itens encontrados no filtro." } }, "required": [ "data", "current_page", "current_items_count", "total_pages", "total_items" ] } }, "required": [ "subscriptions" ] }, "example": { "subscriptions": { "data": [ { "code": "PPCS000000", "recurrent_type_enum": "3", "installments": 1, "start_date_recurrent": "2026-06-20", "end_date_recurrent": null, "next_date_recurrent": "2026-08-20", "canceled_date": null, "charges_made": 2, "subscription_status_enum": "2", "subscription_status_detail": "active", "subscription_detail_enum": "5", "payment_type_enum": 1, "payment_type_enum_description": "Cart\u00e3o de cr\u00e9dito", "currency_enum": 1, "customer": { "email": "maria@example.com", "full_name": "Maria Compradora", "phone_area_code": "11", "phone_number": "988887777" }, "product": { "code": "PPPBEXEMPLO", "name": "Assinatura Premium" }, "plan": { "code": "PPLQEXEMPLO", "name": "Plano Mensal" }, "subscription_amount": "49.90", "subscription_amount_float": 49.9, "sales": [ { "transaction_token": "PPCPMT000000001", "sale_status_enum": 2, "sale_status_enum_description": "Aprovado", "date_created": "2026-07-20 10:00:00", "date_approved": "2026-07-20 10:00:05", "sale_amount": 49.9, "payment_type_enum": 1, "payment_type_enum_description": "Cart\u00e3o de cr\u00e9dito" } ] } ], "current_page": 1, "current_items_count": 1, "total_pages": 1, "total_items": 1 } } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "GetInvoiceIntegrationRequest": { "type": "object", "properties": { "transaction_token": { "type": [ "string", "null" ], "description": "Filtra pela transa\u00e7\u00e3o da venda (opcional).", "maxLength": 255 }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Data inicial do per\u00edodo de emiss\u00e3o, no formato yyyy-mm-dd. Padr\u00e3o: ontem.", "examples": [ "2026-01-01" ] }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "Data final do per\u00edodo de emiss\u00e3o, no formato yyyy-mm-dd. Padr\u00e3o: hoje.", "examples": [ "2026-01-31" ] }, "page": { "type": [ "number", "null" ], "description": "P\u00e1gina da pagina\u00e7\u00e3o." } }, "title": "GetInvoiceIntegrationRequest" }, "GetTrackingIntegrationRequest": { "type": "object", "properties": { "transaction_token": { "type": "string", "description": "C\u00f3digo da transa\u00e7\u00e3o da venda (obrigat\u00f3rio).", "maxLength": 255 } }, "required": [ "transaction_token" ], "title": "GetTrackingIntegrationRequest" }, "InvoiceIntegrationRequest": { "type": "object", "properties": { "transaction_token": { "type": "string", "description": "C\u00f3digo da transa\u00e7\u00e3o da venda (obrigat\u00f3rio).", "maxLength": 255 }, "external_id": { "type": [ "string", "null" ], "description": "Identificador externo da nota fiscal (opcional).", "maxLength": 255 }, "logistic_id": { "type": [ "string", "null" ], "description": "Identificador do envio\/log\u00edstica vinculado (opcional).", "maxLength": 255 }, "fiscal_number": { "type": "string", "description": "N\u00famero da nota fiscal.", "maxLength": 255 }, "fiscal_access_key": { "type": "string", "description": "Chave de acesso da nota fiscal.", "maxLength": 500 }, "fiscal_pdf": { "type": "string", "description": "URL do PDF da nota fiscal.", "maxLength": 1000 }, "fiscal_xml": { "type": [ "string", "null" ], "description": "URL do XML da nota fiscal (opcional).", "maxLength": 1000 }, "fiscal_status": { "type": "string", "description": "Status da nota fiscal.", "maxLength": 255 }, "fiscal_date_emission": { "type": "string", "format": "date-time", "description": "Data\/hora de emiss\u00e3o da nota fiscal, no formato yyyy-mm-dd HH:ii:ss.", "examples": [ "2026-01-01 12:00:00" ] } }, "required": [ "transaction_token", "fiscal_number", "fiscal_access_key", "fiscal_pdf", "fiscal_status", "fiscal_date_emission" ], "title": "InvoiceIntegrationRequest" }, "LoginRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "E-mail da conta PerfectPay." }, "password": { "type": "string", "description": "Senha da conta." } }, "required": [ "email", "password" ], "title": "LoginRequest" }, "SalesIntegrationRequest": { "type": "object", "properties": { "page": { "type": [ "integer", "null" ], "description": "P\u00e1gina da pagina\u00e7\u00e3o (1 a 10000).", "minimum": 1, "maximum": 10000 }, "paginate": { "type": [ "integer", "null" ], "description": "Itens por p\u00e1gina (1 a 1000).", "minimum": 1, "maximum": 1000 }, "start_date_approved": { "type": "string", "format": "date", "description": "Data inicial de aprova\u00e7\u00e3o da venda, no formato yyyy-mm-dd.", "examples": [ "2026-01-01" ] }, "end_date_approved": { "type": "string", "format": "date", "description": "Data final de aprova\u00e7\u00e3o da venda, no formato yyyy-mm-dd. Obrigat\u00f3rio junto com start_date_approved.", "examples": [ "2026-01-31" ] }, "start_date_sale": { "type": "string", "format": "date", "description": "Data inicial da venda (cria\u00e7\u00e3o), no formato yyyy-mm-dd.", "examples": [ "2026-01-01" ] }, "end_date_sale": { "type": "string", "format": "date", "description": "Data final da venda (cria\u00e7\u00e3o), no formato yyyy-mm-dd. Obrigat\u00f3rio junto com start_date_sale.", "examples": [ "2026-01-31" ] }, "start_date_updated": { "type": "string", "format": "date", "description": "Data inicial de atualiza\u00e7\u00e3o da venda, no formato yyyy-mm-dd.", "examples": [ "2026-01-01" ] }, "end_date_updated": { "type": "string", "format": "date", "description": "Data final de atualiza\u00e7\u00e3o da venda, no formato yyyy-mm-dd. Obrigat\u00f3rio junto com start_date_updated.", "examples": [ "2026-01-31" ] }, "sale_status": { "type": [ "array", "null" ], "description": "Filtra por status da venda (array de valores de SaleStatusEnum).", "items": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "15", "16", "17", "18", "19", "20" ] } }, "transaction_token": { "type": [ "string", "null" ], "description": "C\u00f3digo da transa\u00e7\u00e3o da venda.", "maxLength": 50 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Filtro por e-mail do comprador.", "maxLength": 200 }, "product_code": { "type": [ "string", "null" ], "description": "Filtra por c\u00f3digo do produto (aceita m\u00faltiplos c\u00f3digos separados por v\u00edrgula).", "maxLength": 300 } }, "title": "SalesIntegrationRequest" }, "TrackingIntegrationRequest": { "type": "object", "properties": { "transaction_token": { "type": "string", "description": "C\u00f3digo da transa\u00e7\u00e3o da venda (obrigat\u00f3rio).", "maxLength": 255 }, "tracking_code": { "type": "string", "description": "C\u00f3digo de rastreio gerado pela transportadora.", "maxLength": 255 }, "tracking_url": { "type": "string", "description": "URL de rastreio da transportadora.", "maxLength": 255 }, "external_id": { "type": "string", "description": "Identificador externo do envio (opcional).", "maxLength": 255 }, "status_tracking": { "type": "string", "description": "Status do envio (ex.: Enviado, Entregue).", "maxLength": 255 } }, "required": [ "transaction_token", "tracking_code", "tracking_url", "status_tracking" ], "title": "TrackingIntegrationRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } }, "webhooks": { "PostBack": { "post": { "summary": "PostBack (webhook de sa\u00edda)", "description": "Enviado por PerfectPay via `POST` (JSON) para a URL cadastrada pelo produtor sempre que a venda muda para um dos status marcados no cadastro do webhook (Ferramentas > Webhook - Vendas). Sua URL deve responder HTTP 2xx e ser idempotente em rela\u00e7\u00e3o ao campo `code`.", "requestBody": { "description": "Corpo enviado \u00e0 URL do produtor.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Hash MD5 (32 caracteres) do c\u00f3digo do usu\u00e1rio dono do webhook. \u00c9 o mesmo em todos os eventos da sua conta; use para validar a origem do postback." }, "code": { "type": "string", "description": "Transaction token da venda (identificador \u00fanico). Use como chave de idempot\u00eancia." }, "sale_amount": { "type": "number", "description": "Valor total da venda." }, "currency_enum": { "type": "integer", "description": "Moeda da venda. Valores: 1 = BRL (Real), 2 = USD (D\u00f3lar), 3 = EUR (Euro)." }, "currency_enum_key": { "type": "string", "description": "Chave textual da moeda (ex.: BRL)." }, "coupon_code": { "type": [ "string", "null" ], "description": "Cupom de desconto aplicado." }, "installments": { "type": "integer", "description": "N\u00famero de parcelas." }, "installment_amount": { "type": "number", "description": "Valor de cada parcela." }, "shipping_type_enum": { "type": [ "integer", "null" ], "description": "Tipo de frete (quando o produto tem envio). Valores: 1 = PAC, 2 = SEDEX." }, "shipping_type_enum_key": { "type": [ "string", "null" ], "description": "Chave textual do tipo de frete." }, "shipping_amount": { "type": [ "number", "null" ], "description": "Valor do frete." }, "payment_method_enum": { "type": "integer", "description": "Bandeira\/meio de pagamento. Valores comuns: 0 = none, 1 = visa, 3 = amex, 4 = elo, 5 = hipercard, 6 = master, 9 = pix, 10 = discover, 11 = diners, 72 = google_pay, 73 = apple_pay, 74 = picpay, 75 = paypal." }, "payment_method_enum_key": { "type": "string", "description": "Chave textual do meio de pagamento." }, "payment_type_enum": { "type": "integer", "description": "Tipo de pagamento. Valores: 1 = credit_card, 2 = billet (boleto), 3 = paypal, 4 = credit_card_recurrent, 5 = free_price, 6 = credit_card_upsell, 7 = pix, 8 = billet_installments, 9 = open_finance, 10 = google_pay, 11 = apple_pay, 12 = picpay, 13 = mercado_pago_brick, 16 = amazon_pay. Carteiras digitais (Apple\/Google Pay) podem chegar normalizadas como cart\u00e3o (1)." }, "payment_type_enum_key": { "type": "string", "description": "Chave textual do tipo de pagamento." }, "payment_format_enum": { "type": "integer", "description": "Formato do checkout. Valores: 1 = regular, 2 = orderbump, 3 = upsell." }, "payment_format_enum_key": { "type": "string", "description": "Chave textual do formato do checkout." }, "original_code": { "type": [ "string", "null" ], "description": "Transaction token da venda original, quando esta \u00e9 uma troca\/upgrade." }, "billet_url": { "type": [ "string", "null" ], "description": "Link do boleto ou do checkout." }, "billet_number": { "type": [ "string", "null" ], "description": "Linha digit\u00e1vel do boleto, ou o c\u00f3digo Pix copia-e-cola quando o pagamento \u00e9 Pix." }, "billet_expiration": { "type": [ "string", "null" ], "description": "Expira\u00e7\u00e3o do boleto ou do Pix (datetime)." }, "quantity": { "type": "integer", "description": "Quantidade contratada do plano." }, "sale_status_enum": { "type": "integer", "description": "Status da venda no momento do envio. Valores: 1 = pending (aguardando pagamento), 2 = approved (aprovado), 3 = in_process (em an\u00e1lise), 4 = in_mediation (em disputa), 5 = rejected (rejeitado), 6 = cancelled (cancelado), 7 = refunded (devolvido), 8 = authorized (autorizado), 9 = charged_back (chargeback), 10 = completed (completo), 11 = checkout_error (dados incorretos), 12 = precheckout, 13 = expired (expirado), 15 = cancelled_regenerated, 16 = in_review (revis\u00e3o antifraude), 17 = pre_chargeback, 18 = pre_refunded, 19 = med, 20 = pre_med. No PostBack alguns status s\u00e3o normalizados (8\/10\/16 -> 2; 11 -> 6; 17 -> 9; 18\/19\/20 -> 7)." }, "sale_status_enum_key": { "type": "string", "description": "Chave textual do status." }, "sale_status_detail": { "type": [ "string", "null" ], "description": "Detalhe adicional do status (ex.: motivo de recusa, \"paid\")." }, "date_created": { "type": "string", "description": "Data de cria\u00e7\u00e3o da venda (datetime)." }, "date_approved": { "type": [ "string", "null" ], "description": "Data de aprova\u00e7\u00e3o da venda, quando aplic\u00e1vel (datetime)." }, "tracking": { "type": [ "string", "null" ], "description": "C\u00f3digo de rastreio (log\u00edstica), quando cadastrado." }, "url_tracking": { "type": [ "string", "null" ], "description": "URL de rastreio." }, "checkout_type_enum": { "type": "string", "description": "Repete a chave textual de payment_format_enum (mantido por compatibilidade)." }, "academy_access_url": { "type": [ "string", "null" ], "description": "Link de acesso ao curso, quando o produto integra a Academy." }, "currency_paid": { "type": [ "string", "null" ], "description": "Moeda efetivamente paga. Presente apenas no evento de carrinho abandonado (precheckout)." }, "sale_amount_paid": { "type": [ "number", "null" ], "description": "Valor efetivamente pago\/convertido. Presente apenas no evento de carrinho abandonado (precheckout)." }, "sale_code": { "type": [ "string", "null" ], "description": "Code interno da venda. Presente apenas quando o destino \u00e9 o tracker interno da plataforma (integra\u00e7\u00e3o interna, n\u00e3o o webhook comum do produtor)." }, "pay_tax": { "type": [ "number", "null" ], "description": "Custo percentual da plataforma sobre a venda. Presente apenas no tracker interno da plataforma." }, "pay_abs": { "type": [ "number", "null" ], "description": "Custo absoluto da plataforma sobre a venda. Presente apenas no tracker interno da plataforma." }, "unit_value": { "type": [ "number", "null" ], "description": "Valor unit\u00e1rio do produto. Presente apenas no tracker interno da plataforma." }, "product": { "type": "object", "description": "Dados do produto.", "properties": { "code": { "type": "string", "description": "C\u00f3digo do produto." }, "name": { "type": "string", "description": "Nome do produto." }, "external_reference": { "type": [ "string", "null" ], "description": "Refer\u00eancia externa do produto (ou tax code, quando n\u00e3o h\u00e1 refer\u00eancia)." }, "guarantee": { "type": "integer", "description": "Dias de garantia." } } }, "plan": { "type": "object", "description": "Dados do plano.", "properties": { "code": { "type": "string", "description": "C\u00f3digo do plano." }, "name": { "type": "string", "description": "Nome do plano." }, "offer_name": { "type": [ "string", "null" ], "description": "Nome interno da oferta do plano, definido pelo produtor. N\u00e3o \u00e9 exibido no checkout." }, "quantity": { "type": "integer", "description": "Quantidade do plano." }, "tax_code": { "type": [ "string", "null" ], "description": "C\u00f3digo fiscal do plano." } } }, "plan_itens": { "type": "array", "description": "Itens\/orderbumps consolidados do plano.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "C\u00f3digo do plano ao qual o item pertence." }, "item_code": { "type": "string", "description": "C\u00f3digo do item." }, "name": { "type": "string", "description": "Nome do item." }, "price": { "type": "number", "description": "Pre\u00e7o do item." }, "quantity": { "type": "integer", "description": "Quantidade do item." } } } }, "customer": { "type": "object", "description": "Dados do comprador. Campos de endere\u00e7o s\u00f3 s\u00e3o preenchidos quando o produto tem frete.", "properties": { "customer_type_enum": { "type": "integer", "description": "Tipo do comprador. Valores: 1 = pessoa f\u00edsica, 2 = pessoa jur\u00eddica. (No PostBack, customer_type_enum_key vem do enum de comiss\u00e3o por um bug conhecido; use identification_type para diferenciar CPF\/CNPJ.)" }, "customer_type_enum_key": { "type": "string", "description": "Chave textual do tipo do comprador (ver observa\u00e7\u00e3o no campo customer_type_enum)." }, "full_name": { "type": "string", "description": "Nome completo do comprador." }, "email": { "type": "string", "description": "E-mail do comprador." }, "identification_type": { "type": "string", "description": "Tipo de documento (CPF\/CNPJ)." }, "identification_number": { "type": "string", "description": "N\u00famero do documento." }, "birthday": { "type": [ "string", "null" ], "description": "Data de nascimento." }, "date_birth": { "type": [ "string", "null" ], "description": "Data de nascimento (duplicado por compatibilidade)." }, "phone_extension": { "type": "string", "description": "DDI do telefone (padr\u00e3o \"55\")." }, "phone_area_code": { "type": "string", "description": "DDD do telefone." }, "phone_number": { "type": "string", "description": "N\u00famero do telefone." }, "phone_formated": { "type": "string", "description": "Telefone formatado." }, "phone_formated_ddi": { "type": "string", "description": "Telefone formatado com DDI (E.164)." }, "ip": { "type": "string", "description": "IP do comprador na compra." }, "user_agent": { "type": "string", "description": "User agent do navegador do comprador." }, "street_name": { "type": "string", "description": "Logradouro." }, "street_number": { "type": "string", "description": "N\u00famero." }, "district": { "type": "string", "description": "Bairro." }, "complement": { "type": "string", "description": "Complemento." }, "zip_code": { "type": "string", "description": "CEP." }, "city": { "type": "string", "description": "Cidade." }, "state": { "type": "string", "description": "UF." }, "country": { "type": [ "string", "null" ], "description": "Pa\u00eds do comprador." }, "language": { "type": [ "string", "null" ], "description": "Idioma\/locale do comprador (ex.: pt_BR)." } } }, "metadata": { "type": "object", "description": "Metadados de rastreio da venda. As chaves de UTM\/origem abaixo costumam vir sempre (null quando n\u00e3o capturadas); al\u00e9m delas, o objeto pode conter QUALQUER outra chave de rastreio registrada na venda (ex.: _fbc, _fbp, fbclid, ref, mcr, fbpixel, click_id) \u2014 trate como mapa aberto.", "additionalProperties": { "type": [ "string", "null" ], "description": "Outras chaves de rastreio registradas na venda (din\u00e2micas)." }, "properties": { "src": { "type": [ "string", "null" ], "description": "Origem\/source de rastreio." }, "sck": { "type": [ "string", "null" ], "description": "Sub click \/ identificador de rastreio de campanha." }, "utm_source": { "type": [ "string", "null" ], "description": "UTM source." }, "utm_medium": { "type": [ "string", "null" ], "description": "UTM medium." }, "utm_campaign": { "type": [ "string", "null" ], "description": "UTM campaign." }, "utm_content": { "type": [ "string", "null" ], "description": "UTM content." }, "utm_term": { "type": [ "string", "null" ], "description": "UTM term." }, "utm_perfect": { "type": [ "string", "null" ], "description": "Par\u00e2metro de rastreio interno da plataforma." }, "ttclid": { "type": [ "string", "null" ], "description": "Click ID do TikTok Ads." }, "_fbc": { "type": [ "string", "null" ], "description": "Cookie _fbc do Facebook (click ID), quando presente." }, "_fbp": { "type": [ "string", "null" ], "description": "Cookie _fbp do Facebook (browser ID), quando presente." }, "fbclid": { "type": [ "string", "null" ], "description": "Facebook click ID (fbclid), quando presente." }, "ref": { "type": [ "string", "null" ], "description": "Refer\u00eancia interna de rastreio (ex.: code de afilia\u00e7\u00e3o)." } } }, "subscription": { "type": "object", "description": "Presente somente quando a venda pertence a uma assinatura.", "properties": { "code": { "type": "string", "description": "C\u00f3digo da assinatura." }, "charges_made": { "type": "integer", "description": "Quantidade de cobran\u00e7as j\u00e1 realizadas." }, "next_charge_date": { "type": [ "string", "null" ], "description": "Data da pr\u00f3xima cobran\u00e7a (datetime)." }, "subscription_status_enum": { "type": "integer", "description": "Status da assinatura. Valores: 1 = trial, 2 = active (ativa), 3 = cancelled (cancelada), 4 = awaiting_payment (aguardando pagamento), 5 = expired (expirada), 6 = in_mediation (em disputa), 7 = finished (finalizada)." }, "status": { "type": "string", "description": "Chave textual do status da assinatura." }, "status_event": { "type": [ "string", "null" ], "description": "Chave do evento de assinatura que originou o envio (ex.: renova\u00e7\u00e3o, cancelamento)." } } }, "webhook_owner": { "type": "string", "description": "Presente somente quando h\u00e1 afilia\u00e7\u00e3o configurada: code da afilia\u00e7\u00e3o dona do cadastro do webhook." }, "commission": { "type": "array", "description": "Presente somente junto com webhook_owner. Uma entrada por participante da venda.", "items": { "type": "object", "properties": { "affiliation_code": { "type": "string", "description": "Code da afilia\u00e7\u00e3o (ou do usu\u00e1rio, quando a afilia\u00e7\u00e3o n\u00e3o existe mais)." }, "affiliation_type_enum": { "type": "integer", "description": "Tipo de afilia\u00e7\u00e3o. Valores: 0 = platform (plataforma), 1 = producer (produtor), 2 = co_producer (coprodutor), 3 = affiliate_management (gestor de afiliados), 4 = partner (parceiro), 5 = affiliate (afiliado), 6 = premium, 7 = provider (fornecedor), 8 = cpa." }, "affiliation_type_enum_key": { "type": "string", "description": "Chave textual do tipo de afilia\u00e7\u00e3o." }, "name": { "type": "string", "description": "Nome de quem recebe a comiss\u00e3o." }, "email": { "type": "string", "description": "E-mail de quem recebe a comiss\u00e3o." }, "identification_number": { "type": "string", "description": "Documento de quem recebe a comiss\u00e3o." }, "commission_amount": { "type": "number", "description": "Valor da comiss\u00e3o." }, "currency_enum": { "type": [ "integer", "null" ], "description": "Moeda da comiss\u00e3o (presente quando quem cadastrou \u00e9 produtor\/coprodutor). Valores: 1 = BRL (Real), 2 = USD (D\u00f3lar), 3 = EUR (Euro)." }, "currency_enum_key": { "type": [ "string", "null" ], "description": "Chave textual da moeda da comiss\u00e3o." } } } }, "marketplaces": { "type": "object", "description": "Presente somente quando o produto tem marketplaces ativos cobrados na venda. As CHAVES do objeto s\u00e3o os c\u00f3digos dos marketplaces.", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do marketplace." }, "itens": { "type": "number", "description": "Soma das transa\u00e7\u00f5es de itens de marketplace cobradas na venda." }, "sale": { "type": "number", "description": "Soma das transa\u00e7\u00f5es de venda de marketplace cobradas na venda." } } } }, "url_send_webhook_pay": { "type": "string", "description": "A pr\u00f3pria URL cadastrada, com os placeholders j\u00e1 substitu\u00eddos pelos dados desta venda." } } }, "example": { "token": "b3e2f1a4c5d6789012345678abcdef01", "code": "PPCPMT000000000", "sale_amount": 197.9, "currency_enum": 1, "currency_enum_key": "BRL", "coupon_code": null, "installments": 3, "installment_amount": 65.97, "shipping_type_enum": null, "shipping_type_enum_key": null, "shipping_amount": 0, "payment_method_enum": 6, "payment_method_enum_key": "master", "payment_type_enum": 1, "payment_type_enum_key": "credit_card", "payment_format_enum": 1, "payment_format_enum_key": "regular", "original_code": null, "billet_url": null, "billet_number": null, "billet_expiration": null, "quantity": 1, "sale_status_enum": 2, "sale_status_enum_key": "approved", "sale_status_detail": "paid", "date_created": "2026-07-20 14:32:10", "date_approved": "2026-07-20 14:32:15", "tracking": null, "url_tracking": null, "checkout_type_enum": "regular", "academy_access_url": null, "product": { "code": "PPPBEXEMPLO", "name": "Curso de Marketing Digital", "external_reference": "00000", "guarantee": 30 }, "plan": { "code": "PPLQEXEMPLO", "name": "Plano Mensal", "offer_name": "Curso de Marketing Digital: [Afiliados] [Funil 269] [Mensal]", "quantity": 1, "tax_code": null }, "plan_itens": [], "customer": { "customer_type_enum": 1, "customer_type_enum_key": "percent", "full_name": "Maria Compradora", "email": "maria@example.com", "identification_type": "CPF", "identification_number": "00000000000", "birthday": null, "date_birth": null, "phone_extension": "55", "phone_area_code": "11", "phone_number": "988887777", "phone_formated": "(11) 98888-7777", "phone_formated_ddi": "+5511988887777", "ip": "203.0.113.10", "user_agent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64)", "street_name": "", "street_number": "", "district": "", "complement": "", "zip_code": "", "city": "", "state": "", "country": "BR", "language": "pt_BR" }, "metadata": { "src": "organic", "sck": null, "utm_source": "facebook", "utm_medium": "cpc", "utm_campaign": "campanha-exemplo", "utm_content": "anuncio-01", "utm_term": null, "ttclid": null, "_fbc": "fb.1.0000000000000.EXEMPLO", "_fbp": "fb.1.0000000000000.0000000000", "fbclid": "EXEMPLOfbclid", "ref": "PPA1EXEMPLO" }, "subscription": { "code": "PPCS000000", "charges_made": 1, "next_charge_date": "2026-08-20 14:32:15", "subscription_status_enum": 2, "status": "active", "status_event": null }, "webhook_owner": "PPA0EXEMPLO", "commission": [ { "affiliation_code": "PPA1EXEMPLO", "affiliation_type_enum": 5, "affiliation_type_enum_key": "affiliate", "name": "Jo\u00e3o Afiliado", "email": "joao@example.com", "identification_number": "00000000000", "commission_amount": 39.58, "currency_enum": 1, "currency_enum_key": "BRL" }, { "name": "PerfectPay", "commission_amount": 9.9, "affiliation_type_enum": 0 } ], "url_send_webhook_pay": "https:\/\/meusite.com\/postback?transacao=PPCPMT000000000&status=approved&valor=197.90" } } } }, "responses": { "200": { "description": "A URL do produtor deve responder 2xx para confirmar o recebimento." } } } } } }