The Link Premio Card is a platform for incentive and reward distribution, allowing companies to register awardees (individuals or businesses) and provide them with balance in a virtual card.
\nThrough this API, you can:
\nManage Participants: Register and manage individuals and businesses
\nVirtual Card Management: Create and manage virtual cards for participants
\nBalance Operations: Check company balances, manage balance types, and transfer funds
\nCampaign Management: Create and manage reward campaigns
\nOrder Processing: Process bulk reward distributions
\nWebhook Integration: Set up real-time event notifications
\nThis API is designed for companies (our clients) to integrate their systems seamlessly with Link Premio Card.
\nAll requests require valid API Keys issued by Link Premio Card.
\nKeys are unique per company.
\nMust be sent in the request headers.
\nKeep your credentials secure and never expose them publicly.
\nThe Link Premio Card API provides both Production and Staging environments.
\nThe Staging environment is intended solely for integration testing and uses simulated logic for certain flows, including KYC.
\nWhen using the Staging environment, the KYC analysis response (kyc_status) is determined by the first digit of the value provided in the document field.
This allows you to easily simulate different KYC outcomes.
\n⚠️ These rules apply only in Staging.
\nProduction performs real KYC validation.
\nTo guarantee availability and performance for all clients, the API is protected by throttling rules.
\nRequests exceeding the limit will be rejected with 429 Too Many Requests.
Please implement retry logic with exponential backoff.
\n⚠️ Detailed limits (requests per second/minute) are available upon request with our support team.
\nWhen performing operations such as payments or participant creation, do not cancel or immediately retry requests if they take longer than expected.
\nEven if the HTTP request times out or is interrupted, the operation may still be processing on our servers.
\nRetrying the same request without proper control can result in:
\nDuplicate payments
\nDuplicate participant registrations
\nInconsistent transaction states
\nImportant: Client-side timeouts do not cancel server-side processing.
\nAlways ensure proper retry strategies using idempotency or unique identifiers before attempting a new request.
\nIf you encounter any issues while setting up or using our product, or if you have any questions:
\n📧 Please contact our support team exclusively via email (ticket system).
\nWe’ll ensure quick and effective assistance.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Important – Request Retries & Timeouts","slug":"important-request-retries-timeouts"}],"owner":"41529363","collectionId":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","publishedId":"2sBY4Mw2D5","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-07-16T20:07:37.000Z"},"item":[{"name":"Entities","item":[{"name":"Company","item":[{"name":"Balance Type","item":[{"name":"Retrieve Balance Types","id":"bc80a6d3-62ba-41f4-8cdd-1ca050f70683","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{url}}/balance-type","description":"Retorna uma lista paginada de tipos de saldo disponíveis para a empresa autenticada.
\nItens que não possuem um swap.id válido no JSON da coluna integration são omitidos automaticamente da listagem.
GET /api/external/balance-type\n\ncurl -X GET \"https://api.exemplo.com/api/external/balance-type?page=1&limit=10&status=Active\" \\\n -H \"x-api-key: eyJhbGciOiJIUzI1NiIs...\"\n\ncurl -X GET \"https://api.exemplo.com/api/external/balance-type?query=carteira\" \\\n -H \"x-api-key: eyJhbGciOiJIUzI1NiIs...\"\n\n{\n \"data\": [\n {\n \"id\": \"c8a2b3e4-5f67-4a89-bcde-f0123456789a\",\n \"status\": \"Active\",\n \"name\": \"Carteira Digital\",\n \"type\": \"1\"\n },\n {\n \"id\": \"d9b3c4f5-6a78-4b90-cdef-0123456789ab\",\n \"status\": \"Disabled\",\n \"name\": \"Vale Refeição\",\n \"type\": \"4\"\n }\n ],\n \"totalItems\": 2,\n \"totalPages\": 1,\n \"page\": 1,\n \"limit\": 15\n}\n\ndata[]{\n \"title\": \"Erro de validação\",\n \"message\": \"Erro de validação dos campos\",\n \"code\": 1001,\n \"details\": [\n {\n \"path\": \"page\",\n \"message\": \"Number must be greater than or equal to 1\"\n }\n ]\n}\n\nnumber: [1-9999]
\n","type":"text/plain"},"key":"limit","value":"1"},{"disabled":true,"description":{"content":"number: [1-999999]
\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"Filters balance types by status.
\n","type":"text/plain"},"key":"status","value":"Active / Disabled"}],"variable":[]}},"response":[{"id":"7fb90dcc-db12-4edc-9e19-403f053d28dc","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":{"raw":"{{url}}/balance-type","host":["{{url}}"],"path":["balance-type"],"query":[{"key":"limit","value":"1","description":"number: [1-9999]","disabled":true},{"key":"page","value":"1","description":"number: [1-999999]","disabled":true},{"key":"status","value":"Active","description":"Active | Disabled","type":"text","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"483"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Mon, 18 Aug 2025 13:21:38 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"1e3-UBla1FuWH5xnqWwBgZ3m20Xdt/U\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"15c87e36-c2c3-4c1b-94b1-ad6bbdf337ad\",\n \"status\": \"Disabled\",\n \"name\": \"Balance 5\"\n },\n {\n \"id\": \"2928e252-5281-46ba-99c7-3921f67f6e58\",\n \"status\": \"Disabled\",\n \"name\": \"Balance 2\"\n },\n {\n \"id\": \"34549121-0517-4e9b-8fe8-80c1ebb90c2a\",\n \"status\": \"Active\",\n \"name\": \"Balance 1\"\n },\n {\n \"id\": \"3644e50b-d590-416b-a890-c998505e9dc1\",\n \"status\": \"Disabled\",\n \"name\": \"Balance 4\"\n },\n {\n \"id\": \"f2fbbba5-61a7-425c-8ccc-4d4497ab30f9\",\n \"status\": \"Disabled\",\n \"name\": \"Balance 3\"\n }\n ],\n \"totalItems\": 5,\n \"totalPages\": 1,\n \"page\": 1,\n \"limit\": 10\n}"},{"id":"6ab1c31b-281f-420f-9885-ebd89b8cb9df","name":"401 Unauthorized","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":{"raw":"{{url}}/balance-type","host":["{{url}}"],"path":["balance-type"],"query":[{"key":"limit","value":"1","description":"number: [1-9999]","disabled":true},{"key":"page","value":"1","description":"number: [1-999999]","disabled":true},{"key":"status","value":"Active","description":"Active | Disabled","type":"text","disabled":true}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"72"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Mon, 18 Aug 2025 13:22:32 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"48-r2Sjlk9iydsU25uLtA64N03socs\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"API key is missing\",\n \"error\": \"Unauthorized\",\n \"statusCode\": 401\n}"}],"_postman_id":"bc80a6d3-62ba-41f4-8cdd-1ca050f70683"},{"name":"Retrieve a Balance Type by id","id":"b20905c0-acbd-463b-8664-310ac76fe0cb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{url}}/balance-type/:id","description":"Retorna os detalhes de um tipo de saldo específico.
\nGET /api/external/balance-type/{id}\n\ncurl -X GET \"https://api.exemplo.com/api/external/balance-type/c8a2b3e4-5f67-4a89-bcde-f0123456789a\" \\\n -H \"x-api-key: eyJhbGciOiJIUzI1NiIs...\"\n\nPara um balance type com integration válida:
{\n \"id\": \"c8a2b3e4-5f67-4a89-bcde-f0123456789a\",\n \"status\": \"Active\",\n \"name\": \"Carteira Digital\",\n \"type\": \"1\"\n}\n\nPara um balance type sem swap.id no JSON de integration, o campo type não é incluído:
{\n \"id\": \"e4c5d6f7-8a90-4bcd-ef01-23456789abcd\",\n \"status\": \"Active\",\n \"name\": \"Saldo Genérico\"\n}\n\n{\n \"title\": \"Registro não encontrado\",\n \"message\": \"Nao foi possivel localizar os dados da categoria de saldo no momento. Por favor, tente novamente mais tarde ou contate o suporte.\",\n \"code\": 5001,\n \"status\": 404,\n \"details\": {\n \"companyId\": null,\n \"info\": \"Balance type not found in database.\"\n }\n}\n\nThe UUID of the balance type to retrieve. Must be a valid balance type ID.
\n","type":"text/plain"},"type":"any","value":"","key":"id"}]}},"response":[{"id":"51662408-1520-4bfd-a565-b750c538490b","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":{"raw":"{{url}}/balance-type/:id","host":["{{url}}"],"path":["balance-type",":id"],"variable":[{"key":"id","value":""}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"82"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Mon, 18 Aug 2025 13:21:56 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"52-oy9HakFzUeXgg9y0tqAHPtKpyT4\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"34549121-0517-4e9b-8fe8-80c1ebb90c2a\",\n \"status\": \"Active\",\n \"name\": \"Balance 1\"\n}"},{"id":"58468f98-3e8c-4ec5-975b-dd5ba7c75bee","name":"404 Not found","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":{"raw":"{{url}}/balance-type/:id","host":["{{url}}"],"path":["balance-type",":id"],"variable":[{"key":"id","value":""}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"78"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Mon, 18 Aug 2025 13:20:34 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"4e-KRVnSuYZR03j4t4PHE6FyQj+ru4\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"Balance type was not found.\",\n \"error\": \"Not Found\",\n \"statusCode\": 404\n}"},{"id":"317a0b84-212b-4b2c-99b5-d17880c98c9b","name":"401 Unauthorized","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":{"raw":"{{url}}/balance-type/:id","host":["{{url}}"],"path":["balance-type",":id"],"variable":[{"key":"id","value":""}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"72"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Mon, 18 Aug 2025 13:22:40 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"48-r2Sjlk9iydsU25uLtA64N03socs\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"API key is missing\",\n \"error\": \"Unauthorized\",\n \"statusCode\": 401\n}"}],"_postman_id":"b20905c0-acbd-463b-8664-310ac76fe0cb"},{"name":"Update Status Balance Type","id":"feb64022-486a-473f-882e-af64632e6507","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[],"url":"{{url}}/balance-type/:id","description":"Ativa ou desativa um tipo de saldo alterando seu status para Active ou Disabled.
PUT /api/external/balance-type/{id}\n\nAtivar um balance type:
\ncurl -X PUT \"https://api.exemplo.com/api/external/balance-type/c8a2b3e4-5f67-4a89-bcde-f0123456789a\" \\\n -H \"x-api-key: eyJhbGciOiJIUzI1NiIs...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"Active\"}'\n\nDesativar um balance type:
\ncurl -X PUT \"https://api.exemplo.com/api/external/balance-type/c8a2b3e4-5f67-4a89-bcde-f0123456789a\" \\\n -H \"x-api-key: eyJhbGciOiJIUzI1NiIs...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"Disabled\"}'\n\n{\n \"id\": \"c8a2b3e4-5f67-4a89-bcde-f0123456789a\",\n \"status\": \"Active\",\n \"name\": \"Carteira Digital\",\n \"type\": \"1\"\n}\n\n{\n \"title\": \"Erro de validação\",\n \"message\": \"Erro de validação dos campos\",\n \"code\": 1001,\n \"details\": [\n {\n \"path\": \"status\",\n \"message\": \"Invalid enum value. Expected 'Active' | 'Disabled', received 'Ativo'\"\n }\n ]\n}\n\n{\n \"title\": \"Erro de validação\",\n \"message\": \"Erro de validação dos campos\",\n \"code\": 1001,\n \"details\": [\n {\n \"path\": \"status\",\n \"message\": \"Required\"\n }\n ]\n}\n\n{\n \"title\": \"Registro não encontrado\",\n \"message\": \"Nao foi possivel localizar os dados da categoria de saldo no momento. Por favor, tente novamente mais tarde ou contate o suporte.\",\n \"code\": 5001,\n \"status\": 404,\n \"details\": {\n \"companyId\": null,\n \"info\": \"Balance type not found in database.\"\n }\n}\n\nIdentificador único do balance type
\n","type":"text/plain"},"type":"any","value":"","key":"id"}]}},"response":[],"_postman_id":"feb64022-486a-473f-882e-af64632e6507"}],"id":"b961e455-0acb-47b3-9d53-d53534d0de3d","description":"O consumo do saldo segue uma ordem de prioridade previamente definida. Para cada transação, o sistema verifica a categoria correspondente ao estabelecimento (MCC e/ou Merchant ID) e realiza o débito no saldo da carteira prioritária aplicável. Caso não exista saldo disponível na carteira correspondente, as regras de fallback definidas pelo produto serão aplicadas.
\nSe uma compra for realizada em um estabelecimento classificado como Alimentação, o sistema tentará consumir o saldo da carteira Alimentação primeiro. Caso não haja saldo disponível, seguirá a ordem de prioridade definida até encontrar uma carteira elegível para realizar o débito.
\n","_postman_id":"b961e455-0acb-47b3-9d53-d53534d0de3d","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Retrieve Company Information","event":[{"listen":"test","script":{"id":"2feb5c8e-2671-4eb2-9582-fe2ed9e2e572","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"a239a32a-2274-4be0-8ed3-977e7a973c41","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{url}}/company","description":"Retrieves detailed information about a company. It is designed to provide details such as the company's identification, contact information, and financial balance.
\nThis endpoint does not require any input parameters. The response provides comprehensive details about the company's profile and financial standing, which can be utilized for various purposes such as reporting, analysis, or integration with other systems.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}},"urlObject":{"path":["company"],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"85d4633e-18fa-41bf-aef9-e25d8a27ba38","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{url}}/company"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Length","value":"702","enabled":true},{"key":"Content-Type","value":"application/json; charset=utf-8","enabled":true},{"key":"Date","value":"Tue, 04 Feb 2025 13:34:37 GMT","enabled":true},{"key":"Access-Control-Allow-Origin","value":"*","enabled":true},{"key":"ETag","value":"W/\"2be-g7b7VbWUS2TgooUZ85hUJGUVpR4\"","enabled":true},{"key":"request-context","value":"appId=cid-v1:","enabled":true},{"key":"X-Powered-By","value":"Express","enabled":true},{"key":"X-RateLimit-Limit","value":"20","enabled":true},{"key":"X-RateLimit-Remaining","value":"19","enabled":true},{"key":"X-RateLimit-Reset","value":"10","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"status\": \"Active\",\n \"name\": \"Example Company Name\",\n \"email\": \"contact@example.com\",\n \"document\": \"00000000000000\",\n \"phone\": \"+5500000000000\",\n \"logo\": \"https://example.com/logo.png\",\n \"address\": {\n \"street\": \"Example Street\",\n \"number\": \"123\",\n \"complement\": \"Office 456\",\n \"neighborhood\": \"Example Neighborhood\",\n \"city\": \"Example City\",\n \"state\": \"EX\",\n \"country\": \"Brazil\",\n \"postalCode\": \"00000-000\"\n },\n \"balance\": {\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"status\": \"Active\",\n \"value\": 100000,\n }\n}"},{"id":"e90a372c-a27e-406a-bf02-3f4142f41057","name":"401 - Unauthorized","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{url}}/company"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"72"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Mon, 18 Aug 2025 13:24:24 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"48-r2Sjlk9iydsU25uLtA64N03socs\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"API key is missing\",\n \"error\": \"Unauthorized\",\n \"statusCode\": 401\n}"}],"_postman_id":"a239a32a-2274-4be0-8ed3-977e7a973c41"}],"id":"87c87cd0-f1b2-4774-b6f5-c0f59c5baf25","_postman_id":"87c87cd0-f1b2-4774-b6f5-c0f59c5baf25","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Customers","item":[{"name":"Person","item":[{"name":"Create a Person","event":[{"listen":"test","script":{"id":"d1f4b200-8850-4827-ab8a-b624cd3466cc","exec":[""],"type":"text/javascript","packages":{},"requests":{}}},{"listen":"prerequest","script":{"id":"2d4a77c7-4dc9-4252-8b65-6ff1030bff07","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"e100fed8-9e98-4871-b5dc-4b5769b4b8ea","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"firstName\": \"Joao\",\r\n \"lastName\": \"Silva\",\r\n \"email\": \"joao.silva@example.com\",\r\n \"document\": \"123.456.789-09\",\r\n \"birthdate\": \"1995-03-20\",\r\n \"phone\": \"+5511999990000\",\r\n \"motherName\": \"Maria Silva\",\r\n \"address\": {\r\n \"street\": \"Rua Exemplo\",\r\n \"number\": \"100\",\r\n \"neighborhood\": \"Centro\",\r\n \"postalCode\": \"01000-000\",\r\n \"city\": \"São Paulo\",\r\n \"state\": \"SP\",\r\n \"country\": \"BR\"\r\n },\r\n \"campaignId\": \"00000000-0000-0000-0000-000000000000\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/person","description":"Creates a person in complete registration mode.
\nThis endpoint allows you to create a person in complete registration mode within a specific campaign. Complete registration requires all mandatory information to be provided upfront, including full address details and personal information. The person will be created with Pending status and will be integrated with external services immediately for card activation and balance management.
\nThe Link Premio Card API provides both Production and Staging environments.
\nThe Staging environment is intended solely for integration testing and simulates specific behaviors to make validation predictable.
\nWhen using the Staging environment, the approval result for LPC flows is determined exclusively by the first digit of the value provided in the document field.
⚠️ These rules apply only in Staging.
\nProduction performs real KYC validation.
\n> Important: The field amount must always be sent in cents (e.g., 1500 = R$ 15,00).
\nfirstName → Required field for complete registration
\nemail → Required field for complete registration
\ndocument → Must be a valid CPF format
\nbirthdate → Must be valid date with age ≥ 18 years
\nphone → Required for complete registration
\naddress → All address fields except complement are required
\nbalanceTypeId → Optional, must be a valid identifier of the balance type
\namount → Optional, value in cents (integer, no decimals)
\ncampaignId → Required, links the person to a specific campaign
\nCreates a person in pre-registration mode.
\nThis endpoint allows you to create a person in pre-registration mode within a specific campaign.
\nPre-registration should be used when some information is not yet available (such as address or phone number).
\nThe person will only be able to access the Link Premio Card and approved balance after all missing data is collected.
\nThe Link Premio Card API provides both Production and Staging environments.
\nThe Staging environment is intended solely for integration testing and simulates specific behaviors to make validation predictable.
\nWhen using the Staging environment, the approval result for LPC flows is determined exclusively by the first digit of the value provided in the document field.
⚠️ These rules apply only in Staging.
\nValidation Rules**
\n⚠️ Important: The field amount must always be sent in cents (e.g., 1500 = R$ 15,00).
balanceTypeId → must be a valid identifier of the balance type.
amount → value in cents (integer, no decimals).
campaignId → links the person to a specific campaign.
This endpoint allows you to retrieve a paginated list of people from your system with various filtering options. You can filter by status, search by name/email/document, and paginate through results. The endpoint returns basic person information including user details, contact information, and current status.
\nCompany Scope: Results are automatically filtered by the authenticated company
\nSearch Behavior: The query parameter searches across first name, last name, email, and document fields
\nStatus Filtering: Multiple status values can be provided as an array
\nDate Format: All dates should be provided in YYYY-MM-DD format
\nCase Sensitivity: Search and email/document filtering are case-insensitive
\nOrdering: Results are ordered by first name in ascending order by default
\nnumber: [1-9999]
\n","type":"text/plain"},"key":"limit","value":""},{"disabled":true,"description":{"content":"number: [1-99999]
\n","type":"text/plain"},"key":"page","value":""},{"disabled":true,"description":{"content":"YYYY-MM-DD
\n","type":"text/plain"},"key":"startDate","value":""},{"disabled":true,"description":{"content":"YYYY-MM-DD
\n","type":"text/plain"},"key":"endDate","value":""},{"disabled":true,"description":{"content":"Paid | Rejected| Disabled
\n","type":"text/plain"},"key":"status[]","value":""},{"disabled":true,"description":{"content":"text
\n","type":"text/plain"},"key":"document ","value":""},{"disabled":true,"description":{"content":"text | Filter by: firstName, lastName, email, document
\n","type":"text/plain"},"key":"query","value":""}],"variable":[]}},"response":[{"id":"e13d78af-5f11-4823-acfb-104a08c42162","name":"200 Ok","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{url}}/person","host":["{{url}}"],"path":["person"],"query":[{"key":"limit","value":"","description":"number: [1-9999]","disabled":true},{"key":"page","value":"","description":"number: [1-99999]","type":"text","disabled":true},{"key":"startDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"endDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"status[]","value":"","description":"Paid | Rejected| Disabled","disabled":true},{"key":"document ","value":"","description":"text","type":"text","disabled":true},{"key":"query","value":"","description":"text | Filter by: firstName, lastName, email, document","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"data\": [\r\n {\r\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\r\n \"status\": \"Paid\",\r\n \"firstName\": \"João\",\r\n \"lastName\": \"Silva\",\r\n \"email\": \"joao.silva@example.com\",\r\n \"document\": \"12345678901\",\r\n \"phone\": \"11999999999\",\r\n \"birthdate\": \"1990-01-01T00:00:00.000Z\",\r\n \"motherName\": \"Maria Silva\"\r\n }\r\n ],\r\n \"totalItems\": 1,\r\n \"totalPages\": 1,\r\n \"page\": 1,\r\n \"limit\": 10\r\n}"},{"id":"77b8aef4-8999-417b-b643-6418d469aac5","name":"400 Bad Request","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{url}}/person","host":["{{url}}"],"path":["person"],"query":[{"key":"limit","value":"","description":"number: [1-9999]","disabled":true},{"key":"page","value":"","description":"number: [1-99999]","type":"text","disabled":true},{"key":"startDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"endDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"status[]","value":"","description":"Paid | Rejected| Disabled","disabled":true},{"key":"document ","value":"","description":"text","type":"text","disabled":true},{"key":"query","value":"","description":"text | Filter by: firstName, lastName, email, document","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_small\",\r\n \"minimum\": 1,\r\n \"type\": \"number\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Number must be greater than or equal to 1\",\r\n \"path\": [\"page\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"8ed84755-773a-42d2-b55a-9539b8d2f2a9","name":"400 Bad Request","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{url}}/person","host":["{{url}}"],"path":["person"],"query":[{"key":"limit","value":"","description":"number: [1-9999]","disabled":true},{"key":"page","value":"","description":"number: [1-99999]","type":"text","disabled":true},{"key":"startDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"endDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"status[]","value":"","description":"Paid | Rejected| Disabled","disabled":true},{"key":"document ","value":"","description":"text","type":"text","disabled":true},{"key":"query","value":"","description":"text | Filter by: firstName, lastName, email, document","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_big\",\r\n \"maximum\": 9999,\r\n \"type\": \"number\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Number must be less than or equal to 9999\",\r\n \"path\": [\"limit\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"1cbd0c8e-95d3-4395-a132-89287bfefdcf","name":"400 Bad Request","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{url}}/person","host":["{{url}}"],"path":["person"],"query":[{"key":"limit","value":"","description":"number: [1-9999]","disabled":true},{"key":"page","value":"","description":"number: [1-99999]","type":"text","disabled":true},{"key":"startDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"endDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"status[]","value":"","description":"Paid | Rejected| Disabled","disabled":true},{"key":"document ","value":"","description":"text","type":"text","disabled":true},{"key":"query","value":"","description":"text | Filter by: firstName, lastName, email, document","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_string\",\r\n \"expected\": \"email\",\r\n \"received\": \"string\",\r\n \"message\": \"Invalid email\",\r\n \"path\": [\"email\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"afb7b99c-18a7-49e4-8fa9-07a62ddd6589","name":"400 Bad Request","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{url}}/person","host":["{{url}}"],"path":["person"],"query":[{"key":"limit","value":"","description":"number: [1-9999]","disabled":true},{"key":"page","value":"","description":"number: [1-99999]","type":"text","disabled":true},{"key":"startDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"endDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"status[]","value":"","description":"Paid | Rejected| Disabled","disabled":true},{"key":"document ","value":"","description":"text","type":"text","disabled":true},{"key":"query","value":"","description":"text | Filter by: firstName, lastName, email, document","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"custom\",\r\n \"message\": \"Invalid date, the value does not represent a valid date.\",\r\n \"path\": [\"startDate\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"96ae219d-2522-4825-bf3d-3b30cfe90878","name":"400 Bad Request","originalRequest":{"method":"GET","header":[],"url":{"raw":"{{url}}/person","host":["{{url}}"],"path":["person"],"query":[{"key":"limit","value":"","description":"number: [1-9999]","disabled":true},{"key":"page","value":"","description":"number: [1-99999]","type":"text","disabled":true},{"key":"startDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"endDate","value":"","description":"YYYY-MM-DD","type":"text","disabled":true},{"key":"status[]","value":"","description":"Paid | Rejected| Disabled","disabled":true},{"key":"document ","value":"","description":"text","type":"text","disabled":true},{"key":"query","value":"","description":"text | Filter by: firstName, lastName, email, document","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_enum_value\",\r\n \"options\": [\"Paid\", \"Pending\", \"Disabled\"],\r\n \"path\": [\"status\", 0],\r\n \"message\": \"Invalid enum value. Expected 'Paid' | 'Pending' | 'Disabled', received 'InvalidStatus'\"\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"}],"_postman_id":"47d15600-873a-4be2-a04b-c0d3b0dfb388"},{"name":"Retrieve Person by Id","id":"cab4f4e9-61d1-43f3-a0f3-d7cd9018744e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{url}}/person/:id","description":"This endpoint allows you to retrieve comprehensive information about a specific person using their unique UUID identifier. The response includes complete person details, address information, user status, and any rejection reasons if the person's status is \"Pending\".
\nRejection Reasons: The errors field contains rejection reasons only when status is \"Pending\"
\nAddress Information: Complete address details are included in the response
\nBalance Information: Balance details are currently commented out in the response
\nA rota POST /api/v2/external/person permite cadastrar participantes de forma assíncrona. Diferente da V1, esta rota retorna imediatamente um ID de registro e o processamento real ocorre em segundo plano, com notificações via Webhook.
Todos os requests devem incluir o header x-api-key com sua chave de API fornecida.
x-api-key: sua-chave-api-aqui\nContent-Type: application/json\n\naddressbalanceExemplo Completo (todos os campos)
\n{\n \"referenceId\": \"cad-unico-2024-001\",\n \"firstName\": \"João\",\n \"lastName\": \"da Silva\",\n \"document\": \"12345678901\",\n \"email\": \"joao.silva@email.com\",\n \"birthdate\": \"1990-05-15\",\n \"phone\": \"+5511999887766\",\n \"motherName\": \"Maria da Silva\",\n \"campaignId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"123\",\n \"complement\": \"Apto 4B\",\n \"neighborhood\": \"Centro\",\n \"postalCode\": \"01001-000\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"Brasil\"\n },\n \"balance\": {\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"amount\": 5000\n }\n}\n\nExemplo Mínimo (campos obrigatórios)
\n{\n \"referenceId\": \"cad-unico-2024-002\",\n \"firstName\": \"Maria\",\n \"email\": \"joao.silva@email.com\",\n \"document\": \"98765432100\",\n \"campaignId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"balance\": {\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"amount\": 10000\n }\n}\n\nRetornado quando o referenceId é único e o cadastro foi colocado na fila com sucesso.
{\n \"referenceId\": \"cad-unico-2024-001\",\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"status\": \"QUEUED\",\n \"jobId\": \"bull:person-registration-abc123:1\",\n \"payload\": {\n \"firstName\": \"João\",\n \"lastName\": \"da Silva\",\n \"email\": \"joao.silva@email.com\",\n \"person\": {\n \"document\": \"12345678901\",\n \"birthdate\": \"1990-05-15\",\n \"phone\": \"+5511999887766\",\n \"motherName\": \"Maria da Silva\"\n },\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"123\",\n \"complement\": \"Apto 4B\",\n \"neighborhood\": \"Centro\",\n \"postalCode\": \"01001-000\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"Brasil\"\n },\n \"balance\": {\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"amount\": 5000\n },\n \"campaignId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"companyId\": \"sua-company-id\",\n \"referenceId\": \"cad-unico-2024-001\"\n }\n}\n\nRetornado quando você envia o mesmo referenceId novamente. O campo status reflete o estado atual do registro existente.
Ainda na fila
\n{\n \"referenceId\": \"cad-unico-2024-001\",\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"status\": \"QUEUED\",\n \"message\": \"Registration already exists.\"\n}\n\nEm processamento
\n{\n \"referenceId\": \"cad-unico-2024-001\",\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"status\": \"PROCESSING\",\n \"message\": \"Registration already exists.\"\n}\n\nConcluído
\n{\n \"referenceId\": \"cad-unico-2024-001\",\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"status\": \"COMPLETED\",\n \"message\": \"Registration already exists.\"\n}\n\nFalhou
\n{\n \"referenceId\": \"cad-unico-2024-001\",\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"status\": \"FAILED\",\n \"message\": \"Registration already exists.\"\n}\n\nComo o processamento é assíncrono, você deve configurar um Webhook para receber as atualizações de status. Consulte a documentação de Gerenciamento de Webhooks para saber como registrar sua URL.
\nperson_registration.processingDisparado quando o cadastro sai da fila e inicia o processamento.
\n{\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"referenceId\": \"cad-unico-2024-001\",\n \"status\": \"PROCESSING\"\n}\n\nperson_registration.completedDisparado quando o cadastro é concluído com sucesso. O campo personId é o ID do participante criado na plataforma.
{\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"referenceId\": \"cad-unico-2024-001\",\n \"personId\": \"c9bf9e5b-5e17-4c61-a7e1-1c9043f3c9c1\",\n \"status\": \"COMPLETED\",\n \"result\": {\n \"id\": \"c9bf9e5b-5e17-4c61-a7e1-1c9043f3c9c1\",\n \"firstName\": \"João\",\n \"lastName\": \"da Silva\",\n \"document\": \"12345678901\",\n \"email\": \"joao.silva@email.com\"\n }\n}\n\nperson_registration.failedDisparado quando o processamento falha após todas as tentativas de retry (3 tentativas com backoff exponencial).
\nSaldo insuficiente da empresa
\n{\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"referenceId\": \"cad-unico-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Saldo insuficiente para esta operação.\"\n}\n\nCampanha não encontrada
\n{\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"referenceId\": \"cad-unico-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Campanha não encontrada.\"\n}\n\nErro no sistema externo
\n{\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"referenceId\": \"cad-unico-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Erro ao comunicar com o sistema externo. Tente novamente mais tarde.\"\n}\n\n[Request 201] → QUEUED → PROCESSING → COMPLETED (sucesso)\n → FAILED (erro após retries)\n\nSua requisição é validada e retorna 201 com status QUEUED
O job entra na fila e aguarda processamento
\nQuando um worker pega o job, o status muda para PROCESSING e o webhook person_registration.processing é disparado
O cadastro é executado no sistema externo
\nSucesso: status muda para COMPLETED, personId é salvo e o webhook person_registration.completed é disparado
Erro: o job tenta novamente (até 3 vezes). Se falhar em todas, status muda para FAILED e o webhook person_registration.failed é disparado
A rota usa a combinação de referenceId + companyId como chave de idempotência. Isso garante que:
O mesmo referenceId nunca será processado duas vezes
Se você reenviar o mesmo referenceId, a API retorna o status atual do registro existente
É seguro fazer retry de requisições que tiveram timeout ou falha de rede
\nRecomendação: Use um identificador único da sua aplicação (ex: ID do seu banco de dados, UUID gerado pelo seu sistema) como referenceId.
This endpoint allows you to create a business in pre-registration mode within a specific campaign.Pre-registration should be used when some information is not yet available (such as complete address or business details).The business will only be able to access the Link Premio Card and approved balance after all missing data is collected.
\nImportant: The field amount must always be sent in cents (e.g., 1500 = R$ 15,00).
\nbalanceTypeId → must be a valid identifier of the balance type.
\namount → value in cents (integer, no decimals).
\ncampaignId → links the business to a specific campaign.
\nThis endpoint allows you to retrieve a paginated list of businesses associated with your company.The response includes business information along with associated user details, providing a comprehensive view of all businesses in your system. Results can be filtered by search terms, status, and business type to help you find specific businesses efficiently.
\nResults are automatically scoped to your company - you can only retrieve businesses associated with your company.
\nThe search parameter searches within the business trading name using case-insensitive matching.
\nAll query parameters are optional and can be combined for more specific filtering.
\nThe response includes pagination metadata to help with navigation through large result sets.
\nnumber: [1-9999]
\n","type":"text/plain"},"key":"limit","value":""},{"disabled":true,"description":{"content":"number: [1-999999]
\n","type":"text/plain"},"key":"page","value":""},{"disabled":true,"description":{"content":"YYYY-MM-DD
\n","type":"text/plain"},"key":"startDate","value":""},{"disabled":true,"description":{"content":"YYYY-MM-DD
\n","type":"text/plain"},"key":"endDate","value":""},{"disabled":true,"description":{"content":"Paid | Rejected| Disabled
\n","type":"text/plain"},"key":"status[]","value":""},{"disabled":true,"description":{"content":"text
\n","type":"text/plain"},"key":"document","value":""},{"disabled":true,"description":{"content":"text | Filter by: tradingName, legalName, email, document
\n","type":"text/plain"},"key":"query","value":""}],"variable":[]}},"response":[{"id":"4629e142-2dc3-4f84-baeb-e8b7a9fb18bd","name":"200 OK - Businesses retrieved","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"This endpoint allows you to retrieve detailed information about a specific business by providing its unique identifier.The response includes comprehensive business information, associated user details, address information, and any validation errors if the business registration is incomplete.This endpoint is useful for getting complete business details for display, editing, or status checking purposes.
\nResults are automatically scoped to your company - you can only retrieve businesses associated with your company.
\nThe business must not be deleted (status not equal to 'Deleted').
\nIf the business user status is 'Rejected', the errors field will contain the rejection reasons.
\nThe response includes all related information (address, user details, agency, partner) in a single request.
\nAll timestamps are returned in ISO 8601 format.
\nDescription: Business not found
\nCondition: When the provided business ID doesn't exist or belongs to a different company
\nDescription: Internal server error
\nCondition: When there's a database or system error
\nEsta rota permite obter os dados detalhados de uma empresa específica utilizando seu ID ou CNPJ.
\nURL: GET /api/partner/company/:identifier
Autenticação: Requer Token JWT de Parceiro (Bearer Token)
\nPor ID:
\ncurl --location --request GET 'https://api.hub4pay.com.br/api/partner/company/d9390ffe-ba93-4fca-bf3e-f397771e37b3' \\\n--header 'Authorization: Bearer SEU_TOKEN_AQUI'\n\nPor CNPJ:
\ncurl --location --request GET 'https://api.hub4pay.com.br/api/partner/company/06990590000123' \\\n--header 'Authorization: Bearer SEU_TOKEN_AQUI'\n\n{\n \"id\": \"uuid-da-empresa\",\n \"name\": \"Razão Social da Empresa\",\n \"fantasyName\": \"Nome Fantasia\",\n \"email\": \"contato@empresa.com\",\n \"document\": \"06990590000123\",\n \"phone\": \"+5511999999999\",\n \"status\": \"Active\",\n \"address\": {\n \"street\": \"Rua Exemplo\",\n \"number\": \"123\",\n \"complement\": \"Sala 1\",\n \"neighborhood\": \"Centro\",\n \"postalCode\": \"01001-000\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"Brasil\"\n },\n \"balance\": {\n \"value\": 10000\n },\n \"companyFeature\": {\n \"paymentBoletoEnabled\": true,\n \"paymentTEDEnabled\": false,\n \"paymentPIXEnabled\": false\n }\n}\n\nEsta rota permite que um parceiro liste todas as empresas vinculadas à sua agência.
\nURL: GET /api/partner/company
Autenticação: Requer Token JWT de Parceiro (Bearer Token)
\ncurl --location --request GET 'https://api.hub4pay.com.br/api/partner/company?page=1&limit=10' \\\n--header 'Authorization: Bearer SEU_TOKEN_AQUI'\n\n{\n \"data\": [\n {\n \"id\": \"uuid-da-empresa\",\n \"name\": \"Nome da Empresa\",\n \"fantasyName\": \"Nome Fantasia\",\n \"email\": \"empresa@email.com\",\n \"document\": \"00.000.000/0001-00\",\n \"status\": \"Active\",\n \"createdAt\": \"2023-01-01T00:00:00.000Z\",\n \"agencyId\": \"seu-agency-id\",\n \"partnerId\": \"seu-partner-id\"\n }\n ],\n \"totalItems\": 1,\n \"totalPages\": 1\n}\n\nCria uma nova empresa e um usuário administrador associado.
\nURL: /api/partner/company
Método: POST
Autenticação: Bearer Token (JWT)
\n{\n \"company\": {\n \"companyName\": \"Minha Empresa LTDA\",\n \"corporateName\": \"Empresa Exemplo LTDA\",\n \"cnpj\": \"12.345.678/0001-90\",\n \"financialResponsibleEmail\": \"financeiro@empresa.com.br\",\n \"address\": {\n \"street\": \"Rua das Flores\",\n \"number\": \"123\",\n \"complement\": \"Bloco A\",\n \"neighborhood\": \"Centro\",\n \"postalCode\": \"01234-567\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"Brasil\"\n }\n },\n \"user\": {\n \"fullName\": \"João Silva\",\n \"phone\": \"(11) 98888-7777\",\n \"email\": \"joao.silva@empresa.com\"\n }\n}\n\ncompanyaddressuser{\n \"status\": \"success\",\n \"companyId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n}\n\nA API utiliza códigos de erro padronizados para facilitar a identificação de problemas.
\n{\n \"title\": \"Erro de validação\",\n \"message\": \"Os dados fornecidos são inválidos.\",\n \"code\": 1001,\n \"details\": [\n {\n \"code\": \"invalid_string\",\n \"path\": [\"user\", \"email\"],\n \"message\": \"E-mail inválido.\"\n }\n ]\n}\n\nBody (JSON)
{
name: Nome da Campanha,
description: Descrição da campanha,
companyId: uuid-da-empresa,
startDate: 2026-03-01T00:00:00.000Z,
endDate: 2026-12-31T23:59:59.000Z,
type: STANDARD,
status: Active,
typeOfService: INCENTIVE,
prepaidPercentage: 5,
prepaidPaymentTermsDays: 5
}
Campos
\nTipos de Campanha
STANDARD (Link Prêmio Card)
Requer: prepaidPercentage, prepaidPaymentTermsDays
\nOpcional: typeOfService (BENEFIT ou INCENTIVE)
PIX (Premio Conta)
Requer: pixFeePercentage, pixTariffCents
\ntypeOfService deve ser INCENTIVE (automático se enviado outro valor)
\nExemplo de Resposta (201 Created)
{
id: uuid-da-campanha,
name: Nome da Campanha,
description: Descrição da campanha,
status: Active,
type: STANDARD,
typeOfService: INCENTIVE,
startDate: 2026-03-01T00:00:00.000Z,
endDate: 2026-12-31T23:59:59.000Z,
companyId: uuid-da-empresa,
createdAt: 2026-02-27T10:00:00.000Z,
updatedAt: 2026-02-27T10:00:00.000Z
}
Códigos de Erro
\n","urlObject":{"protocol":"https","path":["api","partner","campaign"],"host":["api","hub4pay","com","br"],"query":[],"variable":[]}},"response":[{"id":"96c6e097-124c-4e0a-8db9-ea5b90d46552","name":"create-compaign","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"Campanha Verão 2026 2\",\n \"description\": \"Campanha promocional de verão\",\n \"companyId\": \"1dc1d79c-332f-4f46-8016-5d9f52fbe181\",\n \"startDate\": \"2026-03-01\",\n \"endDate\": \"2026-03-30\",\n \"type\": \"STANDARD\",\n \"status\": \"Active\",\n \"typeOfService\": \"INCENTIVE\",\n \"prepaidPercentage\": 10,\n \"prepaidPaymentTermsDays\": 12\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:3335/api/partner/campaign"},"status":"Created","code":201,"_postman_previewlanguage":"Text","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"503"},{"key":"ETag","value":"W/\"1f7-hVXWNsIOdHKPDOjU4N2mWV+iLso\""},{"key":"Date","value":"Thu, 26 Feb 2026 17:55:09 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"campaign\": {\n \"id\": \"c7789670-fa0d-449a-b9d0-18a189bc2728\",\n \"type\": \"STANDARD\",\n \"status\": \"Active\",\n \"createdAt\": \"2026-02-26T17:55:07.385Z\",\n \"updatedAt\": \"2026-02-26T17:55:07.385Z\",\n \"description\": \"Campanha promocional de verão\",\n \"startDate\": \"2026-03-01T03:00:00.000Z\",\n \"endDate\": \"2026-03-30T03:00:00.000Z\",\n \"companyId\": \"1dc1d79c-332f-4f46-8016-5d9f52fbe181\",\n \"name\": \"Campanha Verão 2026 2\",\n \"typeOfService\": \"INCENTIVE\",\n \"cityServiceCode\": \"5820\",\n \"cnae\": \"8299-7/02\",\n \"federalServiceCode\": \"15.01\"\n },\n \"isFirstCampaign\": false\n}"}],"_postman_id":"1a4e7ec2-8244-4b8b-b055-b462a8970994"},{"name":"update campaign","id":"9b2bb2e6-741d-401f-bc0b-eee8ffd017c5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Headers
\nParâmetros de Path
\nBody (JSON)
{
name: Nome Atualizado,
description: Descrição atualizada,
status: Active,
startDate: 2026-03-01T00:00:00.000Z,
endDate: 2026-12-31T23:59:59.000Z,
type: STANDARD,
typeOfService: INCENTIVE,
prepaidPercentage: 7,
prepaidPaymentTermsDays: 10,
pixFeePercentage: 3,
pixTariffCents: 100
}
Campos (todos opcionais)
\nRegras de Validação
Se type=STANDARD:
prepaidPercentage deve ser informado (ou null)
\nprepaidPaymentTermsDays deve ser informado (ou null)
Se type=PIX:
pixFeePercentage é obrigatório
\npixTariffCents é obrigatório
\ntypeOfService deve ser INCENTIVE (se enviado outro valor, retornará erro)
Datas:
startDate não pode ser anterior à data atual
\nendDate não pode ser anterior a startDate
\nExemplo de Resposta (200 OK)
{
id: 550e8400-e29b-41d4-a716-446655440000,
name: Campanha Atualizada,
description: Nova descrição,
status: Active,
type: STANDARD,
typeOfService: INCENTIVE,
startDate: 2026-03-01T00:00:00.000Z,
endDate: 2026-12-31T23:59:59.000Z,
companyId: 123e4567-e89b-12d3-a456-426614174000,
cityServiceCode: 1234,
cnae: 1234567,
federalServiceCode: 12.345,
createdAt: 2026-01-15T10:30:00.000Z,
updatedAt: 2026-02-27T15:20:00.000Z
}
Códigos de Erro
\n","urlObject":{"protocol":"https","path":["api","partner","campaign","c7789670-fa0d-449a-b9d0-18a189bc2728"],"host":["api","hub4pay","com","br"],"query":[],"variable":[]}},"response":[{"id":"144fd027-b1b6-442e-a764-8f7eb1c49a2a","name":"update-campaign","originalRequest":{"method":"PUT","header":[],"body":{"mode":"raw","raw":"{\n \"type\": \"PIX\",\n \"status\": \"Active\",\n \"createdAt\": \"2026-02-26T17:55:07.385Z\",\n \"updatedAt\": \"2026-02-26T17:55:07.385Z\",\n \"description\": \"Campanha promocional de verão\",\n \"startDate\": \"2026-03-01T03:00:00.000Z\",\n \"endDate\": \"2026-03-30T03:00:00.000Z\",\n \"companyId\": \"1dc1d79c-332f-4f46-8016-5d9f52fbe181\",\n \"name\": \"Campanha Verão 2026 2\",\n \"typeOfService\": \"INCENTIVE\",\n \"pixFeePercentage\": 12,\n \"pixTariffCents\": 10\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:3335/api/partner/campaign/c7789670-fa0d-449a-b9d0-18a189bc2728"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"461"},{"key":"ETag","value":"W/\"1cd-MI3hP2pPygG/13dU1bO367b1FLg\""},{"key":"Date","value":"Thu, 26 Feb 2026 18:02:07 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"c7789670-fa0d-449a-b9d0-18a189bc2728\",\n \"type\": \"PIX\",\n \"status\": \"Active\",\n \"createdAt\": \"2026-02-26T17:55:07.385Z\",\n \"updatedAt\": \"2026-02-26T18:02:07.149Z\",\n \"description\": \"Campanha promocional de verão\",\n \"startDate\": \"2026-03-01T03:00:00.000Z\",\n \"endDate\": \"2026-03-30T03:00:00.000Z\",\n \"companyId\": \"1dc1d79c-332f-4f46-8016-5d9f52fbe181\",\n \"name\": \"Campanha Verão 2026 2\",\n \"typeOfService\": \"INCENTIVE\",\n \"cityServiceCode\": \"5820\",\n \"cnae\": \"8299-7/02\",\n \"federalServiceCode\": \"15.01\"\n}"}],"_postman_id":"9b2bb2e6-741d-401f-bc0b-eee8ffd017c5"},{"name":"fetch campaigns","id":"e29ba929-aeb7-4668-adb0-b10303d728bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Headers
\nQuery Params
\nExemplos de Requisição
Listar todas:
GET /api/partner/campaign
Com paginação:
GET /api/partner/campaign?page=1&limit=10
Com filtros:
GET /api/partner/campaign?status=Active&type=STANDARD&companyId=123e4567-e89b-12d3-a456-426614174000
Buscar por nome:
GET /api/partner/campaign?query=campanha incentivo
Filtrar por período:
GET /api/partner/campaign?startDate=2026-01-01&endDate=2026-12-31
Exemplo de Resposta (200 OK)
{
data: [
{
id: 550e8400-e29b-41d4-a716-446655440000,
name: Campanha Prize 2026,
description: Campanha de incentivo anual,
status: Active,
type: STANDARD,
typeOfService: INCENTIVE,
startDate: 2026-01-01T00:00:00.000Z,
endDate: 2026-12-31T23:59:59.000Z,
companyId: 123e4567-e89b-12d3-a456-426614174000,
company: {
name: Empresa Exemplo Ltda
},
createdAt: 2026-01-15T10:30:00.000Z,
updatedAt: 2026-02-20T14:45:00.000Z
},
{
id: 660e8400-e29b-41d4-a716-446655440001,
name: Campanha PIX Bonus,
description: Campanha de bônus PIX,
status: Disabled,
type: PIX,
typeOfService: INCENTIVE,
startDate: 2026-02-01T00:00:00.000Z,
endDate: 2026-06-30T23:59:59.000Z,
companyId: 123e4567-e89b-12d3-a456-426614174000,
company: {
name: Empresa Exemplo Ltda
},
createdAt: 2026-01-20T09:00:00.000Z,
updatedAt: 2026-02-10T11:00:00.000Z
}
],
totalItems: 2,
totalPages: 1
}
Descrição dos Campos da Resposta
\nObservações
\nSe status for Active, retorna campanhas ativas com endDate >= hoje
\nSe status for Disabled, retorna campanhas desativadas
\nSe status for omitido, retorna todas (incluindo finished)
\nCampanhas com endDate < hoje aparecem com status Finished
\nCódigos de Erro
\n","urlObject":{"protocol":"https","path":["api","partner","campaign"],"host":["api","hub4pay","com","br"],"query":[],"variable":[]}},"response":[],"_postman_id":"e29ba929-aeb7-4668-adb0-b10303d728bf"},{"name":"get compaign by id","id":"f735732b-18a9-4ebf-8938-65067f06a588","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Headers
\nParâmetros de Path
\nExemplo de Requisição
GET /api/partner/campaign/550e8400-e29b-41d4-a716-446655440000
Exemplo de Resposta (200 OK)
{
id: 550e8400-e29b-41d4-a716-446655440000,
name: Campanha Prize 2026,
description: Campanha de incentivo para funcionários,
status: Active,
type: STANDARD,
typeOfService: INCENTIVE,
startDate: 2026-01-01T00:00:00.000Z,
endDate: 2026-12-31T23:59:59.000Z,
companyId: 123e4567-e89b-12d3-a456-426614174000,
cityServiceCode: 1234,
cnae: 1234567,
federalServiceCode: 12.345,
campaignFeesConfiguration: {
id: abc12345-6789-0abc-def1-234567890abc,
prepaidPercentage: 5,
prepaidPaymentTermsDays: 5,
postpaidPercentage: null,
postpaidPaymentTermsDays: null,
pixFeePercentage: null,
pixTariffCents: null
},
createdAt: 2026-01-15T10:30:00.000Z,
updatedAt: 2026-02-20T14:45:00.000Z
}
Descrição dos Campos da Resposta
\nCódigos de Erro
\n","urlObject":{"protocol":"https","path":["api","partner","campaign","c7789670-fa0d-449a-b9d0-18a189bc2728"],"host":["api","hub4pay","com","br"],"query":[],"variable":[]}},"response":[{"id":"a3cd1916-c9d8-4281-92b4-13d6d554ea50","name":"get-compaign","originalRequest":{"method":"GET","header":[],"url":"http://localhost:3335/api/partner/campaign/c7789670-fa0d-449a-b9d0-18a189bc2728"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"904"},{"key":"ETag","value":"W/\"388-+0JfDf4XwhYYt9EGrTnCagdZmMk\""},{"key":"Date","value":"Thu, 26 Feb 2026 17:58:24 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"Keep-Alive","value":"timeout=5"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"c7789670-fa0d-449a-b9d0-18a189bc2728\",\n \"type\": \"PIX\",\n \"status\": \"Active\",\n \"createdAt\": \"2026-02-26T17:55:07.385Z\",\n \"updatedAt\": \"2026-02-26T17:58:19.371Z\",\n \"description\": \"Campanha promocional de verão\",\n \"startDate\": \"2026-03-01T03:00:00.000Z\",\n \"endDate\": \"2026-03-30T03:00:00.000Z\",\n \"companyId\": \"1dc1d79c-332f-4f46-8016-5d9f52fbe181\",\n \"name\": \"Campanha Verão 2026 2\",\n \"typeOfService\": \"INCENTIVE\",\n \"cityServiceCode\": \"5820\",\n \"cnae\": \"8299-7/02\",\n \"federalServiceCode\": \"15.01\",\n \"campaignFeesConfiguration\": {\n \"id\": \"ee480db1-3f29-4371-b6ea-5d36446d0342\",\n \"status\": \"Active\",\n \"createdAt\": \"2026-02-26T17:55:07.385Z\",\n \"updatedAt\": \"2026-02-26T17:58:11.962Z\",\n \"prepaidPercentage\": null,\n \"postpaidPercentage\": null,\n \"prepaidPaymentTermsDays\": null,\n \"postpaidPaymentTermsDays\": null,\n \"pixFeePercentage\": 0,\n \"pixTariffCents\": 0,\n \"campaignId\": \"c7789670-fa0d-449a-b9d0-18a189bc2728\",\n \"partnerFeeConfigurationId\": \"da54981a-82aa-42a9-8521-02d2e5698b54\"\n }\n}"}],"_postman_id":"f735732b-18a9-4ebf-8938-65067f06a588"}],"id":"fbc68789-b581-4113-8a47-ed6540915bd1","_postman_id":"fbc68789-b581-4113-8a47-ed6540915bd1","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Balance-Request","item":[{"name":"Public","item":[{"name":"get balance request","id":"a102edec-980a-4734-87fa-070ac0c45fda","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"page","value":"1","type":"text"},{"key":"limit","value":"10","type":"text"}],"url":"https://api.hub4pay.com.br/api/balance-request/20260225201615869BQ","description":"GET /api/balance-request/20260225201615869BQ\n\n200{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"code\": \"20260225201615869BQ\",\n \"status\": \"WAITING_PAYMENT\",\n \"value\": 100000,\n \"totalValue\": 105000,\n \"destination\": \"linkpremiocard\",\n \"pixTariffCents\": null,\n \"paymentDueDate\": \"2026-03-04T00:00:00.000Z\",\n \"company\": {\n \"name\": \"Empresa Exemplo Ltda\",\n \"fantasyName\": \"Empresa Exemplo\"\n },\n \"campaign\": {\n \"name\": \"Campanha Prize 2026\"\n }\n}\n\n\n\n
Os valores são retornados em centavos. Para converter:
\n100000 = R$ 1.000,00\n\n
Esta é uma rota pública, não requer autenticação
\nRetorna informações básicas da solicitação de saldo para consulta externa
\n{\n \"invoiceLink\": \"https://exemplo.com/nota-fiscal.pdf\",\n \"invoiceNumber\": 1234,\n \"paymentDueDate\": \"2026-03-15T00:00:00.000Z\",\n \"paymentDate\": null,\n \"value\": 105000,\n \"observation\": \"Observações adicionais (opcional)\"\n}\n\nPOST /api/partner/balance-requests/240080d0-2bb7-4a4f-9f3f-8b4f341d92a8/invoices\n\n{\n \"invoiceLink\": \"https://exemplo.com/nota-fiscal.pdf\",\n \"invoiceNumber\": 1234,\n \"paymentDueDate\": \"2026-03-15T00:00:00.000Z\",\n \"value\": 105000\n}\n\n201{\n \"id\": \"invoice-uuid-001\",\n \"balanceRequestId\": \"240080d0-2bb7-4a4f-9f3f-8b4f341d92a8\",\n \"invoiceLink\": \"https://exemplo.com/nota-fiscal.pdf\",\n \"invoiceNumber\": 1234,\n \"paymentDueDate\": \"2026-03-15T00:00:00.000Z\",\n \"paymentDate\": null,\n \"value\": 105000,\n \"observation\": null,\n \"createdAt\": \"2026-02-27T15:30:00.000Z\",\n \"updatedAt\": \"2026-02-27T15:30:00.000Z\"\n}\n\n\n\n
Os valores são retornados em centavos. Para converter:
\n105000 = R$ 1.050,00\n\n<ul ><li ><div>Ao criar uma invoice, o status da solicitação de saldo pode ser alterado automaticamente</div></li><li ><div>Se a invoice for criada com sucesso e a solicitação estiver no status adequado, pode permitir a liberação do saldo</div></li></ul>
\n
\n\n<p >Todos os campos são opcionais</p>
\n
{\n \"invoiceLink\": \"https://exemplo.com/nota-fiscal-atualizada.pdf\",\n \"invoiceNumber\": 1235,\n \"paymentDueDate\": \"2026-03-20T00:00:00.000Z\",\n \"paymentDate\": \"2026-03-18T00:00:00.000Z\",\n \"value\": 110000,\n \"observation\": \"Observação atualizada\"\n}\n\nPATCH /api/partner/balance-requests/240080d0-2bb7-4a4f-9f3f-8b4f341d92a8/invoices/invoice-uuid-001\n\n{\n \"invoiceNumber\": 1235,\n \"paymentDate\": \"2026-03-18T00:00:00.000Z\"\n}\n\n200{\n \"id\": \"invoice-uuid-001\",\n \"balanceRequestId\": \"240080d0-2bb7-4a4f-9f3f-8b4f341d92a8\",\n \"invoiceLink\": \"https://exemplo.com/nota-fiscal.pdf\",\n \"invoiceNumber\": 1235,\n \"paymentDueDate\": \"2026-03-15T00:00:00.000Z\",\n \"paymentDate\": \"2026-03-18T00:00:00.000Z\",\n \"value\": 105000,\n \"observation\": \"Observação atualizada\",\n \"createdAt\": \"2026-02-27T15:30:00.000Z\",\n \"updatedAt\": \"2026-02-27T16:00:00.000Z\"\n}\n\n\n\n
Os valores são retornados em centavos. Para converter:
\n105000 = R$ 1.050,00{\n \"companyId\": \"uuid-da-empresa\",\n \"campaignId\": \"uuid-da-campanha\",\n \"responsible\": \"Nome do responsável\",\n \"value\": 100000,\n \"paymentDueDate\": \"2026-03-15T00:00:00.000Z\",\n \"details\": \"Observações adicionais (opcional)\",\n \"destination\": \"linkpremiocard\",\n \"spreadsheetUrl\": \"https://url-da-planilha.com/planilha.xlsx\",\n \"taxPercentage\": 5.5\n}\n\ndestinationlinkpremiocard — Link Prêmio Card
pix — PIX
200{\n \"requestId\": \"uuid-da-solicitacao\",\n \"deductionsAmount\": 1000.00,\n \"servicesAmount\": 1055.00,\n \"invoiceId\": \"uuid-da-nota\",\n \"invoiceExternalId\": \"id-externo-nfe\",\n \"invoiceNumber\": 1234,\n \"nfeStatus\": \"Pending\",\n \"balanceRequestStatus\": \"GENERATING_INVOICE\",\n \"balanceRequestCode\": \"COD-2026-XXXXX\"\n}\n\n# Listar todas\nGET /api/partner/balance-requests\n# Com paginação\nGET /api/partner/balance-requests?page=1&limit=10\n# Com filtros\nGET /api/partner/balance-requests?status=WAITING_PAYMENT&companyId=123e4567-e89b-12d3-a456-426614174000\n# Buscar por código\nGET /api/partner/balance-requests?query=COD-2026-0001\n# Filtrar por campanha\nGET /api/partner/balance-requests?campaignId=550e8400-e29b-41d4-a716-446655440000\n\n200{\n \"data\": [\n {\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"code\": \"COD-2026-0001\",\n \"value\": 100000,\n \"totalValue\": 105000,\n \"status\": \"WAITING_PAYMENT\",\n \"destination\": \"linkpremiocard\",\n \"createdAt\": \"2026-02-27T10:30:00.000Z\",\n \"balanceReleaseDate\": \"2026-03-04T10:30:00.000Z\",\n \"campaign\": {\n \"name\": \"Campanha Prize 2026\"\n }\n },\n {\n \"id\": \"660e8400-e29b-41d4-a716-446655440001\",\n \"code\": \"COD-2026-0002\",\n \"value\": 50000,\n \"totalValue\": 51500,\n \"status\": \"COMPLETED\",\n \"destination\": \"pix\",\n \"createdAt\": \"2026-02-20T14:00:00.000Z\",\n \"balanceReleaseDate\": \"2026-02-25T14:00:00.000Z\",\n \"campaign\": {\n \"name\": \"Campanha PIX Bonus\"\n }\n }\n ],\n \"totalItems\": 2,\n \"totalPages\": 1\n}\n\n\n\n
Os valores são retornados em centavos. Para converter:
\n100000 = R$ 1.000,00GET /api/partner/balance-requests/COD-2026-0001\n\n200{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"code\": \"COD-2026-0001\",\n \"status\": \"WAITING_PAYMENT\",\n \"value\": 100000,\n \"totalValue\": 105000,\n \"details\": \"Observações adicionais\",\n \"destination\": \"linkpremiocard\",\n \"responsible\": \"João Silva\",\n \"campaignFeeType\": \"prepaid\",\n \"campaignFeePercentage\": 5,\n \"pixTariffCents\": null,\n \"spreadsheetUrl\": \"https://exemplo.com/planilha.xlsx\",\n \"createdAt\": \"2026-02-27T10:30:00.000Z\",\n \"updatedAt\": \"2026-02-27T10:30:00.000Z\",\n \"balanceReleaseDate\": \"2026-03-04T10:30:00.000Z\",\n \"companyId\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"agencyId\": \"987fcdeb-51a2-3d45-e678-901234567890\",\n \"campaignId\": \"abc12345-6789-0abc-def1-234567890abc\",\n \"requester\": {\n \"id\": \"user-uuid-123\",\n \"firstName\": \"João\",\n \"lastName\": \"Silva\"\n },\n \"agency\": {\n \"id\": \"987fcdeb-51a2-3d45-e678-901234567890\",\n \"name\": \"Agência Exemplo Ltda\"\n },\n \"campaign\": {\n \"name\": \"Campanha Prize 2026\"\n }\n}\n\n\n\n
Os valores são retornados em centavos. Para converter:
\n100000 = R$ 1.000,00{\n \"status\": \"WAITING_PAYMENT\",\n \"reason\": \"Motivo da alteração (opcional)\"\n}\n\nPATCH /api/partner/balance-requests/{{UUID}}/status\n\n{\n \"status\": \"WAITING_PAYMENT\"\n}\n\n201{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"WAITING_PAYMENT\",\n \"updatedAt\": \"2026-02-27T11:00:00.000Z\"\n}\n\nStatus permitido — Não é possível alterar para COMPLETED diretamente (somente via liberação de saldo)
reason obrigatório — Quando o status for REJECTED, o campo reason é obrigatório
Invoice obrigatória — Para alterar para BALANCE_RELEASE, a solicitação deve ter pelo menos uma invoice associada
POST /api/partner/balance-requests/:UUID/release-balance\n\n\n\n<p >Body: Vazio (não requer body)</p>
\n
201{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"COMPLETED\"\n}\n\nGET /api/partner/balance-requests/20260225201615869BQ/logs\n\n200{\n \"data\": [\n {\n \"id\": \"log-uuid-001\",\n \"message\": \"Solicitação de saldo criada pela agência Exemplo Ltda com o valor de R$ 1000.00.\",\n \"createdAt\": \"2026-02-25T20:16:15.000Z\"\n },\n {\n \"id\": \"log-uuid-002\",\n \"message\": \"Status alterado para WAITING_PAYMENT.\",\n \"createdAt\": \"2026-02-25T20:20:00.000Z\"\n },\n {\n \"id\": \"log-uuid-003\",\n \"message\": \"Status alterado para BALANCE_RELEASE.\",\n \"createdAt\": \"2026-02-26T10:00:00.000Z\"\n }\n ],\n \"totalItems\": 3,\n \"totalPages\": 1\n}\n\nPOST /api/partner/balance-requests/20260225201615869BQ/pix\n\n\n\n<p >Body: Vazio (não requer body)</p>
\n
201{\n \"transactionId\": \"tx-uuid-001\",\n \"emv\": \"00020101021229330014br.gov.bcb.pix0133a8f9d8-7b6c-4f5e-9a3d-2e1f0a9b8c9d5204000053039865404100.005802BR5909LinkPremio6010São Paulo62070503*__6304D3E7\",\n \"expiresAt\": \"2026-02-28T10:30:00.000Z\"\n}\n\nA solicitação deve estar em um dos seguintes status:
\nGENERATING_INVOICE
WAITING_PAYMENT
A solicitação deve ter destination igual a pix
A solicitação deve ter uma empresa vinculada (companyId)
O QR Code expira em 5 minutos
\n\n\n
Se já existir um QR Code ativo, ele será substituído (superseded)
O valor do PIX é baseado no totalValue da solicitação, ou no value se totalValue for zero ou nulo
GET /api/partner/balance-requests/20260225201615869BQ/pix\n\n200{\n \"transactionId\": \"tx-uuid-001\",\n \"emv\": \"00020101021229330014br.gov.bcb.pix0133a8f9d8-7b6c-4f5e-9a3d-2e1f0a9b8c9d5204000053039865404100.005802BR5909LinkPremio6010São Paulo62070503*\\\\6304D3E7\",\n \"expiresAt\": \"2026-02-28T10:30:00.000Z\"\n}\n\n\n\n
A solicitação deve ter destination igual a pix
O QR Code possui um tempo de expiração
\nÉ necessário gerar o QR Code primeiro via POST antes de consultá-lo
{\n \"companyId\": \"uuid-da-company\",\n \"url\": \"https://seudominio.com/webhook\",\n \"events\": [\n \"balance_request.paid\",\n \"balance_request.failed\",\n \"balance_request.refunded\",\n \"balance_request.cancelled\"\n ],\n \"headers\": {\n \"Authorization\": \"Bearer token\",\n \"X-API-Key\": \"sua-chave\"\n },\n \"description\": \"Webhook para notificações de balance request\",\n \"status\": \"Active\"\n}\n\nbalance_request.paid
balance_request.failed
balance_request.refunded
balance_request.cancelled
201{\n \"id\": \"uuid-do-webhook\",\n \"url\": \"https://seudominio.com/webhook\",\n \"events\": [\"balance_request.paid\"],\n \"headers\": {},\n \"description\": \"Webhook para notificações\",\n \"status\": \"Active\",\n \"companyId\": \"uuid-da-company\",\n \"createdAt\": \"2026-03-03T10:00:00Z\",\n \"updatedAt\": \"2026-03-03T10:00:00Z\"\n}\n` ` `\n\nWebhook Balance Request — Payloads
\nDocumentação dos payloads enviados para cada evento de balance_request.
balance_request.paidDisparado quando o pagamento da requisição de saldo é confirmado e o saldo é liberado.
\n{\n \"event\": \"balance_request.paid\",\n \"timestamp\": \"2026-03-18T10:30:00Z\",\n \"data\": {\n \"id\": \"uuid-da-balance-request\",\n \"code\": \"BR-20260318-ABC123\",\n \"value\": 500000,\n \"totalValue\": 505250,\n \"status\": \"COMPLETED\",\n \"reason\": null,\n \"destination\": \"linkpremiocard\",\n \"createdAt\": \"2026-03-18T09:00:00Z\",\n \"updatedAt\": \"2026-03-18T10:30:00Z\",\n \"balanceReleaseDate\": \"2026-03-18T10:30:00Z\",\n \"campaignFeePercentage\": 5,\n \"campaignFeeType\": \"prepaid\",\n \"pixTariffCents\": null,\n \"requester\": {\n \"id\": \"uuid-do-usuario\",\n \"firstName\": \"João\",\n \"lastName\": \"Silva\",\n \"email\": \"joao.silva@empresa.com\"\n },\n \"agency\": {\n \"id\": \"uuid-da-agencia\",\n \"name\": \"Agência Central\"\n },\n \"company\": {\n \"id\": \"uuid-da-company\",\n \"name\": \"Empresa XYZ\",\n \"document\": \"12345678000190\"\n },\n \"campaign\": {\n \"id\": \"uuid-da-campanha\",\n \"name\": \"Campanha Natal 2026\",\n \"type\": \"STANDARD\"\n }\n }\n}\n\nbalance_request.failedDisparado quando o pagamento da requisição de saldo falha.
\n{\n \"event\": \"balance_request.failed\",\n \"timestamp\": \"2026-03-18T10:30:00Z\",\n \"data\": {\n \"id\": \"uuid-da-balance-request\",\n \"code\": \"BR-20260318-ABC123\",\n \"value\": 500000,\n \"totalValue\": 505250,\n \"status\": \"REJECTED\",\n \"reason\": \"Pagamento não identificado após expiração do prazo\",\n \"destination\": \"linkpremiocard\",\n \"createdAt\": \"2026-03-18T09:00:00Z\",\n \"updatedAt\": \"2026-03-18T10:30:00Z\",\n \"balanceReleaseDate\": null,\n \"campaignFeePercentage\": 5,\n \"campaignFeeType\": \"prepaid\",\n \"pixTariffCents\": null,\n \"requester\": {\n \"id\": \"uuid-do-usuario\",\n \"firstName\": \"João\",\n \"lastName\": \"Silva\",\n \"email\": \"joao.silva@empresa.com\"\n },\n \"agency\": {\n \"id\": \"uuid-da-agencia\",\n \"name\": \"Agência Central\"\n },\n \"company\": {\n \"id\": \"uuid-da-company\",\n \"name\": \"Empresa XYZ\",\n \"document\": \"12345678000190\"\n },\n \"campaign\": {\n \"id\": \"uuid-da-campanha\",\n \"name\": \"Campanha Natal 2026\",\n \"type\": \"STANDARD\"\n }\n }\n}\n\nreason)balance_request.refundedDisparado quando há um estorno de uma requisição de saldo já paga.
\n{\n \"event\": \"balance_request.refunded\",\n \"timestamp\": \"2026-03-18T14:00:00Z\",\n \"data\": {\n \"id\": \"uuid-da-balance-request\",\n \"code\": \"BR-20260318-ABC123\",\n \"value\": 500000,\n \"totalValue\": 505250,\n \"status\": \"REFUNDED\",\n \"reason\": \"Estorno solicitado pelo cliente\",\n \"destination\": \"linkpremiocard\",\n \"createdAt\": \"2026-03-18T09:00:00Z\",\n \"updatedAt\": \"2026-03-18T14:00:00Z\",\n \"balanceReleaseDate\": \"2026-03-18T10:30:00Z\",\n \"refundedAt\": \"2026-03-18T14:00:00Z\",\n \"refundedValue\": 500000,\n \"campaignFeePercentage\": 5,\n \"campaignFeeType\": \"prepaid\",\n \"pixTariffCents\": null,\n \"requester\": {\n \"id\": \"uuid-do-usuario\",\n \"firstName\": \"João\",\n \"lastName\": \"Silva\",\n \"email\": \"joao.silva@empresa.com\"\n },\n \"agency\": {\n \"id\": \"uuid-da-agencia\",\n \"name\": \"Agência Central\"\n },\n \"company\": {\n \"id\": \"uuid-da-company\",\n \"name\": \"Empresa XYZ\",\n \"document\": \"12345678000190\"\n },\n \"campaign\": {\n \"id\": \"uuid-da-campanha\",\n \"name\": \"Campanha Natal 2026\",\n \"type\": \"STANDARD\"\n }\n }\n}\n\nreason)balance_request.cancelledDisparado quando uma requisição de saldo é cancelada pelo solicitante ou pelo sistema.
\n{\n \"event\": \"balance_request.cancelled\",\n \"timestamp\": \"2026-03-18T09:15:00Z\",\n \"data\": {\n \"id\": \"uuid-da-balance-request\",\n \"code\": \"BR-20260318-ABC123\",\n \"value\": 500000,\n \"totalValue\": 505250,\n \"status\": \"CANCELLED\",\n \"reason\": \"Cancelado pelo solicitante\",\n \"destination\": \"linkpremiocard\",\n \"createdAt\": \"2026-03-18T09:00:00Z\",\n \"updatedAt\": \"2026-03-18T09:15:00Z\",\n \"balanceReleaseDate\": null,\n \"cancellationDetails\": {\n \"cancelledBy\": \"user\",\n \"cancelledByUserId\": \"uuid-do-usuario\",\n \"cancellationType\": \"manual\"\n },\n \"campaignFeePercentage\": 5,\n \"campaignFeeType\": \"prepaid\",\n \"pixTariffCents\": null,\n \"requester\": {\n \"id\": \"uuid-do-usuario\",\n \"firstName\": \"João\",\n \"lastName\": \"Silva\",\n \"email\": \"joao.silva@empresa.com\"\n },\n \"agency\": {\n \"id\": \"uuid-da-agencia\",\n \"name\": \"Agência Central\"\n },\n \"company\": {\n \"id\": \"uuid-da-company\",\n \"name\": \"Empresa XYZ\",\n \"document\": \"12345678000190\"\n },\n \"campaign\": {\n \"id\": \"uuid-da-campanha\",\n \"name\": \"Campanha Natal 2026\",\n \"type\": \"STANDARD\"\n }\n }\n}\n\nValores em centavos — Todos os valores monetários (value, totalValue, refundedValue, pixTariffCents) são em centavos. Ex: 500000 = R$ 5.000,00
Timestamps — Todos os campos de data/hora seguem o formato ISO 8601. Ex: 2026-03-18T10:30:00Z
Campos nulos — Os campos campaign, company, pixTariffCents, reason e balanceReleaseDate podem ser null dependendo do contexto
Taxa de campanha — O campo campaignFeePercentage indica o percentual da taxa cobrada. O tipo (prepaid ou postpaid) afeta como a taxa é calculada no valor total
{\n \"companyId\": \"uuid-da-company\",\n \"url\": \"https://novodominio.com/webhook\",\n \"events\": [\n \"balance_request.paid\",\n \"balance_request.failed\"\n ],\n \"headers\": {\n \"Authorization\": \"Bearer novo-token\"\n },\n \"description\": \"Nova descrição\",\n \"status\": \"Active\"\n}\n\nPUT /api/partner/webhooks/uuid-do-webhook
\n200{\n\"id\": \"uuid-do-webhook\",\n\"url\": \"https://novodominio.com/webhook\",\n\"events\": [\n\"balance_request.paid\",\n\"balance_request.failed\"\n],\n\"headers\": {\n\"Authorization\": \"Bearer novo-token\"\n},\n\"description\": \"Nova descrição\",\n\"status\": \"Active\",\n\"companyId\": \"uuid-da-company\",\n\"createdAt\": \"2026-03-03T10:00:00Z\",\n\"updatedAt\": \"2026-03-03T12:00:00Z\"\n}\n\n404 — Webhook não encontrado{\n \"message\": \"Webhook uuid-do-webhook not found\",\n \"error\": \"Not Found\",\n \"statusCode\": 404\n}\n` ` `\n\nDELETE /api/partner/webhooks/uuid-do-webhook?companyId=uuid-da-company\n\n204\n\nNo Content
\n
404 — Webhook não encontrado{\n \"message\": \"Webhook uuid-do-webhook not found\",\n \"error\": \"Not Found\",\n \"statusCode\": 404\n}\n\nGET /api/partner/webhooks?companyId=uuid-da-company&page=1&limit=10\n\n200{\n \"data\": [\n {\n \"id\": \"uuid-do-webhook\",\n \"url\": \"https://seudominio.com/webhook\",\n \"events\": [\"balance_request.created\"],\n \"headers\": {},\n \"description\": \"Webhook para notificações\",\n \"status\": \"Active\",\n \"companyId\": \"uuid-da-company\",\n \"createdAt\": \"2026-03-03T10:00:00Z\",\n \"updatedAt\": \"2026-03-03T10:00:00Z\"\n }\n ],\n \"totalItems\": 1,\n \"totalPages\": 1\n}\n\nGET /api/partner/webhooks/uuid-do-webhook?companyId=uuid-da-company\n\n200{\n \"data\": {\n \"id\": \"uuid-do-webhook\",\n \"url\": \"https://seudominio.com/webhook\",\n \"events\": [\"balance_request.created\"],\n \"headers\": {},\n \"description\": \"Webhook para notificações\",\n \"status\": \"Active\",\n \"companyId\": \"uuid-da-company\",\n \"createdAt\": \"2026-03-03T10:00:00Z\",\n \"updatedAt\": \"2026-03-03T10:00:00Z\"\n }\n}\n\n200{\n \"data\": null\n}\n\nPara acessar a maioria das rotas da API de Parceiros, é necessário gerar um token de acesso utilizando as credenciais fornecidas (clientId e secret).
Autentica o parceiro e retorna um JWT (JSON Web Token).
\nURL: /api/partner/auth
Método: POST
Autenticação: Não requer token prévio
{\n \"clientId\": \"71348122-8356-427c-9588-44448555e088\",\n \"secret\": \"sua_chave_secreta_aqui\"\n}\n\n{\n \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"expiresIn\": 1715600000\n}\n\nA API possui dois níveis de autenticação:
\nPermite acesso aos recursos globais da agência.
\nNecessário para consumir recursos específicos de uma empresa vinculada à agência.
\nPara consumir rotas que operam em nível de company, é obrigatório gerar o token informando o companyId no payload.
{\n \"clientId\": \"71348122-8356-427c-9588-44448555e088\",\n \"secret\": \"sua_chave_secreta_aqui\",\n \"companyId\": \"9dc7b6f1-12a4-4c9e-8f9b-123456789abc\"\n}\n\nTokens gerados apenas com clientId e secret → nível agência
Tokens gerados com clientId, secret e companyId → nível company
Para acessar rotas de company, o companyId deve estar presente no payload do token
Se o token não contiver companyId, o acesso às rotas de company será negado.
Todas as rotas que exigem autenticação aceitam:
\nAuthorization: Bearer <accessToken>\n\nSe utilizar Authorization: Bearer, não deve enviar x-api-key
Se utilizar x-api-key, não deve enviar Authorization
O envio simultâneo dos dois headers resultará em 401 Unauthorized
Um request, um token, um formato. Simples, direto, sem ambiguidade.
\nAgência acessando recursos globais → token simples
\nAgência acessando recursos de uma empresa → token com companyId
Toda rota protegida aceita x-api-key ou Authorization: Bearer
Se o token não tiver o escopo correto, a API responde com 401 Unauthorized.
Entities section manages both individual persons and business entities within the platform.
\n","_postman_id":"260d696a-1d46-4597-b695-c7857b1e6e55","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Transfer","item":[{"name":"Balance","id":"6be5bad2-9b40-4b08-b7a1-4a1099000040","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"balanceTypeId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"description\": \"Description\",\r\n \"campaignId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"amount\": 1000\r\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/transfer/balance","description":"This endpoint allows you to transfer balance from your company to a customer (person or business). The transfer can be made to both active customers and customers in pre-registration mode. For pre-registered customers, the balance will be held until they complete their registration and become active. The system automatically handles different customer statuses and ensures proper balance validation before processing the transfer.
\nBalance is immediately transferred to the customer's account
\nCustomer can access and use the transferred balance immediately
\nTransaction is processed through the payment system
\nBalance is held in pre-registration mode
\nCustomer cannot access the balance until they become active
\nBalance will be available once customer completes registration
\nTransaction is recorded but not processed through payment system
\nCompany must exist and be active
\nCompany must have sufficient available balances
\nCompany balance must account for pending transactions
\nCompany balance must account for pre-registered amounts
\nCustomer (person or business) must exist
\nCustomer must be in a valid status for transfer
\nCustomer must have the specified balance type
\nBalance type must exist and be active
\nBalance type must be valid for the customer
\nIf provided, campaign must exist
\nCampaign is required
\nAmount: Must always be sent in cents (e.g., 1500 = R$ 15,00)
\nRate Limiting: Only one transfer per customer per 60 seconds
\nCustomer Types: Supports both persons and businesses
\nPre-Registration: Balance is held for inactive customers until they become active
\nTransaction Tracking: All transfers are recorded with unique transaction IDs
\nA rota POST /api/v2/external/transfer/balance permite transferir saldo para participantes de forma assíncrona. Diferente da V1, esta rota retorna imediatamente um ID de transferência e o processamento real ocorre em segundo plano, com notificações via Webhook.
Todos os requests devem incluir o header x-api-key com sua chave de API fornecida.
x-api-key: sua-chave-api-aqui\nContent-Type: application/json\n\nExemplo Completo (com descrição)
\n{\n \"referenceId\": \"transf-2024-001\",\n \"customerId\": \"c9bf9e5b-5e17-4c61-a7e1-1c9043f3c9c1\",\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"campaignId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"amount\": 10000,\n \"description\": \"Bônus de boas-vindas - campanha natalina\"\n}\n\nExemplo Mínimo
\n{\n \"referenceId\": \"transf-2024-002\",\n \"customerId\": \"c9bf9e5b-5e17-4c61-a7e1-1c9043f3c9c1\",\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"campaignId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"amount\": 1\n}\n\nExemplo com Valor Alto (R$ 500,00)
\n{\n \"referenceId\": \"transf-premio-003\",\n \"customerId\": \"d8e7f6a5-b4c3-2d1e-0f9a-8b7c6d5e4f3a\",\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"campaignId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"amount\": 50000,\n \"description\": \"Prêmio do sorteio mensal\"\n}\n\nRetornado quando o referenceId é único e a transferência foi colocada na fila com sucesso.
{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"QUEUED\",\n \"jobId\": \"bull:balance-transfer-abc123:1\"\n}\n\nRetornado quando você envia o mesmo referenceId novamente. O campo status reflete o estado atual da transferência existente.
Ainda na fila
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"QUEUED\",\n \"message\": \"Transfer already exists.\"\n}\n\nEm processamento
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"PROCESSING\",\n \"message\": \"Transfer already exists.\"\n}\n\nConcluída
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"COMPLETED\",\n \"message\": \"Transfer already exists.\"\n}\n\nFalhou
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"message\": \"Transfer already exists.\"\n}\n\nComo o processamento é assíncrono, você deve configurar um Webhook para receber as atualizações de status. Consulte a documentação de Gerenciamento de Webhooks para saber como registrar sua URL.
\nbalance_transfer.processingDisparado quando a transferência sai da fila e inicia o processamento.
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"PROCESSING\"\n}\n\nbalance_transfer.completedDisparado quando a transferência é concluída com sucesso. O campo result contém os detalhes da transação realizada.
{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"COMPLETED\",\n \"result\": {\n \"transactionId\": \"tx-9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d\",\n \"customerId\": \"c9bf9e5b-5e17-4c61-a7e1-1c9043f3c9c1\",\n \"balanceTypeId\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"amount\": 10000,\n \"description\": \"Bônus de boas-vindas - campanha natalina\"\n }\n}\n\nbalance_transfer.failedDisparado quando a transferência falha após todas as tentativas de retry (3 tentativas com backoff exponencial).
\nSaldo insuficiente da empresa
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Saldo insuficiente para esta operação.\"\n}\n\nCliente (participante) não encontrado
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Cliente não encontrado.\"\n}\n\nTipo de saldo não encontrado ou desabilitado
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Tipo de saldo não encontrado.\"\n}\n\nCarteira da empresa não configurada
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Carteira da empresa não encontrada.\"\n}\n\nCliente não está em estado ativo
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"O cliente não está em um estado ativo.\"\n}\n\nEmpresa não encontrada ou desabilitada
\n{\n \"transferQueueId\": \"d290f1ee-6c54-4b01-90e6-d701748f0851\",\n \"referenceId\": \"transf-2024-001\",\n \"status\": \"FAILED\",\n \"error\": \"Empresa não encontrada.\"\n}\n\n[Request 201] → QUEUED → PROCESSING → COMPLETED (sucesso)\n → FAILED (erro após retries)\n\nSua requisição é validada e retorna 201 com status QUEUED
O job entra na fila e aguarda processamento
\nQuando um worker pega o job, o status muda para PROCESSING e o webhook balance_transfer.processing é disparado
A transferência é executada (validações de saldo, cliente, tipo de saldo, etc.)
\nSucesso: status muda para COMPLETED, a transação é registrada e o webhook balance_transfer.completed é disparado com os detalhes da transação
Erro: o job tenta novamente (até 3 vezes). Se falhar em todas, status muda para FAILED e o webhook balance_transfer.failed é disparado
A rota usa a combinação de referenceId + companyId como chave de idempotência. Isso garante que:
O mesmo referenceId nunca será processado duas vezes
Se você reenviar o mesmo referenceId, a API retorna o status atual da transferência existente
É seguro fazer retry de requisições que tiveram timeout ou falha de rede
\nRecomendação: Use um identificador único da sua aplicação (ex: ID do seu banco de dados, UUID gerado pelo seu sistema) como referenceId.
Transfer section handles financial transactions and balance management.
\n","_postman_id":"185605c3-20dd-4a0c-9fc0-a4c8bcc30a27","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Card","item":[{"name":"Virtual Card","item":[{"name":"Issue a Virtual Card","id":"a5b68d21-9202-4cea-b2db-d66d38b7550d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"personId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"singleUse\": \"yes\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/card/virtual","description":"Create Virtual Card
\nThis endpoint allows you to create a new virtual card for an active person in your system. The card is issued through the platform and can be configured as either a single-use card (for one-time transactions) or a reusable card for ongoing use.
\nPerson must exist and belong to your company
\nPerson must have status 'Active'
\nPerson must have valid Swap integration data
\nPerson must have a valid balance group with Swap integration
\nCompany must exist and have valid Swap integration
\nCompany must have a valid treasury account holder ID
\nThis endpoint allows you to retrieve a paginated list of virtual cards for a specific person. Results are filtered by the person ID and can be searched by masked card number for easy identification.
\nSingle-Use Cards: Can only be used for one transaction and become invalid after use
\nReusable Cards: Can be used multiple times until expiry
\nMasking: Card numbers are masked for security (only last 4 digits visible)
\nExpiry: Cards have standard expiry dates managed by the payment platform
\nCompany Scoping: You can only create and view cards for persons in your company
\nActive Status: Only active persons can have virtual cards created
\nSearch: The query parameter searches within the masked card number for easy card identification
\nMust be a valid UUID of an existing person.
\n","type":"text/plain"},"key":"personId","value":""},{"disabled":true,"description":{"content":"Page number (starts from 1). Default: 1. Min: 1. Max: 9999.
\n","type":"text/plain"},"key":"page","value":""},{"disabled":true,"description":{"content":"Number of items per page. Default: 10. Min: 1. Max: 9999.
\n","type":"text/plain"},"key":"limit","value":""},{"disabled":true,"description":{"content":"Search term to filter by masked card number.
\n","type":"text/plain"},"key":"query","value":""}],"variable":[]}},"response":[{"id":"f9d5504b-65ca-4ca7-8e47-551eae33de20","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{url}}/card/virtual"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"data\": [\r\n {\r\n \"id\": \"00000000-0000-0000-0000-000000000000\",\r\n \"status\": \"active\",\r\n \"panMasked\": \"5123********1234\",\r\n \"singleUse\": false\r\n },\r\n {\r\n \"id\": \"00000000-0000-0000-0000-000000000000\",\r\n \"status\": \"inactive\",\r\n \"panMasked\": \"5123********5678\",\r\n \"singleUse\": true\r\n }\r\n ],\r\n \"totalItems\": 2,\r\n \"totalPages\": 1,\r\n \"page\": 1,\r\n \"limit\": 10\r\n}"},{"id":"36c949d1-4aa0-48be-a375-03bf127a6fa1","name":"400 Bad Request - Invalid query params","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":{"raw":"{{url}}/card/virtual","host":["{{url}}"],"path":["card","virtual"],"query":[{"key":"page","value":null,"disabled":true},{"key":"limit","value":null,"disabled":true},{"key":"personId","value":null,"disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n \"page must be greater than or equal to 1\",\r\n \"limit must be greater than or equal to 1\",\r\n \"personId is required\"\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"cff37212-cb46-40fb-a72b-0c975ec41e3f","name":"401 Unauthorized - Missing/invalid API key","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"url":"{{url}}/card/virtual"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 401,\r\n \"message\": \"API key is missing\"\r\n}"}],"_postman_id":"f285b01e-4066-446a-a9fd-3d532c2c804b"}],"id":"a69224b9-ca91-4f24-bef5-8218fafe469e","_postman_id":"a69224b9-ca91-4f24-bef5-8218fafe469e","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}}],"id":"9dfa4245-d537-4f3f-88a7-8e18fca22b3a","description":"Card section manages virtual card creation and management.
\n","_postman_id":"9dfa4245-d537-4f3f-88a7-8e18fca22b3a","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Banking","item":[{"name":"Boleto","item":[{"name":"Pay Boleto","id":"372e555f-b7ba-4436-b3be-f91e12819267","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"{{api_key}}","description":"Company API key
\n"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"barcode\": \"33690000090000001004126514423149400000000000000\"\n}"},"url":"{{base_url}}/api/external/boleto/pay","description":"Pay a boleto using the company's available balance.
\nType: API Key + Company
\nHeader: x-api-key
Required: Yes
\nMethod: POST
URL: {{base_url}}/api/external/boleto/pay
Headers:
\nBody:
\nBody Example:
\n{\n \"barcode\": \"00190500949244918902316910436569870000000000\"\n}\n\n{\n \"success\": true,\n \"status\": \"success\",\n \"logId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n\n{\n \"success\": false,\n \"status\": \"pending\",\n \"logId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}\n\nImportant: Status 202 means the operation was received but the final result is uncertain. The company MUST query the /stuck endpoint to verify the real payment status.
{\n \"title\": \"Validation error\",\n \"message\": \"The provided data is invalid.\",\n \"code\": 1001,\n \"details\": [\n {\n \"path\": \"barcode\",\n \"message\": \"Expected string, received undefined\"\n }\n ]\n}\n\n{\n \"title\": \"Insufficient balance\",\n \"message\": \"Insufficient balance to complete the transaction.\",\n \"code\": 3002,\n \"details\": {\n \"available\": 5000,\n \"requested\": 15000\n }\n}\n\n{\n \"title\": \"Unauthorized\",\n \"message\": \"Invalid or expired API key.\",\n \"code\": 401\n}\n\n{\n \"title\": \"Boleto not found\",\n \"message\": \"Invalid or not found barcode.\",\n \"code\": 3020\n}\n\n{\n \"title\": \"Payment in progress\",\n \"message\": \"There is already a payment being processed for this company.\",\n \"code\": 3026\n}\n\n{\n \"title\": \"Boleto already paid\",\n \"message\": \"This boleto has already been paid or is in recent processing.\",\n \"code\": 3027\n}\n\n{\n \"title\": \"Invalid barcode\",\n \"message\": \"Malformed barcode. Please verify and try again.\",\n \"code\": 3021\n}\n\n{\n \"title\": \"Outside operating hours\",\n \"message\": \"Request made outside normal operating hours for Boleto payments. Try again on the next business day.\",\n \"code\": 3023\n}\n\n{\n \"title\": \"Limit exceeded\",\n \"message\": \"Transaction limit exceeded for this account.\",\n \"code\": 3024\n}\n\n{\n \"title\": \"Pending payment\",\n \"message\": \"There is a pending transaction for this boleto. Wait or contact support.\",\n \"code\": 3025\n}\n\n{\n \"title\": \"Request limit exceeded\",\n \"message\": \"Too many requests. Wait a moment and try again.\",\n \"code\": 429\n}\n\n{\n \"title\": \"Internal error\",\n \"message\": \"Internal error. Contact support.\",\n \"code\": 3031\n}\n\n{\n \"title\": \"Service unavailable\",\n \"message\": \"Boleto payment service temporarily unavailable. Try again later.\",\n \"code\": 3028\n}\n\n{\n \"title\": \"Institution unavailable\",\n \"message\": \"Error communicating with the institution. Try again.\",\n \"code\": 3029\n}\n\nAvailable balance: Calculation considers balance.value - consignedValue - totalPendingTransactions
Status 202: Means uncertain state - NOT a failure. The payment may or may not have been processed. The company MUST query /stuck to verify the status.
Idempotency: The same barcode cannot be paid again within 60 seconds for the same company
\nDistributed lock: A company can only have one payment in progress at a time
\nRollback: If payment fails after balance debit, the value is automatically CREDITED back (not a reverse transaction, it is compensation)
\nLogId: The logId field is the audit log identifier - save for traceability
Consult information of a boleto before payment.
\nType: API Key
\nHeader: x-api-key
Required: Yes
\nMethod: GET
URL: {{base_url}}/api/external/boleto/consult
Headers:
\nQuery Params:
\n{\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"barcode\": \"00190500949244918902316910436569870000000000\",\n \"amount\": 15000,\n \"due_date\": \"2026-12-31\",\n \"payee\": {\n \"name\": \"Empresa de Serviços Ltda\",\n \"document\": \"12345678901234\"\n },\n \"payer\": {\n \"name\": \"João Silva\",\n \"document\": \"12345678901\"\n },\n \"status\": \"active\",\n \"allow_change_value\": false,\n \"isOverdue\": false,\n \"isNearDueDate\": false,\n \"warningMessage\": null\n}\n\n{\n \"title\": \"Validation error\",\n \"message\": \"The provided data is invalid.\",\n \"code\": 1001,\n \"details\": [\n {\n \"path\": \"barcode\",\n \"message\": \"Expected string, received undefined\"\n }\n ]\n}\n\n{\n \"title\": \"Unauthorized\",\n \"message\": \"Invalid or expired API key.\",\n \"code\": 401\n}\n\n{\n \"title\": \"Boleto not found\",\n \"message\": \"Invalid or not found barcode.\",\n \"code\": 3020\n}\n\n{\n \"title\": \"Boleto already paid\",\n \"message\": \"This boleto has already been paid.\",\n \"code\": 3022\n}\n\n{\n \"title\": \"Outside operating hours\",\n \"message\": \"Request made outside normal operating hours for Boleto payments. Try again on the next business day.\",\n \"code\": 3023\n}\n\n{\n \"title\": \"Invalid barcode\",\n \"message\": \"Malformed barcode. Please verify and try again.\",\n \"code\": 3021\n}\n\n{\n \"title\": \"Request limit exceeded\",\n \"message\": \"Too many requests. Wait a moment and try again.\",\n \"code\": 429\n}\n\n{\n \"title\": \"Internal error\",\n \"message\": \"Internal error. Contact support.\",\n \"code\": 3031\n}\n\n{\n \"title\": \"Service unavailable\",\n \"message\": \"Boleto payment service temporarily unavailable. Try again later.\",\n \"code\": 3028\n}\n\nThe amount field is returned in cents (15000 = R$ 150.00)
The isNearDueDate field is true when due date is within 3 days
The warningMessage field is populated when the boleto is overdue
If the boleto is overdue, the warningMessage field will contain: \"Boleto overdue. The amount may have additional charges.\"
Get details of a paid boleto by ID. Use the 'id' field returned from payment response.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}},"urlObject":{"path":["api","external","boleto","02f40ab2-5beb-40a0-a5dd-9f9ecb5690ec"],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"b969b00b-2bb1-44ba-8197-3272944c45ef","name":"Success - 200","originalRequest":{"method":"GET","header":[],"url":"{{base_url}}/api/external/boleto/7ef48f57-41ed-4546-b385-6ddd36ac4ac3"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"paid\",\n \"amount\": 6458,\n \"barcode\": \"858700000006645803282107900708210764544880537616\",\n \"paidAt\": \"2025-04-10T15:45:00Z\",\n \"authentication\": \"5100\",\n \"settleDate\": \"2025-04-10\",\n \"issuer\": \"Companhia de Águas\",\n \"receipt\": \"PROTOCOLO 0006363616\\r\\n1 10/04/2025 14:45\\r\\nTERM 228005 AGENTE 228005 AUTE 05100\\r\\n----------------------------------------\\r\\nAUTO 959946 RECEBIMENTO CONTA\\r\\n \\r\\n COMPANHIA DE ÁGUAS\\r\\n 85870000000-6 64580328210-7 \\r\\n 90070821076-4 54488053761-6\\r\\n----------------------------------------\\r\\nDATA DE LIQUIDACAO 10/04/2025\\r\\nVALOR COBRADO 64,58\\r\\n VALIDO COMO RECIBO DE PAGAMENTO\\r\\n----------------------------------------\\r\\n\",\n \"id\": \"7ef48f57-41ed-4546-b385-6ddd36ac4ac3\"\n}"},{"id":"f11280e7-14d6-4417-813f-e908d42b61cb","name":"Error - Boleto Not Found - 404","originalRequest":{"method":"GET","header":[],"url":"{{base_url}}/api/external/boleto/00000000-0000-0000-0000-000000000000"},"status":"Not Found","code":404,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"title\": \"Boleto não encontrado\",\n \"message\": \"Código de barras inválido ou não encontrado.\",\n \"code\": 3020\n}"}],"_postman_id":"f2680482-163e-4b58-8ad2-c29a49121dc4"}],"id":"104f97a9-f87c-4c86-ba85-21800e923749","description":"Endpoints for consulting and paying utility bills (boletos) through the Linkpremio integration API.
\nBase URL: {{base_url}}/api/external/boleto
\nAuthentication: API Key (x-api-key header)
\nBoleto to test:
\n","_postman_id":"104f97a9-f87c-4c86-ba85-21800e923749","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Pix","item":[{"name":"Order","item":[{"name":"Create","id":"68d44af6-d9bd-4d64-8053-7105b89563f6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-api-key","value":"","type":"text"}],"body":{"mode":"raw","raw":"{ \"transfers\": [ { \"method\": \"pix\", \"amount\": 1500, \"typeKey\": \"PHONE\", \"creditKey\": \"+5511993387834\" }, { \"method\": \"pix\", \"amount\": 2000, \"typeKey\": \"PHONE\", \"creditKey\": \"+5511993367367\" } ] }","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders","description":"(That's a pix request and will not be processed immediately.)
\nThis endpoint allows you to create a Pix order within a specific campaign.
\nIt supports batch transfers, where each transfer must contain the payment method, amount, and the corresponding payment details (Pix key or full bank account).
\nPix transfers support multiple key types.
Use the typeKey field to explicitly define the Pix key type.
StartFragment
\nEndFragment
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}},"urlObject":{"path":["orders"],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"03440ff2-421b-4d0f-aa57-0a16542eb79e","name":"200 Create Pix order","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"pix\",\n \"amount\": 2500,\n \"typeKey\": \"PHONE\",\n \"creditKey\": \"+5511999999998\"\n },\n {\n \"method\": \"pix\",\n \"amount\": 2500,\n \"typeKey\": \"PHONE\",\n \"creditKey\": \"+5511999999999\"\n },\n {\n \"method\": \"pix\",\n \"amount\": 1500,\n \"typeKey\": \"EMAIL\",\n \"creditKey\": \"user@example.com\"\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Created","code":201,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"50"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:34:28 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"32-vfAD3gDgUZTOQMzRslyupZu/76o\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"orderId\": \"aac277d6-b06f-4f3a-9ce3-d3424bff4272\",\n \"transfers\": [\n {\n \"id\": \"1b522f72-f36c-4759-8262-31780f4bd6fa\",\n \"amount\": 2500,\n \"method\": \"pix\",\n \"status\": \"Processando\",\n \"createdAt\": \"2025-11-21T19:19:04.503Z\",\n \"creditKey\": \"+5511999999998\"\n },\n {\n \"id\": \"45bd4ef9-4fad-4b2c-bb9a-7a9df2dcfb1e\",\n \"amount\": 2500,\n \"method\": \"pix\",\n \"status\": \"Processando\",\n \"createdAt\": \"2025-11-21T19:19:04.503Z\",\n \"creditKey\": \"+5511999999999\"\n },\n {\n \"id\": \"a1a210fa-ec2d-46ac-8be3-d1f9d51250f6\",\n \"amount\": 1500,\n \"method\": \"pix\",\n \"status\": \"Processando\",\n \"createdAt\": \"2025-11-21T19:19:04.503Z\",\n \"creditKey\": \"user@example.com\"\n }\n ]\n}"},{"id":"d8d4b250-3c73-4545-ab6f-bd26892069d4","name":"200 Create order with bank transfer","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"bank_transfer\",\n \"amount\": 5000,\n \"creditName\": \"João da Silva\",\n \"creditDocument\": \"12345678901\",\n \"creditBankCode\": \"001\",\n \"creditAccountBranch\": \"1234\",\n \"creditAccountNumber\": \"56789\",\n \"creditAccountDigit\": \"0\",\n \"creditAccountType\": \"ccac\"\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Created","code":201,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"50"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:35:23 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"32-f3Pt2oXFhHFFndgB1LVRrudnCKI\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"orderId\": \"aac277d6-b06f-4f3a-9ce3-d3424bff4272\",\n \"transfers\": [\n {\n \"id\": \"7cc75cf6-21fc-46c8-be23-994d863e0765\",\n \"amount\": 5000,\n \"method\": \"bank_transfer\",\n \"status\": \"Processando\",\n \"createdAt\": \"2025-11-21T19:19:46.187Z\",\n \"creditName\": \"João da Silva\",\n \"creditDocument\": \"12345678901\",\n \"creditBankName\": \"Banco do Brasil S.A.\",\n \"creditBankIspb\": \"00000000\",\n \"creditAccountBranch\": \"1234\",\n \"creditAccountNumber\": \"56789\",\n \"creditAccountDigit\": \"0\",\n \"creditAccountType\": \"ccac\"\n }\n ]\n}"},{"id":"591525da-9651-4b95-9b53-16a337d12554","name":"400 Missing required field","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": []\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"368"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:42:23 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"170-deZXZyCSb9Ei4zYVjXiUJXW2h9E\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"errors\": [\n {\n \"code\": \"too_small\",\n \"minimum\": 1,\n \"type\": \"array\",\n \"inclusive\": true,\n \"exact\": false,\n \"message\": \"Pelo menos uma transferência é necessária.\",\n \"path\": [\n \"transfers\"\n ]\n }\n ]\n}"},{"id":"2fa22189-d8db-4d9f-92bb-be1d138d6103","name":"400 Pix - invalid phone number","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"pix\",\n \"amount\": 2500,\n \"typeKey\": \"PHONE\",\n \"creditKey\": \"11999999999\"\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"177"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:43:17 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"b1-5jYB0P6FtZwPf/qXf+ykIL/ehh0\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"errors\": [\n {\n \"path\": [\n \"transfers\",\n 0,\n \"creditKey\"\n ],\n \"code\": \"custom\",\n \"message\": \"Telefone inválido. Use o formato internacional com código do país (ex: +5599999999999).\"\n }\n ]\n}"},{"id":"1636c9fd-5b6c-4433-90fe-3bfced08af29","name":"400 Pix - type key is required","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"pix\",\n \"amount\": 2500,\n \"creditKey\": \"+12133734253\"\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"177"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:43:17 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"b1-5jYB0P6FtZwPf/qXf+ykIL/ehh0\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"errors\": [\n {\n \"path\": [\n \"transfers\",\n 0,\n \"typeKey\"\n ],\n \"code\": \"custom\",\n \"message\": \"O tipo da chave Pix (typeKey) é obrigatório quando o método é Pix.\"\n }\n ]\n}"},{"id":"29c72523-0290-41fa-90f4-399b84d31ec9","name":"400 Pix without a key","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"pix\",\n \"amount\": 2000\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"177"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:43:17 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"b1-5jYB0P6FtZwPf/qXf+ykIL/ehh0\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"errors\": [\n {\n \"path\": [\n \"transfers\",\n 0,\n \"typeKey\"\n ],\n \"code\": \"custom\",\n \"message\": \"O tipo da chave Pix (typeKey) é obrigatório quando o método é Pix.\"\n },\n {\n \"path\": [\n \"transfers\",\n 0,\n \"creditKey\"\n ],\n \"code\": \"custom\",\n \"message\": \"A chave Pix é obrigatória quando o método é Pix.\"\n }\n ]\n}"},{"id":"60b57e57-b394-45b4-b8d4-d34bb785a522","name":"409 - Duplicated request","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"pix\",\n \"amount\": 1500,\n \"typeKey\": \"PHONE\",\n \"creditKey\": \"+5511993387834\"\n }]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Conflict","code":409,"_postman_previewlanguage":"Text","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"message\": \"Essa solicitação já foi processada recentemente. Aguarde 1 minuto antes de reenviar.\",\n \"code\": 4009,\n \"details\": {\n \"orderId\": \"aac277d6-b06f-4f3a-9ce3-d3424bff4272\"\n }\n}"},{"id":"bf4088cd-e1b6-4dee-81ec-3170574ecb89","name":"500 Non existent bank","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"transfers\": [\n {\n \"method\": \"bank_transfer\",\n \"amount\": 3000,\n \"creditName\": \"Maria Souza\",\n \"creditDocument\": \"98765432100\",\n \"creditBankCode\": \"999\",\n \"creditAccountBranch\": \"1234\",\n \"creditAccountNumber\": \"98765\",\n \"creditAccountDigit\": \"1\",\n \"creditAccountType\": \"svgs\"\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{url}}/orders"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"Text","header":[{"key":"Content-Length","value":"62"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Date","value":"Fri, 03 Oct 2025 19:44:39 GMT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"ETag","value":"W/\"3e-meXuo0m+bS3djeW4zqa4RQK/L8E\""},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"Content-Security-Policy","value":"default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Cross-Origin-Resource-Policy","value":"same-origin"},{"key":"Origin-Agent-Cluster","value":"?1"},{"key":"Referrer-Policy","value":"no-referrer"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-DNS-Prefetch-Control","value":"off"},{"key":"X-Download-Options","value":"noopen"},{"key":"X-Frame-Options","value":"SAMEORIGIN"},{"key":"X-Permitted-Cross-Domain-Policies","value":"none"},{"key":"X-XSS-Protection","value":"0"},{"key":"X-RateLimit-Limit","value":"50"},{"key":"X-RateLimit-Remaining","value":"49"},{"key":"X-RateLimit-Reset","value":"1"}],"cookie":[],"responseTime":null,"body":"{\n \"message\": \"O banco informado não foi encontrado.\",\n \"code\": 3201,\n \"details\": {\n \"bankCode\": \"999\"\n }\n}"}],"_postman_id":"68d44af6-d9bd-4d64-8053-7105b89563f6"},{"name":"fetch-transfers","id":"e7595641-c117-4ae1-bee2-b85348d6a900","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{token}}","type":"text"}],"url":"{{url}}/orders/transfers?page=1&limit=20&query=&startDate=2025-11-08T18:02:03.353Z&endDate=2025-11-08T18:02:03.353Z","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}},"urlObject":{"path":["orders","transfers"],"host":["{{url}}"],"query":[{"key":"page","value":"1"},{"key":"limit","value":"20"},{"key":"query","value":""},{"key":"startDate","value":"2025-11-08T18:02:03.353Z"},{"description":{"content":"timestamp
\n","type":"text/plain"},"key":"endDate","value":"2025-11-08T18:02:03.353Z"}],"variable":[]}},"response":[],"_postman_id":"e7595641-c117-4ae1-bee2-b85348d6a900"},{"name":"get-transfer-details","id":"771de42f-4574-4865-8cb5-7fa5a50bbb87","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{url}}/orders/transfers/:transfer_id","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}},"urlObject":{"path":["orders","transfers",":transfer_id"],"host":["{{url}}"],"query":[],"variable":[{"id":"d0369149-e0ee-41d1-913e-8a301710bb4b","type":"any","value":"","key":"transfer_id"}]}},"response":[],"_postman_id":"771de42f-4574-4865-8cb5-7fa5a50bbb87"}],"id":"1a019558-a87d-45e8-8ed4-71d1bb5255ee","_postman_id":"1a019558-a87d-45e8-8ed4-71d1bb5255ee","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}}],"id":"46d7e13c-2d36-4936-bf58-8a80250ffd24","_postman_id":"46d7e13c-2d36-4936-bf58-8a80250ffd24","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}}],"id":"5d85ad5c-a5f2-4e29-87cc-5dd94be5a821","description":"Banking section handles financial operations and payment processing.
\n","_postman_id":"5d85ad5c-a5f2-4e29-87cc-5dd94be5a821","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}},{"name":"Webhooks","item":[{"name":"Banking","item":[{"name":"Pix","item":[{"name":"Order","item":[{"name":"order.updated","id":"348ab9c0-c45f-46a8-9935-4b9655fd6885","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"connection":true,"accept-encoding":true,"user-agent":true,"accept":true,"host":true,"content-type":true,"content-length":true}},"request":{"method":"HEAD","header":[{"key":"Authorization","value":"\"Bearer {{token}}\"","type":"text"}],"body":{"mode":"raw","raw":"{\n \"event\": \"order.updated\",\n \"timestamp\": \"2025-11-24T23:59:40.201Z\",\n \"webhookId\": \"7b4cc5bd-ea4b-42e1-a38f-9b31727419d3\",\n \"orders\": [\n {\n \"orderId\": \"d7c41c22-9c52-48a1-9b7e-07d9c7e2a1a9\",\n \"code\": \"925424\",\n \"campaign\": \"Campaign Test\",\n \"transfers\": [\n {\n \"transferId\": \"98aa43c1-56c9-4f62-8cd0-6f53db7f7c3e\",\n \"identifier\": \"12345678900\",\n \"amount\": 15000,\n \"receiptUrl\": \"https://api.sistema.com/storage/receipts/PED123/98aa43c1-56c9-4f62-8cd0-6f53db7f7c3e.pdf\",\n \"status\": \"sucesso\"\n }\n ]\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"","description":"This document describes the order.updated webhook — the POST request automatically sent by the system to notify companies about orders that have had status updates (completed or with errors). The scheduled job runs daily and sends a batch of orders per company.
\nEvent: order.updated
\nSchedule: Daily execution (cron job), typically at 23:59 (sends orders updated on that day)
\nBatching: For each company with an active webhook, the system groups all relevant orders from the day and sends a single POST containing an array of orders
\nFiltering: Companies without configured webhooks or with inactive webhooks are ignored
\nMethod: POST
\nURL: Configurable per company — webhook.url field in the system. In Postman use {{webhook_url}}
\nHeaders: Defined by company (webhook.headers field stored as JSON). If headers are invalid, the system falls back to {} (empty headers)
\nTimeout: ~15 seconds (HTTP request with timeout)
\nWhen a transfer fails, the error object provides human-readable information plus contextual metadata:
\"error\": {\n \"message\": \"The transaction was rejected by the destination bank.\",\n \"code\": 2202,\n \"details\": {\n \"info\": \"The destination financial institution refused the operation.\",\n \"original\": {\n \"raw\": \"Creditor account number invalid or missing\"\n }\n }\n}\n\n{\n \"transferId\": \"...\",\n \"identifier\": \"70162565453\",\n \"amount\": 3000,\n \"receiptUrl\": \"https://.../receipts/<code class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml' class='preserveHtml'>/<id>.pdf\",\n \"status\": \"success\"\n}\n\n{\n \"transferId\": \"...\",\n \"identifier\": \"70162565453\",\n \"amount\": 30000000,\n \"receiptUrl\": null,\n \"status\": \"error\",\n \"error\": {\n \"message\": \"The transaction was rejected by the destination bank.\",\n \"code\": 2202,\n \"details\": {\n \"info\": \"The destination financial institution refused the operation.\",\n \"original\": {\n \"raw\": \"Creditor account number invalid or missing\"\n }\n }\n }\n}\n\nChave de API da empresa para autenticação.
\n","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook","description":"Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos que ocorrem na plataforma. Quando um evento é disparado, a plataforma envia automaticamente uma requisição HTTP POST para a URL configurada, contendo os dados do evento.
Esse mecanismo é essencial para acompanhar o processamento assíncrono das rotas da versão V2, como cadastro de participantes e transferência de saldo.
\nPOST /api/external/webhooks\n\nx-api-key: sua-chave-api-aqui\nContent-Type: application/json\n\nperson.updated
order.updated
person_registration.processing
person_registration.completed
person_registration.failed
balance_transfer.processing
balance_transfer.completed
balance_transfer.failed
{\n \"url\": \"https://meusistema.com/webhook\",\n \"events\": [\n \"person_registration.completed\",\n \"person_registration.failed\",\n \"balance_transfer.completed\"\n ],\n \"headers\": {\n \"Authorization\": \"Bearer meu-token-secreto\"\n },\n \"description\": \"Webhook para acompanhar cadastros e transferências\"\n}\n\n{\n \"id\": \"webhook-123\",\n \"url\": \"https://meusistema.com/webhook\",\n \"events\": [\n \"person_registration.completed\",\n \"balance_transfer.completed\"\n ],\n \"status\": \"Active\",\n \"createdAt\": \"2026-04-30T12:00:00Z\"\n}\n\nQuando um evento ocorre:
\nA plataforma envia uma requisição HTTP POST para a URL configurada
O corpo da requisição contém os dados do evento
\nSua aplicação deve responder com um status HTTP da família 2xx
Caso a entrega falhe:
\nA plataforma realiza até 3 tentativas de reenvio
\nÉ aplicado backoff exponencial entre as tentativas
\n{\n \"event\": \"person_registration.completed\",\n \"timestamp\": \"2026-04-30T12:00:00Z\",\n \"data\": {}\n}\n\n{\n \"event\": \"person_registration.completed\",\n \"timestamp\": \"2026-04-30T12:00:00Z\",\n \"data\": {\n \"registrationId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n \"referenceId\": \"cad-unico-2024-001\",\n \"personId\": \"c9bf9e5b-5e17-4c61-a7e1-1c9043f3c9c1\",\n \"status\": \"COMPLETED\"\n }\n}\n\nImplemente mecanismos para validar a autenticidade das requisições recebidas, como:
\nTokens em headers personalizados
\nValidação de IP de origem
\nEvite realizar operações demoradas diretamente no recebimento do webhook. Recomenda-se:
\nRegistrar o evento
\nEnfileirar o processamento
\nResponder imediatamente com status 200
Certifique-se de que sua API responde rapidamente. Respostas lentas podem ser interpretadas como falha e gerar reenvios.
\nChave de API da empresa para autenticação.
\n","type":"text"}],"url":"{{url}}/webhook","description":"Retrieves a paginated list of all webhooks associated with the company. This endpoint allows you to view, search, and filter your webhook subscriptions with pagination support.
\nDefault Values: If not specified, page defaults to 1 and limit defaults to 10
\nLimits: Maximum page is 9999, maximum limit is 999
\nEmpty Results: Returns empty data array when no webhooks match the criteria
\nQuery Search: The query parameter searches in webhook URLs and descriptions (case-insensitive partial match)
\nStatus Filter: Use status parameter to filter by webhook status (\"Active\" or \"Disabled\")
\nCombined Filters: All filters can be used together for precise results
\nLimited Fields: The response only includes essential fields (id, url, events, status)
\nCompany Scoped: Only returns webhooks belonging to your company
\nReal-time Data: Results reflect the current state of your webhooks
\nPage number for pagination. Must be between 1 and 9999.
\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"Number of results per page. Must be between 1 and 999.
\n","type":"text/plain"},"key":"limit","value":"20"},{"disabled":true,"description":{"content":"Search term to filter webhooks by URL or description (case-insensitive partial match).
\n","type":"text/plain"},"key":"query","value":""},{"disabled":true,"description":{"content":"Filter results by webhook status. Allowed values: \"Active\", \"Disabled\".
\n","type":"text/plain"},"key":"status","value":"Active"}],"variable":[]}},"response":[{"id":"fd1a51a8-5a2c-437c-a8b4-1de75047fe4b","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"url":{"raw":"{{url}}/webhook","host":["{{url}}"],"path":["webhook"],"query":[{"key":"page","value":"1","description":"Page number for pagination. Must be between 1 and 9999.","disabled":true},{"key":"limit","value":"20","description":"Number of results per page. Must be between 1 and 999.","disabled":true},{"key":"query","value":"","description":"Search term to filter webhooks by URL or description (case-insensitive partial match).","disabled":true},{"key":"status","value":"Active","description":"Filter results by webhook status. Allowed values: \"Active\", \"Disabled\".","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"data\": [\r\n {\r\n \"id\": \"webhook-uuid-123e4567-e89b-12d3-a456-426614174000\",\r\n \"url\": \"https://crm.example.com/webhook-listener\",\r\n \"events\": [\"person.updated\"],\r\n \"status\": \"Active\"\r\n },\r\n {\r\n \"id\": \"webhook-uuid-987fcdeb-51a2-43d1-b789-123456789abc\",\r\n \"url\": \"https://analytics.example.com/webhook\",\r\n \"events\": [\"order.updated\", \"person.updated\"],\r\n \"status\": \"Active\"\r\n },\r\n {\r\n \"id\": \"webhook-uuid-456def12-34a5-67b8-9cde-f01234567890\",\r\n \"url\": \"https://notifications.example.com/webhook\",\r\n \"events\": [\"order.updated\"],\r\n \"status\": \"Disabled\"\r\n }\r\n ],\r\n \"totalItems\": 3,\r\n \"totalPages\": 1,\r\n \"page\": 1,\r\n \"limit\": 10\r\n}"},{"id":"d6c7a59e-5926-4485-b3ce-f19361483910","name":"401 Unauthorized","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"url":{"raw":"{{url}}/webhook","host":["{{url}}"],"path":["webhook"],"query":[{"key":"page","value":"1","disabled":true},{"key":"limit","value":"20","disabled":true},{"key":"query","value":"","disabled":true},{"key":"status","value":"Active","disabled":true}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 401,\r\n \"message\": \"API key is missing\",\r\n \"error\": \"Unauthorized\"\r\n}"},{"id":"c7bacb05-25ba-4d82-b60f-7f9fc62444dd","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_small\",\r\n \"minimum\": 1,\r\n \"type\": \"number\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Number must be greater than or equal to 1\",\r\n \"path\": [\"page\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"8997408e-16d5-4c15-b557-45aebf11ae12","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_small\",\r\n \"minimum\": 1,\r\n \"type\": \"number\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Number must be greater than or equal to 1\",\r\n \"path\": [\"limit\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"4b46705e-d88e-44ac-b99e-9917631fc9d0","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_big\",\r\n \"maximum\": 9999,\r\n \"type\": \"number\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Number must be less than or equal to 9999\",\r\n \"path\": [\"page\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"73430a1d-0928-4bd6-b24d-3fbaf178757a","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_big\",\r\n \"maximum\": 999,\r\n \"type\": \"number\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Number must be less than or equal to 999\",\r\n \"path\": [\"limit\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"41efc083-289f-4cfe-a0be-10b3170f4c4b","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_type\",\r\n \"expected\": \"number\",\r\n \"received\": \"nan\",\r\n \"message\": \"Expected number, received nan\",\r\n \"path\": [\"page\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"d48b335f-bcad-4bee-b2e6-93c09fd4bbe0","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/webhook-receiver\",\n \"events\": [\n \"person.updated\",\n \"order.updated\"\n ],\n \"headers\": {\n \"Custom-Auth-Token\": \"my-secret-token-123\"\n },\n \"description\": \"Webhook to notify order updates.\",\n \"status\": \"Active\"\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_type\",\r\n \"expected\": \"number\",\r\n \"received\": \"nan\",\r\n \"message\": \"Expected number, received nan\",\r\n \"path\": [\"limit\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"}],"_postman_id":"150ed546-c01e-498c-bcd8-beb9e6f06c7c"},{"name":"Retrieve Webhook by ID","id":"e911bc22-1fe0-4327-8905-adc4a53eba6b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.
\n","type":"text"}],"url":"{{url}}/webhook/:id","description":"Retrieves detailed information about a specific webhook by its ID. Returns a subset of webhook fields (id, url, events, status).
\nLimited Fields: The response only includes essential fields (not description, headers, createdAt, updatedAt)
\nNo Company Validation: Unlike list endpoints, this endpoint does not validate company ownership on retrieval
\nCompany Scoped: Webhooks belong to specific companies, but ownership validation is not performed on GET
\nWebhook Verification: Verify if a webhook exists before updating it
\nQuick Status Check: Check webhook status and subscribed events
\nIntegration Testing: Test webhook configuration during development
\nMonitoring: Monitor webhook configuration in production systems
\nThe UUID of the webhook to retrieve. Must be a valid webhook ID.
\n","type":"text/plain"},"type":"any","value":"","key":"id"}]}},"response":[{"id":"70280969-a0cd-4a51-84f5-b8939f34878e","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to retrieve. Must be a valid webhook ID."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"id\": \"123e4567-e89b-12d3-a456-426614174000\",\r\n \"url\": \"https://crm.example.com/webhook-listener\",\r\n \"events\": [\"person.updated\", \"order.updated\"],\r\n \"status\": \"Active\"\r\n}"},{"id":"acdf6078-84bf-4afa-b779-62a4c4a9e99d","name":"401 Unauthorized - Missing API key","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"personId\": \"00000000-0000-0000-0000-000000000000\"\r\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/card/virtual"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 401,\r\n \"message\": \"API key is missing\",\r\n \"error\": \"Unauthorized\"\r\n}"},{"id":"51a7cd94-36b8-496e-b059-edf0f0a5d53f","name":"401 Unauthorized - Invalid API key","originalRequest":{"method":"POST","header":[{"key":"x-api-key","value":"{{x-api-key}}","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"customerId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"balanceTypeId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"description\": \"Description\",\r\n \"campaignId\": \"00000000-0000-0000-0000-000000000000\",\r\n \"amount\": 1000\r\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/transfer/balance"},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 401,\r\n \"message\": \"Invalid API key\",\r\n \"error\": \"Unauthorized\"\r\n}"}],"_postman_id":"e911bc22-1fe0-4327-8905-adc4a53eba6b"},{"name":"Update Webhook","id":"98b10106-3ccd-407c-afea-c468420f69ef","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.
\n","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/webhook/:id","description":"Updates the data of an existing webhook. You can send only the fields you want to change (partial update). The webhook must belong to your company and exist in the system.
\nÉ necessário enviar a chave de API da empresa no cabeçalho x-api-key.
The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company.
\n","type":"text/plain"},"type":"any","value":"","key":"id"}]}},"response":[{"id":"3b85e239-bfd3-46bd-9450-a99a3e9bcab9","name":"200 OK","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"id\": \"webhook-uuid-123e4567-e89b-12d3-a456-426614174000\",\r\n \"url\": \"https://your-system.com/webhook-listener\",\r\n \"events\": [\"person.updated\", \"order.updated\"],\r\n \"status\": \"Active\"\r\n}"},{"id":"662f131d-b47f-4ab8-9de9-ee1a29fba06a","name":"429 Too Many Requests","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"status":"Too Many Requests","code":429,"_postman_previewlanguage":"Text","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\r\n \"statusCode\": 429,\r\n \"message\": \"Você atingiu o limite de requisições permitidas. Tente novamente mais tarde.\",\r\n \"error\": \"Too Many Requests\"\r\n}"},{"id":"a2dfc17a-7fdc-4646-84b9-8ce1b8d40b40","name":"400 Bad Request","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_string\",\r\n \"expected\": \"url\",\r\n \"received\": \"string\",\r\n \"message\": \"Invalid url\",\r\n \"path\": [\"url\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"8b715e42-5f2a-4a35-8ebc-7517ed8f5cce","name":"400 Bad Request","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"too_small\",\r\n \"minimum\": 1,\r\n \"type\": \"array\",\r\n \"inclusive\": true,\r\n \"exact\": false,\r\n \"message\": \"Array must contain at least 1 element(s)\",\r\n \"path\": [\"events\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"5a7c6603-7756-43d4-8730-4f8588e68cd2","name":"400 Bad Request","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"custom\",\r\n \"message\": \"Invalid event provided. Allowed events: person.updated, order.updated\",\r\n \"path\": [\"events\"]\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"674f90f1-9ff8-46b1-bb53-2803eb3aec67","name":"400 Bad Request","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_enum_value\",\r\n \"options\": [\"Active\", \"Disabled\"],\r\n \"received\": \"InvalidStatus\",\r\n \"path\": [\"status\"],\r\n \"message\": \"Invalid enum value. Expected 'Active' | 'Disabled', received 'InvalidStatus'\"\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"},{"id":"0a1ac79a-6f7a-419a-b366-6e305efa0100","name":"400 Bad Request","originalRequest":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-api-key","value":"{{x-api-key}}","description":"Chave de API da empresa para autenticação.","type":"text"}],"body":{"mode":"raw","raw":"{\n \"url\": \"https://mywebsite.com/new-endpoint\",\n \"status\": \"Disabled\",\n \"events\": [\n \"person.updated\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"{{url}}/webhook/:id","host":["{{url}}"],"path":["webhook",":id"],"variable":[{"key":"id","value":"","description":"The UUID of the webhook to be updated. Must be a valid webhook ID that belongs to your company."}]}},"_postman_previewlanguage":"Text","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"statusCode\": 400,\r\n \"message\": [\r\n {\r\n \"code\": \"invalid_type\",\r\n \"expected\": \"string\",\r\n \"received\": \"number\",\r\n \"path\": [\"headers\", \"Authorization\"],\r\n \"message\": \"Expected string, received number\"\r\n }\r\n ],\r\n \"error\": \"Bad Request\"\r\n}"}],"_postman_id":"98b10106-3ccd-407c-afea-c468420f69ef"}],"id":"b74070cb-1efd-4595-a61c-53f816512bab","description":"Webhooks section manages real-time notifications and event subscriptions.
\n","_postman_id":"b74070cb-1efd-4595-a61c-53f816512bab","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","id":"f66d0b0b-4c0f-424d-a956-83eb7c2ddb19","name":"Link Premio Card API - Documentation","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-api-key"},{"key":"value","value":"{{token}}"}]}},"event":[{"listen":"prerequest","script":{"id":"70b5a80a-b0ba-45d7-8f25-48f552ac4159","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"c951d6ed-2df6-448d-812e-df93c8616842","type":"text/javascript","exec":[""]}}]}