{ "schemes": [], "swagger": "2.0", "info": { "description": "API de Online Sales do Yumepay. Parceiros enviam requisições de pré-captura e consulta de status PIX.", "title": "Yumepay Online Sales API", "contact": {}, "version": "1.0" }, "host": "localhost:8001", "basePath": "/", "paths": { "/api/token/": { "post": { "description": "Troca e-mail e senha por access e refresh. O campo username recebe o e-mail completo, não o nome curto de login. Qualquer falha devolve 401. Limitado por IP.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Obter o par de tokens", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "429": { "description": "Too Many Requests", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/token/refresh/": { "post": { "description": "Devolve um novo access. O refresh não é rotacionado e segue válido. Limitado por IP.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Renovar o token de acesso", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "429": { "description": "Too Many Requests", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/checkout-links/{guid}": { "get": { "description": "Público. Devolve os dados necessários para montar a tela. payerName traz o nome do pagador, gravado no passo do pagador.", "produces": [ "application/json" ], "tags": [ "checkout-links" ], "summary": "Carregar o checkout de um link", "parameters": [ { "type": "string", "description": "payment_link_guid devolvido na criação do link", "name": "guid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/checkout-links/{guid}/address": { "patch": { "description": "Público. O campo do CEP se chama cep. complement e reference são opcionais.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "checkout-links" ], "summary": "Gravar o endereço do pagador", "parameters": [ { "type": "string", "description": "payment_link_guid", "name": "guid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Conflict", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/checkout-links/{guid}/pay": { "put": { "description": "Público. Recebe o cartão cifrado com a chave pública RSA, padding PKCS#1 v1.5. Repetir num link já pago devolve 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "checkout-links" ], "summary": "Concluir o pagamento do link", "parameters": [ { "type": "string", "description": "payment_link_guid", "name": "guid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Conflict", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/checkout-links/{guid}/payer": { "patch": { "description": "Público. payer_name é o nome do pagador (merchant_name segue aceito como alias). O documento é validado com dígito verificador.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "checkout-links" ], "summary": "Gravar os dados do pagador", "parameters": [ { "type": "string", "description": "payment_link_guid", "name": "guid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Conflict", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/cielo/chargeback/accept/": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel do aceite de chargeback da Cielo (PUT). Aceitar considera a venda inválida e concorda com o estorno pela Cielo. O status HTTP e o corpo da Cielo são repassados como recebidos.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Aceite de contestação Cielo", "parameters": [ { "description": "Lista de contestações a aceitar", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.chargebackAcceptRequest" } } ], "responses": { "200": { "description": "Resposta da Cielo", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Body inválido ou erro de negócio da Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": true } }, "412": { "description": "Pré-condições inválidas (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/consult/": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel da consulta de chargeback da Cielo. status/page/pageSize e ordenação vão por query; os filtros vão no corpo JSON. O status HTTP e o corpo da Cielo são repassados como recebidos (200 é um envelope de paginação com os itens em \"content\").", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Consulta de contestações Cielo (pendentes ou tratadas)", "parameters": [ { "enum": [ "PENDING", "DONE" ], "type": "string", "description": "PENDING (pendentes) ou DONE (tratadas)", "name": "status", "in": "query", "required": true }, { "type": "string", "default": "0", "description": "Página; 0 é a primeira", "name": "page", "in": "query" }, { "type": "string", "default": "200", "description": "Registros por página; máximo 200", "name": "pageSize", "in": "query" }, { "enum": [ "receptionDate", "treatmentDeadline" ], "type": "string", "description": "Campo de ordenação", "name": "orderBy", "in": "query" }, { "enum": [ "asc", "desc" ], "type": "string", "description": "Sentido da ordenação", "name": "Order", "in": "query" }, { "description": "Filtros da consulta", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/handler.chargebackConsultRequest" } } ], "responses": { "200": { "description": "Envelope de paginação da Cielo", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "status inválido ou JSON malformado", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": true } }, "412": { "description": "Pré-condições inválidas (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/contested/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lista as contestações recebidas via webhook que ainda não foram tratadas (aceitas/recusadas), com os dados necessários para a decisão do operador.", "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Lista de contestações pendentes", "responses": { "200": { "description": "results com as contestações pendentes", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Erro interno", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/contested/history/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lista as contestações já tratadas (aceitas, ou recusadas com desfecho win/loss), uma por chargeback, desfecho mais recente primeiro. Paginada por limit/offset.", "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Histórico de contestações tratadas", "parameters": [ { "type": "integer", "description": "Tamanho da página (default 50)", "name": "limit", "in": "query" }, { "type": "integer", "description": "Deslocamento (default 0)", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "results com o histórico de contestações", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Erro interno", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/document-issuer/{establishmentNumber}/{idDocumento}/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel do download de documento do emissor da Cielo. idDocumento é obtido antes via list-issuer-documents (fluxo: listar → baixar). Diferente das rotas JSON, repassa os bytes crus e o Content-Type/Content-Disposition retornados pela Cielo (sem forçar application/json).", "produces": [ "application/octet-stream" ], "tags": [ "cielo-chargeback" ], "summary": "Download de documento do emissor", "parameters": [ { "type": "string", "description": "Número do estabelecimento", "name": "establishmentNumber", "in": "path", "required": true }, { "type": "string", "description": "Id do documento (obtido na listagem)", "name": "idDocumento", "in": "path", "required": true } ], "responses": { "200": { "description": "Bytes do documento (Content-Type repassado da Cielo)", "schema": { "type": "file" } }, "400": { "description": "path params ausentes/ inválidos", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/lifecycle/{idCase}/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel da pesquisa de ciclo de vida da Cielo por idCase. O status HTTP e o corpo da Cielo são repassados como recebidos (200 traz o mesmo payload da notificação de lifecycle, incluindo o campo ActionCicleDate).", "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Pesquisa de ciclo de vida do chargeback Cielo", "parameters": [ { "type": "string", "description": "Id do case do chargeback (máx. 20)", "name": "idCase", "in": "path", "required": true } ], "responses": { "200": { "description": "Ciclo de vida do chargeback (LifecyclePayload)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "idCase ausente/ inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": true } }, "412": { "description": "Pré-condições inválidas (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/list-issuer-documents/{establishmentNumber}/{idChargeback}/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel da listagem de documentos do emissor da Cielo. Fornece nomes e códigos (idDocumento, nameFile) dos documentos enviados pelo emissor. Fluxo documentado: listar aqui e, em seguida, baixar via document-issuer. O status HTTP e o corpo da Cielo são repassados como recebidos.", "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Lista documentos do emissor", "parameters": [ { "type": "string", "description": "Número do estabelecimento", "name": "establishmentNumber", "in": "path", "required": true }, { "type": "string", "description": "Id do chargeback", "name": "idChargeback", "in": "path", "required": true } ], "responses": { "200": { "description": "Documentos do emissor (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "path params ausentes/ inválidos", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": true } }, "412": { "description": "Pré-condições inválidas (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/pending-count/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retorna quantas contestações (chargebacks) recebidas via webhook ainda não foram tratadas. Usado pelo badge do portal (polling).", "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Contagem de contestações pendentes", "responses": { "200": { "description": "count de pendentes", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Erro interno", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/refuse/": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel da recusa de chargeback da Cielo (PUT). Recusar defende a venda anexando evidência (documento base64) e um texto de justificativa. Restrições do documento: formatos .TIF/.TIFF/.PDF/.JPEG, até 8MB, máximo de 10 páginas, e o nome do documento deve ser igual ao IdCase. O status HTTP e o corpo da Cielo são repassados como recebidos.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Recusa de contestação Cielo", "parameters": [ { "description": "Dados e evidência da recusa", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.chargebackRefuseRequest" } } ], "responses": { "200": { "description": "Resposta da Cielo", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Body inválido, restrição de arquivo ou erro de negócio da Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": true } }, "412": { "description": "Pré-condições inválidas (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/cielo/chargeback/support-document/{establishmentNumber}/{idChargeback}/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Proxy fiel da consulta de documento de defesa da Cielo. Quando a contestação é recusada, o documento de defesa anexado fica disponível para consulta. O status HTTP e o corpo da Cielo são repassados como recebidos.", "produces": [ "application/json" ], "tags": [ "cielo-chargeback" ], "summary": "Consulta de documento (defesa anexada na recusa)", "parameters": [ { "type": "string", "description": "Número do estabelecimento", "name": "establishmentNumber", "in": "path", "required": true }, { "type": "string", "description": "Id do chargeback", "name": "idChargeback", "in": "path", "required": true } ], "responses": { "200": { "description": "Documento de defesa (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "path params ausentes/ inválidos", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Sem permissão (repassado da Cielo/auth)", "schema": { "type": "object", "additionalProperties": true } }, "412": { "description": "Pré-condições inválidas (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Erro interno (Cielo)", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha de comunicação com a Cielo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Integração Cielo Chargeback não configurada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/commercial-contacts/": { "get": { "description": "Lista os gerentes comerciais em ordem alfabética, para seleção no cadastro de lojista.", "produces": [ "application/json" ], "tags": [ "commercial-contacts" ], "summary": "Gerentes comerciais", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "description": "Cria um contato reutilizável, que pode ser associado a vários lojistas.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "commercial-contacts" ], "summary": "Cadastra um gerente comercial", "responses": { "201": { "description": "Created", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/commercial-contacts/{pk}/": { "patch": { "description": "Atualiza os dados do contato. Campo ausente preserva o valor atual.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "commercial-contacts" ], "summary": "Edita um gerente comercial", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/global-ceo/": { "get": { "description": "Retorna o contato global do CEO, ou nulo quando ainda não foi cadastrado.", "produces": [ "application/json" ], "tags": [ "commercial-contacts" ], "summary": "CEO global", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } }, "put": { "description": "Grava a configuração única do CEO. O contato não pertence a lojista nem a carteira.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "commercial-contacts" ], "summary": "Cadastra ou edita o CEO global", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/me/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Devolve o lojista vinculado ao token. O username aqui é o nome curto de login, não o e-mail.", "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Conferir a credencial", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/online/sales/pre-capture/": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Inicia o fluxo de pré-captura para uma venda online (PIX/cartão). Aceita JWT do /api/token/, token individual do lojista ou token fixo do sistema. HTTP 200 não significa aprovação — sempre valide data.approved e data.sale_status.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "online-sales" ], "summary": "Pré-captura de venda online", "parameters": [ { "description": "Dados da venda", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.preCaptureRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.preCaptureSuccessResponse" } }, "400": { "description": "Campos obrigatórios ausentes ou inválidos", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Erro interno", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Erro no gateway de pagamento", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/online/sales/{id}/cancel-capture/": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Cancela uma venda de cartão pré-autorizada (PRE_CAPTURED) ou capturada (CONFIRMED, se allow_void_on_confirmed). Não se aplica a PIX.", "produces": [ "application/json" ], "tags": [ "online-sales" ], "summary": "Cancelar/estornar venda", "parameters": [ { "type": "integer", "description": "ID da venda online", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "502": { "description": "Bad Gateway", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/online/sales/{id}/capture/": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Confirma e captura uma venda de cartão previamente autorizada (status PRE_CAPTURED). Não se aplica a PIX.", "produces": [ "application/json" ], "tags": [ "online-sales" ], "summary": "Confirmar/capturar venda", "parameters": [ { "type": "integer", "description": "ID da venda online", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "502": { "description": "Bad Gateway", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/online/sales/{id}/pix/status/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retorna o status atual do pagamento PIX associado à venda informada. Não chama nenhum gateway externo — apenas lê o banco e devolve o status atual. Aceita token fixo do sistema ou token individual do lojista.", "produces": [ "application/json" ], "tags": [ "online-sales" ], "summary": "Status do PIX de uma venda online", "parameters": [ { "type": "integer", "description": "ID da venda online (online_sale_id)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Token ausente ou inválido", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Acesso negado — venda pertence a outro lojista", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Venda não encontrada", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Erro interno", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/payment-links/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Devolve o envelope de listagem: filtros aplicados, links, opções para montar a tela, resumo e paginação.", "produces": [ "application/json" ], "tags": [ "payment-links" ], "summary": "Listar links de pagamento", "parameters": [ { "type": "string", "description": "day, week, month ou year", "name": "period", "in": "query" }, { "type": "string", "description": "Data inicial, YYYY-MM-DD ou DD/MM/YYYY", "name": "start_date", "in": "query" }, { "type": "string", "description": "Data final, mesmos formatos", "name": "end_date", "in": "query" }, { "type": "integer", "description": "Status do link", "name": "status", "in": "query" }, { "type": "integer", "description": "ID do lojista, apenas para administradores", "name": "merchant", "in": "query" }, { "type": "integer", "description": "Número da página", "name": "page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Cria um link de checkout por cartão de crédito. O lojista vem do token — não envie merchant. payer_name pré-preenche o nome do pagador (merchant_name é alias).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "payment-links" ], "summary": "Criar link de pagamento", "responses": { "201": { "description": "Created", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/payment-links/{id}/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Mesmo formato da criação. É por aqui que se acompanha o status até a confirmação do pagamento.", "produces": [ "application/json" ], "tags": [ "payment-links" ], "summary": "Detalhe de um link de pagamento", "parameters": [ { "type": "integer", "description": "ID do link", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/public-key": { "get": { "description": "Pública. Devolve a chave RSA 2048 em PEM, usada para cifrar o cartão nos dois checkouts. Padding PKCS#1 v1.5.", "produces": [ "application/json" ], "tags": [ "checkout-links" ], "summary": "Chave pública RSA", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/settlements/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lista liquidações com filtros de período/data, merchant (superuser) e status, paginadas de 10 em 10. Mesmo contrato do endpoint Django.", "produces": [ "application/json" ], "tags": [ "Liquidações" ], "summary": "Listagem de liquidações", "parameters": [ { "type": "string", "description": "day|month|year (default day)", "name": "period", "in": "query" }, { "type": "string", "description": "DD/MM/YYYY, YYYY-MM-DD ou DD-MM-YYYY", "name": "start_date", "in": "query" }, { "type": "string", "description": "idem start_date", "name": "end_date", "in": "query" }, { "type": "integer", "description": "ID do lojista (somente superuser)", "name": "merchant", "in": "query" }, { "type": "integer", "description": "Status da liquidação", "name": "status", "in": "query" }, { "type": "integer", "description": "Página (default 1)", "name": "page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Cria uma liquidação manual no portal. Superusuário define o merchant; lojista cria para seu próprio merchant.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Liquidações" ], "summary": "Criação manual de liquidação", "responses": { "201": { "description": "Created", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/settlements/{pk}/": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retorna a liquidação e seus recebíveis (paginados de 10 em 10, ordenados por -due_date). Mesmo contrato do endpoint Django.", "produces": [ "application/json" ], "tags": [ "Liquidações" ], "summary": "Detalhe de liquidação", "parameters": [ { "type": "integer", "description": "ID da liquidação", "name": "pk", "in": "path", "required": true }, { "type": "integer", "description": "Página dos recebíveis (default 1)", "name": "page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Usuário sem lojista vinculado", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Liquidação não encontrada no escopo", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Atualiza campos de uma liquidação manual existente. Lojista comum só pode atualizar suas próprias liquidações.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Liquidações" ], "summary": "Edição manual de liquidação", "parameters": [ { "type": "integer", "description": "ID da liquidação", "name": "pk", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/subscription-checkout/{guid}": { "get": { "description": "Público. Expõe apenas o necessário para montar a tela de ativação.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Carregar o checkout de uma assinatura pendente", "parameters": [ { "type": "string", "description": "paymentGuid devolvido na criação sem cartão", "name": "guid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscription-checkout/{guid}/pay": { "put": { "description": "Público. Recebe o cartão cifrado com a chave pública RSA. A assinatura passa a ACTIVE e, se o vencimento for hoje, a cobrança sai na hora.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Ativar a assinatura com o cartão", "parameters": [ { "type": "string", "description": "paymentGuid", "name": "guid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Conflict", "schema": { "type": "object", "additionalProperties": true } }, "422": { "description": "Cartão recusado pelo adquirente", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Falha real de gateway (timeout/rede/5xx)", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Lista assinaturas do lojista", "parameters": [ { "type": "integer", "description": "Status da assinatura", "name": "status", "in": "query" }, { "type": "string", "description": "Status da última cobrança: CONFIRMED, DENIED, REFUNDED ou código numérico", "name": "lastChargeStatus", "in": "query" }, { "type": "integer", "description": "Quantidade mínima de negações consecutivas (\u003e=1)", "name": "minConsecutiveDenied", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } }, "post": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Cria uma assinatura recorrente", "parameters": [ { "description": "Payload de criação: use apenas uma forma de cartão (campos em claro, encryptedCardData/encrypted_card_data, ou sourceSubscriptionId)", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.SubscriptionCreateRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "sourceSubscriptionId sem cartão reaproveitável ou de outro pagador (payerDocument diferente)", "schema": { "type": "object", "additionalProperties": true } }, "422": { "description": "Cartão recusado pelo adquirente", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/charges": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Lista cobranças com filtros opcionais. Aceita JWT do portal e token de lojista.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Lista cobranças recorrentes do lojista", "parameters": [ { "type": "string", "description": "Cliente, descrição ou referência", "name": "search", "in": "query" }, { "type": "integer", "description": "0=processando, 1=confirmada, 2=negada, 3=estornada", "name": "status", "in": "query" }, { "type": "integer", "description": "ID da assinatura", "name": "subscriptionId", "in": "query" }, { "type": "string", "description": "Vencimento inicial YYYY-MM-DD", "name": "startDate", "in": "query" }, { "type": "string", "description": "Vencimento final YYYY-MM-DD (inclusivo)", "name": "endDate", "in": "query" }, { "type": "integer", "description": "Página", "name": "page", "in": "query" }, { "type": "integer", "description": "Tamanho da página (máximo 200)", "name": "pageSize", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.subscriptionChargesSuccessResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/overview": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Totais de assinaturas; cobranças por vencimento no mês atual de Brasília. Valores monetários em centavos. Aceita JWT do portal e token de lojista.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Resumo de recorrência do lojista autenticado", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.subscriptionOverviewSuccessResponse" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal Server Error", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/retry-policy": { "get": { "security": [ { "BearerAuth": [] } ], "description": "enabled indica se a retentativa está ligada. intervalsDays e maxRetries são os que valem com ela ligada.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Consulta a política de retentativa de cobrança negada do lojista", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/{id}/": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Detalhe de uma assinatura", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Permite editar assinaturas ACTIVE e PENDING_PAYMENT. Campos aceitos: value, cycle, nextDueDate, endDate, description. Qualquer outro campo retorna 400 com rejectedFields.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Atualiza uma assinatura", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true }, { "description": "Payload de atualização", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.SubscriptionUpdateRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Conflict", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/{id}/callback": { "put": { "security": [ { "BearerAuth": [] } ], "description": "Exige http ou https com host. Vazio é aceito e desliga os webhooks da assinatura.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Atualizar a URL de callback", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "401": { "description": "Unauthorized", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/v1/subscriptions/{id}/cancel": { "post": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Cancela uma assinatura", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/{id}/card": { "put": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Atualiza o cartao de uma assinatura", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true }, { "description": "Payload de troca de cartão: use apenas uma forma (campos em claro, encryptedCardData/encrypted_card_data, ou sourceSubscriptionId)", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.SubscriptionUpdateCardRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Assinatura não ACTIVE, ou sourceSubscriptionId sem cartão reaproveitável ou de outro pagador", "schema": { "type": "object", "additionalProperties": true } }, "422": { "description": "Cartão recusado pelo adquirente", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/{id}/charges/": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Lista cobranças de uma assinatura", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/subscriptions/{id}/charges/{chargeId}/refund": { "post": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Estorna uma cobrança de assinatura", "parameters": [ { "type": "integer", "description": "ID da assinatura", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "ID da cobrança", "name": "chargeId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Conflict", "schema": { "type": "object", "additionalProperties": true } }, "502": { "description": "Bad Gateway", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/v1/yume-fees/": { "get": { "description": "Retorna a configuração única das taxas YumePay (antecipação e administração).", "produces": [ "application/json" ], "tags": [ "yume-fees" ], "summary": "Taxas YumePay", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } }, "patch": { "description": "Grava a taxa de antecipação e/ou de administração. Campo ausente preserva o valor atual; campo nulo limpa a taxa.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "yume-fees" ], "summary": "Atualiza as taxas YumePay", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/payment": { "post": { "description": "Recebe callbacks ecommerce e POS da Phoebus/PayStore com token dedicado.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "callbacks" ], "summary": "Callback Phoebus/PayStore", "parameters": [ { "type": "string", "description": "Bearer token ou token raw", "name": "Authorization", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "x-api-key", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "token", "in": "header" }, { "description": "Payload Phoebus/PayStore", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.phoebusCallbackRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.phoebusCallbackEnvelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } } } } }, "/payment/": { "post": { "description": "Recebe callbacks ecommerce e POS da Phoebus/PayStore com token dedicado.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "callbacks" ], "summary": "Callback Phoebus/PayStore", "parameters": [ { "type": "string", "description": "Bearer token ou token raw", "name": "Authorization", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "x-api-key", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "token", "in": "header" }, { "description": "Payload Phoebus/PayStore", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.phoebusCallbackRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.phoebusCallbackEnvelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } } } } }, "/payments/": { "post": { "description": "Recebe callbacks ecommerce e POS da Phoebus/PayStore com token dedicado.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "callbacks" ], "summary": "Callback Phoebus/PayStore", "parameters": [ { "type": "string", "description": "Bearer token ou token raw", "name": "Authorization", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "x-api-key", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "token", "in": "header" }, { "description": "Payload Phoebus/PayStore", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.phoebusCallbackRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.phoebusCallbackEnvelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } } } } }, "/phoebus/callback/payment-transaction/": { "post": { "description": "Recebe callbacks ecommerce e POS da Phoebus/PayStore com token dedicado.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "callbacks" ], "summary": "Callback Phoebus/PayStore", "parameters": [ { "type": "string", "description": "Bearer token ou token raw", "name": "Authorization", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "x-api-key", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "token", "in": "header" }, { "description": "Payload Phoebus/PayStore", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.phoebusCallbackRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.phoebusCallbackEnvelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } } } } }, "/phoebus/callback/payment-transaction/payment": { "post": { "description": "Recebe callbacks ecommerce e POS da Phoebus/PayStore com token dedicado.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "callbacks" ], "summary": "Callback Phoebus/PayStore", "parameters": [ { "type": "string", "description": "Bearer token ou token raw", "name": "Authorization", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "x-api-key", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "token", "in": "header" }, { "description": "Payload Phoebus/PayStore", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.phoebusCallbackRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.phoebusCallbackEnvelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } } } } }, "/phoebus/callback/payment-transaction/payment/": { "post": { "description": "Recebe callbacks ecommerce e POS da Phoebus/PayStore com token dedicado.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "callbacks" ], "summary": "Callback Phoebus/PayStore", "parameters": [ { "type": "string", "description": "Bearer token ou token raw", "name": "Authorization", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "x-api-key", "in": "header" }, { "type": "string", "description": "Token alternativo", "name": "token", "in": "header" }, { "description": "Payload Phoebus/PayStore", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handler.phoebusCallbackRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.phoebusCallbackEnvelope" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.phoebusCallbackErrorEnvelope" } } } } } }, "definitions": { "handler.SubscriptionCreateRequest": { "type": "object", "properties": { "callbackUrl": { "type": "string", "maxLength": 500, "example": "https://merchant.example.com/webhook" }, "cardHolder": { "type": "string", "example": "Client Name" }, "cardNumber": { "type": "string", "example": "4111111111111111" }, "cvv": { "type": "string", "example": "123" }, "cycle": { "type": "string", "enum": [ "WEEKLY", "BIWEEKLY", "MONTHLY", "QUARTERLY", "SEMIANNUALLY", "YEARLY" ], "example": "MONTHLY" }, "description": { "type": "string", "maxLength": 255, "example": "Monthly plan" }, "encryptedCardData": { "type": "string", "example": "base64-ciphertext" }, "encrypted_card_data": { "type": "string", "example": "base64-ciphertext" }, "endDate": { "type": "string", "format": "date", "example": "2031-10-10" }, "expirationDate": { "description": "MM/AAAA (ou MM/AA), mês de 01 a 12 e não vencido.", "type": "string", "example": "12/2030" }, "externalReference": { "type": "string", "maxLength": 100, "example": "sub_123" }, "nextDueDate": { "description": "Primeiro vencimento (YYYY-MM-DD), hoje ou depois. Data passada retorna 400.", "type": "string", "format": "date", "example": "2030-10-10" }, "payerDocument": { "description": "CPF ou CNPJ com dígito verificador válido, com ou sem pontuação.", "type": "string", "maxLength": 20, "example": "52998224725" }, "payerEmail": { "type": "string", "maxLength": 100, "example": "client@example.com" }, "payerName": { "type": "string", "maxLength": 100, "example": "Client Name" }, "payerPhone": { "type": "string", "maxLength": 20, "example": "+5511999999999" }, "sourceSubscriptionId": { "type": "integer", "example": 321 }, "value": { "description": "Valor em centavos, inteiro (R$ 19,90 = 1990). Fração, zero ou negativo retorna 400.", "type": "integer", "maximum": 2147483647, "minimum": 1, "example": 1990 } } }, "handler.SubscriptionUpdateCardRequest": { "type": "object", "properties": { "cardHolder": { "type": "string", "example": "Client Name" }, "cardNumber": { "type": "string", "example": "4111111111111111" }, "cvv": { "type": "string", "example": "123" }, "encryptedCardData": { "type": "string", "example": "base64-ciphertext" }, "encrypted_card_data": { "type": "string", "example": "base64-ciphertext" }, "expirationDate": { "type": "string", "example": "12/2030" }, "sourceSubscriptionId": { "type": "integer", "example": 321 } } }, "handler.SubscriptionUpdateRequest": { "type": "object", "properties": { "cycle": { "type": "string", "enum": [ "WEEKLY", "BIWEEKLY", "MONTHLY", "QUARTERLY", "SEMIANNUALLY", "YEARLY" ], "example": "MONTHLY" }, "description": { "type": "string", "maxLength": 255, "example": "Monthly plan" }, "endDate": { "type": "string", "format": "date", "example": "2031-10-10" }, "nextDueDate": { "description": "YYYY-MM-DD, hoje ou depois. Data passada retorna 400.", "type": "string", "format": "date", "example": "2030-10-10" }, "value": { "description": "Valor em centavos, inteiro. Vale a partir da próxima cobrança gerada.", "type": "integer", "maximum": 2147483647, "minimum": 1, "example": 1990 } } }, "handler.chargebackAcceptItem": { "type": "object", "properties": { "establishmentNumber": { "type": "string", "example": "1234567890" }, "idChargeback": { "type": "string", "example": "CB-2024-0001" }, "userName": { "type": "string", "example": "analista@empresa.com.br" } } }, "handler.chargebackAcceptRequest": { "type": "object", "properties": { "updateChargeback": { "type": "array", "items": { "$ref": "#/definitions/handler.chargebackAcceptItem" } } } }, "handler.chargebackConsultRequest": { "type": "object", "properties": { "cardAssociationCode": { "type": "array", "items": { "type": "integer" } }, "endNotificationPeriod": { "type": "string", "example": "2024-12-31" }, "establishmentNumber": { "type": "array", "items": { "type": "string" } }, "hierarchyType": { "type": "string", "example": "4" }, "idCase": { "type": "string" }, "mainCustomer": { "type": "string" }, "nsu": { "type": "string" }, "process": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "array", "items": { "type": "string" } }, "startNotificationPeriod": { "type": "string", "example": "2024-12-01" }, "tid": { "type": "string" } } }, "handler.chargebackRefuseRequest": { "type": "object", "properties": { "establishmentNumber": { "type": "string", "example": "1234567890" }, "file": { "type": "string" }, "idChargeback": { "type": "string", "example": "987654321" }, "nameFile": { "type": "string", "example": "987654321.pdf" }, "reasonToRefuse": { "type": "string", "example": "Venda legítima; segue comprovante de entrega." }, "userName": { "type": "string", "example": "analista@empresa.com.br" } } }, "handler.phoebusCallbackEnvelope": { "type": "object", "properties": { "data": {}, "status": { "type": "string", "example": "success" } } }, "handler.phoebusCallbackErrorEnvelope": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid JSON payload" }, "status": { "type": "string", "example": "error" } } }, "handler.phoebusCallbackRequest": { "type": "object", "additionalProperties": {} }, "handler.preCaptureDataResponse": { "type": "object", "properties": { "approved": { "type": "boolean", "example": false }, "denial": { "$ref": "#/definitions/handler.preCaptureDenialResponse" }, "online_sale_id": { "type": "integer", "example": 12345 }, "pix_payload": { "type": "string" }, "pix_qr_code": { "type": "string" }, "sale_status": { "type": "string", "example": "DENIED" } } }, "handler.preCaptureDenialResponse": { "type": "object", "properties": { "code": { "type": "string", "example": "57" }, "message": { "type": "string", "example": "Operation not permitted to cardholder." } } }, "handler.preCaptureRequest": { "type": "object", "properties": { "card_holder": { "type": "string", "maxLength": 100, "example": "JOAO DA SILVA" }, "document": { "type": "string", "maxLength": 20, "example": "12345678901" }, "email": { "type": "string", "maxLength": 100, "example": "joao@email.com" }, "mobile": { "type": "string", "maxLength": 20, "example": "11999999999" }, "payment_type": { "type": "string", "example": "PIX" }, "value": { "description": "Valor em centavos, inteiro (R$ 10,00 = 1000). Fração, zero ou negativo retorna 400.", "type": "integer", "maximum": 2147483647, "minimum": 1, "example": 1000 }, "webhookUrl": { "type": "string", "example": "https://meu-sistema.com/callback" } } }, "handler.preCaptureSuccessResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.preCaptureDataResponse" }, "status": { "type": "string", "example": "success" } } }, "handler.subscriptionChargesPaginationResponse": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 120 }, "totalPages": { "type": "integer", "example": 5 } } }, "handler.subscriptionChargesSuccessResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/subscription.PortalCharge" } }, "pagination": { "$ref": "#/definitions/handler.subscriptionChargesPaginationResponse" } } }, "handler.subscriptionOverviewPeriodResponse": { "type": "object", "properties": { "endDate": { "type": "string", "example": "2026-09-30" }, "startDate": { "type": "string", "example": "2026-09-01" } } }, "handler.subscriptionOverviewSuccessResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/subscription.Overview" }, "period": { "$ref": "#/definitions/handler.subscriptionOverviewPeriodResponse" } } }, "subscription.Overview": { "type": "object", "properties": { "active": { "type": "integer" }, "confirmedValue": { "type": "integer" }, "deniedCount": { "type": "integer" }, "pendingActivation": { "type": "integer" } } }, "subscription.PortalCharge": { "type": "object", "properties": { "attempts": { "type": "integer" }, "denialCode": { "type": "string" }, "denialMessage": { "type": "string" }, "description": { "type": "string" }, "dueDate": { "type": "string" }, "id": { "type": "integer" }, "nextRetryAt": { "type": "string" }, "payerName": { "type": "string" }, "status": { "type": "integer" }, "subscriptionId": { "type": "integer" }, "value": { "type": "integer" } } } }, "securityDefinitions": { "BearerAuth": { "description": "JWT de acesso do /api/token/, token individual do lojista (Merchant.online_token) ou token fixo do sistema (FIXED_BEARER_TOKEN, só Online Sales). Formato: Bearer \u003ctoken\u003e", "type": "apiKey", "name": "Authorization", "in": "header" } } }