{ "openapi": "3.1.0", "info": { "title": "SharkPay API", "version": "2026-10-14", "summary": "API HTTP/JSON do gateway SharkPay.", "description": "API REST do SharkPay para cobranças (Pix, boleto, cartão), saques Pix, clientes, checkout hospedado e webhooks.\n\n**Esta especificação descreve apenas o que está implementado no backend.** Itens planejados ficam no changelog\ndo site (`/developers/changelog`) e **não** aparecem aqui como operações.\n\n## Autenticação\n1. `POST /api/auth` com `Authorization: Basic base64(public_key:secret_key)` devolve um token Bearer (Passport).\n2. Use `Authorization: Bearer ` nas demais chamadas.\nAs chaves ficam no painel (Perfil). A chave secreta **nunca** deve ir para navegador ou app.\n\n## Idempotência\nEnvie `Idempotency-Key` (8–100 caracteres `A-Za-z0-9_.:-`) em operações `POST` de criação.\nÉ **obrigatório** em `POST /api/pixout/create`. Mesma chave + mesmo corpo reenvia a resposta original\n(`Idempotent-Replayed: true`); mesma chave + corpo diferente → 422; ainda em processamento → 409.\n\n## Limites\n`POST /api/auth`: 10/min por IP. `GET /api/cep/search/{cep}`: 30/min por IP. Demais rotas: 60/min por conta (ou IP).\nExcedido → `429` com `Retry-After`.\n\n## Erros\n`{\"error\": \"mensagem\"}` ou, em validação (422), `{\"error\": {\"campo\": [\"mensagem\"]}}`. Falhas inesperadas → 500\n`{\"error\": \"Internal error...\", \"code\": \"internal_error\"}` (detalhes ficam só no log do servidor).\n\n## Ambientes\nNão existe ambiente *sandbox* separado na API. Use uma instalação de homologação com chaves próprias.\n", "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://{host}", "description": "Sua instalação do SharkPay", "variables": { "host": { "default": "pay.example.com" } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Autenticação" }, { "name": "Cobranças" }, { "name": "Pix" }, { "name": "Saques Pix" }, { "name": "Clientes" }, { "name": "Checkout hospedado" }, { "name": "Webhooks" }, { "name": "Referência" }, { "name": "Interno" } ], "paths": { "/api/auth": { "post": { "tags": [ "Autenticação" ], "operationId": "authenticate", "summary": "Obter token de acesso", "security": [ { "basicAuth": [] } ], "responses": { "200": { "description": "Token emitido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "object", "required": [ "token", "token_type", "expires_in" ], "properties": { "token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "description": "Validade em segundos (PASSPORT_TOKEN_DAYS, padrão 30 dias)." } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/invoices": { "get": { "tags": [ "Cobranças" ], "operationId": "listInvoices", "summary": "Listar cobranças", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "invoice_no", "in": "query", "description": "Busca parcial pelo número informado na criação.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Busca parcial por e-mail.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Use junto com end_date.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Página de cobranças (somente as suas).", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/invoice/{invoice_id}": { "get": { "tags": [ "Cobranças" ], "operationId": "getInvoice", "summary": "Consultar cobrança pelo id numérico", "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cobrança.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/invoice/ref/{ref_id}": { "get": { "tags": [ "Cobranças" ], "operationId": "getInvoiceByRef", "summary": "Consultar cobrança pela referência (INV-xxxxxx)", "parameters": [ { "name": "ref_id", "in": "path", "required": true, "schema": { "type": "string", "example": "INV-A1B2C3" } } ], "responses": { "200": { "description": "Cobrança.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/creditcard/create": { "post": { "tags": [ "Cobranças" ], "operationId": "createCreditcardCharge", "summary": "Cobrar cartão de crédito", "description": "Cria a cobrança e tenta autorizar na hora. **Os dados do cartão passam pelo seu servidor e pelo SharkPay:\nisso traz obrigações PCI DSS para quem os coleta.** Nunca registre número/CVV em logs.\nRequer o método \"cartão\" habilitado para a conta. `total = amount × quantity + imposto% − desconto%`.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditcardChargeRequest" } } } }, "responses": { "200": { "description": "Pagamento aprovado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "reference": { "type": "string" }, "total": { "type": "string", "example": "190.00" }, "due_date": { "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "transaction": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "string" }, "status": { "type": "integer" }, "description": { "type": "string" }, "method": { "type": "string", "const": "creditcard" } } } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/boleto/create": { "post": { "tags": [ "Cobranças" ], "operationId": "createBoleto", "summary": "Emitir boleto", "description": "Requer o método \"boleto\" habilitado e um cliente já cadastrado (`POST /api/customer`).", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoRequest" } } } }, "responses": { "200": { "description": "Boleto emitido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "reference": { "type": "string" }, "total": { "type": [ "string", "number" ] }, "due_date": { "type": "string", "format": "date" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "boleto": { "type": "string", "description": "URL do boleto." }, "barcode": { "type": "string" }, "digitable": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/pix/create": { "post": { "tags": [ "Pix" ], "operationId": "createPixCharge", "summary": "Criar cobrança Pix (QR Code e copia-e-cola)", "description": "Requer o método Pix habilitado. A confirmação chega por webhook (`invoice.paid`) ou consulta.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixChargeRequest" } } } }, "responses": { "200": { "description": "Cobrança criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "reference": { "type": "string", "example": "INV-A1B2C3" }, "total": { "type": "string", "example": "190.00" }, "txid": { "type": "string" }, "due_date": { "type": "string" }, "copy": { "type": "string", "description": "Código Pix copia-e-cola." }, "qrcode": { "type": "string", "description": "Imagem do QR Code (conteúdo para exibição)." } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/pix/invoice/{ref}": { "get": { "tags": [ "Pix" ], "operationId": "getPixInvoice", "summary": "Consultar cobrança (registro bruto) pela referência", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Registro da cobrança.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/pix/txid/{txid}": { "get": { "tags": [ "Pix" ], "operationId": "getPixByTxid", "summary": "Consultar cobrança (registro bruto) pelo txid do Pix", "parameters": [ { "name": "txid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Registro da cobrança.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/pixout/create": { "post": { "tags": [ "Saques Pix" ], "operationId": "createPixout", "summary": "Solicitar saque Pix", "description": "Reserva o saldo (valor + tarifa) de forma atômica e envia ao banco. **`Idempotency-Key` é obrigatório.**\nSe o banco recusar, o valor é estornado e o saque fica `CANCELED`.\n", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixoutRequest" } } } }, "responses": { "200": { "description": "Saque registrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "withdraw": { "$ref": "#/components/schemas/Withdraw" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/pixout/withdraw/{txid}": { "get": { "tags": [ "Saques Pix" ], "operationId": "getPixout", "summary": "Consultar saque pela referência", "parameters": [ { "name": "txid", "in": "path", "required": true, "description": "Valor de `reference` do saque.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saque.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "withdraw": { "$ref": "#/components/schemas/Withdraw" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/pixout/list": { "get": { "tags": [ "Saques Pix" ], "operationId": "listPixouts", "summary": "Listar saques (25 por página)", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "start", "in": "query", "description": "YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "end", "in": "query", "description": "YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "PAID", "CANCELED" ] } } ], "responses": { "200": { "description": "Saques.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "withdrawals": { "type": "array", "items": { "$ref": "#/components/schemas/Withdraw" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/customer": { "post": { "tags": [ "Clientes" ], "operationId": "createCustomer", "summary": "Cadastrar cliente", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerRequest" } } } }, "responses": { "200": { "description": "Cliente criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api/customer/{custome_id}": { "get": { "tags": [ "Clientes" ], "operationId": "getCustomer", "summary": "Consultar cliente", "parameters": [ { "name": "custome_id", "in": "path", "required": true, "description": "Id numérico do cliente (o nome do parâmetro mantém a grafia original da rota).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cliente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/customers": { "get": { "tags": [ "Clientes" ], "operationId": "listCustomers", "summary": "Listar/buscar clientes", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "document", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } }, { "name": "mobilephone", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Clientes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/checkout/{tx_ref}": { "get": { "tags": [ "Checkout hospedado" ], "operationId": "getCheckout", "summary": "Consultar o resultado de um checkout hospedado", "description": "Use o `tx_ref` que você enviou no formulário `POST /ext_transfer`. Sempre confirme o pagamento por esta\nconsulta no seu servidor antes de liberar o pedido — o redirecionamento do cliente a `callback_url` não prova pagamento.\n", "parameters": [ { "name": "tx_ref", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transação.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "type": "object", "properties": { "tx_ref": { "type": "string" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "ABANDONED", "UNKNOWN" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "amount": { "type": "string" }, "total": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "payment_type": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/webhook": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "Ver configuração do webhook", "responses": { "200": { "description": "Configuração (o segredo nunca é devolvido aqui).", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "secret_configured": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "tags": [ "Webhooks" ], "operationId": "setWebhook", "summary": "Definir a URL do webhook", "description": "A URL deve ser **https**, sem credenciais, porta 443/8443 e **não pode resolver para IP privado/reservado**.\nNa primeira configuração é gerado o segredo de assinatura (`whsec_...`), **mostrado uma única vez**.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "URL salva.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "url": { "type": "string" }, "secret": { "type": "string", "description": "Somente na primeira configuração." }, "secret_notice": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/api/webhook/secret/rotate": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Gerar novo segredo de assinatura", "description": "O segredo anterior deixa de valer imediatamente. O novo é mostrado uma única vez.", "responses": { "200": { "description": "Novo segredo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "secret": { "type": "string" }, "secret_notice": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/webhook/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Enfileirar um evento `ping`", "responses": { "202": { "description": "Evento na fila.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_id": { "type": "string" }, "status": { "type": "string", "const": "queued" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/api/webhook/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "Últimas 25 entregas (diagnóstico)", "responses": { "200": { "description": "Entregas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "type": { "type": "string" }, "attempts": { "type": "integer" }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/country/all": { "get": { "tags": [ "Referência" ], "operationId": "listCountries", "summary": "Listar países", "responses": { "200": { "description": "Países.", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/country/{country_id}": { "get": { "tags": [ "Referência" ], "operationId": "getCountry", "summary": "Consultar país pelo id", "parameters": [ { "name": "country_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "País.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/country/iso/{iso}": { "get": { "tags": [ "Referência" ], "operationId": "getCountryByIso", "summary": "Consultar país pelo código ISO (2 letras)", "parameters": [ { "name": "iso", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "País.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/country/iso3/{iso3}": { "get": { "tags": [ "Referência" ], "operationId": "getCountryByIso3", "summary": "Consultar país pelo código ISO3", "parameters": [ { "name": "iso3", "in": "path", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "País.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/state/all": { "get": { "tags": [ "Referência" ], "operationId": "listStates", "summary": "Listar estados", "responses": { "200": { "description": "Estados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "states": { "type": "array", "items": { "$ref": "#/components/schemas/State" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/state/{state_id}": { "get": { "tags": [ "Referência" ], "operationId": "getState", "summary": "Consultar estado pelo id", "parameters": [ { "name": "state_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Estado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/State" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/state/uf/{uf}": { "get": { "tags": [ "Referência" ], "operationId": "getStateByUf", "summary": "Consultar estado pela UF (2 letras)", "parameters": [ { "name": "uf", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "Estado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/State" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/cep/search/{cep}": { "get": { "tags": [ "Referência" ], "operationId": "searchCep", "summary": "Buscar endereço por CEP (sem autenticação)", "security": [], "parameters": [ { "name": "cep", "in": "path", "required": true, "description": "8 dígitos (hífen opcional).", "schema": { "type": "string", "example": "01001000" } } ], "responses": { "200": { "description": "Endereço.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "address": { "type": "object", "properties": { "cep": { "type": "string" }, "logradouro": { "type": "string" }, "complemento": { "type": "string" }, "bairro": { "type": "string" }, "localidade": { "type": "string" }, "uf": { "type": "string" }, "ibge": { "type": "string" } } } } } } } }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/originalbank/account/register": { "post": { "tags": [ "Interno" ], "operationId": "registerOriginalBankAccount", "summary": "Abrir conta no Banco Original (uso interno/parceiro)", "description": "Fluxo de integração com o banco parceiro, **fora do contrato público estável**. Pode mudar sem aviso.", "x-internal": true, "responses": { "200": { "description": "Resultado do banco.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "webhooks": { "sharkpay-event": { "post": { "summary": "Evento enviado pelo SharkPay à sua URL", "description": "Cabeçalhos: `SharkPay-Signature: t=,v1=`, `SharkPay-Event-Id`, `User-Agent: SharkPay-Webhooks/1.0`.\n`v1 = HMAC_SHA256(segredo, \".\" + corpo_bruto)` em hexadecimal. Rejeite `t` com mais de 5 minutos de diferença.\nResponda **2xx** em até 10 s. Qualquer outra resposta ou timeout → nova tentativa (até 8, com espera de 1, 5, 15 min, 1 h, 3 h, 6 h, 12 h).\nEntrega **pelo menos uma vez**: deduplique por `id`. A ordem não é garantida.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Recebido." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "basicAuth": { "type": "http", "scheme": "basic", "description": "Usuário = chave pública (PUB-...), senha = chave secreta (SEC-...)." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado. 8–100 caracteres `A-Za-z0-9_.:-`.", "schema": { "type": "string", "minLength": 8, "maxLength": 100 } } }, "responses": { "Error": { "description": "Requisição inválida ou regra de negócio violada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Campos inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Unauthorized": { "description": "Token ausente/inválido/expirado, ou credenciais incorretas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Não encontrado (ou pertence a outra conta).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IdempotencyConflict": { "description": "A mesma Idempotency-Key ainda está em processamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Limite de requisições excedido. Aguarde `Retry-After` segundos.", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "InternalError": { "description": "Falha inesperada. Seguro repetir com a mesma Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "Presente em alguns erros: idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, internal_error." } } }, "ValidationError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "InvoiceStatus": { "type": "string", "enum": [ "PENDING", "PAID", "CANCELED", "REFUNDED" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "integer" }, "ref_id": { "type": "string", "example": "INV-A1B2C3" }, "invoice_no": { "type": "string" }, "email": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "item": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "amount": { "type": "string", "example": "100.00" }, "tax": { "type": "string", "description": "Valor do imposto em moeda." }, "discount": { "type": "string", "description": "Valor do desconto em moeda." }, "charge": { "type": "string" }, "total": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "boleto": { "type": "object", "additionalProperties": true }, "pix": { "type": "object", "additionalProperties": true }, "customer": { "$ref": "#/components/schemas/Customer" }, "transactions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "_ChargeCommon": { "type": "object", "required": [ "amount", "quantity", "discount", "invoice_no", "due_date", "item_name" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 999999999, "description": "Valor unitário." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100000 }, "discount": { "type": "number", "minimum": 0, "maximum": 100, "description": "Desconto em %." }, "tax": { "type": "number", "minimum": 0, "maximum": 100, "description": "Imposto em %." }, "invoice_no": { "type": "string", "maxLength": 100 }, "due_date": { "type": "string", "format": "date" }, "item_name": { "type": "string", "maxLength": 255 }, "notes": { "type": "string", "maxLength": 500 } } }, "PixChargeRequest": { "allOf": [ { "$ref": "#/components/schemas/_ChargeCommon" }, { "type": "object", "required": [ "email", "tax", "document", "client" ], "properties": { "email": { "type": "string", "format": "email" }, "document": { "type": "string", "description": "CPF/CNPJ do pagador." }, "client": { "type": "string", "description": "Nome do pagador." } } } ] }, "BoletoRequest": { "allOf": [ { "$ref": "#/components/schemas/_ChargeCommon" }, { "type": "object", "required": [ "customer" ], "properties": { "customer": { "type": "integer", "description": "Id de um cliente seu (POST /api/customer)." }, "instructions": { "type": "string", "maxLength": 255 } } } ] }, "CreditcardChargeRequest": { "allOf": [ { "$ref": "#/components/schemas/_ChargeCommon" }, { "type": "object", "required": [ "email", "tax", "installments", "creditcard_holder", "creditcard_number", "creditcard_cvv", "creditcard_month", "creditcard_year", "creditcard_brand" ], "properties": { "email": { "type": "string", "format": "email" }, "installments": { "type": "integer", "minimum": 1, "maximum": 24 }, "creditcard_holder": { "type": "string" }, "creditcard_number": { "type": "string", "pattern": "^[0-9]{12,19}$" }, "creditcard_cvv": { "type": "string", "pattern": "^[0-9]{3,4}$" }, "creditcard_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "creditcard_year": { "type": "integer", "description": "4 dígitos." }, "creditcard_brand": { "type": "string", "example": "Visa" } } } ] }, "PixoutRequest": { "type": "object", "required": [ "amount", "pixkey", "keytype" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "pixkey": { "type": "string", "maxLength": 140 }, "keytype": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ] }, "client": { "type": "string" }, "document": { "type": "string" }, "email": { "type": "string", "format": "email" }, "description": { "type": "string", "maxLength": 140 } } }, "Withdraw": { "type": "object", "properties": { "reference": { "type": "string" }, "total": { "type": "string", "description": "valor + tarifa" }, "charge": { "type": "string" }, "loquidAmount": { "type": "string", "deprecated": true, "description": "Nome legado (grafia original). Use netAmount." }, "netAmount": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "PAID", "CANCELED" ] }, "pixkey": { "type": "string" }, "keytype": { "type": "string" }, "destinataryName": { "type": [ "string", "null" ] }, "destinataryDocument": { "type": [ "string", "null" ] }, "destinataryEmail": { "type": [ "string", "null" ] }, "paidAt": { "type": [ "string", "null" ] }, "entoend": { "type": [ "string", "null" ], "deprecated": true, "description": "Nome legado. Use endToEndId." }, "endToEndId": { "type": [ "string", "null" ] }, "errorMsg": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "CustomerRequest": { "type": "object", "required": [ "name", "document", "document_type", "zipcode", "country_id", "state", "city", "district", "street", "number", "email", "phone", "mobilephone" ], "properties": { "name": { "type": "string" }, "document": { "type": "string" }, "document_type": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "zipcode": { "type": "string" }, "country_id": { "type": "integer", "description": "Id de GET /api/country/all." }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "description": "UF." }, "city": { "type": "string" }, "district": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "mobilephone": { "type": "string" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "document": { "type": "string" }, "document_type": { "type": "string" }, "zipcode": { "type": "string" }, "country": { "$ref": "#/components/schemas/Country" }, "state": { "type": "object", "properties": { "name": { "type": "string" }, "uf": { "type": "string" }, "ibge": { "type": [ "string", "integer", "null" ] }, "ddd": { "type": [ "string", "integer", "null" ] } } }, "city": { "type": "string" }, "district": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "mobilephone": { "type": "string" } } }, "Country": { "type": "object", "properties": { "id": { "type": "integer" }, "iso": { "type": "string" }, "name": { "type": "string" }, "nicename": { "type": "string" }, "iso3": { "type": [ "string", "null" ] }, "numcode": { "type": [ "integer", "null" ] }, "phonecode": { "type": [ "integer", "null" ] } } }, "State": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "uf": { "type": "string" }, "ibge": { "type": [ "string", "integer", "null" ] }, "ddd": { "type": [ "string", "integer", "null" ] } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "created", "api_version", "data" ], "properties": { "id": { "type": "string", "example": "evt_abcdefghijklmnopqrstuvwx" }, "type": { "type": "string", "enum": [ "invoice.paid", "invoice.canceled", "invoice.refunded", "pixout.paid", "pixout.canceled", "ping" ] }, "created": { "type": "integer", "description": "Unix timestamp." }, "api_version": { "type": "string", "example": "2026-10-14" }, "data": { "type": "object", "description": "`invoice` (reference, invoice_no, total, status) para eventos invoice.*; `withdraw` (reference, amount, status) para pixout.*; `message` para ping.", "additionalProperties": true } } } } } }