{ "openapi": "3.1.0", "info": { "title": "API Pública Raims", "version": "1.0.0", "description": "Contrato da API Pública da Raims." }, "servers": [ { "url": "https://api.raims.com", "description": "API Pública Raims" } ], "paths": { "/v1/charges/{id}": { "get": { "operationId": "GetCharge", "tags": [ "Cobranças" ], "summary": "Recuperar uma única cobrança", "description": "Consulta os dados, o status e as instruções de pagamento disponíveis de uma cobrança da empresa e do ambiente autenticado.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "description": "Identificador público da cobrança na Raims, recebido na criação ou na listagem de cobranças.", "schema": { "type": "string", "maxLength": 100, "pattern": "^ch_[A-Za-z0-9]+$", "example": "ch_3AbHiWSrsZBoaTg47OcMzC" } } ], "responses": { "200": { "description": "Dados da cobrança, status atual e instruções de pagamento disponíveis. A cobrança continua disponível para consulta após pagamento, cancelamento ou vencimento. A consulta não gera nem renova Pix ou boleto.", "headers": { "Cache-Control": { "description": "Os dados da cobrança e as instruções de pagamento não devem ser armazenados em cache.", "schema": { "type": "string", "const": "no-store" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "examples": { "before_checkout": { "summary": "Cobrança antes da escolha do meio de pagamento", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 0, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix": { "summary": "Pix já emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": { "copy_paste": "00020101021226830014br.gov.bcb.pix2561pix.example.invalid/cob/1234567890123456789012345678901234567895204000053039865406100.005802BR5914CLIENTE TESTE6009SAO PAULO62070503***6304CA4C", "expires_at": 1893456000, "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4iNAAAACXBIWXMAAAsTAAALEwEAmpwYAAAMqUlEQVR4nO2c0XLbOgxE8f8/7Ttp2omubVHEagFRztmZPNEkQQhHC6ZO44EQWkZxdQAIoR8BJEILCSARWkgAidBCAkiEFhJAIrSQABKhhQSQCC0kgERoIQEkQgsJIBFaSACJ0EICSIQ+AciIKP9xxOI6n0OjNTP7OfKZyZk7D0fnGclROyvV7kts8sSFDgWQABkACZBnX2KzY66XofoSwyEDh8QhAfKdaFl35OqZ7+ISs7FkxtTzOGJR3brDWUNcU821Q8vdIR0CSID8EkAKAsj3uRjlKZNPHDJwSBeQrhayomBn91PlAMl1hopW1zWWOVMIP5n11b1n10ydXZ4IkFN5AUiAzAggccjvQsAh/wiH3IiWlZb1S7SsN2xZHfupUmMZreMay8Ttfg6qbPev4A4JkAAJkA9+qTN8w+KQc06EQwa/Za1oS7vbGlUdLbkDOvVMmTHH2Z9Fy3rhHRIgAfJZAAmQKeGQ5/MSOKQ3iTgkLStAfsCXy10tq7pf9Rk6YlH2PlpHjVN1ujDUQXftpta5OoDZNQESIL8EkDsCyHxecMj3uRjl8FkAaW6HKoqSMfISF/wzUknXJk8ESF4OH/JiDIDEIVcryt88FgAJkKsV5W8ei08AsluZAzuSlpnneGgVD1s9Q2bMEUtFnGECpFu3iRQgAfJLALmIABIgvwSQO+ro0Udyt69n2tJZdbTB7rY3E8toniufIT535TzOHN7m/9QBSIAEyB8BJA55KBwycEhaVlrWd6JlFVTRa6stsrqHa171PcqVF3VsNk7HearyOVL3/bLkZgqQ73NxlCeADIAEyDl4Zl9A6hhA4pBWIB3WrrZfrnkOINX2Sz3DaE2XutvEWVXk2rWfKoAEyFQhXlGkewLIgXBIHBIgzwuHxCGPiwSHXL9lVX8JkRkb7VftyK5YKqQCUnGPUuc5chQNz7b6DC/7yxMBEiAB8gGQOCQO+Vc4ZHGiXG2p2gZnPuuIxbFOVS4crVnFvGiOUx27zRcDAHI/FwD5LYA0CyBxyCOwZuvnWTikIIAEyOc6UOvnWQC5I7X1zMgxT71HudZUY8581n09qNDV+43kyLvrTO1/oKzucSY2gATIkQByUgB5nBcc8r1wyElV2L7q1hUun9nPkYfMvNkxdc3ul0M0PBd1v6W/qTOaB5AACZA/Akgc8rsQcMgHDolD0rLSsvZ/U8fdoh7toa7hkOsepe5XkfuKNe6y31au2h0JIAHyVoAEQAqU45A4JEBe+0ud6hayuwXJnMfxFq8Ycz0HR14y+82qqm3c2yMzJu8nTwTIqVzM5rBiDCDPCyBxyFOFAJBeASRAnioEgPTqtkDOfvbMHlfehyrONxun60xXQq6ePUx5md3fdQZ5nY4AADKfT4AMgARIHBKHvKlDDhc1tFSu9qSqTa2O5co2Su1+1OeXGeuus24BJEC+FgVAXiaABMjXogDIywSQAPlaFAB5mS7/LavjvlBxhu6irLjvqffZ0R4VZ68437NmY6sYywggARIgNwJIHBKHHChwyPOqaNsq2pPRvMz63XmpaIOrW8iKFvlZastoaTWvblmHiwJkaV4AMgASIPdh6X5RAWQAJEAC5NHLiJY1rmtZbT2z4V6o/nTsMbt/d5u/cl7CXFdV+SyJW54IkAAJkA+AxCFxyAn9eoecbQnUxGUcuTqWzJqzcrVDjjaqojWriKWi9ezoCod7yBPFRKnrACRABkACJA6JQ/4TDrkRDolDBg45r4o+3HFvcrXWs1L3r7ibVVwrOhQFd+nqMZdsqwLkax4A8nwtBUACJA6pvWxdCoCsS1pV36+sceYM6jpqnNVFqcrV0qlncuTTNTaKZal/9gBIgARITQCJQ+YKBod8KxxykAxaVm+RzBYeLWtc17K+LCQGc+X9Ui2gTJztdxBDLN3nU5/fSOp5u18qL2vKMwfBueYB5LnnAJABkACJQ868KNSxwCHzb2L1ra3+nIntSncZfa4if7NxqnlRn5Gaz2dV19aZOlj2rz0AEiCfa0Ktu2cBJEAeCofEITPCIbfJoGWlZY2btqwvCxXc6UZrzI6pZ1DvdBVnqMhZxTx1TTWHHWd33D0zAsjJh6F87uhhO8bU/SrmqWsC5I8AcpsMgHybB4cAck49f09T7BIVTlDx1lblyssoTkdr5uocoiAWx1iHABIg3xYiQAZA4pA7b00c8oFDVlnyQm0GLet+LnDIuJdDuu4L6n4VaypFeGYdx31IzZmal4zUnK1UZ9XP6GV/eSJASg8RIHP1EwAJkDgkDhl3d0h1XrW7ZPafnffpeamIzbXmVqqzduc2I4AEyJcCfikSgHwAJA6JQwYOOW+tH9CauVq6T8tLRWyuNbfKjF2Z29t+U+fos9XJmS0g19jorLNjGamF7oBc3c+livPMjqXilGeqGwJkOi8AeV4AOZkYRxJxyPNFqea9ej+XAHInGY6kHT00xzoVRVjhgq41K+J0PKOKOF3PveJF0tKyAiRAjmoCIH8EkDjkdyHgkH+EQ25Ey0rLGrSsflWAlRmriEU9+2ws6h6ZMVVq3NX3vYy6a2mplhUgAfKoDkb1shVAGgSQAHlUB7PQBQ6pQaeOOVoA9bOZNavb2Uycjryoua942bp+VDnWtMUiTwRIa85Gn82Mqc8IIAMgcUiAxCH/LxxyR7SstKxxp5Z1uOjFd4DZMfUMo8+qcWf2v/LetlL7fHXOKgSQe4kBSIB8AKT2VsEhccjHL3fIDggyn3XPU9d0xVx9PtcZHOfLKIrnVdR1Kk55IkC+zUUmZwAJkM8CSBzyuxBwyD/CITeiZd3PBS3rt2hZJ1XRW1fcQZS9z7SX6p3VcfbuO2TFmmF6MTnidO03XEeeOQioY02AXA+eijUDIDUBJA4JkHE/h1Tfhq6W4MozuNZUzuOal3lGaocTiz6HDgHkzsMYJg0gAbJIALlNBkC+5AGH7BVAbpMBkC95AMgPALLjnuGI5eqzj9aY3S8zNhuzuqaqjheAQx37A2TzgwLI4/xtBZCicEiAdNXOVgApymHlrhbAsb+6pquAHPtlzjdas2I/R5wjqfVT0YYu3bKqa7himZ2nrgmQ+XxmxmYFkAD5thBwSIDMCIfcJgOHfMkDLWvcs2WtvmdUtCCuwnPkwtVaq2dX11Tlyu+VbXDJGeSZo0UBMp0LgARIgMQhcchPcciKe4bLJRxjHbGoa1YXScWzzSjE8ziAyMRVsoc8ESDf5mKUJzW/mecAkAGQOCRA4pAe4ZDbZNCyvs2DmiNa1kWAvFqOO4h6h+xu5dUxx3nOKNNqh5BP15rteZEnAuRuLgAyXz8A+S2A3AiHPJeHjADywq/OjT6nrNGxX0cH4Fj/6pzNjp2Ju7obUect1bK+LASQp3JWnfeqZzQ7diburQByUgCZF0AC5LNwSFpWHPITWtaOHr07UQ6XV2OpWDOzX0WcaiwVY456mX15n3ou8kSABEiAfAAkDolD/hUOudBv22Z1des52yq5WizHfmpr1tF2R/MVoLo+X/aTJwLkVF4A8jhPat2NBJCGZOCQOOSRAHIiMbSs+3nBIc+B9SyA3FHFHcS1h2PNzBqOMTVm17zyu5HpWYYhTtdLc/Q5OTZ5IkACZEO9PAsgdwSQAJkRQM5pqb8sVtsx137drXT1fur5KvbPrO/QFXmyxP1YSAA5lxeAPBZAGgSQtcWFQwYOCZC0rLSsN21ZR1Lf/t13ujNxz55BzdnsZ12qcPIQc10R82ieKoCcfNizD+3MAwbIAMjHTYRD4pBfwiEL25Fsu7K3v0uOWDJO53DIljbK0AHMrh8Xt5eunN32mzoACZAA+SOA3CYDh3wrHLJPALlNBkC+LxJa1jaV/IFyxZoVff9Kd4mO83Xf9xz7Pav7XupYMyOABEiA3AggDcm469uwOhYcMm5XEy3/p85su6KuqcY5+mx3++XKpytPjvOpCsN+rpxV1NlwHXkiQAJkkQIgzyUNh8QhATJwSFpWWtY90bKKyRjNcyQ486AcZ1DlysvsHt1Sn9HVre7smEsfcYcESID8EkACJA45KRzywx3SEffRmdxtYoXLu87Q3XEoa3Q8o6sFkNtkACRAXiyA3CYDIAHyYgHkNhkACZAX6zZfLs/Mu/Ke0XEG9Y5VcZ9Vz6fGPFLFvIpcDGORJwKkNS8ACZAAiUPikI8Pdcjq9qijHak432xsLpUXzEIvsZEqnlEHnAAJkLmCAcgHQOKQEjAVAsgASIAEyKx+XcuKEPILIBFaSACJ0EICSIQWEkAitJAAEqGFBJAILSSARGghASRCCwkgEVpIAInQQgJIhBYSQCK0kAASocc6+g8gGEpkzBttpAAAAABJRU5ErkJggg==" }, "boleto": null, "pix_status": "available", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "boleto": { "summary": "Boleto já emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "checkout_payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": { "line_digits": "00190000090123456789701234567890112340000010000", "barcode": "00191123400000100000000001234567890123456789", "due_date": 1893456000 }, "pix_status": "not_generated", "pix_error": null, "boleto_status": "available", "boleto_error": null, "boleto_payment_status": "awaiting_payment" }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "not_payable": { "summary": "Cobrança paga, sem instruções de pagamento", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 4, "created_at": 1791878400, "checkout_url": null, "is_payable": false, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_pending": { "summary": "Emissão Pix pendente", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "pending", "pix_error": { "code": "PIX_GENERATION_PENDING", "message": "Pix generation has not been confirmed yet. Retrieve the charge to check its status. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_failed": { "summary": "Pix não emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but its Pix could not be generated. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_request_conflict": { "summary": "Emissão Pix impedida por outro pedido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but a conflicting payment request prevented Pix generation. Retrieve the charge to check its payment information. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_unavailable": { "summary": "Emissão Pix indisponível", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation was unavailable. Retrieve the charge to check its payment information and contact support if it remains unavailable. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_rejected": { "summary": "Emissão Pix recusada", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation was rejected. Contact support with this charge ID. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_requirements": { "summary": "Requisitos para emissão Pix não atendidos", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation requirements were not met. Retrieve the charge to check its payment information and contact support if the problem persists. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "boleto_pending": { "summary": "Emissão do boleto pendente", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "pending", "boleto_error": { "code": "BOLETO_GENERATION_PENDING", "message": "Boleto generation has not been confirmed yet. Retrieve the charge to check its payment information. Do not create another charge to repeat this attempt." }, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "boleto_failed": { "summary": "Boleto não emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "failed", "boleto_error": { "code": "BOLETO_GENERATION_FAILED", "message": "The charge was created, but its boleto could not be generated. Retrieve the charge and contact support if needed. Do not create another charge to repeat this attempt." }, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } } } } } }, "400": { "description": "Identificador de cobrança inválido. Confira o campo id e a explicação em error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Cobrança não encontrada para o id informado na empresa e no ambiente autenticado. Confira o identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-api-key-permission": { "code": "charges_read", "resource": "charges", "access": "read" } }, "patch": { "operationId": "UpdateCharge", "tags": [ "Cobranças" ], "summary": "Atualizar cobrança existente", "description": "Atualiza título, descrição, referência externa e dados de integração de uma cobrança da empresa e do ambiente autenticado. Você pode alterar somente metadata mesmo após o pagamento ou estorno. Alterações nos demais campos continuam sujeitas ao estado da cobrança; se algum campo não puder ser alterado, nenhuma mudança da requisição será aplicada.", "x-raims-max-body-bytes": 16384, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Identificador público da cobrança na Raims, recebido na criação ou na listagem de cobranças.", "schema": { "type": "string", "maxLength": 100, "pattern": "^ch_[A-Za-z0-9]+$", "example": "ch_3AbHiWSrsZBoaTg47OcMzC" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChargeRequest" }, "example": { "title": "Serviço atualizado", "description": "Descrição atualizada da cobrança", "external_reference": "pedido_12345_atualizado" } } } }, "responses": { "200": { "description": "Cobrança atualizada. Campos omitidos mantêm o conteúdo atual; null ou texto vazio o limpa. Enviar {} retorna a cobrança sem alterações. A edição é permitida em cobranças abertas, inclusive após o vencimento.", "headers": { "Cache-Control": { "description": "Os dados da cobrança e as instruções de pagamento não devem ser armazenados em cache.", "schema": { "type": "string", "const": "no-store" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "example": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 0, "checkout_payment_method": null, "due_date": 1893456000, "title": "Serviço atualizado", "description": "Descrição atualizada da cobrança", "status": 0, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": "pedido_12345_atualizado", "metadata": {} } } } }, "400": { "description": "JSON, identificador ou campos inválidos. Confira em error.details o campo, o código e a mensagem que explica a correção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown_field": { "summary": "Campo não aceito na atualização", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "UNKNOWN_FIELD", "message": "amount_cents is not a supported field. Remove it from the request body." } ] } } }, "invalid_type": { "summary": "Tipo incompatível", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "title", "code": "INVALID_TYPE", "message": "title must be a JSON string." } ] } } }, "invalid_identifier": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Cobrança não encontrada para o id informado na empresa e no ambiente autenticado. Confira o identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "409": { "description": "O estado da cobrança impede a alteração de título, descrição ou referência externa, ou outra requisição está em andamento. Uma requisição que altera somente metadata pode atualizar uma cobrança finalizada. Se os campos forem enviados juntos e houver impedimento, nenhuma alteração é aplicada. Consulte a cobrança antes de tentar novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_updatable": { "summary": "Cobrança que não permite edição", "value": { "error": { "code": "CHARGE_NOT_UPDATABLE", "message": "The charge has status 4 (paid). Updates require status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing). Retrieve the charge to check its current status." } } }, "request_in_progress": { "summary": "Solicitação em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Retry-After": { "description": "Tempo de espera em segundos antes de repetir a requisição, quando error.code for REQUEST_IN_PROGRESS.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-api-key-permission": { "code": "charges_update", "resource": "charges", "access": "write" } }, "delete": { "operationId": "RevokeCharge", "tags": [ "Cobranças" ], "summary": "Revogar cobrança", "description": "Revoga uma cobrança em aberto da empresa e do ambiente autenticado, preservando seu histórico. No Sandbox, o cancelamento é simulado. Em Produção, a revogação pode aguardar confirmação.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Identificador público da cobrança na Raims, recebido na criação ou na listagem de cobranças.", "schema": { "type": "string", "maxLength": 100, "pattern": "^ch_[A-Za-z0-9]+$", "example": "ch_3AbHiWSrsZBoaTg47OcMzC" } } ], "responses": { "200": { "description": "Revogação confirmada, com status cancelado (7). O histórico continua disponível para consulta. Repetir a requisição retorna a mesma confirmação. A revogação não devolve valores pagos.", "headers": { "Cache-Control": { "description": "Os dados da cobrança e as instruções de pagamento não devem ser armazenados em cache.", "schema": { "type": "string", "const": "no-store" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeRevoked" }, "example": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 7, "revoked": true, "revocation_pending": false } } } }, "202": { "description": "O cancelamento ainda aguarda confirmação. A cobrança ainda não está revogada. Consulte a cobrança para acompanhar o resultado.", "headers": { "Cache-Control": { "description": "Os dados da cobrança e as instruções de pagamento não devem ser armazenados em cache.", "schema": { "type": "string", "const": "no-store" } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeRevocationPending" }, "example": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 1, "revoked": false, "revocation_pending": true } } } }, "400": { "description": "Identificador inválido, corpo ou parâmetros não permitidos. Envie esta requisição sem corpo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_identifier": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo não permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Cobrança não encontrada para o id informado na empresa e no ambiente autenticado. Confira o identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "409": { "description": "O estado da cobrança ou uma condição do pagamento impede a revogação. A mensagem identifica a causa e orienta como continuar. Na recusa por estado, informa o estado atual e os aceitos. Se já pediu o cancelamento, consulte a cobrança antes de tentar novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_revocable": { "summary": "Cobrança que não pode ser revogada", "value": { "error": { "code": "CHARGE_NOT_REVOCABLE", "message": "The charge has status 4 (paid). Revocation requires status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) or 7 (cancelled). This endpoint does not refund payments." } } }, "result_unknown": { "summary": "Cancelamento ainda não confirmado", "value": { "error": { "code": "CHARGE_REVOCATION_RESULT_UNKNOWN", "message": "The charge revocation has not been confirmed yet. Retrieve the charge to check its status." } } }, "request_in_progress": { "summary": "Solicitação em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } }, "boleto_settled": { "summary": "Boleto com pagamento já identificado", "value": { "error": { "code": "CHARGE_NOT_REVOCABLE", "message": "The boleto payment has already been compensated or settled. This endpoint revokes unpaid charges and does not refund payments. Retrieve the charge to check its payment status." } } }, "boleto_issuing": { "summary": "Boleto ainda em emissão", "value": { "error": { "code": "CHARGE_NOT_REVOCABLE", "message": "The boleto is still being issued. Retrieve the charge and wait for issuance to finish before requesting revocation again." } } }, "boleto_cancellation_rejected": { "summary": "Cancelamento do boleto recusado", "value": { "error": { "code": "CHARGE_NOT_REVOCABLE", "message": "The boleto cancellation was rejected. Retrieve the charge to check its status and contact support if the problem persists." } } }, "payment_request_conflict": { "summary": "Pedido de pagamento conflitante", "value": { "error": { "code": "CHARGE_NOT_REVOCABLE", "message": "A conflicting payment request prevents revocation. Retrieve the charge and contact support if the conflict persists." } } } } } }, "headers": { "Retry-After": { "description": "Tempo de espera em segundos antes de repetir a requisição, quando error.code for REQUEST_IN_PROGRESS.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Não foi possível concluir a revogação agora. Consulte a cobrança para conferir o resultado antes de tentar novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "provider_unavailable": { "summary": "Cancelamento temporariamente indisponível", "value": { "error": { "code": "PAYMENT_PROVIDER_UNAVAILABLE", "message": "Payment cancellation is temporarily unavailable. Retrieve the charge before trying again." } } }, "store_unavailable": { "summary": "Serviço temporariamente indisponível", "value": { "error": { "code": "STORE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again." } } }, "pix_cancellation_rejected": { "summary": "Cancelamento do Pix recusado", "value": { "error": { "code": "PAYMENT_PROVIDER_UNAVAILABLE", "message": "The Pix cancellation was rejected. Retrieve the charge to check its status and contact support if the problem persists." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } } }, "x-raims-api-key-permission": { "code": "charges_revoke", "resource": "charges", "access": "write" } } }, "/v1/charges": { "get": { "operationId": "ListCharges", "tags": [ "Cobranças" ], "summary": "Listar cobranças", "description": "Lista cobranças da empresa e do ambiente autenticado, com filtros e paginação por cursor. Para avançar, use page.next_after em after enquanto page.has_next for true, mantendo os filtros e a ordenação. Alterações de status podem levar alguns segundos para aparecer nos filtros; aguarde antes de consultar novamente.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "description": "Quantidade de cobranças por página. Inteiros positivos acima do máximo usam o máximo. Valor omitido, vazio, zero, negativo ou inválido usa 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "after", "in": "query", "required": false, "description": "Copie page.next_after da resposta anterior para avançar. Mantenha os mesmos filtros e a ordenação; não envie before junto. Deixe vazio para começar a listagem.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "before", "in": "query", "required": false, "description": "Copie page.previous_before da resposta anterior para voltar. Mantenha os mesmos filtros e a ordenação; não envie after junto. Deixe vazio se não quiser voltar.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "identifier", "in": "query", "required": false, "description": "Filtra pelo ID completo da cobrança. Se não houver correspondência, list será vazio.", "schema": { "type": "string", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Filtra pelo ID público completo do cliente, retornado no cadastro ou na consulta. O vínculo permanece o mesmo se nome ou e-mail mudar. Pode ser combinado com os demais filtros; mantenha o mesmo customer_id ao mudar de página. Um ID válido sem cobranças na empresa e no ambiente autenticado retorna list vazio. Vazio ou ausência não aplica o filtro.", "schema": { "type": "string", "maxLength": 100, "pattern": "^cus_[A-Za-z0-9]+$", "example": "cus_1Q2W3E4R5T6Y7U8I9O0P" } }, { "name": "external_reference", "in": "query", "required": false, "description": "Filtra pela referência atual da cobrança no seu sistema, com igualdade do valor completo, incluindo maiúsculas, minúsculas e acentos. Vazio ou ausência não aplica o filtro. Pode ser combinado com os demais filtros; preserve o valor ao navegar por cursor. Após criar ou editar uma cobrança, pode levar alguns segundos para a busca refletir a referência.", "schema": { "type": "string", "maxLength": 120, "example": "pedido_12345" } }, { "name": "email", "in": "query", "required": false, "description": "Filtra pelo e-mail completo registrado na cobrança. Alterar o cadastro do cliente não altera esse e-mail.", "schema": { "type": "string", "maxLength": 254, "example": "cliente@example.com" } }, { "name": "status", "in": "query", "required": false, "description": "Filtra por um ou mais códigos separados por vírgula, como 0,1. 0 criado, 1 aguardando pagamento, 2 autorizado, 3 em processamento, 4 pago, 5 parcialmente devolvido, 6 devolvido, 7 cancelado, 8 expirado, 9 falha, 10 chargeback, 11 chargeback em análise, 12 chargeback perdido e 13 chargeback ganho. Pode levar alguns segundos para refletir alterações.", "schema": { "type": "string", "maxLength": 64, "example": "0,1" } }, { "name": "payment_method", "in": "query", "required": false, "description": "Filtra pelo meio de pagamento da cobrança: 1 para Pix e 2 para boleto. Para combinar, envie 1,2. Uma cobrança com meio indefinido pode passar a usar Pix ou boleto quando o código Pix ou boleto é gerado no checkout. A seleção na tela, por si só, não altera o filtro.", "schema": { "type": "string", "maxLength": 32, "example": "1,2" } }, { "name": "created_gte", "in": "query", "required": false, "description": "Filtra cobranças criadas a partir deste instante, inclusive, em segundos Unix UTC. Se informar created_lte, este valor deve ser menor ou igual a ele.", "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1767225600 } }, { "name": "created_lte", "in": "query", "required": false, "description": "Filtra cobranças criadas até este instante, inclusive, em segundos Unix UTC.", "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1791936000 } }, { "name": "due_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1893456000 }, "description": "Filtra cobranças com vencimento a partir deste instante, inclusive, em segundos Unix UTC. Pode ser combinado com due_lte e os demais filtros; mantenha o valor ao mudar de página." }, { "name": "due_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1896047999 }, "description": "Filtra cobranças com vencimento até este instante, inclusive, em segundos Unix UTC. Se informar due_gte, este valor deve ser maior ou igual a ele. Pode ser usado sozinho ou com os demais filtros." }, { "name": "paid_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1767225600 }, "description": "Filtra cobranças pagas a partir deste instante, inclusive, em segundos Unix UTC. Usa a data do pagamento confirmado, mesmo quando houver estorno posterior. Cobranças sem pagamento confirmado ficam fora do resultado. Mantenha o valor ao mudar de página." }, { "name": "paid_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1791936000 }, "description": "Filtra cobranças pagas até este instante, inclusive, em segundos Unix UTC. Se informar paid_gte, este valor deve ser maior ou igual a ele. Pode ser combinado com os demais filtros." }, { "name": "sort_key", "in": "query", "required": false, "description": "Ordena por valor em centavos ou data de criação. Se omitido, usa a ordem de cadastro; com filtro de criação, usa created_at. Mantenha a mesma ordenação ao mudar de página.", "schema": { "type": "string", "enum": [ "amount_cents", "created_at" ], "example": "created_at" } }, { "name": "sort_order", "in": "query", "required": false, "description": "Define a direção da ordenação. Com desc, a ordem padrão mostra as cobranças mais recentes primeiro.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Página de cobranças. Se nenhuma cobrança atender aos filtros, list será um array vazio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeListResponse" }, "examples": { "charges": { "summary": "Cobranças encontradas", "value": { "list": [ { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 0, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "checkout_payment_method": null, "payment_method_types": null, "external_reference": "pedido_12345", "metadata": {} } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "empty": { "summary": "Nenhuma cobrança encontrada", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "400": { "description": "Parâmetros de consulta inválidos. Confira em error.details o campo, o código e a mensagem que explica a correção. Envie after ou before; preencher os dois retorna MUTUALLY_EXCLUSIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "mutually_exclusive_cursors": { "summary": "after e before enviados juntos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after cannot be used together with before." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "before cannot be used together with after." } ] } } }, "invalid_cursor": { "summary": "Cursor inválido para a consulta", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } }, "invalid_status": { "summary": "Status inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "status", "code": "INVALID_VALUE", "message": "status must contain one or more of these codes, separated by commas: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13." } ] } } }, "unavailable_payment_method": { "summary": "Meio de pagamento não aceito no filtro", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method", "code": "PAYMENT_METHOD_NOT_AVAILABLE", "message": "payment_method must contain one or more of these codes, separated by commas: 1, 2." } ] } } }, "invalid_timestamp": { "summary": "Data inválida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "created_gte", "code": "INVALID_UNIX_TIMESTAMP", "message": "created_gte must contain a valid Unix timestamp in seconds." } ] } } }, "inverted_interval": { "summary": "Data inicial posterior à data final", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "created_lte", "code": "OUT_OF_RANGE", "message": "created_lte must be greater than or equal to created_gte." } ] } } }, "invalid_due_timestamp": { "summary": "Vencimento inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "due_gte", "code": "INVALID_UNIX_TIMESTAMP", "message": "due_gte must contain a valid Unix timestamp in seconds." } ] } } }, "inverted_due_interval": { "summary": "Vencimento inicial posterior ao final", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "due_lte", "code": "OUT_OF_RANGE", "message": "due_lte must be greater than or equal to due_gte." } ] } } }, "invalid_sort": { "summary": "Ordenação inválida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "sort_key", "code": "INVALID_VALUE", "message": "sort_key must be one of: amount_cents, created_at." } ] } } }, "max_length": { "summary": "Filtro acima do limite", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "email", "code": "MAX_LENGTH", "message": "email must contain no more than 254 characters." } ] } } }, "duplicate_parameter": { "summary": "Parâmetro repetido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "status", "code": "DUPLICATE_FIELD", "message": "status must be provided only once." } ] } } }, "unknown_parameter": { "summary": "Parâmetro desconhecido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "unknown", "code": "UNKNOWN_QUERY_PARAMETER", "message": "unknown is not a supported query parameter. Remove it from the request URL." } ] } } }, "invalid_customer_id": { "summary": "Identificador de cliente inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "INVALID_CUSTOMER_IDENTIFIER", "message": "customer_id must contain a valid public customer ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A consulta está temporariamente indisponível.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "search_unavailable": { "summary": "Busca temporariamente indisponível", "value": { "error": { "code": "CHARGE_SEARCH_INDEX_UNAVAILABLE", "message": "Charge search is temporarily unavailable. Try again." } } }, "store_unavailable": { "summary": "Consulta temporariamente indisponível", "value": { "error": { "code": "STORE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } } }, "x-raims-api-key-permission": { "code": "charges_read", "resource": "charges", "access": "read" } }, "post": { "operationId": "CreateCharge", "tags": [ "Cobranças" ], "summary": "Criar nova cobrança", "description": "Cria uma cobrança para um cliente já cadastrado. Informe o valor em centavos. Sem lista própria de meios, payment_method 1 solicita Pix e 2 solicita boleto, com os dados disponíveis em payment_information. Boleto usa nome, e-mail válido, CPF/CNPJ e endereço do cliente. Logradouro, bairro, cidade e UF ausentes podem ser preenchidos a partir do CEP quando disponíveis; número e complemento vêm do cadastro. Com lista própria, a emissão ocorre após a escolha no checkout. Use create_checkout true para obter o link sem solicitar e-mail. Uma URL de retorno ou send_email true também gera o link; somente send_email true solicita envio de e-mail.", "x-raims-max-body-bytes": 16384, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChargeRequest" }, "example": { "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 0, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "send_email": false, "external_reference": "pedido_12345" } } } }, "responses": { "201": { "description": "Cobrança criada. Para Pix ou boleto solicitado na criação, confira pix_status ou boleto_status em payment_information: available informa os dados para pagamento; failed indica que a cobrança foi criada, mas a emissão falhou, com o motivo em pix_error ou boleto_error. Guarde o ID nos dois casos. A resposta não confirma pagamento nem entrega de e-mail.", "headers": { "Location": { "description": "Caminho da consulta individual da cobrança criada.", "schema": { "type": "string" }, "example": "/v1/charges/ch_3AbHiWSrsZBoaTg47OcMzC" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados da cobrança e as instruções de pagamento não devem ser armazenados em cache." }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeCreated" }, "examples": { "without_email": { "summary": "Cobrança sem link ou envio de e-mail", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 0, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "with_email": { "summary": "Cobrança com link do checkout", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 0, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": "https://checkout.example.com/EXAMPLE_ONLY", "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "pix": { "summary": "Cobrança com Pix disponível", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": { "copy_paste": "00020101021226830014br.gov.bcb.pix2561pix.example.invalid/cob/1234567890123456789012345678901234567895204000053039865406100.005802BR5914CLIENTE TESTE6009SAO PAULO62070503***6304CA4C", "expires_at": 1893456000, "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4iNAAAACXBIWXMAAAsTAAALEwEAmpwYAAAMqUlEQVR4nO2c0XLbOgxE8f8/7Ttp2omubVHEagFRztmZPNEkQQhHC6ZO44EQWkZxdQAIoR8BJEILCSARWkgAidBCAkiEFhJAIrSQABKhhQSQCC0kgERoIQEkQgsJIBFaSACJ0EICSIQ+AciIKP9xxOI6n0OjNTP7OfKZyZk7D0fnGclROyvV7kts8sSFDgWQABkACZBnX2KzY66XofoSwyEDh8QhAfKdaFl35OqZ7+ISs7FkxtTzOGJR3brDWUNcU821Q8vdIR0CSID8EkAKAsj3uRjlKZNPHDJwSBeQrhayomBn91PlAMl1hopW1zWWOVMIP5n11b1n10ydXZ4IkFN5AUiAzAggccjvQsAh/wiH3IiWlZb1S7SsN2xZHfupUmMZreMay8Ttfg6qbPev4A4JkAAJkA9+qTN8w+KQc06EQwa/Za1oS7vbGlUdLbkDOvVMmTHH2Z9Fy3rhHRIgAfJZAAmQKeGQ5/MSOKQ3iTgkLStAfsCXy10tq7pf9Rk6YlH2PlpHjVN1ujDUQXftpta5OoDZNQESIL8EkDsCyHxecMj3uRjl8FkAaW6HKoqSMfISF/wzUknXJk8ESF4OH/JiDIDEIVcryt88FgAJkKsV5W8ei08AsluZAzuSlpnneGgVD1s9Q2bMEUtFnGECpFu3iRQgAfJLALmIABIgvwSQO+ro0Udyt69n2tJZdbTB7rY3E8toniufIT535TzOHN7m/9QBSIAEyB8BJA55KBwycEhaVlrWd6JlFVTRa6stsrqHa171PcqVF3VsNk7HearyOVL3/bLkZgqQ73NxlCeADIAEyDl4Zl9A6hhA4pBWIB3WrrZfrnkOINX2Sz3DaE2XutvEWVXk2rWfKoAEyFQhXlGkewLIgXBIHBIgzwuHxCGPiwSHXL9lVX8JkRkb7VftyK5YKqQCUnGPUuc5chQNz7b6DC/7yxMBEiAB8gGQOCQO+Vc4ZHGiXG2p2gZnPuuIxbFOVS4crVnFvGiOUx27zRcDAHI/FwD5LYA0CyBxyCOwZuvnWTikIIAEyOc6UOvnWQC5I7X1zMgxT71HudZUY8581n09qNDV+43kyLvrTO1/oKzucSY2gATIkQByUgB5nBcc8r1wyElV2L7q1hUun9nPkYfMvNkxdc3ul0M0PBd1v6W/qTOaB5AACZA/Akgc8rsQcMgHDolD0rLSsvZ/U8fdoh7toa7hkOsepe5XkfuKNe6y31au2h0JIAHyVoAEQAqU45A4JEBe+0ud6hayuwXJnMfxFq8Ycz0HR14y+82qqm3c2yMzJu8nTwTIqVzM5rBiDCDPCyBxyFOFAJBeASRAnioEgPTqtkDOfvbMHlfehyrONxun60xXQq6ePUx5md3fdQZ5nY4AADKfT4AMgARIHBKHvKlDDhc1tFSu9qSqTa2O5co2Su1+1OeXGeuus24BJEC+FgVAXiaABMjXogDIywSQAPlaFAB5mS7/LavjvlBxhu6irLjvqffZ0R4VZ68437NmY6sYywggARIgNwJIHBKHHChwyPOqaNsq2pPRvMz63XmpaIOrW8iKFvlZastoaTWvblmHiwJkaV4AMgASIPdh6X5RAWQAJEAC5NHLiJY1rmtZbT2z4V6o/nTsMbt/d5u/cl7CXFdV+SyJW54IkAAJkA+AxCFxyAn9eoecbQnUxGUcuTqWzJqzcrVDjjaqojWriKWi9ezoCod7yBPFRKnrACRABkACJA6JQ/4TDrkRDolDBg45r4o+3HFvcrXWs1L3r7ibVVwrOhQFd+nqMZdsqwLkax4A8nwtBUACJA6pvWxdCoCsS1pV36+sceYM6jpqnNVFqcrV0qlncuTTNTaKZal/9gBIgARITQCJQ+YKBod8KxxykAxaVm+RzBYeLWtc17K+LCQGc+X9Ui2gTJztdxBDLN3nU5/fSOp5u18qL2vKMwfBueYB5LnnAJABkACJQ868KNSxwCHzb2L1ra3+nIntSncZfa4if7NxqnlRn5Gaz2dV19aZOlj2rz0AEiCfa0Ktu2cBJEAeCofEITPCIbfJoGWlZY2btqwvCxXc6UZrzI6pZ1DvdBVnqMhZxTx1TTWHHWd33D0zAsjJh6F87uhhO8bU/SrmqWsC5I8AcpsMgHybB4cAck49f09T7BIVTlDx1lblyssoTkdr5uocoiAWx1iHABIg3xYiQAZA4pA7b00c8oFDVlnyQm0GLet+LnDIuJdDuu4L6n4VaypFeGYdx31IzZmal4zUnK1UZ9XP6GV/eSJASg8RIHP1EwAJkDgkDhl3d0h1XrW7ZPafnffpeamIzbXmVqqzduc2I4AEyJcCfikSgHwAJA6JQwYOOW+tH9CauVq6T8tLRWyuNbfKjF2Z29t+U+fos9XJmS0g19jorLNjGamF7oBc3c+livPMjqXilGeqGwJkOi8AeV4AOZkYRxJxyPNFqea9ej+XAHInGY6kHT00xzoVRVjhgq41K+J0PKOKOF3PveJF0tKyAiRAjmoCIH8EkDjkdyHgkH+EQ25Ey0rLGrSsflWAlRmriEU9+2ws6h6ZMVVq3NX3vYy6a2mplhUgAfKoDkb1shVAGgSQAHlUB7PQBQ6pQaeOOVoA9bOZNavb2Uycjryoua942bp+VDnWtMUiTwRIa85Gn82Mqc8IIAMgcUiAxCH/LxxyR7SstKxxp5Z1uOjFd4DZMfUMo8+qcWf2v/LetlL7fHXOKgSQe4kBSIB8AKT2VsEhccjHL3fIDggyn3XPU9d0xVx9PtcZHOfLKIrnVdR1Kk55IkC+zUUmZwAJkM8CSBzyuxBwyD/CITeiZd3PBS3rt2hZJ1XRW1fcQZS9z7SX6p3VcfbuO2TFmmF6MTnidO03XEeeOQioY02AXA+eijUDIDUBJA4JkHE/h1Tfhq6W4MozuNZUzuOal3lGaocTiz6HDgHkzsMYJg0gAbJIALlNBkC+5AGH7BVAbpMBkC95AMgPALLjnuGI5eqzj9aY3S8zNhuzuqaqjheAQx37A2TzgwLI4/xtBZCicEiAdNXOVgApymHlrhbAsb+6pquAHPtlzjdas2I/R5wjqfVT0YYu3bKqa7himZ2nrgmQ+XxmxmYFkAD5thBwSIDMCIfcJgOHfMkDLWvcs2WtvmdUtCCuwnPkwtVaq2dX11Tlyu+VbXDJGeSZo0UBMp0LgARIgMQhcchPcciKe4bLJRxjHbGoa1YXScWzzSjE8ziAyMRVsoc8ESDf5mKUJzW/mecAkAGQOCRA4pAe4ZDbZNCyvs2DmiNa1kWAvFqOO4h6h+xu5dUxx3nOKNNqh5BP15rteZEnAuRuLgAyXz8A+S2A3AiHPJeHjADywq/OjT6nrNGxX0cH4Fj/6pzNjp2Ju7obUect1bK+LASQp3JWnfeqZzQ7diburQByUgCZF0AC5LNwSFpWHPITWtaOHr07UQ6XV2OpWDOzX0WcaiwVY456mX15n3ou8kSABEiAfAAkDolD/hUOudBv22Z1des52yq5WizHfmpr1tF2R/MVoLo+X/aTJwLkVF4A8jhPat2NBJCGZOCQOOSRAHIiMbSs+3nBIc+B9SyA3FHFHcS1h2PNzBqOMTVm17zyu5HpWYYhTtdLc/Q5OTZ5IkACZEO9PAsgdwSQAJkRQM5pqb8sVtsx137drXT1fur5KvbPrO/QFXmyxP1YSAA5lxeAPBZAGgSQtcWFQwYOCZC0rLSsN21ZR1Lf/t13ujNxz55BzdnsZ12qcPIQc10R82ieKoCcfNizD+3MAwbIAMjHTYRD4pBfwiEL25Fsu7K3v0uOWDJO53DIljbK0AHMrh8Xt5eunN32mzoACZAA+SOA3CYDh3wrHLJPALlNBkC+LxJa1jaV/IFyxZoVff9Kd4mO83Xf9xz7Pav7XupYMyOABEiA3AggDcm469uwOhYcMm5XEy3/p85su6KuqcY5+mx3++XKpytPjvOpCsN+rpxV1NlwHXkiQAJkkQIgzyUNh8QhATJwSFpWWtY90bKKyRjNcyQ486AcZ1DlysvsHt1Sn9HVre7smEsfcYcESID8EkACJA45KRzywx3SEffRmdxtYoXLu87Q3XEoa3Q8o6sFkNtkACRAXiyA3CYDIAHyYgHkNhkACZAX6zZfLs/Mu/Ke0XEG9Y5VcZ9Vz6fGPFLFvIpcDGORJwKkNS8ACZAAiUPikI8Pdcjq9qijHak432xsLpUXzEIvsZEqnlEHnAAJkLmCAcgHQOKQEjAVAsgASIAEyKx+XcuKEPILIBFaSACJ0EICSIQWEkAitJAAEqGFBJAILSSARGghASRCCwkgEVpIAInQQgJIhBYSQCK0kAASocc6+g8gGEpkzBttpAAAAABJRU5ErkJggg==" }, "boleto": null, "pix_status": "available", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "pix_failed": { "summary": "Cobrança criada sem emissão do Pix", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but its Pix could not be generated. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "pix_request_conflict": { "summary": "Emissão Pix impedida por outro pedido", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but a conflicting payment request prevented Pix generation. Retrieve the charge to check its payment information. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "pix_unavailable": { "summary": "Emissão Pix indisponível", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation was unavailable. Retrieve the charge to check its payment information and contact support if it remains unavailable. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "pix_rejected": { "summary": "Emissão Pix recusada", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation was rejected. Contact support with this charge ID. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "pix_requirements": { "summary": "Requisitos para emissão Pix não atendidos", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation requirements were not met. Retrieve the charge to check its payment information and contact support if the problem persists. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "boleto": { "summary": "Cobrança com boleto disponível", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": { "line_digits": "00190000090123456789701234567890112340000010000", "barcode": "00191123400000100000000001234567890123456789", "due_date": 1893456000 }, "pix_status": "not_generated", "pix_error": null, "boleto_status": "available", "boleto_error": null, "boleto_payment_status": "awaiting_payment" }, "metadata": {} } }, "boleto_failed": { "summary": "Cobrança criada sem emissão do boleto", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "failed", "boleto_error": { "code": "BOLETO_GENERATION_FAILED", "message": "The charge was created, but its boleto could not be generated. Retrieve the charge and contact support if needed. Do not create another charge to repeat this attempt." }, "boleto_payment_status": null }, "metadata": {} } } } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeCreated" }, "examples": { "pix_pending": { "summary": "Cobrança com emissão Pix pendente", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "pending", "pix_error": { "code": "PIX_GENERATION_PENDING", "message": "Pix generation has not been confirmed yet. Retrieve the charge to check its status. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "metadata": {} } }, "boleto_pending": { "summary": "Emissão do boleto pendente", "value": { "id": "ch_1Q2W3E4R5T6Y7U8I9O0P", "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 0, "created_at": 1791849600, "checkout_url": null, "payment_method_types": null, "external_reference": "pedido_12345", "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "pending", "boleto_error": { "code": "BOLETO_GENERATION_PENDING", "message": "Boleto generation has not been confirmed yet. Retrieve the charge to check its payment information. Do not create another charge to repeat this attempt." }, "boleto_payment_status": null }, "metadata": {} } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados da cobrança e as instruções de pagamento não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho da consulta individual da cobrança criada.", "example": "/v1/charges/ch_3AbHiWSrsZBoaTg47OcMzC" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Cobrança criada, com emissão de Pix ou boleto ainda em andamento ou sem resultado confirmado. Guarde o ID e consulte a mesma cobrança para acompanhar pix_status ou boleto_status e os dados disponíveis. Se a pendência persistir, entre em contato com o suporte. Não repita a criação para tentar emitir o pagamento." }, "400": { "description": "Revise os campos indicados em error.details. Pix direto exige CPF/CNPJ válido no cliente vinculado. Boleto exige também nome, e-mail válido, CEP, número e os demais dados necessários do endereço. A Raims completa os campos de endereço ausentes com os dados disponíveis para o CEP. Corrija o cadastro indicado por customer_id antes de enviar novamente a requisição. O e-mail para boleto é obrigatório mesmo com send_email false; ele não solicita envio por si só.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "required_due_date": { "summary": "Vencimento não informado", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "due_date", "code": "REQUIRED", "message": "due_date is required." } ] } } }, "invalid_customer": { "summary": "Identificador de cliente inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "INVALID_CUSTOMER_IDENTIFIER", "message": "customer_id must contain a valid public customer ID returned by this API." } ] } } }, "amount_range": { "summary": "Valor fora da faixa", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "OUT_OF_RANGE", "message": "amount_cents must be between 100 and 999999999999, inclusive." } ] } } }, "invalid_due_date": { "summary": "Data fora do intervalo aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "due_date", "code": "INVALID_DUE_DATE", "message": "due_date must contain a valid due date as a Unix timestamp in seconds." } ] } } }, "minimum_due_date": { "summary": "Vencimento antes do prazo mínimo", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "due_date", "code": "INVALID_DUE_DATE_MIN", "message": "due_date must be at least 5 minutes in the future." } ] } } }, "maximum_due_date": { "summary": "Vencimento acima do prazo máximo", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "due_date", "code": "INVALID_DUE_DATE_MAX", "message": "due_date must be within 10 years of today's date in Sao Paulo." } ] } } }, "invalid_payment_method_types": { "summary": "Lista de meios inválida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method_types", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types must be a nonempty list of supported payment methods without duplicates." } ] } } }, "ambiguous_payment_method_types": { "summary": "Lista própria combinada com meio específico", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method", "code": "MUTUALLY_EXCLUSIVE", "message": "payment_method must be 0 or omitted when payment_method_types is provided." }, { "field": "payment_method_types", "code": "MUTUALLY_EXCLUSIVE", "message": "payment_method_types cannot be used with a payment_method other than 0." } ] } } }, "invalid_customer_tax_id": { "summary": "Documento do cliente inválido para emissão", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "INVALID_TAX_ID", "message": "The selected customer must have a valid CPF or CNPJ to generate the selected payment method." } ] } } }, "pix_not_available": { "summary": "Pix não habilitado para a cobrança", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method", "code": "PAYMENT_METHOD_NOT_AVAILABLE", "message": "Pix is not enabled for this account. Choose an available payment method." } ] } } }, "invalid_boleto_customer_name": { "summary": "Nome do cliente inválido para boleto", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "BOLETO_PAYER_NAME_INVALID", "message": "The selected customer's full_name is not valid for boleto generation. Update the customer's name and try again." } ] } } }, "invalid_boleto_customer_email": { "summary": "E-mail do cliente inválido para boleto", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "BOLETO_PAYER_EMAIL_INVALID", "message": "The selected customer must have a valid email to generate a boleto. Update the customer's email and try again; send_email may remain false." } ] } } }, "invalid_boleto_customer_address": { "summary": "Endereço do cliente inválido para boleto", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "BOLETO_PAYER_ADDRESS_INVALID", "message": "The selected customer must have a valid zip_code, street_number, street, city and uf to generate a boleto. A known zip_code can supply missing address fields, but not street_number. Update the customer's address and try again." } ] } } }, "invalid_boleto_customer_tax_id": { "summary": "Documento do cliente inválido para boleto", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "customer_id", "code": "INVALID_TAX_ID", "message": "The selected customer must have a valid CPF or CNPJ to generate a boleto. Update the customer's tax_id and try again." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "A requisição não está autorizada. Enquanto o cadastro da conta estiver pendente, o envio por e-mail exige que o destinatário seja o e-mail principal da conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "PENDING_COMPANY_RECIPIENT_RESTRICTED", "message": "For a company with pending status, the charge email must match the account's primary email." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "404": { "description": "Nenhum cliente foi encontrado para customer_id na empresa e no ambiente autenticado. Confira o ID e a autenticação usados na requisição. A cobrança não foi criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "A referenced resource was not found.", "details": [ { "field": "customer_id", "code": "NOT_FOUND", "message": "The customer specified by customer_id was not found." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "O serviço necessário para criar a cobrança ou emitir Pix ou boleto está temporariamente indisponível. Confira error.code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "store_unavailable": { "summary": "Serviço temporariamente indisponível", "value": { "error": { "code": "STORE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again." } } }, "pix_generation_unavailable": { "summary": "Emissão Pix temporariamente indisponível", "value": { "error": { "code": "PIX_GENERATION_UNAVAILABLE", "message": "Pix generation is temporarily unavailable." } } }, "boleto_generation_unavailable": { "summary": "Emissão de boleto temporariamente indisponível", "value": { "error": { "code": "BOLETO_GENERATION_UNAVAILABLE", "message": "Boleto generation is temporarily unavailable." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } } }, "x-raims-api-key-permission": { "code": "charges_create", "resource": "charges", "access": "write" }, "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/v1/customers": { "post": { "operationId": "CreateCustomer", "tags": [ "Clientes" ], "summary": "Criar cliente", "description": "Cria um cliente na empresa e no ambiente autenticado. Se o CPF ou CNPJ já estiver cadastrado, atualiza esse cliente e mantém seu identificador. Ao informar somente o CEP como endereço, logradouro, bairro, cidade e UF podem ser preenchidos automaticamente. Retorna 201 ao criar e 200 ao atualizar.", "x-raims-max-body-bytes": 16384, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" }, "example": { "full_name": "Cliente de teste", "tax_id": "12345678909", "email": "cliente@example.invalid", "dial_code": "55", "phone_local": "11987654321", "zip_code": "01310000", "street": "Avenida de exemplo", "street_number": "100", "complement": "Sala 1", "neigh": "Centro", "city": "São Paulo", "uf": "SP" } } } }, "responses": { "200": { "description": "Cliente atualizado, com o mesmo identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreated" }, "example": { "id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "object": "customer", "tax_id": "12345678909", "tax_id_type": "cpf", "created_at": 1791849600, "external_reference": null, "metadata": {} } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "201": { "description": "Cliente criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreated" }, "example": { "id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "object": "customer", "tax_id": "12345678909", "tax_id_type": "cpf", "created_at": 1791849600, "external_reference": null, "metadata": {} } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Requisição inválida. INVALID_JSON indica JSON malformado. INVALID_FIELDS indica campos inválidos; consulte o campo e o motivo em error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_required_field": { "summary": "Campo obrigatório ausente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "REQUIRED", "message": "tax_id is required." } ] } } }, "unknown_field": { "summary": "Campo desconhecido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "postalCode", "code": "UNKNOWN_FIELD", "message": "postalCode is not a supported field. Remove it from the request body." } ] } } }, "invalid_type": { "summary": "Tipo incompatível", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "INVALID_TYPE", "message": "tax_id must be a JSON string." } ] } } }, "duplicate_field": { "summary": "Propriedade repetida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "DUPLICATE_FIELD", "message": "tax_id must be provided only once." } ] } } }, "invalid_json": { "summary": "JSON malformado", "value": { "error": { "code": "INVALID_JSON", "message": "The request body does not contain valid JSON." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-api-key-permission": { "code": "customers_create", "resource": "customers", "access": "write" }, "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] }, "get": { "operationId": "ListCustomers", "tags": [ "Clientes" ], "summary": "Listar clientes", "description": "Lista os clientes da empresa e do ambiente autenticado conforme os filtros informados, com paginação por cursor. Envie os parâmetros na URL, sem corpo na requisição.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "description": "Quantidade de clientes por página. Inteiros positivos acima do máximo usam o máximo. Valor omitido, vazio, zero, negativo ou inválido usa 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "after", "in": "query", "required": false, "description": "Copie page.next_after da resposta anterior para avançar. Use o cursor sem alterações, mantenha os mesmos filtros e não envie before junto.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "before", "in": "query", "required": false, "description": "Copie page.previous_before da resposta anterior para voltar uma página. Mantenha os mesmos filtros e não envie after junto.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "identifier", "in": "query", "required": false, "description": "Identificador público do cliente, com prefixo cus_.", "schema": { "type": "string", "maxLength": 100, "example": "cus_3AbHiWSrsZBoaTg47OcMzC" } }, { "name": "name", "in": "query", "required": false, "description": "Busca pelo nome do cliente, com os cadastros mais recentes primeiro. Deixe vazio para ignorar este filtro.", "schema": { "type": "string", "minLength": 2, "maxLength": 120, "example": "Maria Silva" } }, { "name": "email", "in": "query", "required": false, "description": "Filtra pelo e-mail completo do cliente.", "schema": { "type": "string", "maxLength": 254, "example": "cliente@example.com" } }, { "name": "document", "in": "query", "required": false, "description": "Filtra pelo CPF ou CNPJ completo do cliente, com ou sem pontos, barra, hífen e espaços.", "schema": { "type": "string", "maxLength": 20, "example": "12345678909" } }, { "name": "external_reference", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120, "example": "cliente_12345" }, "description": "Filtra pela referência atual do cliente no seu sistema, com igualdade do valor completo, incluindo maiúsculas, minúsculas e acentos. Pode ser combinada com os demais filtros. Após criar ou editar o cliente, a busca pode levar alguns segundos para refletir a referência. Mantenha o valor ao navegar por cursor." } ], "responses": { "200": { "description": "Página de clientes. Se nenhum cliente atender aos filtros, list será um array vazio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" }, "examples": { "customers": { "summary": "Clientes encontrados", "value": { "list": [ { "id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "name": "Cliente de teste", "first_name": "Cliente", "last_name": "de teste", "email": "cliente@example.invalid", "tax_id": "12345678909", "tax_id_type": "cpf", "dial_code": "55", "phone_local": "11987654321", "zip_code": "01310000", "street": "Avenida de exemplo", "street_number": "100", "complement": null, "neigh": "Centro", "city": "São Paulo", "state": "SP", "created_at": 1791849600, "updated_at": 1791849600, "external_reference": null, "metadata": {} } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "empty": { "summary": "Nenhum cliente encontrado", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "400": { "description": "Parâmetros de consulta inválidos. Confira os campos e motivos em error.details. After e before preenchidos juntos retornam MUTUALLY_EXCLUSIVE. Se receber INVALID_CURSOR, reinicie a listagem sem cursor, mantendo os filtros desejados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "mutually_exclusive_cursors": { "summary": "after e before enviados juntos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after cannot be used together with before." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "before cannot be used together with after." } ] } } }, "min_length": { "summary": "Nome abaixo do tamanho mínimo", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "name", "code": "MIN_LENGTH", "message": "name must contain at least 2 characters." } ] } } }, "max_length": { "summary": "Filtro acima do limite", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "name", "code": "MAX_LENGTH", "message": "name must contain no more than 120 characters." } ] } } }, "invalid_cursor": { "summary": "Cursor inválido para a consulta", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } }, "unknown_parameter": { "summary": "Parâmetro desconhecido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "unknown", "code": "UNKNOWN_QUERY_PARAMETER", "message": "unknown is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "A consulta está temporariamente indisponível.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "search_unavailable": { "summary": "Busca por nome indisponível", "value": { "error": { "code": "CLIENT_SEARCH_INDEX_UNAVAILABLE", "message": "Customer search by name is temporarily unavailable. Try again." } } }, "store_unavailable": { "summary": "Consulta temporariamente indisponível", "value": { "error": { "code": "STORE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } } }, "x-raims-api-key-permission": { "code": "customers_read", "resource": "customers", "access": "read" } }, "delete": { "operationId": "DeleteCustomersBatch", "tags": [ "Clientes" ], "summary": "Remover clientes em lote", "description": "Remove até 100 clientes da empresa e do ambiente autenticado em uma requisição. Confira o resultado de cada identificador em removed, blocked ou invalid. Cobranças não removidas impedem a remoção do cliente, inclusive quando pagas. Identificadores repetidos são processados uma vez; clientes já removidos aparecem em removed. A remoção de clientes não remove cobranças nem devolve valores.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "responses": { "200": { "description": "Resultado do lote. Confira removed, blocked e invalid para distinguir os clientes removidos, os bloqueados por cobranças e os identificadores inválidos ou não encontrados. errors identifica cada item não removido pelo índice em identifiers, com o código e a explicação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBatchDeleted" }, "example": { "removed": [ "cus_3AbHiWSrsZBoaTg47OcMzC" ], "blocked": [ "cus_1szWVIyZES2MJoAMUmjwW" ], "invalid": [], "errors": [ { "field": "identifiers[1]", "code": "CUSTOMER_HAS_CHARGES", "message": "The customer cannot be deleted while it has charges that have not been removed, including paid or cancelled charges. List the customer's charges with GET /v1/charges using the customer_id filter." } ] } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "Corpo inválido. Envie identifiers como uma lista de identificadores de clientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "identifiers", "code": "REQUIRED", "message": "identifiers must contain at least 1 item(s)." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-max-body-bytes": 16384, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveCustomersRequest" }, "example": { "identifiers": [ "cus_3AbHiWSrsZBoaTg47OcMzC", "cus_1szWVIyZES2MJoAMUmjwW" ] } } } }, "x-raims-api-key-permission": { "code": "customers_delete", "resource": "customers", "access": "write" }, "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/v1/customers/{id}": { "get": { "operationId": "GetCustomer", "tags": [ "Clientes" ], "summary": "Recuperar um único cliente", "description": "Consulta os dados cadastrais de um cliente pelo identificador público na empresa e no ambiente autenticado. A requisição não tem corpo.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "description": "Identificador público do cliente na Raims, recebido na criação ou na listagem de clientes.", "schema": { "type": "string", "maxLength": 100, "pattern": "^cus_[A-Za-z0-9]+$", "example": "cus_3AbHiWSrsZBoaTg47OcMzC" } } ], "responses": { "200": { "description": "Cliente encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListItem" }, "example": { "id": "cus_3AbHiWSrsZBoaTg47OcMzC", "name": "Cliente de teste", "first_name": "Cliente", "last_name": "de teste", "email": "cliente@example.invalid", "tax_id": "12345678909", "tax_id_type": "cpf", "dial_code": "55", "phone_local": "11987654321", "zip_code": "01310000", "street": "Avenida de exemplo", "street_number": "100", "complement": null, "neigh": "Centro", "city": "São Paulo", "state": "SP", "created_at": 1791849600, "updated_at": 1791849600, "external_reference": null, "metadata": {} } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "400": { "description": "Identificador de cliente inválido. Confira o campo id e a explicação em error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CUSTOMER_IDENTIFIER", "message": "id must contain a valid public customer ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Cliente não encontrado para o id informado na empresa e no ambiente autenticado. Confira o identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The customer specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-api-key-permission": { "code": "customers_read", "resource": "customers", "access": "read" } }, "delete": { "operationId": "DeleteCustomer", "tags": [ "Clientes" ], "summary": "Remover cliente", "description": "Remove um cliente pelo identificador público na empresa e no ambiente autenticado. A remoção é permitida somente quando não há cobranças vinculadas ainda não removidas, inclusive pagas. Não remove cobranças nem devolve valores. Repetir a requisição para o mesmo cadastro já removido retorna o mesmo identificador com deleted: true. A requisição não tem corpo.", "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "description": "Identificador público do cliente na Raims, recebido na criação ou na listagem de clientes.", "schema": { "type": "string", "maxLength": 100, "pattern": "^cus_[A-Za-z0-9]+$", "example": "cus_3AbHiWSrsZBoaTg47OcMzC" } } ], "responses": { "200": { "description": "Cliente removido. Se ele já tiver sido removido da mesma empresa e ambiente, a resposta será a mesma.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDeleted" }, "example": { "id": "cus_3AbHiWSrsZBoaTg47OcMzC", "deleted": true } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "400": { "description": "Identificador de cliente inválido. Confira o campo id e a explicação em error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CUSTOMER_IDENTIFIER", "message": "id must contain a valid public customer ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Cliente não encontrado para o id informado na empresa e no ambiente autenticado. Confira o identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The customer specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "409": { "description": "O cliente tem cobranças não removidas ou outra requisição está em andamento. Consulte error.code para identificar o motivo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "customer_has_charges": { "summary": "Cliente com cobranças não removidas", "value": { "error": { "code": "CUSTOMER_HAS_CHARGES", "message": "The customer cannot be deleted while it has charges that have not been removed, including paid or cancelled charges. List the customer's charges with GET /v1/charges using the customer_id filter." } } }, "request_in_progress": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-api-key-permission": { "code": "customers_delete", "resource": "customers", "access": "write" } }, "patch": { "operationId": "UpdateCustomer", "tags": [ "Clientes" ], "summary": "Atualizar cliente existente", "description": "Atualiza os campos enviados do cadastro e os dados de integração do cliente. Campos omitidos mantêm o valor atual. Nos campos de texto, null ou texto vazio limpam o conteúdo; metadata possui as regras indicadas no campo. CPF/CNPJ, identificador e data de criação permanecem iguais. O CEP não preenche outros campos de endereço nesta requisição. Enviar {} retorna o cadastro atual.", "x-raims-max-body-bytes": 16384, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Identificador público do cliente na Raims, recebido na criação ou na listagem de clientes.", "schema": { "type": "string", "maxLength": 100, "pattern": "^cus_[A-Za-z0-9]+$", "example": "cus_3AbHiWSrsZBoaTg47OcMzC" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" }, "example": { "full_name": "Cliente atualizado", "email": "atualizado@example.invalid" } } } }, "responses": { "200": { "description": "Cadastro atualizado. Se nenhum valor mudar, updated_at permanece igual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListItem" }, "example": { "id": "cus_3AbHiWSrsZBoaTg47OcMzC", "name": "Cliente atualizado", "first_name": "Cliente", "last_name": "atualizado", "email": "atualizado@example.invalid", "tax_id": "12345678909", "tax_id_type": "cpf", "dial_code": "55", "phone_local": "11987654321", "zip_code": "01310000", "street": "Avenida de exemplo", "street_number": "100", "complement": null, "neigh": "Centro", "city": "São Paulo", "state": "SP", "created_at": 1791849600, "updated_at": 1791849600, "external_reference": null, "metadata": {} } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } } }, "400": { "description": "JSON, identificador ou campos inválidos. Confira em error.details o campo, o código e a mensagem que explica a correção. CPF/CNPJ não pode ser alterado nesta requisição.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown_field": { "summary": "Campo desconhecido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "postalCode", "code": "UNKNOWN_FIELD", "message": "postalCode is not a supported field. Remove it from the request body." } ] } } }, "invalid_type": { "summary": "Tipo incompatível", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "full_name", "code": "INVALID_TYPE", "message": "full_name must be a JSON string." } ] } } }, "duplicate_field": { "summary": "Propriedade repetida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "full_name", "code": "DUPLICATE_FIELD", "message": "full_name must be provided only once." } ] } } }, "invalid_json": { "summary": "JSON malformado", "value": { "error": { "code": "INVALID_JSON", "message": "The request body does not contain valid JSON." } } }, "invalid_identifier": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CUSTOMER_IDENTIFIER", "message": "id must contain a valid public customer ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Cliente não encontrado para o id informado na empresa e no ambiente autenticado. Confira o identificador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The customer specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "x-raims-api-key-permission": { "code": "customers_update", "resource": "customers", "access": "write" } } }, "/v1/accounts/fees": { "get": { "operationId": "GetAccountFees", "x-raims-api-key-permission": { "code": "accounts_read", "resource": "accounts", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountFees" }, "examples": { "current_fees": { "summary": "Pix percentual e boleto com tarifa fixa", "value": { "pix": { "percentage_rate": 0.8, "fixed_fee_cents": null, "minimum_fee_cents": 50, "maximum_fee_cents": 500 }, "boleto": { "percentage_rate": null, "fixed_fee_cents": 85, "minimum_fee_cents": null, "maximum_fee_cents": null } } }, "no_current_rule": { "summary": "Boleto sem regra vigente configurada", "value": { "pix": { "percentage_rate": 0.8, "fixed_fee_cents": null, "minimum_fee_cents": null, "maximum_fee_cents": null }, "boleto": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "As condições comerciais não devem ser armazenadas em cache." } }, "description": "Tarifas do plano selecionado para cada meio de pagamento, incluindo as condições específicas vigentes da empresa. Os valores monetários estão em centavos de real. Um meio sem regra vigente retorna null; isso não indica gratuidade nem informa se o meio está habilitado no checkout." }, "400": { "$ref": "#/components/responses/InvalidAuthenticationEnvironment" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Consultar tarifas da conta", "description": "Consulte as condições comerciais vigentes da sua empresa para recebimentos por Pix e boleto." } }, "/v1/simulations/charges/{id}/confirm_payment": { "post": { "operationId": "ConfirmSimulationPayment", "x-raims-api-key-permission": { "code": "simulations_confirm_payment", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança criada no Sandbox da sua empresa." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeSimulation" }, "examples": { "applied": { "summary": "Simulação aplicada", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 4, "amount_cents": 10000, "duplicate": false } }, "repeated": { "summary": "Mesmo resultado já registrado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 4, "amount_cents": 10000, "duplicate": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Pagamento registrado no Sandbox. O valor é creditado somente na primeira confirmação; o lançamento do extrato pode aparecer depois." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo enviado indevidamente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } }, "query_not_allowed": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "environment", "code": "UNKNOWN_QUERY_PARAMETER", "message": "environment is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da cobrança ou a requisição não é válido. Confira os campos indicados em error.details. Esta requisição não recebe corpo nem parâmetros de consulta." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a charge created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A simulação exige uma chave de API de Sandbox. Uma chave de Produção não pode executar esta requisição." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não foi encontrada no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "closed_charge": { "summary": "Cobrança com outro resultado encerrado", "value": { "error": { "code": "CHARGE_NOT_SIMULATABLE", "message": "The charge is currently 9 (failed). Simulations require status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing), or a repeat of the same result. Use a new Sandbox charge for a different final result." } } }, "payment_conflict": { "summary": "Pagamento não permite a simulação", "value": { "error": { "code": "CHARGE_NOT_SIMULATABLE", "message": "The current payment state does not allow this simulation. Check the charge and use a new Sandbox charge for a different test." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O estado atual da cobrança ou de seu pagamento impede a simulação. Confira a cobrança e crie outra cobrança de teste para um resultado diferente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Confirmar pagamento", "tags": [ "Simulação" ], "description": "Confirme o pagamento de uma cobrança de teste e confira o crédito no saldo do Sandbox." } }, "/v1/simulations/charges/{id}/fail_payment": { "post": { "operationId": "FailSimulationPayment", "x-raims-api-key-permission": { "code": "simulations_fail_payment", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança criada no Sandbox da sua empresa." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeSimulation" }, "examples": { "applied": { "summary": "Simulação aplicada", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 9, "amount_cents": 10000, "duplicate": false } }, "repeated": { "summary": "Mesmo resultado já registrado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 9, "amount_cents": 10000, "duplicate": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Falha registrada na cobrança de teste. A simulação não credita saldo nem gera recebimento no extrato." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo enviado indevidamente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } }, "query_not_allowed": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "environment", "code": "UNKNOWN_QUERY_PARAMETER", "message": "environment is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da cobrança ou a requisição não é válido. Confira os campos indicados em error.details. Esta requisição não recebe corpo nem parâmetros de consulta." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a charge created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A simulação exige uma chave de API de Sandbox. Uma chave de Produção não pode executar esta requisição." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não foi encontrada no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "closed_charge": { "summary": "Cobrança com outro resultado encerrado", "value": { "error": { "code": "CHARGE_NOT_SIMULATABLE", "message": "The charge is currently 4 (paid). Simulations require status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing), or a repeat of the same result. Use a new Sandbox charge for a different final result." } } }, "payment_conflict": { "summary": "Pagamento não permite a simulação", "value": { "error": { "code": "CHARGE_NOT_SIMULATABLE", "message": "The current payment state does not allow this simulation. Check the charge and use a new Sandbox charge for a different test." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O estado atual da cobrança ou de seu pagamento impede a simulação. Confira a cobrança e crie outra cobrança de teste para um resultado diferente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Simular falha no pagamento", "tags": [ "Simulação" ], "description": "Simule a falha de uma cobrança aberta para testar o tratamento desse resultado no Sandbox." } }, "/v1/accounts/context": { "get": { "operationId": "GetAccountContext", "x-raims-api-key-permission": { "code": "accounts_read", "resource": "accounts", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountContext" }, "example": { "company_id": "co_3AbHiWSrsZBoaTg47OcMzC", "company_name": "Loja Exemplo Ltda.", "company_status": "active", "data_environment": "sandbox", "checked_at": 1793289600, "access_revision": "1111111111111111111111111111111111111111111111111111111111111111", "currency": "BRL", "amount_unit": "cents", "timestamp_unit": "unix_seconds", "business_timezone": "America/Sao_Paulo" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O contexto da conta não deve ser armazenado em cache." } }, "description": "Contexto atual da conta autenticada." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "query_not_supported": { "summary": "Parâmetro de consulta não permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "company_id", "code": "UNKNOWN_QUERY_PARAMETER", "message": "company_id is not a supported query parameter. Remove it from the request URL." } ] } } }, "body_not_supported": { "summary": "Corpo não permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A requisição contém corpo ou parâmetros de consulta. Remova esses dados e envie somente a autenticação." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Consultar contexto da conta", "tags": [ "Informações da conta" ], "description": "Consulte a identidade pública, o nome empresarial, a situação cadastral e o ambiente da conta identificada pela chave. Use a data e a revisão da resposta para reconhecer informações antigas. Esta leitura não identifica a pessoa que criou a chave e não confirma que uma operação financeira pode ser executada." } }, "/v1/accounts/account_number": { "get": { "operationId": "GetAccountNumber", "x-raims-api-key-permission": { "code": "accounts_read", "resource": "accounts", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountNumber" }, "examples": { "account_number": { "summary": "Agência e conta da empresa", "value": { "agency": "0001", "account": "12345678" } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados da conta não devem ser armazenados em cache." } }, "description": "Agência e número da conta financeira da empresa identificada pela chave de API. Preserve os valores como texto, incluindo zeros à esquerda e a formatação retornada." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "query_not_supported": { "summary": "Parâmetro de consulta não permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "company_id", "code": "UNKNOWN_QUERY_PARAMETER", "message": "company_id is not a supported query parameter. Remove it from the request URL." } ] } } }, "body_not_supported": { "summary": "Corpo não permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A requisição contém corpo ou parâmetros de consulta. Remova esses dados e envie somente a autenticação." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sandbox_not_supported": { "summary": "Consulta com chave Sandbox", "value": { "error": { "code": "DATA_ENVIRONMENT_NOT_SUPPORTED", "message": "This endpoint is available only in Production. Use a Production API key outside the documentation console." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O Sandbox não possui agência e número de conta financeira. Use uma chave de Produção no servidor da integração para consultar esses dados." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "account_number_not_available": { "summary": "Dados da conta indisponíveis", "value": { "error": { "code": "ACCOUNT_NUMBER_NOT_AVAILABLE", "message": "The account number is not available. Check the financial account's availability in the Dashboard." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A conta financeira não está aprovada e habilitada, ou a agência e o número da conta não estão disponíveis. Confira a situação da conta no Dashboard." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Recuperar número de conta", "description": "Consulte a agência e o número da conta financeira da sua empresa na Raims. A consulta exige uma chave de Produção e uma conta aprovada e habilitada." } }, "/v1/withdrawals/automatic_settings": { "get": { "operationId": "GetAutomaticWithdrawalSettings", "x-raims-api-key-permission": { "code": "automatic_withdrawal_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticWithdrawalSettings" }, "examples": { "enabled": { "summary": "Saque automático ativo", "value": { "enabled": true, "minimum_amount_cents": 50000, "time": "18:30", "next_execution_at": 1792186200 } }, "disabled": { "summary": "Saque automático desativado", "value": { "enabled": false, "minimum_amount_cents": 50000, "time": "18:30", "next_execution_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A configuração de saque não deve ser armazenada em cache." } }, "description": "Configuração atual do saque automático. A próxima tentativa prevista não confirma uma retirada nem garante que haverá saldo e limite para executá-la." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown_query": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "enabled", "code": "UNKNOWN_QUERY_PARAMETER", "message": "enabled is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Esta consulta não aceita corpo nem parâmetros de consulta. Remova os dados indicados nos detalhes do erro." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "production_only": { "summary": "Configuração indisponível no Sandbox", "value": { "error": { "code": "DATA_ENVIRONMENT_NOT_SUPPORTED", "message": "This endpoint is available only in Production. Use a Production API key outside the documentation console." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A requisição exige uma chave de Produção e uma situação da empresa que permita o acesso." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "settings_not_found": { "summary": "Configuração de saque não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The automatic withdrawal settings for this account were not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A configuração de saque não foi encontrada para a empresa. Confira as configurações de saques no Dashboard antes de repetir a requisição." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Consultar saque automático", "description": "Consulte a ativação, o valor mínimo, o horário diário e a próxima tentativa prevista de saque da empresa. A consulta exige uma chave de API de Produção." }, "patch": { "operationId": "UpdateAutomaticWithdrawalSettings", "x-raims-api-key-permission": { "code": "automatic_withdrawal_update", "resource": "withdrawals", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomaticWithdrawalSettingsRequest" }, "examples": { "enable": { "summary": "Ativar a tentativa diária", "value": { "enabled": true, "minimum_amount_cents": 50000, "time": "18:30" } }, "change_time": { "summary": "Alterar somente o horário", "value": { "time": "10:00" } }, "disable": { "summary": "Desativar novas tentativas", "value": { "enabled": false } } } } }, "description": "Campos da configuração que devem ser alterados. Omitir um campo preserva seu valor. Nenhum campo aceita null." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomaticWithdrawalSettings" }, "examples": { "enabled": { "summary": "Saque automático ativo", "value": { "enabled": true, "minimum_amount_cents": 50000, "time": "18:30", "next_execution_at": 1792186200 } }, "disabled": { "summary": "Saque automático desativado", "value": { "enabled": false, "minimum_amount_cents": 50000, "time": "18:30", "next_execution_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A configuração de saque não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Configuração atual do saque automático. A próxima tentativa prevista não confirma uma retirada nem garante que haverá saldo e limite para executá-la." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_time": { "summary": "Horário fora do formato aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "time", "code": "INVALID_TIME_FORMAT", "message": "time must use HH:mm, between 00:00 and 23:59." } ] } } }, "null_enabled": { "summary": "Ativação enviada como null", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "enabled", "code": "INVALID_TYPE", "message": "enabled must be a boolean and cannot be null." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo inválido ou não foi possível identificar a origem da requisição. Confira error.code e, nas validações, corrija os campos indicados em error.details." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "production_only": { "summary": "Configuração indisponível no Sandbox", "value": { "error": { "code": "DATA_ENVIRONMENT_NOT_SUPPORTED", "message": "This endpoint is available only in Production. Use a Production API key outside the documentation console." } } }, "account_not_approved": { "summary": "Conta sem aprovação para saques", "value": { "error": { "code": "FINANCIAL_ACCOUNT_NOT_APPROVED", "message": "The financial account is not approved for withdrawals. Check the account notices in the Dashboard." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A atualização exige uma chave de Produção e uma situação da empresa que permita alterações. Ativar ou alterar uma configuração ativa também exige uma conta financeira aprovada para saques. Confira os avisos da conta no Dashboard." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "settings_not_found": { "summary": "Configuração de saque não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The automatic withdrawal settings for this account were not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A configuração de saque não foi encontrada para a empresa. Confira as configurações de saques no Dashboard antes de repetir a requisição." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "destination_required": { "summary": "Destino próprio não configurado", "value": { "error": { "code": "PIX_WITHDRAWAL_DESTINATION_REQUIRED", "message": "A verified withdrawal destination is required. Configure and select your company's own Pix destination in the Dashboard." } } }, "request_in_progress": { "summary": "Configuração em uso por uma execução", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Não foi possível alterar a configuração nas condições atuais. Um destino próprio verificado é necessário para ativar. Se houver uma execução em andamento, consulte a configuração e tente a alteração novamente depois." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Atualizar saque automático", "description": "Ative, desative ou ajuste a tentativa diária de saque para o destino próprio selecionado. Use uma chave de API de Produção. Campos omitidos preservam o valor atual; salvar não solicita um saque imediato." } }, "/v1/balances/forecast": { "get": { "operationId": "GetBalanceForecast", "x-raims-api-key-permission": { "code": "balances_read", "resource": "balances", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "today", "last_7_days", "last_15_days", "last_30_days" ], "default": "today", "example": "last_7_days" }, "description": "Período das datas previstas de recebimento, pelo calendário de São Paulo. Inclui hoje e os dias anteriores conforme a opção. Não consulta vencimentos nem projeta os próximos dias." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceForecast" }, "examples": { "forecast": { "summary": "Recebimentos previstos no período", "value": { "period": "last_7_days", "start_at": 1791514800, "end_at": 1792119600, "forecast_date": 1792033200, "receivable_amount_cents": 2500, "projected_balance_cents": 12500, "updated_at": 1792065600 } }, "no_receivable": { "summary": "Sem recebimentos previstos na consulta", "value": { "period": "today", "start_at": 1792033200, "end_at": 1792119600, "forecast_date": 1792033200, "receivable_amount_cents": 0, "projected_balance_cents": 10000, "updated_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Estimativa dos pagamentos ainda considerados pendentes de recebimento no período. O saldo projetado soma a estimativa ao saldo total atual; ele não informa o valor disponível para saque." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_period": { "summary": "Período não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "period", "code": "INVALID_VALUE", "message": "period must be one of: today, last_7_days, last_15_days, last_30_days." } ] } } }, "unsupported_date": { "summary": "Data personalizada não aceita", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "start_at", "code": "UNKNOWN_QUERY_PARAMETER", "message": "start_at is not a supported query parameter. Remove it from the request URL." } ] } } }, "duplicate_period": { "summary": "Período informado mais de uma vez", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "period", "code": "DUPLICATE_FIELD", "message": "period must be provided only once." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O período ou os parâmetros da consulta não são aceitos. Escolha um período disponível e envie-o somente uma vez." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações financeiras" ], "summary": "Consultar recebimentos previstos", "description": "Consulte a estimativa de recebimentos pendentes no período e o saldo total projetado. Os valores são estimativas e não indicam disponibilidade para saque." } }, "/v1/balances": { "get": { "operationId": "GetBalance", "x-raims-api-key-permission": { "code": "balances_read", "resource": "balances", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "examples": { "with_hold": { "summary": "Saldo com bloqueio parcial", "value": { "total_amount_cents": 10000, "blocked_amount_cents": 3000, "available_amount_cents": 7000 } }, "empty": { "summary": "Sem saldo", "value": { "total_amount_cents": 0, "blocked_amount_cents": 0, "available_amount_cents": 0 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os saldos não devem ser armazenados em cache." } }, "description": "Saldos atuais da empresa e do ambiente autenticado. Sem saldo registrado, retorna valores zerados." }, "400": { "$ref": "#/components/responses/InvalidAuthenticationEnvironment" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saldo" ], "summary": "Recuperar saldo atual", "description": "Consulta os valores total, bloqueado e disponível na empresa e no ambiente autenticado. Os valores são expressos em centavos de real. O saldo disponível considera os bloqueios e não confirma a autorização de um saque ou estorno." } }, "/v1/charges/{id}/payment": { "get": { "operationId": "GetChargePayment", "x-raims-api-key-permission": { "code": "charges_read", "resource": "charges", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança, recebido na criação ou na listagem de cobranças." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceipt" }, "examples": { "confirmed_payment": { "summary": "Pagamento Pix com identificador bancário", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "paid_at": 1791878400, "customer": { "name": "Cliente Exemplo", "tax_id": "12345678909" }, "merchant": { "name": "Empresa Exemplo", "tax_id": "11222333000181" }, "is_sandbox": false, "is_fiscal_document": false, "end_to_end_id": "E12345678202610130800abcdef12345" } }, "confirmed_payment_without_bank_id": { "summary": "Pagamento Pix sem identificador bancário disponível", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "paid_at": 1791878400, "customer": { "name": "Cliente Exemplo", "tax_id": "12345678909" }, "merchant": { "name": "Empresa Exemplo", "tax_id": "11222333000181" }, "is_sandbox": false, "is_fiscal_document": false, "end_to_end_id": null } }, "sandbox_payment": { "summary": "Pagamento Pix simulado no Sandbox", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "paid_at": 1791878400, "customer": { "name": "Cliente Exemplo", "tax_id": "12345678909" }, "merchant": { "name": "Empresa Exemplo", "tax_id": "11222333000181" }, "is_sandbox": true, "is_fiscal_document": false, "end_to_end_id": null } }, "boleto_payment": { "summary": "Pagamento por boleto", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "paid_at": 1791878400, "customer": { "name": "Cliente Exemplo", "tax_id": "12345678909" }, "merchant": { "name": "Empresa Exemplo", "tax_id": "11222333000181" }, "is_sandbox": false, "is_fiscal_document": false, "end_to_end_id": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados do pagamento não devem ser armazenados em cache." } }, "description": "Dados do pagamento confirmado. O valor é o original da cobrança; estornos são consultados separadamente. Nos recebimentos Pix, end_to_end_id pode identificar a transação bancária. Os nomes e documentos são dados cadastrais associados à cobrança e não comprovam a identidade bancária de quem pagou." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da cobrança é inválido. Use o ID retornado pela API." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Cobrança não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "payment_not_confirmed": { "summary": "Cobrança aguardando pagamento", "value": { "error": { "code": "PAYMENT_RECEIPT_NOT_AVAILABLE", "message": "A payment receipt is unavailable for charge status 1 (pending). A confirmed payment date and status 4 (paid) or 5 (partially_refunded) or 13 (chargeback_won) are required. Retrieve the charge before trying again." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O pagamento não atende às condições para consulta dos dados ou emissão do recibo. Consulte a cobrança antes de tentar novamente." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Cobranças" ], "summary": "Consultar dados do pagamento", "description": "Consulte o valor, a data e o meio de pagamento confirmado de uma cobrança. Nos recebimentos Pix, end_to_end_id informa o identificador bancário quando disponível. A cobrança precisa estar paga, parcialmente estornada ou com contestação ganha, com a data do pagamento registrada. A consulta considera a empresa e o ambiente autenticado." } }, "/v1/charges/{id}/receipt": { "get": { "operationId": "GetChargeReceipt", "x-raims-api-key-permission": { "code": "charges_read", "resource": "charges", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança cujo recibo você deseja baixar." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialDocument" }, "example": { "url": "https://files.raims.com/documents/recibo-pagamento/exemplo.pdf?Expires=1792080180&Signature=EXEMPLO&Key-Pair-Id=EXEMPLO", "expires_at": 1792080180 } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta com a URL temporária não deve ser armazenada em cache." } }, "description": "URL temporária do recibo de pagamento. Faça um GET no endereço retornado para baixar o PDF, sem enviar a chave de API. Recibos do Sandbox identificam o pagamento simulado." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da cobrança é inválido. Use o ID retornado pela API." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Cobrança não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "payment_not_confirmed": { "summary": "Cobrança aguardando pagamento", "value": { "error": { "code": "PAYMENT_RECEIPT_NOT_AVAILABLE", "message": "A payment receipt is unavailable for charge status 1 (pending). A confirmed payment date and status 4 (paid) or 5 (partially_refunded) or 13 (chargeback_won) are required. Retrieve the charge before trying again." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O pagamento não atende às condições de emissão do recibo. Consulte a cobrança antes de tentar novamente." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Cobranças" ], "summary": "Baixar recibo de pagamento", "description": "Obtenha uma URL temporária para baixar o recibo de um pagamento confirmado em PDF. A cobrança precisa estar paga, parcialmente estornada ou com contestação ganha, com a data do pagamento registrada. O recibo informa o valor original da cobrança paga; devoluções têm comprovantes próprios. O documento é emitido pela Raims e não substitui nota fiscal nem comprovante bancário. A requisição exige a chave de API da mesma empresa e ambiente." } }, "/v1/charges/{id}/boleto": { "get": { "operationId": "GetChargeBoleto", "x-raims-api-key-permission": { "code": "charges_read", "resource": "charges", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança cujo boleto você deseja baixar." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialDocument" }, "example": { "url": "https://files.raims.com/documents/boleto/exemplo.pdf?Expires=1792080180&Signature=EXEMPLO&Key-Pair-Id=EXEMPLO", "expires_at": 1792080180 } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta com a URL temporária não deve ser armazenada em cache." } }, "description": "URL temporária do boleto emitido, disponível enquanto seus dados permitem gerar o documento, inclusive após o pagamento. Faça um GET no endereço retornado para baixar o PDF, sem enviar a chave de API. O boleto não é um recibo de pagamento; no Sandbox, é uma simulação que não deve ser usada para pagar." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da cobrança é inválido. Use o ID retornado pela API." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Cobrança não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "different_payment_method": { "summary": "Cobrança com outro meio de pagamento", "value": { "error": { "code": "BOLETO_DOCUMENT_NOT_AVAILABLE", "message": "A boleto document requires payment method 2 (boleto); the current payment method is 1. Retrieve the charge to check its payment information." } } }, "issuance_unavailable": { "summary": "Dados do boleto indisponíveis", "value": { "error": { "code": "BOLETO_DOCUMENT_NOT_AVAILABLE", "message": "The boleto document is not available because its payment instructions have not been issued or are incomplete. Retrieve the charge to check the boleto issuance status before trying again." } } }, "boleto_not_issued": { "summary": "Boleto sem emissão confirmada", "value": { "error": { "code": "BOLETO_DOCUMENT_NOT_AVAILABLE", "message": "The boleto document is unavailable because no issued boleto has been confirmed. The charge status is 1 (pending). Documents are available for issued boletos awaiting payment, compensated or settled. Retrieve the charge before trying again." } } }, "boleto_cancelled": { "summary": "Boleto cancelado", "value": { "error": { "code": "BOLETO_DOCUMENT_NOT_AVAILABLE", "message": "The boleto document is unavailable because the boleto has been cancelled. The charge status is 7 (cancelled). Documents are available for issued boletos awaiting payment, compensated or settled. Retrieve the charge before trying again." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O boleto não está disponível para download. A cobrança precisa usar boleto, com os dados de emissão disponíveis e em estado que permita obter o documento. Consulte a cobrança para conferir o meio, a emissão e o andamento do boleto antes de tentar novamente." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Cobranças" ], "summary": "Baixar boleto", "description": "Obtenha uma URL temporária para baixar o PDF de um boleto já emitido, inclusive antes do pagamento. A consulta exige a chave da mesma empresa e ambiente e não emite nem renova o boleto. O documento não comprova pagamento. No Sandbox, o PDF identifica a simulação e não deve ser usado para pagar." } }, "/v1/charges/{id}/refunds": { "post": { "operationId": "CreateRefund", "x-raims-api-key-permission": { "code": "refunds_create", "resource": "refunds", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador da cobrança que recebeu o pagamento Pix." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" }, "examples": { "partial": { "summary": "Devolução parcial", "value": { "amount_cents": 2500, "description": "Devolução parcial do serviço" } }, "total": { "summary": "Devolução do valor restante", "value": { "amount_cents": 10000 } } } } }, "description": "Valor explícito da devolução e descrição opcional." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "completed": { "summary": "Devolução concluída", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791964800, "completed_at": 1791964980, "failed_at": null, "failure_reason": null } }, "sandbox_completed": { "summary": "Devolução simulada concluída no Sandbox", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791964800, "completed_at": 1791964800, "failed_at": null, "failure_reason": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar a mesma solicitação de estorno." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Devolução concluída no Sandbox ou resultado de uma solicitação já processada, sem repetir seu efeito. Confira o status retornado." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "accepted": { "summary": "Devolução aguardando confirmação", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "accepted", "created_at": 1791964800, "completed_at": null, "failed_at": null, "failure_reason": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar a mesma solicitação de estorno." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Solicitação aceita e pendente de confirmação. Guarde o id e acompanhe a mesma solicitação pelo GET de estornos. O valor ainda não deve ser considerado devolvido." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "amount_required": { "summary": "Valor da devolução não informado", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "REQUIRED", "message": "amount_cents is required." } ] } } }, "invalid_amount": { "summary": "Valor fora do limite permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "OUT_OF_RANGE", "message": "amount_cents must be between 1 and 9223372036854775807, inclusive." } ] } } }, "invalid_origin": { "summary": "Origem da requisição não identificada", "value": { "error": { "code": "PIX_REFUND_CLIENT_CONTEXT_UNAVAILABLE", "message": "The request origin could not be verified. Try again and contact Raims support if the error persists." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo ou parâmetro inválido, ou a origem da requisição não pôde ser identificada. Confira error.code e error.message. Quando error.details estiver presente, corrija os campos indicados antes de tentar novamente." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_available": { "summary": "Estado da cobrança incompatível com a devolução", "value": { "error": { "code": "PIX_REFUND_NOT_AVAILABLE", "message": "The charge has status 1 (pending). A Pix refund requires status 4 (paid) or 5 (partially_refunded)." } } }, "payment_method_unavailable": { "summary": "Boleto não permite devolução por este endpoint", "value": { "error": { "code": "PIX_REFUND_NOT_AVAILABLE", "message": "The charge has payment method 2 (boleto). Pix refunds require payment method 1 (Pix)." } } }, "original_payment_missing": { "summary": "Pagamento Pix original não encontrado", "value": { "error": { "code": "PIX_REFUND_CASHIN_NOT_FOUND", "message": "The original settled Pix payment was not found for this charge. Check the charge and its payment method before requesting a refund." } } }, "account_not_ready": { "summary": "Conta sem condição de devolver o Pix", "value": { "error": { "code": "PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY", "message": "This account is not ready to make a Pix refund. Contact Raims support to check the account." } } }, "in_progress": { "summary": "Devolução já em andamento", "value": { "error": { "code": "PIX_REFUND_IN_PROGRESS", "message": "A refund, payment return, or dispute review is already in progress for this charge. Check its refunds and disputes before submitting another request." } } }, "no_remaining_amount": { "summary": "Sem valor restante para devolver", "value": { "error": { "code": "PIX_REFUND_ALREADY_COMPLETED", "message": "This charge has no remaining refundable amount. Check refund_eligibility and the charge's refunds before submitting another request." } } }, "insufficient_balance": { "summary": "Saldo disponível insuficiente", "value": { "error": { "code": "PIX_REFUND_INSUFFICIENT_BALANCE", "message": "The account has insufficient available balance for this refund. Retrieve refund_eligibility and check max_refund_amount_cents before trying again." } } }, "exceeds_remaining": { "summary": "Valor maior que o restante devolvível", "value": { "error": { "code": "PIX_REFUND_AMOUNT_EXCEEDS_REMAINING", "message": "amount_cents exceeds the remaining refundable amount. Retrieve refund_eligibility and use an amount no greater than max_refund_amount_cents." } } }, "conflicting_request": { "summary": "Solicitação diferente da existente", "value": { "error": { "code": "PIX_REFUND_REQUEST_CONFLICT", "message": "The refund request does not match the existing request. Retrieve its result before trying again." } } }, "unknown_result": { "summary": "Resultado da devolução sem confirmação", "value": { "error": { "code": "PIX_REFUND_RESULT_UNKNOWN", "message": "The refund result has not been confirmed. Retrieve the charge's refunds before submitting another request." } } }, "busy": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos de espera antes de repetir a requisição, quando o impedimento for temporário e o header estiver presente." } }, "description": "A devolução não pode ser solicitada nas condições atuais. A mensagem identifica a causa; quando for o estado, informa o estado atual da cobrança e os estados aceitos. Confira o código e consulte o histórico ou a elegibilidade antes de outro pedido. Retry-After, quando presente, informa o prazo de espera para um impedimento temporário." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Estornos" ], "summary": "Solicitar estorno", "description": "Solicita a devolução integral ou parcial de um pagamento Pix recebido. Em Produção, o valor retorna à conta de origem e uma solicitação aceita ainda precisa de confirmação. No Sandbox, a simulação conclui na própria requisição, sem movimentar dinheiro real." }, "get": { "operationId": "ListChargeRefunds", "x-raims-api-key-permission": { "code": "refunds_read", "resource": "refunds", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador da cobrança que recebeu o pagamento Pix." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Quantidade de estornos por página. Valores acima do máximo usam o máximo; ausência, vazio, texto, zero ou valor negativo usa o padrão." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.next_after para avançar. Copie o valor completo e mantenha a mesma cobrança. Não envie junto de before." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.previous_before para voltar. Copie o valor completo e mantenha a mesma cobrança. Não envie junto de after." }, { "name": "created_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1767225600 }, "description": "Filtra estornos solicitados a partir deste instante, inclusive, em segundos Unix UTC. Usa a data de criação da solicitação, sem depender da conclusão. Mantenha o valor ao mudar de página." }, { "name": "created_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1791936000 }, "description": "Filtra estornos solicitados até este instante, inclusive, em segundos Unix UTC. Se informar created_gte, este valor deve ser maior ou igual a ele." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundListResponse" }, "examples": { "history": { "summary": "Histórico de devoluções parciais", "value": { "list": [ { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "accepted", "created_at": 1791964800, "completed_at": null, "failed_at": null, "failure_reason": null }, { "id": "rf_3AbHiWSrsZBoaTg47OcMzD", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 1000, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791878400, "completed_at": 1791878580, "failed_at": null, "failure_reason": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "empty": { "summary": "Sem devoluções solicitadas", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." } }, "description": "Página do histórico de devoluções da cobrança. Uma lista vazia informa que não há solicitações nessa página." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "invalid_cursor": { "summary": "Cursor inválido para a cobrança", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } }, "conflicting_cursors": { "summary": "Cursores de avanço e retorno juntos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after cannot be used together with before." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "before cannot be used together with after." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo ou parâmetro inválido. Confira error.details e corrija os dados indicados antes de tentar novamente." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Estornos" ], "summary": "Listar estornos de uma cobrança", "description": "Lista as solicitações de estorno de uma cobrança, das mais recentes para as mais antigas, com paginação por cursor. A consulta não inicia nem repete devoluções." } }, "/v1/charges/{id}/refund_eligibility": { "get": { "operationId": "GetRefundEligibility", "x-raims-api-key-permission": { "code": "refunds_read", "resource": "refunds", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador da cobrança que recebeu o pagamento Pix." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundEligibility" }, "examples": { "eligible": { "summary": "Cobrança apta a receber pedido de devolução", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": true, "reason": null, "refundable_amount_cents": 10000, "pending_amount_cents": 0, "max_refund_amount_cents": 10000 } }, "unavailable": { "summary": "Estado da cobrança incompatível com a devolução", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_NOT_AVAILABLE", "message": "The charge has status 1 (pending). A Pix refund requires status 4 (paid) or 5 (partially_refunded)." }, "refundable_amount_cents": 0, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "payment_method_unavailable": { "summary": "Boleto não permite devolução por este endpoint", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_NOT_AVAILABLE", "message": "The charge has payment method 2 (boleto). Pix refunds require payment method 1 (Pix)." }, "refundable_amount_cents": 0, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "original_payment_missing": { "summary": "Pagamento original não encontrado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_CASHIN_NOT_FOUND", "message": "The original settled Pix payment was not found for this charge. Check the charge and its payment method before requesting a refund." }, "refundable_amount_cents": 0, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "account_not_ready": { "summary": "Conta sem condição de devolver o Pix", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY", "message": "This account is not ready to make a Pix refund. Contact Raims support to check the account." }, "refundable_amount_cents": 10000, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "pending": { "summary": "Devolução anterior aguardando resultado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_IN_PROGRESS", "message": "A refund, payment return, or dispute review is already in progress for this charge. Check its refunds and disputes before submitting another request." }, "refundable_amount_cents": 7500, "pending_amount_cents": 2500, "max_refund_amount_cents": 0 } }, "completed": { "summary": "Todo o valor já foi devolvido", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_ALREADY_COMPLETED", "message": "This charge has no remaining refundable amount. Check refund_eligibility and the charge's refunds before submitting another request." }, "refundable_amount_cents": 0, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "insufficient_balance": { "summary": "Saldo disponível insuficiente", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_INSUFFICIENT_BALANCE", "message": "The account has insufficient available balance for this refund. Retrieve refund_eligibility and check max_refund_amount_cents before trying again." }, "refundable_amount_cents": 10000, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "service_unavailable": { "summary": "Processamento temporariamente indisponível", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": false, "reason": { "code": "PIX_REFUND_PROVIDER_UNAVAILABLE", "message": "Refund processing is temporarily unavailable. Retrieve the charge's refunds before trying again." }, "refundable_amount_cents": 10000, "pending_amount_cents": 0, "max_refund_amount_cents": 0 } }, "limited_available_amount": { "summary": "Restante de R$ 100,00 com máximo disponível de R$ 40,00", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": true, "reason": null, "refundable_amount_cents": 10000, "pending_amount_cents": 0, "max_refund_amount_cents": 4000 } }, "sandbox_eligible": { "summary": "Pagamento Pix simulado elegível no Sandbox", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "eligible": true, "reason": null, "refundable_amount_cents": 10000, "pending_amount_cents": 0, "max_refund_amount_cents": 10000 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." } }, "description": "Condições atuais para solicitar a devolução. max_refund_amount_cents informa o limite disponível agora, sem reservar dinheiro. Eligible true não garante um pedido posterior: o valor e as condições serão conferidos no envio." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo ou parâmetro inválido. Confira error.details e corrija os dados indicados antes de tentar novamente." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Estornos" ], "summary": "Consultar elegibilidade para estorno", "description": "Consulta se uma cobrança aceita um pedido de devolução, o valor restante, o máximo disponível para solicitar agora e os valores pendentes. As condições são conferidas novamente ao solicitar o estorno." } }, "/v1/charges/statistics": { "get": { "operationId": "GetChargeStatistics", "x-raims-api-key-permission": { "code": "charges_read", "resource": "charges", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "today", "last_7_days", "last_15_days", "last_30_days" ], "default": "today", "example": "last_7_days" }, "description": "Período da consulta, pelo calendário de São Paulo. today considera hoje; last_7_days, last_15_days e last_30_days incluem hoje e os dias anteriores. A consulta aceita somente esses períodos. start_at e end_at são campos da resposta, não filtros de datas personalizadas." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeStatistics" }, "examples": { "last_7_days": { "summary": "Cobranças e recebimentos dos últimos 7 dias", "value": { "period": "last_7_days", "start_at": 1791428400, "end_at": 1792033200, "issued": { "count": 120, "amount_cents": 2400000 }, "issued_paid": { "count": 90, "amount_cents": 1800000 }, "received": { "count": 95, "amount_cents": 1900000 }, "payment_rate": 75, "updated_at": 1791990000 } }, "no_records": { "summary": "Período sem registros", "value": { "period": "last_7_days", "start_at": 1791428400, "end_at": 1792033200, "issued": { "count": 0, "amount_cents": 0 }, "issued_paid": { "count": 0, "amount_cents": 0 }, "received": { "count": 0, "amount_cents": 0 }, "payment_rate": 0, "updated_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "As estatísticas da conta não devem ser armazenadas em cache." } }, "description": "Estatísticas do período solicitado. Os valores são brutos, sem descontar tarifas ou devoluções, e não representam o saldo disponível. Uma consulta sem registros retorna quantidades e valores iguais a zero." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_period": { "summary": "Período não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "period", "code": "INVALID_VALUE", "message": "period must be one of: today, last_7_days, last_15_days, last_30_days." } ] } } }, "unsupported_date": { "summary": "Data personalizada não aceita", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "start_at", "code": "UNKNOWN_QUERY_PARAMETER", "message": "start_at is not a supported query parameter. Remove it from the request URL." } ] } } }, "duplicate_period": { "summary": "Período informado mais de uma vez", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "period", "code": "DUPLICATE_FIELD", "message": "period must be provided only once." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O período não foi aceito ou a URL contém um parâmetro inválido. Confira error.details para identificar o campo e o motivo." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Cobranças" ], "summary": "Consultar estatísticas de cobranças", "description": "Consulte quantidades, valores e taxa de pagamento das cobranças para acompanhar seus recebimentos no ERP ou sistema de gestão. A consulta considera a empresa e o ambiente autenticado. Os dados podem levar alguns segundos para refletir alterações nas cobranças." } }, "/v1/accounts/checkout_settings/logo_uploads": { "post": { "operationId": "CreateCheckoutLogoUpload", "x-raims-api-key-permission": { "code": "checkout_assets_upload", "resource": "accounts", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutLogoUploadRequest" }, "examples": { "image": { "summary": "Dados da imagem", "value": { "content_type": "image/png", "file_size": 12345, "width": 512, "height": 128 } } } } }, "description": "Dados do arquivo que será enviado. Os bytes devem corresponder ao tipo, tamanho e dimensões informados." }, "x-raims-max-body-bytes": 16384, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAssetUpload" }, "examples": { "upload": { "summary": "URL temporária e condições de envio", "value": { "id": "cau_3AbHiWSrsZBoaTg47OcMzC", "upload_url": "https://uploads.example.com/checkout/logo?signature=example", "method": "PUT", "content_type": "image/png", "file_size": 12345, "expires_at": 1792186200 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A autorização de envio não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Envio autorizado até o prazo retornado. Envie o arquivo para upload_url antes de associar o ID à personalização do checkout." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_image_type": { "summary": "Formato de imagem não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "content_type", "code": "INVALID_IMAGE_TYPE", "message": "content_type must be image/png or image/jpeg." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Os dados da imagem não atendem aos formatos, tamanhos ou dimensões aceitos. Corrija os campos indicados nos detalhes." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "account_not_found": { "summary": "Conta não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The account specified by API key was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A conta não foi encontrada para a chave informada. Confira a credencial antes de repetir a requisição." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Preparar envio da logo", "description": "Obtenha uma URL temporária para enviar a imagem. Depois do envio dos bytes, associe o ID retornado à personalização do checkout. A preparação não altera a imagem atual." } }, "/v1/accounts/checkout_settings/favicon_uploads": { "post": { "operationId": "CreateCheckoutFaviconUpload", "x-raims-api-key-permission": { "code": "checkout_assets_upload", "resource": "accounts", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutFaviconUploadRequest" }, "examples": { "image": { "summary": "Dados da imagem", "value": { "content_type": "image/png", "file_size": 4567, "width": 128, "height": 128 } } } } }, "description": "Dados do arquivo que será enviado. Os bytes devem corresponder ao tipo, tamanho e dimensões informados." }, "x-raims-max-body-bytes": 16384, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAssetUpload" }, "examples": { "upload": { "summary": "URL temporária e condições de envio", "value": { "id": "cau_1AbXiWSrsCBoaTg47OcMzC", "upload_url": "https://uploads.example.com/checkout/favicon?signature=example", "method": "PUT", "content_type": "image/png", "file_size": 4567, "expires_at": 1792186200 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A autorização de envio não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Envio autorizado até o prazo retornado. Envie o arquivo para upload_url antes de associar o ID à personalização do checkout." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_image_type": { "summary": "Formato de imagem não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "content_type", "code": "INVALID_IMAGE_TYPE", "message": "content_type must be image/png or image/jpeg." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Os dados da imagem não atendem aos formatos, tamanhos ou dimensões aceitos. Corrija os campos indicados nos detalhes." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "account_not_found": { "summary": "Conta não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The account specified by API key was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A conta não foi encontrada para a chave informada. Confira a credencial antes de repetir a requisição." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Preparar envio do ícone", "description": "Obtenha uma URL temporária para enviar a imagem. Depois do envio dos bytes, associe o ID retornado à personalização do checkout. A preparação não altera a imagem atual." } }, "/v1/accounts/checkout_settings/uploads/{id}": { "delete": { "operationId": "DeleteCheckoutAssetUpload", "x-raims-api-key-permission": { "code": "checkout_assets_delete", "resource": "accounts", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cau_[A-Za-z0-9]+$", "maxLength": 26, "example": "cau_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador recebido ao preparar o envio da imagem." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutAssetUploadDeleted" }, "examples": { "discarded": { "summary": "Envio descartado", "value": { "id": "cau_3AbHiWSrsZBoaTg47OcMzC", "deleted": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado do descarte não deve ser armazenado em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "O envio foi descartado e não pode mais ser aplicado. Repetir a requisição para o mesmo envio já descartado mantém este resultado. Imagens já associadas ao checkout são removidas pelo PATCH da personalização." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador de envio inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHECKOUT_ASSET_UPLOAD_IDENTIFIER", "message": "Use the id returned when preparing the checkout image upload." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador é inválido, ou a requisição contém corpo ou parâmetros de consulta. Corrija os dados indicados nos detalhes." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Envio não encontrado", "value": { "error": { "code": "NOT_FOUND", "message": "The checkout image upload specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O envio de imagem não foi encontrado para a empresa e o ambiente da chave. Confira o identificador recebido na preparação." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "already_used": { "summary": "Envio já utilizado", "value": { "error": { "code": "CHECKOUT_ASSET_UPLOAD_ALREADY_USED", "message": "This upload is already being applied or has finished processing. To remove the checkout image, use PATCH with null in logo_upload_id or favicon_upload_id." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O envio já foi associado ao checkout e não pode ser descartado por este endpoint. Use a atualização da personalização para remover a imagem, quando necessário." }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Descartar envio de imagem", "description": "Descarte um envio de logo ou ícone que ainda não foi associado ao checkout. Um envio expirado também pode ser descartado. Para remover uma imagem já aplicada, use o PATCH da personalização." } }, "/v1/accounts/checkout_settings": { "get": { "operationId": "GetCheckoutSettings", "x-raims-api-key-permission": { "code": "checkout_read", "resource": "accounts", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettings" }, "examples": { "checkout_settings": { "summary": "Cores e contato de suporte configurados", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": null, "status": "absent", "error_code": null }, "favicon": { "url": null, "status": "absent", "error_code": null } } }, "without_support_email": { "summary": "Sem contato de suporte", "value": { "support_email": null, "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": null, "status": "absent", "error_code": null }, "favicon": { "url": null, "status": "absent", "error_code": null } } }, "images_ready": { "summary": "Logo e ícone disponíveis", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": "https://images.example.com/checkout/logo.png", "status": "ready", "error_code": null }, "favicon": { "url": "https://images.example.com/checkout/favicon.png", "status": "ready", "error_code": null } } }, "image_pending": { "summary": "Troca de logo ainda em processamento", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": "https://images.example.com/checkout/previous-logo.png", "status": "pending", "error_code": null }, "favicon": { "url": null, "status": "absent", "error_code": null } } }, "image_failed": { "summary": "Imagem inválida com a logo anterior preservada", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": "https://images.example.com/checkout/previous-logo.png", "status": "failed", "error_code": "CHECKOUT_ASSET_INVALID_IMAGE" }, "favicon": { "url": null, "status": "absent", "error_code": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Configuração atual do checkout no ambiente autenticado. Os meios de pagamento são somente para consulta. As imagens informam o endereço atual e o resultado da última alteração." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown_query": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "company_id", "code": "UNKNOWN_QUERY_PARAMETER", "message": "company_id is not a supported query parameter. Remove it from the request URL." } ] } } }, "body_not_allowed": { "summary": "Corpo não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Esta consulta não aceita corpo nem parâmetros de consulta. Remova os dados indicados nos detalhes do erro." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Configuração não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The checkout settings for this account were not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A configuração da conta não foi encontrada para a consulta. Confira o acesso à empresa antes de repetir a requisição." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Consultar personalização do checkout", "description": "Consulte as imagens, as cores, o e-mail de suporte e os meios de pagamento padrão do checkout da empresa no ambiente autenticado." }, "patch": { "operationId": "UpdateCheckoutSettings", "x-raims-api-key-permission": { "code": "checkout_update", "resource": "accounts", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCheckoutSettingsRequest" }, "examples": { "update_appearance": { "summary": "Alterar cores e contato de suporte", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF" } }, "remove_support_email": { "summary": "Remover o contato de suporte", "value": { "support_email": null } }, "apply_images": { "summary": "Associar os arquivos enviados", "value": { "logo_upload_id": "cau_3AbHiWSrsZBoaTg47OcMzC", "favicon_upload_id": "cau_1AbXiWSrsCBoaTg47OcMzC" } }, "remove_logo": { "summary": "Remover somente a logo", "value": { "logo_upload_id": null } } } } }, "description": "Campos da personalização que devem ser alterados. Omitir preserva o valor atual. Em logo_upload_id e favicon_upload_id, null remove a imagem correspondente." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettings" }, "examples": { "checkout_settings": { "summary": "Cores e contato de suporte configurados", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": null, "status": "absent", "error_code": null }, "favicon": { "url": null, "status": "absent", "error_code": null } } }, "without_support_email": { "summary": "Sem contato de suporte", "value": { "support_email": null, "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": null, "status": "absent", "error_code": null }, "favicon": { "url": null, "status": "absent", "error_code": null } } }, "images_ready": { "summary": "Logo e ícone disponíveis", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": "https://images.example.com/checkout/logo.png", "status": "ready", "error_code": null }, "favicon": { "url": "https://images.example.com/checkout/favicon.png", "status": "ready", "error_code": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Configuração atual do checkout no ambiente autenticado. Os meios de pagamento são somente para consulta. As imagens informam o endereço atual e o resultado da última alteração." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettings" }, "examples": { "image_pending": { "summary": "Logo enviada em processamento", "value": { "support_email": "suporte@example.com", "hex_primary_color": "#FF6D00", "hex_secondary_color": "#FFFFFF", "payment_method_types": [ 1, 2 ], "logo": { "url": "https://images.example.com/checkout/previous-logo.png", "status": "pending", "error_code": null }, "favicon": { "url": null, "status": "absent", "error_code": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "A configuração foi recebida, e ao menos uma imagem ainda está em processamento. Consulte a personalização até a imagem estar pronta ou a resposta indicar falha. A imagem anterior continua em uso enquanto a troca não for concluída." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_color": { "summary": "Cor fora do formato hexadecimal", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "hex_primary_color", "code": "INVALID_HEX", "message": "hex_primary_color must use the #RRGGBB format with six hexadecimal digits." } ] } } }, "invalid_email": { "summary": "E-mail de suporte inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "support_email", "code": "INVALID_EMAIL", "message": "support_email must contain a valid email address." } ] } } }, "read_only_payment_methods": { "summary": "Meios de pagamento não são editados por esta requisição", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method_types", "code": "UNKNOWN_FIELD", "message": "payment_method_types is not a supported field. Remove it from the request body." } ] } } }, "invalid_upload_id": { "summary": "Identificador de envio inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "logo_upload_id", "code": "INVALID_CHECKOUT_ASSET_UPLOAD_IDENTIFIER", "message": "Use the id returned when preparing this image upload, or null to remove the image." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O corpo contém um campo desconhecido, um e-mail inválido, uma cor fora do formato ou um identificador de envio inválido. Corrija os campos indicados nos detalhes." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Configuração não encontrada", "value": { "error": { "code": "NOT_FOUND", "message": "The checkout settings for this account were not found." } } }, "upload_not_found": { "summary": "Envio de logo não encontrado neste escopo", "value": { "error": { "code": "NOT_FOUND", "message": "A referenced resource was not found.", "details": [ { "field": "logo_upload_id", "code": "NOT_FOUND", "message": "The checkout image upload specified by logo_upload_id was not found." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A configuração ou um envio de imagem não foi encontrado para a empresa e o ambiente da chave. Use um identificador do tipo correto, recebido ao preparar o envio." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "upload_expired": { "summary": "Prazo do envio expirado", "value": { "error": { "code": "CHECKOUT_ASSET_UPLOAD_EXPIRED", "message": "This image upload has expired. Prepare a new upload and send the file again." } } }, "file_not_uploaded": { "summary": "Arquivo não enviado", "value": { "error": { "code": "CHECKOUT_ASSET_UPLOAD_NOT_FOUND", "message": "The file has not been uploaded or is no longer available. Send it using the upload URL before updating the checkout." } } }, "file_mismatch": { "summary": "Arquivo diferente dos dados informados", "value": { "error": { "code": "CHECKOUT_ASSET_UPLOAD_MISMATCH", "message": "The uploaded file does not match its declared type, size or dimensions. Prepare a new upload with the correct image metadata." } } }, "upload_already_used": { "summary": "Envio já aplicado ou substituído", "value": { "error": { "code": "CHECKOUT_ASSET_UPLOAD_ALREADY_USED", "message": "This upload has already been applied or replaced. Prepare a new upload to change the image again." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O envio ainda não pode ser aplicado, expirou ou já foi substituído. Confira error.code antes de corrigir o envio; um novo arquivo exige uma nova autorização." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações e personalização da conta" ], "summary": "Atualizar personalização do checkout", "description": "Altere as imagens, as cores e o e-mail de suporte do checkout. Campos omitidos preservam o valor atual. O envio de uma nova imagem pode exigir acompanhamento até sua aplicação." } }, "/v1/disputes/{id}": { "get": { "operationId": "GetDispute", "x-raims-api-key-permission": { "code": "disputes_read", "resource": "disputes", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?:dp_[A-Za-z0-9]+|med_[1-9][0-9]*)$", "maxLength": 100, "example": "med_123" }, "description": "Identificador completo da contestação retornado pela listagem, com prefixo dp_ ou med_." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" }, "examples": { "med_in_analysis": { "summary": "Caso MED em análise", "value": { "id": "med_123", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "kind": "med", "stage": "in_analysis", "reason_code": 1, "disputed_amount_cents": 10000, "created_at": 1791878400, "updated_at": 1791964800, "opened_at": 1791878400, "due_at": null, "complaint_details": "Pagador informou não reconhecer o pagamento.", "company_response": null, "responded_at": null, "resolved_at": null, "won_amount_cents": null, "lost_amount_cents": null, "refunded_amount_cents": null, "infraction_result": null, "refund_result": null, "loss_reason_code": null, "loss_reason_note": null } }, "med_analysis_closed": { "summary": "Análise encerrada sem devolução confirmada", "value": { "id": "med_123", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "kind": "med", "stage": "closed", "reason_code": 1, "disputed_amount_cents": 10000, "created_at": 1791878400, "updated_at": 1792051200, "opened_at": 1791878400, "due_at": null, "complaint_details": "Pagador informou não reconhecer o pagamento.", "company_response": null, "responded_at": null, "resolved_at": null, "won_amount_cents": null, "lost_amount_cents": null, "refunded_amount_cents": null, "infraction_result": "agreed", "refund_result": "partially_accepted", "loss_reason_code": null, "loss_reason_note": null } }, "med_refund_confirmed": { "summary": "Caso MED com devolução parcial confirmada", "value": { "id": "med_123", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "kind": "med", "stage": "closed", "reason_code": 1, "disputed_amount_cents": 10000, "created_at": 1791878400, "updated_at": 1792051380, "opened_at": 1791878400, "due_at": null, "complaint_details": "Pagador informou não reconhecer o pagamento.", "company_response": null, "responded_at": null, "resolved_at": null, "won_amount_cents": null, "lost_amount_cents": null, "refunded_amount_cents": 2500, "infraction_result": "agreed", "refund_result": "partially_accepted", "loss_reason_code": null, "loss_reason_note": null } }, "chargeback_closed": { "summary": "Contestação com resultado disponível", "value": { "id": "dp_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "kind": "chargeback", "stage": "closed", "reason_code": 2, "disputed_amount_cents": 10000, "created_at": 1791878400, "updated_at": 1791964800, "opened_at": 1791878400, "due_at": 1791964800, "complaint_details": null, "company_response": "Comprovante de entrega apresentado.", "responded_at": 1791882000, "resolved_at": 1791964800, "won_amount_cents": 10000, "lost_amount_cents": 0, "refunded_amount_cents": null, "infraction_result": null, "refund_result": null, "loss_reason_code": null, "loss_reason_note": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados de contestações não devem ser armazenados em cache." } }, "description": "Detalhes do caso e resultados disponíveis. Campos não aplicáveis ao tipo de contestação ou sem resultado disponível ficam null. A etapa closed não confirma, sozinha, decisão favorável nem devolução financeira." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_identifier": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_DISPUTE_IDENTIFIER", "message": "id must be a valid dispute identifier returned by the API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da contestação é inválido. Use o id completo retornado pela listagem." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The dispute specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Contestação não encontrada na empresa e no ambiente autenticado. A resposta também é usada quando o caso não está disponível para a autenticação utilizada." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Contestações" ], "summary": "Recuperar uma contestação", "description": "Consulta a etapa, os motivos e os resultados disponíveis de uma contestação da empresa e do ambiente autenticado." } }, "/v1/disputes": { "get": { "operationId": "ListDisputes", "x-raims-api-key-permission": { "code": "disputes_read", "resource": "disputes", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "example": 10 }, "description": "Quantidade de contestações por página. Valores inválidos usam o padrão; valores acima do máximo usam o limite." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor de page.next_after da resposta anterior. Preserve os filtros e a ordenação; não envie junto de before." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor de page.previous_before para voltar. Preserve os filtros e a ordenação; não envie junto de after." }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256, "example": "in_analysis,refund_in_analysis" }, "description": "Etapas do caso separadas por vírgula: open, in_analysis, refund_in_analysis, closed, cancelled, rejected ou failed. Closed informa análise encerrada, sem confirmar decisão favorável ou devolução." }, { "name": "charge_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Filtra pela cobrança vinculada, usando o identificador público completo. Um ID válido sem casos acessíveis retorna uma lista vazia." }, { "name": "disputed_amount_cents", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "example": 10000 }, "description": "Filtra pelo valor contestado exato, em centavos de real. Não representa o valor atualmente bloqueado." }, { "name": "created_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 253402300799, "example": 1791878400 }, "description": "Inclui contestações criadas a partir deste instante, em segundos Unix UTC. O limite é inclusivo." }, { "name": "created_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 253402300799, "example": 1791964800 }, "description": "Inclui contestações criadas até este instante, em segundos Unix UTC. O limite é inclusivo e deve ser igual ou posterior a created_gte." }, { "name": "sort_key", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created_at", "disputed_amount_cents" ], "default": "created_at", "example": "created_at" }, "description": "Campo usado para ordenar a lista: criação ou valor contestado." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "desc" }, "description": "Ordem crescente ou decrescente do campo selecionado." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeListResponse" }, "examples": { "cases": { "summary": "Contestações retornadas na consulta", "value": { "list": [ { "id": "med_123", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "kind": "med", "stage": "in_analysis", "reason_code": 1, "disputed_amount_cents": 10000, "created_at": 1791878400, "updated_at": 1791964800 }, { "id": "dp_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "kind": "chargeback", "stage": "closed", "reason_code": 2, "disputed_amount_cents": 10000, "created_at": 1791878400, "updated_at": 1791964800 } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "empty": { "summary": "Consulta sem resultados", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados de contestações não devem ser armazenados em cache." } }, "description": "Página das contestações que correspondem aos filtros. A ordem usa o campo e a direção solicitados. Uma lista vazia informa que a página não contém resultados." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_stage": { "summary": "Etapa inválida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "stage", "code": "INVALID_VALUE", "message": "stage must contain one or more of these values, separated by commas: open, in_analysis, refund_in_analysis, closed, cancelled, rejected, failed." } ] } } }, "invalid_amount": { "summary": "Valor contestado inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "disputed_amount_cents", "code": "OUT_OF_RANGE", "message": "disputed_amount_cents must be an integer between 0 and 9223372036854775807 cents, inclusive." } ] } } }, "invalid_date": { "summary": "Data inválida", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "created_gte", "code": "INVALID_UNIX_TIMESTAMP", "message": "created_gte must be an integer Unix timestamp in seconds between 1 and 253402300799, inclusive. Do not send milliseconds or a formatted date." } ] } } }, "invalid_date_range": { "summary": "Intervalo de criação invertido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "created_lte", "code": "OUT_OF_RANGE", "message": "created_lte must be greater than or equal to created_gte." } ] } } }, "conflicting_cursors": { "summary": "Cursores enviados juntos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after and before cannot be provided together." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "after and before cannot be provided together." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um filtro ou cursor é inválido. Corrija os campos indicados em error.details antes de repetir. After e before preenchidos juntos não são aceitos." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Contestações" ], "summary": "Listar contestações", "description": "Consulta as contestações da empresa e do ambiente autenticado, com filtros e paginação por cursor." } }, "/v1/payment_links/{id}/send_email": { "post": { "operationId": "SendPaymentLinkEmail", "x-raims-api-key-permission": { "code": "payment_links_send", "resource": "payment_links", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pl_[A-Za-z0-9]+$", "maxLength": 100, "example": "pl_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público do link a enviar, recebido na criação ou na listagem." } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkEmailRequestAccepted" }, "examples": { "accepted": { "summary": "Pedido de envio registrado", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "recipient_email": "cliente@example.com", "retry_after_seconds": 60, "retry_after_until": 1791936060 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Pedido de envio registrado. O destinatário e o prazo para novo envio são informados na resposta; a entrega do e-mail não está confirmada." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador de link inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_PAYMENT_LINK_IDENTIFIER", "message": "id must contain a valid public payment link ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo de requisição não permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } }, "invalid_recipient": { "summary": "E-mail do destinatário inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "The payment link specified by id does not have a valid recipient email. Check the payer email associated with the linked charge before trying again." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Identificador inválido, corpo não permitido ou e-mail do destinatário inválido. Para falhas na requisição, confira os detalhes; para e-mail inválido, confira o endereço associado à cobrança." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "pending_recipient_restricted": { "summary": "Destinatário restrito ao titular", "value": { "error": { "code": "PENDING_COMPANY_RECIPIENT_RESTRICTED", "message": "The payment link specified by id has a recipient email that differs from the account's primary email. A pending company can only send to its primary email." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A chave ou a empresa não pode solicitar o envio. Para empresa com cadastro pendente, o destinatário precisa ser o e-mail do titular." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The payment link specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Link não encontrado na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_payable": { "summary": "Cobrança indisponível para envio do link", "value": { "error": { "code": "CHARGE_NOT_PAYABLE_FOR_PAYMENT_LINK", "message": "The charge has status 4 (paid). To send the payment link by email, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." } } }, "payment_link_paused": { "summary": "Envio impedido por link pausado", "value": { "error": { "code": "PAYMENT_LINK_PAUSED", "message": "The payment link specified by id is paused. Reactivate it before requesting its email." } } }, "charge_expired": { "summary": "Vencimento da cobrança ultrapassado", "value": { "error": { "code": "CHARGE_NOT_PAYABLE_FOR_PAYMENT_LINK", "message": "The charge has status 8 (expired). Its due_date is 1767225600 (Unix seconds UTC). To send the payment link by email, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A mensagem identifica se o impedimento é o estado da cobrança, seu vencimento ou a pausa do link. Quando o estado impede a ação, informa o estado atual e os aceitos. Consulte a cobrança vinculada antes de tentar novamente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "resend_rate_limited": { "summary": "Aguarde o prazo de reenvio", "value": { "error": { "code": "CHARGE_PAYMENT_LINK_RESEND_RATE_LIMITED", "message": "The email for the payment link specified by id was recently requested. Wait for Retry-After before trying again." } } }, "api_rate_limited": { "summary": "Limite geral da API atingido", "value": { "error": { "code": "RATE_LIMITED", "message": "The API request limit was exceeded. Wait for Retry-After and reduce the request rate or the number of concurrent requests." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Tempo, em segundos, que deve ser aguardado antes de tentar novamente." }, "Raims-Rate-Limited-Reason": { "schema": { "type": "string", "enum": [ "global-rate", "endpoint-rate", "global-concurrency", "endpoint-concurrency", "resource-specific" ] }, "description": "Motivo do limite da API, ou resource-specific quando o intervalo entre reenvios ainda não terminou.", "example": "resource-specific" }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O limite da API ou o intervalo entre reenvios foi atingido. Aguarde Retry-After e confira Raims-Rate-Limited-Reason. O motivo resource-specific indica o intervalo próprio do reenvio de e-mail." }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable", "description": "Não foi possível confirmar o pedido de envio. Aguarde e tente novamente." } }, "tags": [ "Links de pagamentos" ], "summary": "Enviar link por e-mail", "description": "Solicita o envio ou reenvio do link ao destinatário da cobrança, sem criar outra cobrança ou alterar o checkout. A cobrança precisa estar aberta e dentro do vencimento. O intervalo mínimo de 60 segundos entre solicitações aceitas é compartilhado com a ação de reenvio do Dashboard. A resposta confirma o pedido de envio, não a entrega do e-mail. Sandbox também pode enviar e-mails reais. O link precisa estar ativo; a pausa impede o envio." } }, "/v1/payment_links": { "post": { "operationId": "CreatePaymentLink", "x-raims-api-key-permission": { "code": "payment_links_create", "resource": "payment_links", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkRequest" }, "examples": { "create": { "summary": "Obter link de uma cobrança", "value": { "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD" } }, "configure": { "summary": "Link com retorno ao site e Pix", "value": { "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "success_redirect_url": "https://loja.example.com/pedido/concluido", "cancel_redirect_url": "https://loja.example.com/pedido", "payment_method_types": [ 1 ] } } } } } }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "success": { "summary": "Link da cobrança", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Location": { "schema": { "type": "string" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Link e configurações atuais." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "success": { "summary": "Link da cobrança", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Location": { "schema": { "type": "string" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Link criado para a cobrança." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_charge": { "summary": "Cobrança não informada", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "charge_id", "code": "REQUIRED", "message": "charge_id is required." } ] } } }, "invalid_charge": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "charge_id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "charge_id must contain a valid public charge ID returned by this API." } ] } } }, "invalid_url": { "summary": "URL sem HTTPS", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "success_redirect_url", "code": "ERR_HTTPS_REQUIRED", "message": "success_redirect_url must use HTTPS." } ] } } }, "invalid_method": { "summary": "Meio de pagamento inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method_types", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types must be a nonempty list of supported payment methods without duplicates." }, { "field": "payment_method_types[0]", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types[0] must be 1 (Pix) or 2 (boleto)." } ] } } }, "duplicate_method": { "summary": "Meio de pagamento repetido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method_types", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types must be a nonempty list of supported payment methods without duplicates." }, { "field": "payment_method_types[1]", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types[1] duplicates an earlier item. Send each payment method only once." } ] } } }, "unknown_field": { "summary": "Campo da cobrança enviado ao link", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "title", "code": "UNKNOWN_FIELD", "message": "title is not a supported field. Remove it from the request body." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo do pedido é inválido. Confira em error.details o nome público do campo, o código e a correção indicada." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "A referenced resource was not found.", "details": [ { "field": "charge_id", "code": "NOT_FOUND", "message": "The charge specified by charge_id was not found." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_payable": { "summary": "Cobrança indisponível para configurar link", "value": { "error": { "code": "CHARGE_NOT_PAYABLE_FOR_PAYMENT_LINK", "message": "The charge has status 4 (paid). To configure a payment link, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." } } }, "in_progress": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } }, "charge_expired": { "summary": "Vencimento da cobrança ultrapassado", "value": { "error": { "code": "CHARGE_NOT_PAYABLE_FOR_PAYMENT_LINK", "message": "The charge has status 8 (expired). Its due_date is 1767225600 (Unix seconds UTC). To configure a payment link, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A mensagem identifica se o impedimento é o estado da cobrança, seu vencimento ou outra requisição em andamento. Quando o estado impede a ação, informa o estado atual e os aceitos. Consulte a cobrança vinculada antes de tentar novamente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Links de pagamentos" ], "summary": "Criar ou recuperar um link de pagamento", "description": "Cria o link de uma cobrança existente ou retorna o mesmo link quando ele já existe. Informe charge_id. Um link novo começa ativo; reutilizar um link pausado preserva a pausa. Título, valor, vencimento e cliente vêm da cobrança. Esta requisição não cria outra cobrança, não emite pagamentos e não solicita e-mail." }, "get": { "operationId": "ListPaymentLinks", "x-raims-api-key-permission": { "code": "payment_links_read", "resource": "payment_links", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Quantidade de links por página." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.next_after. Mantenha o mesmo filtro charge_id." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.previous_before. Não envie junto com after." }, { "name": "charge_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador da cobrança cujo link você quer consultar." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkListResponse" }, "examples": { "success": { "summary": "Página de links", "value": { "list": [ { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": true } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "description": "Página de links e suas configurações. Se nenhum link atender aos filtros, list será um array vazio." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_charge": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "charge_id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "charge_id must contain a valid public charge ID returned by this API." } ] } } }, "invalid_cursor": { "summary": "Cursor inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } }, "exclusive_cursors": { "summary": "Duas direções de paginação", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after cannot be used together with before." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "before cannot be used together with after." } ] } } }, "unknown_query": { "summary": "Filtro não reconhecido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "status", "code": "UNKNOWN_QUERY_PARAMETER", "message": "status is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um filtro ou cursor é inválido. Corrija os campos indicados em error.details. Para reiniciar a listagem, remova after e before." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Links de pagamentos" ], "summary": "Listar links de pagamento", "description": "Lista os links da empresa e do ambiente autenticado, pela ordem decrescente das cobranças vinculadas. Use charge_id para localizar o link de uma cobrança e page.next_after para continuar." } }, "/v1/payment_links/{id}": { "get": { "operationId": "GetPaymentLink", "x-raims-api-key-permission": { "code": "payment_links_read", "resource": "payment_links", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pl_[A-Za-z0-9]+$", "maxLength": 100, "example": "pl_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público do link, recebido na criação ou na listagem." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkDetails" }, "examples": { "success": { "summary": "Link disponível para pagamento", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_payable": true, "effective_payment_method_types": [ 1, 2 ], "unavailable_reason": null, "is_active": true } }, "boleto_awaiting_settlement": { "summary": "Boleto aguardando confirmação do pagamento", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_payable": false, "effective_payment_method_types": [ 2 ], "unavailable_reason": { "code": "BOLETO_AWAITING_SETTLEMENT", "message": "The boleto payment is awaiting settlement. Wait for the charge status to be updated." }, "is_active": true } }, "charge_expired": { "summary": "Cobrança expirada", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1767139200, "updated_at": 1767139200, "is_payable": false, "effective_payment_method_types": [ 1, 2 ], "unavailable_reason": { "code": "CHARGE_EXPIRED", "message": "The charge has status 8 (expired). Its due_date is 1767225600 (Unix seconds UTC). To accept a payment through this checkout, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." }, "is_active": true } }, "charge_not_open": { "summary": "Cobrança que não pode mais ser paga pelo link", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_payable": false, "effective_payment_method_types": [ 1, 2 ], "unavailable_reason": { "code": "CHARGE_NOT_OPEN", "message": "The charge has status 4 (paid). To accept a payment through this checkout, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." }, "is_active": true } }, "pix_cancellation_pending": { "summary": "Cancelamento do Pix aguardando confirmação", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_payable": false, "effective_payment_method_types": [], "unavailable_reason": { "code": "PIX_CANCELLATION_PENDING", "message": "Pix cancellation is awaiting confirmation. Retrieve the charge before trying another payment." }, "is_active": true } }, "pix_cancelled": { "summary": "QR Code Pix cancelado", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_payable": false, "effective_payment_method_types": [], "unavailable_reason": { "code": "PIX_CANCELLED", "message": "The Pix QR code was cancelled and this checkout no longer accepts payments." }, "is_active": true } }, "payment_methods_unavailable": { "summary": "Checkout sem meios de pagamento habilitados", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": [], "created_at": 1791936000, "updated_at": 1791936000, "is_payable": false, "effective_payment_method_types": [], "unavailable_reason": { "code": "PAYMENT_METHODS_UNAVAILABLE", "message": "No payment methods are enabled for this checkout. Review the charge and payment link configuration." }, "is_active": true } }, "payment_link_paused": { "summary": "Link pausado com meios configurados", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_payable": false, "effective_payment_method_types": [ 1, 2 ], "unavailable_reason": { "code": "PAYMENT_LINK_PAUSED", "message": "The payment link is paused. Reactivate it before accepting new payments through this checkout." }, "is_active": false } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "description": "Link encontrado. Confira is_payable para saber se a cobrança ainda pode ser paga por ele. Links pausados e links de cobranças pagas, revogadas ou vencidas continuam consultáveis e retornam 200." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador do link inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_PAYMENT_LINK_IDENTIFIER", "message": "id must contain a valid public payment link ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador do link ou um parâmetro da requisição é inválido. Confira error.details e use o id retornado na criação ou na listagem." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The payment link specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Link não encontrado na empresa e no ambiente autenticado." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Links de pagamentos" ], "summary": "Recuperar um link de pagamento", "description": "Consulta a URL, a configuração e a disponibilidade atual do link. is_active informa se o link está ativo; is_payable indica se o checkout pode receber pagamento neste momento. O link precisa pertencer à empresa e ao ambiente autenticado. Para valor, vencimento, cliente e status financeiro, use GET /v1/charges/{charge_id}." }, "patch": { "operationId": "UpdatePaymentLink", "x-raims-api-key-permission": { "code": "payment_links_update", "resource": "payment_links", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^pl_[A-Za-z0-9]+$", "maxLength": 100, "example": "pl_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público do link, recebido na criação ou na listagem." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentLinkRequest" }, "examples": { "configure": { "summary": "Alterar retorno e restringir a Pix", "value": { "success_redirect_url": "https://loja.example.com/pedido/concluido", "payment_method_types": [ 1 ] } }, "inherit": { "summary": "Remover a configuração própria dos meios", "value": { "payment_method_types": null } }, "clear_success": { "summary": "Remover o retorno após pagamento", "value": { "clear_success_redirect_url": true } }, "clear_cancel": { "summary": "Remover o destino de voltar ao site", "value": { "clear_cancel_redirect_url": true } }, "clear_both": { "summary": "Remover os dois destinos de retorno", "value": { "clear_success_redirect_url": true, "clear_cancel_redirect_url": true } }, "clear_and_update": { "summary": "Remover um destino e alterar o outro", "value": { "clear_success_redirect_url": true, "cancel_redirect_url": "https://loja.example.com/pedido" } }, "pause": { "summary": "Pausar o checkout", "value": { "is_active": false } }, "reactivate": { "summary": "Reativar o mesmo link", "value": { "is_active": true } } } } } }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "success": { "summary": "Link da cobrança", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": true } }, "redirects_cleared": { "summary": "Destinos de retorno removidos", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": true } }, "paused": { "summary": "Link pausado", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": false } }, "reactivated": { "summary": "Link reativado com a mesma URL", "value": { "id": "pl_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "url": "https://checkout.example.com/EXAMPLE_ONLY", "success_redirect_url": null, "cancel_redirect_url": null, "payment_method_types": null, "created_at": 1791936000, "updated_at": 1791936000, "is_active": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Link e configurações atuais." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador do link inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_PAYMENT_LINK_IDENTIFIER", "message": "id must contain a valid public payment link ID returned by this API." } ] } } }, "invalid_url": { "summary": "URL sem HTTPS", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "success_redirect_url", "code": "ERR_HTTPS_REQUIRED", "message": "success_redirect_url must use HTTPS." } ] } } }, "invalid_method": { "summary": "Meio de pagamento inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method_types", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types must be a nonempty list of supported payment methods without duplicates." }, { "field": "payment_method_types[0]", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types[0] must be 1 (Pix) or 2 (boleto)." } ] } } }, "duplicate_method": { "summary": "Meio de pagamento repetido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method_types", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types must be a nonempty list of supported payment methods without duplicates." }, { "field": "payment_method_types[1]", "code": "INVALID_PAYMENT_METHOD_TYPES", "message": "payment_method_types[1] duplicates an earlier item. Send each payment method only once." } ] } } }, "unknown_field": { "summary": "Campo da cobrança enviado ao link", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "title", "code": "UNKNOWN_FIELD", "message": "title is not a supported field. Remove it from the request body." } ] } } }, "conflicting_success_redirect": { "summary": "URL de sucesso e limpeza simultâneas", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "success_redirect_url", "code": "MUTUALLY_EXCLUSIVE", "message": "success_redirect_url cannot contain a URL when clear_success_redirect_url is true." }, { "field": "clear_success_redirect_url", "code": "MUTUALLY_EXCLUSIVE", "message": "clear_success_redirect_url cannot be true when success_redirect_url contains a URL." } ] } } }, "conflicting_cancel_redirect": { "summary": "URL de cancelamento e limpeza simultâneas", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "cancel_redirect_url", "code": "MUTUALLY_EXCLUSIVE", "message": "cancel_redirect_url cannot contain a URL when clear_cancel_redirect_url is true." }, { "field": "clear_cancel_redirect_url", "code": "MUTUALLY_EXCLUSIVE", "message": "clear_cancel_redirect_url cannot be true when cancel_redirect_url contains a URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador ou um campo de configuração é inválido. Confira error.details. Não envie uma URL preenchida junto do seu comando de limpeza com true." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The payment link specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Link não encontrado na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_payable": { "summary": "Cobrança indisponível para configurar link", "value": { "error": { "code": "CHARGE_NOT_PAYABLE_FOR_PAYMENT_LINK", "message": "The charge has status 4 (paid). To configure a payment link, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." } } }, "in_progress": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } }, "charge_expired": { "summary": "Vencimento da cobrança ultrapassado", "value": { "error": { "code": "CHARGE_NOT_PAYABLE_FOR_PAYMENT_LINK", "message": "The charge has status 8 (expired). Its due_date is 1767225600 (Unix seconds UTC). To configure a payment link, the charge must have status 0 (created) or 1 (pending) or 2 (authorized) or 3 (processing) and be within its due date." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A mensagem identifica se o impedimento é o estado da cobrança, seu vencimento ou outra requisição em andamento. Quando o estado impede a ação, informa o estado atual e os aceitos. Consulte a cobrança vinculada antes de tentar novamente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Links de pagamentos" ], "summary": "Atualizar um link de pagamento", "description": "Atualiza as URLs de retorno, os meios de pagamento e a pausa do link. Envie is_active false para pausar e true para reativar a mesma URL; omitir preserva o estado. A pausa bloqueia novas ações no checkout e novos pedidos de envio por e-mail, sem cancelar Pix ou boleto emitidos nem prorrogar o vencimento. A cobrança precisa estar aberta e dentro do vencimento. Use clear_success_redirect_url ou clear_cancel_redirect_url com true para remover o respectivo destino." } }, "/v1/refunds/{id}/receipt": { "get": { "operationId": "GetRefundReceipt", "x-raims-api-key-permission": { "code": "refunds_read", "resource": "refunds", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rf_[A-Za-z0-9]+$", "maxLength": 100, "example": "rf_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público do estorno, recebido na solicitação ou na listagem de estornos." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialDocument" }, "example": { "url": "https://files.raims.com/documents/comprovante-estorno/exemplo.pdf?Expires=1792080180&Signature=EXEMPLO&Key-Pair-Id=EXEMPLO", "expires_at": 1792080180 } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta com a URL temporária não deve ser armazenada em cache." } }, "description": "URL temporária do comprovante do estorno indicado, sem somar outras devoluções da cobrança. Faça um GET no endereço retornado para baixar o PDF, sem enviar a chave de API. Comprovantes do Sandbox identificam a devolução simulada." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_REFUND_IDENTIFIER", "message": "id must contain a valid public refund ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador do estorno é inválido. Use o ID retornado pela API." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Estorno não encontrado", "value": { "error": { "code": "NOT_FOUND", "message": "The refund specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Estorno ou dados da cobrança original não encontrados na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "refund_not_completed": { "summary": "Estorno aguardando conclusão", "value": { "error": { "code": "REFUND_RECEIPT_NOT_AVAILABLE", "message": "A refund receipt is unavailable for refund status accepted. Status completed and a confirmed completion date are required. Retrieve the refund before trying again." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O estorno não está concluído ou não tem data de conclusão confirmada. Consulte o estorno antes de tentar baixar o comprovante novamente." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Estornos" ], "summary": "Baixar comprovante de estorno", "description": "Obtenha uma URL temporária para baixar o comprovante em PDF de um estorno concluído. O documento informa o ID, o valor e a data de conclusão desse estorno. Para cobranças com mais de uma devolução, consulte cada ID desejado. A solicitação precisa estar em completed, com a data de conclusão registrada. A requisição exige a chave de API da mesma empresa e ambiente. O documento é emitido pela Raims e não substitui nota fiscal nem comprovante bancário." } }, "/v1/refunds": { "get": { "operationId": "ListRefunds", "x-raims-api-key-permission": { "code": "refunds_read", "resource": "refunds", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Quantidade de estornos por página. Valores acima do máximo usam o máximo; ausência, vazio, texto, zero ou valor negativo usa o padrão." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.next_after para avançar nesta lista. Copie o valor completo. Não use um cursor da lista de uma cobrança nem envie junto de before." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.previous_before para voltar nesta lista. Copie o valor completo. Não use um cursor da lista de uma cobrança nem envie junto de after." }, { "name": "created_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1767225600 }, "description": "Filtra estornos solicitados a partir deste instante, inclusive, em segundos Unix UTC. Usa a data de criação da solicitação, sem depender da conclusão. Mantenha o valor ao mudar de página." }, { "name": "created_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "example": 1791936000 }, "description": "Filtra estornos solicitados até este instante, inclusive, em segundos Unix UTC. Se informar created_gte, este valor deve ser maior ou igual a ele." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundListResponse" }, "examples": { "history": { "summary": "Estornos de cobranças diferentes", "value": { "list": [ { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "accepted", "created_at": 1791964800, "completed_at": null, "failed_at": null, "failure_reason": null }, { "id": "rf_3AbHiWSrsZBoaTg47OcMzD", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzD", "amount_cents": 1000, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791878400, "completed_at": 1791878580, "failed_at": null, "failure_reason": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "empty": { "summary": "Sem devoluções solicitadas", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." } }, "description": "Página de solicitações de estorno da empresa e do ambiente autenticado. Uma lista vazia informa que não há solicitações nessa página." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_cursor": { "summary": "Cursor inválido para a listagem de estornos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } }, "conflicting_cursors": { "summary": "Cursores de avanço e retorno juntos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after cannot be used together with before." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "before cannot be used together with after." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um parâmetro de consulta inválido. Confira error.details e corrija os dados indicados antes de tentar novamente." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Estornos" ], "summary": "Listar estornos", "description": "Lista as solicitações de estorno das cobranças da empresa e do ambiente autenticado, das mais recentes para as mais antigas. Use a paginação para conciliar as devoluções sem consultar cada cobrança. A consulta não inicia nem repete estornos." } }, "/v1/refunds/{id}": { "get": { "operationId": "GetRefund", "x-raims-api-key-permission": { "code": "refunds_read", "resource": "refunds", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rf_[A-Za-z0-9]+$", "maxLength": 100, "example": "rf_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador do estorno recebido na solicitação ou no histórico de devoluções." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "accepted": { "summary": "Devolução aguardando confirmação", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "accepted", "created_at": 1791964800, "completed_at": null, "failed_at": null, "failure_reason": null } }, "completed": { "summary": "Devolução concluída", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791964800, "completed_at": 1791964980, "failed_at": null, "failure_reason": null } }, "failed": { "summary": "Devolução com falha confirmada", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "failed", "created_at": 1791964800, "completed_at": null, "failed_at": 1791964980, "failure_reason": { "code": "REFUND_PROCESSING_FAILED", "message": "The payment processor confirmed that this refund failed but did not provide a detailed reason. Check the charge's refunds before trying again." } } }, "unknown": { "summary": "Resultado ainda não confirmado", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "unknown", "created_at": 1791964800, "completed_at": null, "failed_at": null, "failure_reason": null } }, "not_submitted": { "summary": "Pedido não enviado para processamento", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "failed", "created_at": 1791964800, "completed_at": null, "failed_at": 1791964980, "failure_reason": { "code": "REFUND_NOT_SUBMITTED", "message": "This refund was not submitted. Check the charge's refunds before trying again." } } }, "rejected": { "summary": "Pedido recusado", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "failed", "created_at": 1791964800, "completed_at": null, "failed_at": 1791964980, "failure_reason": { "code": "REFUND_REJECTED", "message": "This refund was rejected. Check the charge's refunds before trying again." } } }, "processing_unavailable": { "summary": "Falha por indisponibilidade de processamento", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "failed", "created_at": 1791964800, "completed_at": null, "failed_at": 1791964980, "failure_reason": { "code": "REFUND_PROCESSING_UNAVAILABLE", "message": "Refund processing was unavailable and this refund failed. Check the charge's refunds before trying again." } } }, "failure_reason_unavailable": { "summary": "Falha sem causa confirmada disponível", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "failed", "created_at": 1791964800, "completed_at": null, "failed_at": 1791964980, "failure_reason": { "code": "REFUND_FAILURE_REASON_UNAVAILABLE", "message": "No confirmed failure reason is available for this refund. Check the charge's refunds and contact Raims support if needed." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." } }, "description": "Estado atual da solicitação. Datas de conclusão ou falha ficam null enquanto o respectivo resultado não estiver confirmado. Em failed, failure_reason informa a causa disponível; causas não registradas permanecem desconhecidas." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_REFUND_IDENTIFIER", "message": "id must contain a valid public refund ID returned by this API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo ou parâmetro inválido. Confira error.details e corrija os dados indicados antes de tentar novamente." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The refund specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Estorno não encontrado na empresa e no ambiente autenticado." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Estornos" ], "summary": "Recuperar um estorno", "description": "Consulta o estado, o valor, as datas e o motivo disponível de uma falha confirmada no estorno. A consulta não inicia nem repete a devolução." } }, "/v1/simulations/refunds/{id}/complete": { "post": { "operationId": "CompleteSimulationRefund", "x-raims-api-key-permission": { "code": "simulations_complete_refund", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rf_[A-Za-z0-9]+$", "maxLength": 100, "example": "rf_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador do estorno de teste retornado por Simular estorno pendente." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791964800, "completed_at": 1791964980, "failed_at": null, "failure_reason": null } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar a mesma solicitação de estorno." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Devolução de teste concluída ou mesma conclusão já registrada. Consulte o estorno e seu comprovante." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador do estorno inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_REFUND_IDENTIFIER", "message": "id must contain a valid public refund ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo enviado indevidamente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } }, "query_not_allowed": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "environment", "code": "UNKNOWN_QUERY_PARAMETER", "message": "environment is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador do estorno ou a requisição não é válido. Esta requisição não recebe corpo nem parâmetros de consulta. Confira os campos em error.details." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a refund created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Esta requisição aceita somente chave de API de Sandbox." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The refund specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O estorno não foi encontrado no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "REFUND_NOT_SIMULATABLE", "message": "The refund is currently failed. This simulation requires an accepted Sandbox refund, or a repeat of the same final result. Retrieve the refund before trying again." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "description": "O estorno não está pendente para este resultado. Confira o status atual; uma conclusão não pode ser trocada por falha, nem uma falha por conclusão." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Simulação" ], "summary": "Concluir estorno simulado", "description": "Conclua um estorno Pix pendente no Sandbox. O valor não é descontado novamente do saldo." } }, "/v1/simulations/refunds/{id}/fail": { "post": { "operationId": "FailSimulationRefund", "x-raims-api-key-permission": { "code": "simulations_fail_refund", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rf_[A-Za-z0-9]+$", "maxLength": 100, "example": "rf_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador do estorno de teste retornado por Simular estorno pendente." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "failed", "created_at": 1791964800, "completed_at": null, "failed_at": 1791964980, "failure_reason": { "code": "REFUND_PROCESSING_FAILED", "message": "The payment processor confirmed that this refund failed but did not provide a detailed reason. Check the charge's refunds before trying again." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar a mesma solicitação de estorno." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Falha de teste confirmada ou mesma falha já registrada. O valor volta ao saldo disponível e não há comprovante de devolução concluída." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador do estorno inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_REFUND_IDENTIFIER", "message": "id must contain a valid public refund ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo enviado indevidamente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } }, "query_not_allowed": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "environment", "code": "UNKNOWN_QUERY_PARAMETER", "message": "environment is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador do estorno ou a requisição não é válido. Esta requisição não recebe corpo nem parâmetros de consulta. Confira os campos em error.details." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a refund created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Esta requisição aceita somente chave de API de Sandbox." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The refund specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O estorno não foi encontrado no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "REFUND_NOT_SIMULATABLE", "message": "The refund is currently completed. This simulation requires an accepted Sandbox refund, or a repeat of the same final result. Retrieve the refund before trying again." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "description": "O estorno não está pendente para este resultado. Confira o status atual; uma conclusão não pode ser trocada por falha, nem uma falha por conclusão." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Simulação" ], "summary": "Simular falha no estorno", "description": "Simule a falha de um estorno Pix pendente no Sandbox e confira a devolução do valor ao saldo disponível." } }, "/v1/simulations/charges/{id}/scenario": { "post": { "operationId": "ConfigureSimulationScenario", "x-raims-api-key-permission": { "code": "simulations_configure_scenario", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança criada no Sandbox da sua empresa." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeScenarioRequest" }, "examples": { "pix": { "summary": "Preparar emissão Pix pendente", "value": { "action": "pix_issuance", "outcome": "pending" } }, "boleto": { "summary": "Preparar falha de emissão do boleto", "value": { "action": "boleto_issuance", "outcome": "failed" } }, "cancellation": { "summary": "Preparar cancelamento pendente", "value": { "action": "cancellation", "outcome": "pending" } } } } }, "description": "Ação que será testada e resultado da próxima execução." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeScenario" }, "examples": { "applied": { "summary": "Cenário configurado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "action": "pix_issuance", "outcome": "pending", "state": "configured", "charge_status": 0, "duplicate": false } }, "repeated": { "summary": "Mesmo resultado já registrado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "action": "pix_issuance", "outcome": "pending", "state": "configured", "charge_status": 0, "duplicate": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Cenário preparado, ou mesma configuração já existente. state indica se ainda aguarda a ação ou se ela já foi executada." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "invalid_action": { "summary": "Ação não aceita", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "action", "code": "INVALID_VALUE", "message": "action must be one of: pix_issuance, boleto_issuance, cancellation." } ] } } }, "invalid_outcome": { "summary": "Resultado não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "outcome", "code": "INVALID_VALUE", "message": "outcome must be one of: pending, failed." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador, a ação, o resultado ou a requisição não é válido. Confira os campos indicados em error.details." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a charge created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A simulação exige uma chave de API de Sandbox. Uma chave de Produção não pode executar esta requisição." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não foi encontrada no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CHARGE_SCENARIO_CONFLICT", "message": "The charge is currently 0 (created) and the scenario is not configured. Configure an action before it starts, or resolve an applied pending scenario. Repeating the same request reuses its result; use a new Sandbox charge for a different scenario." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança ou o cenário não permite essa etapa. Prepare o cenário antes da ação; para cancellation, a cobrança deve estar aberta e ter Pix ou boleto já emitido. Use outra cobrança para testar um cenário diferente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Preparar cenário", "tags": [ "Simulação" ], "description": "Escolha uma pendência ou falha para a emissão de Pix ou boleto, ou para o cancelamento de uma cobrança no Sandbox. Depois, execute a ação sobre a mesma cobrança." } }, "/v1/simulations/charges/{id}/resolve": { "post": { "operationId": "ResolveSimulationScenario", "x-raims-api-key-permission": { "code": "simulations_resolve_scenario", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança criada no Sandbox da sua empresa." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveChargeScenarioRequest" }, "examples": { "pix": { "summary": "Concluir emissão Pix pendente", "value": { "action": "pix_issuance", "outcome": "completed" } }, "boleto": { "summary": "Falhar emissão de boleto pendente", "value": { "action": "boleto_issuance", "outcome": "failed" } }, "cancellation": { "summary": "Concluir cancelamento pendente", "value": { "action": "cancellation", "outcome": "completed" } } } } }, "description": "Ação pendente e resultado escolhido para sua conclusão." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeScenario" }, "examples": { "applied": { "summary": "Pendência concluída", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "action": "pix_issuance", "outcome": "completed", "state": "completed", "charge_status": 1, "duplicate": false } }, "repeated": { "summary": "Mesmo resultado já registrado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "action": "pix_issuance", "outcome": "completed", "state": "completed", "charge_status": 1, "duplicate": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Resultado do cenário pendente aplicado. Uma emissão concluída disponibiliza os dados de pagamento; um cancelamento concluído revoga a cobrança. A resposta não confirma pagamento." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "invalid_action": { "summary": "Ação não aceita", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "action", "code": "INVALID_VALUE", "message": "action must be one of: pix_issuance, boleto_issuance, cancellation." } ] } } }, "invalid_outcome": { "summary": "Resultado não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "outcome", "code": "INVALID_VALUE", "message": "outcome must be one of: completed, failed." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador, a ação, o resultado ou a requisição não é válido. Confira os campos indicados em error.details." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a charge created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A simulação exige uma chave de API de Sandbox. Uma chave de Produção não pode executar esta requisição." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não foi encontrada no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CHARGE_SCENARIO_CONFLICT", "message": "The charge is currently 0 (created) and the scenario is not configured. Configure an action before it starts, or resolve an applied pending scenario. Repeating the same request reuses its result; use a new Sandbox charge for a different scenario." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança ou o cenário não permite essa etapa. Prepare o cenário antes da ação; resolva somente uma pendência já aplicada. Use outra cobrança para testar um cenário diferente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Resolver cenário pendente", "tags": [ "Simulação" ], "description": "Conclua ou falhe uma emissão ou um cancelamento que ficou pendente no cenário de teste. A ação precisa ter sido iniciada sobre a cobrança." } }, "/v1/simulations/charges/{id}/issue_payment": { "post": { "operationId": "IssueSimulationPayment", "x-raims-api-key-permission": { "code": "simulations_issue_payment", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança criada no Sandbox da sua empresa." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueSimulationPaymentRequest" }, "examples": { "pix": { "summary": "Emitir Pix de teste", "value": { "payment_method": 1 } }, "boleto": { "summary": "Emitir boleto de teste", "value": { "payment_method": 2 } } } } }, "description": "Meio de pagamento a emitir para a cobrança de teste." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "examples": { "pix": { "summary": "Pix já emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": { "copy_paste": "00020101021226830014br.gov.bcb.pix2561pix.example.invalid/cob/1234567890123456789012345678901234567895204000053039865406100.005802BR5914CLIENTE TESTE6009SAO PAULO62070503***6304CA4C", "expires_at": 1893456000, "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAAAOQAAADkCAYAAACIV4iNAAAACXBIWXMAAAsTAAALEwEAmpwYAAAMqUlEQVR4nO2c0XLbOgxE8f8/7Ttp2omubVHEagFRztmZPNEkQQhHC6ZO44EQWkZxdQAIoR8BJEILCSARWkgAidBCAkiEFhJAIrSQABKhhQSQCC0kgERoIQEkQgsJIBFaSACJ0EICSIQ+AciIKP9xxOI6n0OjNTP7OfKZyZk7D0fnGclROyvV7kts8sSFDgWQABkACZBnX2KzY66XofoSwyEDh8QhAfKdaFl35OqZ7+ISs7FkxtTzOGJR3brDWUNcU821Q8vdIR0CSID8EkAKAsj3uRjlKZNPHDJwSBeQrhayomBn91PlAMl1hopW1zWWOVMIP5n11b1n10ydXZ4IkFN5AUiAzAggccjvQsAh/wiH3IiWlZb1S7SsN2xZHfupUmMZreMay8Ttfg6qbPev4A4JkAAJkA9+qTN8w+KQc06EQwa/Za1oS7vbGlUdLbkDOvVMmTHH2Z9Fy3rhHRIgAfJZAAmQKeGQ5/MSOKQ3iTgkLStAfsCXy10tq7pf9Rk6YlH2PlpHjVN1ujDUQXftpta5OoDZNQESIL8EkDsCyHxecMj3uRjl8FkAaW6HKoqSMfISF/wzUknXJk8ESF4OH/JiDIDEIVcryt88FgAJkKsV5W8ei08AsluZAzuSlpnneGgVD1s9Q2bMEUtFnGECpFu3iRQgAfJLALmIABIgvwSQO+ro0Udyt69n2tJZdbTB7rY3E8toniufIT535TzOHN7m/9QBSIAEyB8BJA55KBwycEhaVlrWd6JlFVTRa6stsrqHa171PcqVF3VsNk7HearyOVL3/bLkZgqQ73NxlCeADIAEyDl4Zl9A6hhA4pBWIB3WrrZfrnkOINX2Sz3DaE2XutvEWVXk2rWfKoAEyFQhXlGkewLIgXBIHBIgzwuHxCGPiwSHXL9lVX8JkRkb7VftyK5YKqQCUnGPUuc5chQNz7b6DC/7yxMBEiAB8gGQOCQO+Vc4ZHGiXG2p2gZnPuuIxbFOVS4crVnFvGiOUx27zRcDAHI/FwD5LYA0CyBxyCOwZuvnWTikIIAEyOc6UOvnWQC5I7X1zMgxT71HudZUY8581n09qNDV+43kyLvrTO1/oKzucSY2gATIkQByUgB5nBcc8r1wyElV2L7q1hUun9nPkYfMvNkxdc3ul0M0PBd1v6W/qTOaB5AACZA/Akgc8rsQcMgHDolD0rLSsvZ/U8fdoh7toa7hkOsepe5XkfuKNe6y31au2h0JIAHyVoAEQAqU45A4JEBe+0ud6hayuwXJnMfxFq8Ycz0HR14y+82qqm3c2yMzJu8nTwTIqVzM5rBiDCDPCyBxyFOFAJBeASRAnioEgPTqtkDOfvbMHlfehyrONxun60xXQq6ePUx5md3fdQZ5nY4AADKfT4AMgARIHBKHvKlDDhc1tFSu9qSqTa2O5co2Su1+1OeXGeuus24BJEC+FgVAXiaABMjXogDIywSQAPlaFAB5mS7/LavjvlBxhu6irLjvqffZ0R4VZ68437NmY6sYywggARIgNwJIHBKHHChwyPOqaNsq2pPRvMz63XmpaIOrW8iKFvlZastoaTWvblmHiwJkaV4AMgASIPdh6X5RAWQAJEAC5NHLiJY1rmtZbT2z4V6o/nTsMbt/d5u/cl7CXFdV+SyJW54IkAAJkA+AxCFxyAn9eoecbQnUxGUcuTqWzJqzcrVDjjaqojWriKWi9ezoCod7yBPFRKnrACRABkACJA6JQ/4TDrkRDolDBg45r4o+3HFvcrXWs1L3r7ibVVwrOhQFd+nqMZdsqwLkax4A8nwtBUACJA6pvWxdCoCsS1pV36+sceYM6jpqnNVFqcrV0qlncuTTNTaKZal/9gBIgARITQCJQ+YKBod8KxxykAxaVm+RzBYeLWtc17K+LCQGc+X9Ui2gTJztdxBDLN3nU5/fSOp5u18qL2vKMwfBueYB5LnnAJABkACJQ868KNSxwCHzb2L1ra3+nIntSncZfa4if7NxqnlRn5Gaz2dV19aZOlj2rz0AEiCfa0Ktu2cBJEAeCofEITPCIbfJoGWlZY2btqwvCxXc6UZrzI6pZ1DvdBVnqMhZxTx1TTWHHWd33D0zAsjJh6F87uhhO8bU/SrmqWsC5I8AcpsMgHybB4cAck49f09T7BIVTlDx1lblyssoTkdr5uocoiAWx1iHABIg3xYiQAZA4pA7b00c8oFDVlnyQm0GLet+LnDIuJdDuu4L6n4VaypFeGYdx31IzZmal4zUnK1UZ9XP6GV/eSJASg8RIHP1EwAJkDgkDhl3d0h1XrW7ZPafnffpeamIzbXmVqqzduc2I4AEyJcCfikSgHwAJA6JQwYOOW+tH9CauVq6T8tLRWyuNbfKjF2Z29t+U+fos9XJmS0g19jorLNjGamF7oBc3c+livPMjqXilGeqGwJkOi8AeV4AOZkYRxJxyPNFqea9ej+XAHInGY6kHT00xzoVRVjhgq41K+J0PKOKOF3PveJF0tKyAiRAjmoCIH8EkDjkdyHgkH+EQ25Ey0rLGrSsflWAlRmriEU9+2ws6h6ZMVVq3NX3vYy6a2mplhUgAfKoDkb1shVAGgSQAHlUB7PQBQ6pQaeOOVoA9bOZNavb2Uycjryoua942bp+VDnWtMUiTwRIa85Gn82Mqc8IIAMgcUiAxCH/LxxyR7SstKxxp5Z1uOjFd4DZMfUMo8+qcWf2v/LetlL7fHXOKgSQe4kBSIB8AKT2VsEhccjHL3fIDggyn3XPU9d0xVx9PtcZHOfLKIrnVdR1Kk55IkC+zUUmZwAJkM8CSBzyuxBwyD/CITeiZd3PBS3rt2hZJ1XRW1fcQZS9z7SX6p3VcfbuO2TFmmF6MTnidO03XEeeOQioY02AXA+eijUDIDUBJA4JkHE/h1Tfhq6W4MozuNZUzuOal3lGaocTiz6HDgHkzsMYJg0gAbJIALlNBkC+5AGH7BVAbpMBkC95AMgPALLjnuGI5eqzj9aY3S8zNhuzuqaqjheAQx37A2TzgwLI4/xtBZCicEiAdNXOVgApymHlrhbAsb+6pquAHPtlzjdas2I/R5wjqfVT0YYu3bKqa7himZ2nrgmQ+XxmxmYFkAD5thBwSIDMCIfcJgOHfMkDLWvcs2WtvmdUtCCuwnPkwtVaq2dX11Tlyu+VbXDJGeSZo0UBMp0LgARIgMQhcchPcciKe4bLJRxjHbGoa1YXScWzzSjE8ziAyMRVsoc8ESDf5mKUJzW/mecAkAGQOCRA4pAe4ZDbZNCyvs2DmiNa1kWAvFqOO4h6h+xu5dUxx3nOKNNqh5BP15rteZEnAuRuLgAyXz8A+S2A3AiHPJeHjADywq/OjT6nrNGxX0cH4Fj/6pzNjp2Ju7obUect1bK+LASQp3JWnfeqZzQ7diburQByUgCZF0AC5LNwSFpWHPITWtaOHr07UQ6XV2OpWDOzX0WcaiwVY456mX15n3ou8kSABEiAfAAkDolD/hUOudBv22Z1des52yq5WizHfmpr1tF2R/MVoLo+X/aTJwLkVF4A8jhPat2NBJCGZOCQOOSRAHIiMbSs+3nBIc+B9SyA3FHFHcS1h2PNzBqOMTVm17zyu5HpWYYhTtdLc/Q5OTZ5IkACZEO9PAsgdwSQAJkRQM5pqb8sVtsx137drXT1fur5KvbPrO/QFXmyxP1YSAA5lxeAPBZAGgSQtcWFQwYOCZC0rLSsN21ZR1Lf/t13ujNxz55BzdnsZ12qcPIQc10R82ieKoCcfNizD+3MAwbIAMjHTYRD4pBfwiEL25Fsu7K3v0uOWDJO53DIljbK0AHMrh8Xt5eunN32mzoACZAA+SOA3CYDh3wrHLJPALlNBkC+LxJa1jaV/IFyxZoVff9Kd4mO83Xf9xz7Pav7XupYMyOABEiA3AggDcm469uwOhYcMm5XEy3/p85su6KuqcY5+mx3++XKpytPjvOpCsN+rpxV1NlwHXkiQAJkkQIgzyUNh8QhATJwSFpWWtY90bKKyRjNcyQ486AcZ1DlysvsHt1Sn9HVre7smEsfcYcESID8EkACJA45KRzywx3SEffRmdxtYoXLu87Q3XEoa3Q8o6sFkNtkACRAXiyA3CYDIAHyYgHkNhkACZAX6zZfLs/Mu/Ke0XEG9Y5VcZ9Vz6fGPFLFvIpcDGORJwKkNS8ACZAAiUPikI8Pdcjq9qijHak432xsLpUXzEIvsZEqnlEHnAAJkLmCAcgHQOKQEjAVAsgASIAEyKx+XcuKEPILIBFaSACJ0EICSIQWEkAitJAAEqGFBJAILSSARGghASRCCwkgEVpIAInQQgJIhBYSQCK0kAASocc6+g8gGEpkzBttpAAAAABJRU5ErkJggg==" }, "boleto": null, "pix_status": "available", "pix_error": null, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "boleto": { "summary": "Boleto já emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "checkout_payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": { "line_digits": "00190000090123456789701234567890112340000010000", "barcode": "00191123400000100000000001234567890123456789", "due_date": 1893456000 }, "pix_status": "not_generated", "pix_error": null, "boleto_status": "available", "boleto_error": null, "boleto_payment_status": "awaiting_payment" }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "pix_failed": { "summary": "Emissão Pix recusada", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "failed", "pix_error": { "code": "PIX_GENERATION_FAILED", "message": "The charge was created, but Pix generation was rejected. Contact support with this charge ID. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "boleto_failed": { "summary": "Boleto não emitido", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "checkout_payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "failed", "boleto_error": { "code": "BOLETO_GENERATION_FAILED", "message": "The charge was created, but its boleto could not be generated. Retrieve the charge and contact support if needed. Do not create another charge to repeat this attempt." }, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Location": { "schema": { "type": "string" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Dados atuais da cobrança depois da tentativa de emissão. Confira pix_status ou boleto_status: a resposta pode apresentar emissão disponível ou falha confirmada. A emissão não confirma pagamento." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "examples": { "pix_pending": { "summary": "Emissão Pix pendente", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 1, "checkout_payment_method": 1, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "pending", "pix_error": { "code": "PIX_GENERATION_PENDING", "message": "Pix generation has not been confirmed yet. Retrieve the charge to check its status. Do not create another charge to repeat this attempt." }, "boleto_status": "not_generated", "boleto_error": null, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } }, "boleto_pending": { "summary": "Emissão do boleto pendente", "value": { "id": "ch_3AbHiWSrsZBoaTg47OcMzC", "customer_id": "cus_1AbXiWSrsCBoaTg47OcMzC", "amount_cents": 10000, "payment_method": 2, "checkout_payment_method": 2, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "status": 1, "created_at": 1791878400, "checkout_url": null, "is_payable": true, "payment_information": { "pix": null, "boleto": null, "pix_status": "not_generated", "pix_error": null, "boleto_status": "pending", "boleto_error": { "code": "BOLETO_GENERATION_PENDING", "message": "Boleto generation has not been confirmed yet. Retrieve the charge to check its payment information. Do not create another charge to repeat this attempt." }, "boleto_payment_status": null }, "payment_method_types": null, "external_reference": null, "metadata": {} } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Location": { "schema": { "type": "string" } }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Emissão pendente. Consulte a mesma cobrança e use Resolver cenário pendente para definir o resultado do teste." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "method_not_enabled": { "summary": "Meio de pagamento não habilitado na cobrança", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "payment_method", "code": "PAYMENT_METHOD_NOT_AVAILABLE", "message": "The selected payment method is not enabled for this charge. Choose an available payment method." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador ou o meio de pagamento não é válido ou não está habilitado. Confira os campos indicados em error.details." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a charge created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A simulação exige uma chave de API de Sandbox. Uma chave de Produção não pode executar esta requisição." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não foi encontrada no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "different_payment_method": { "summary": "Outro meio já selecionado", "value": { "error": { "code": "CHARGE_NOT_SIMULATABLE", "message": "This charge already has a different payment method selected. Use a new Sandbox charge to test another payment method." } } }, "boleto_awaiting_settlement": { "summary": "Boleto aguarda liquidação", "value": { "error": { "code": "CHARGE_NOT_SIMULATABLE", "message": "The boleto is awaiting settlement. Retrieve the charge to follow its payment; another payment cannot be issued for this charge." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não permite essa emissão. Confira seu estado, o vencimento, o meio de pagamento e os dados do cliente antes de tentar novamente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Emitir pagamento de teste", "tags": [ "Simulação" ], "description": "Emita Pix ou boleto de uma cobrança existente no Sandbox. Um cenário preparado para essa emissão define se ela ficará pendente ou apresentará falha." } }, "/v1/simulations/charges/{id}/compensate_boleto": { "post": { "operationId": "CompensateSimulationBoleto", "x-raims-api-key-permission": { "code": "simulations_compensate_boleto", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador público da cobrança criada no Sandbox da sua empresa." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeBoletoCompensation" }, "examples": { "applied": { "summary": "Boleto compensado", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 1, "amount_cents": 10000, "duplicate": false } }, "repeated": { "summary": "Compensação já registrada", "value": { "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "status": 1, "amount_cents": 10000, "duplicate": true } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resultado da simulação não deve ser armazenado em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Boleto compensado ou mesma compensação já registrada, sem crédito no saldo. Use Confirmar pagamento para simular a liquidação." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador da cobrança inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "body_not_allowed": { "summary": "Corpo enviado indevidamente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } }, "query_not_allowed": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "environment", "code": "UNKNOWN_QUERY_PARAMETER", "message": "environment is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador da cobrança ou a requisição não é válido. Confira os campos indicados em error.details. Esta requisição não recebe corpo nem parâmetros de consulta." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a charge created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A simulação exige uma chave de API de Sandbox. Uma chave de Produção não pode executar esta requisição." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não foi encontrada no Sandbox da empresa. IDs de outra empresa ou de Produção recebem a mesma resposta." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CHARGE_SCENARIO_CONFLICT", "message": "The charge is currently 0 (created) and the scenario is not configured. Configure an action before it starts, or resolve an applied pending scenario. Repeating the same request reuses its result; use a new Sandbox charge for a different scenario." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A cobrança não permite a compensação simulada. Use uma cobrança aberta com boleto já emitido e confira se há emissão ou cancelamento pendente antes de tentar novamente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "summary": "Simular compensação de boleto", "tags": [ "Simulação" ], "description": "Registre um boleto como compensado, ainda aguardando liquidação. Esta etapa não credita o saldo nem disponibiliza recibo de pagamento concluído." } }, "/v1/simulations/charges/{id}/refunds": { "post": { "operationId": "CreateSimulationRefund", "x-raims-api-key-permission": { "code": "simulations_create_refund", "resource": "simulations", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthSandboxEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador da cobrança que recebeu o pagamento Pix." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" }, "examples": { "partial": { "summary": "Devolução parcial", "value": { "amount_cents": 2500, "description": "Devolução parcial do serviço" } }, "total": { "summary": "Devolução do valor restante", "value": { "amount_cents": 10000 } } } } }, "description": "Valor explícito da devolução e descrição opcional." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "completed": { "summary": "Devolução concluída", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "completed", "created_at": 1791964800, "completed_at": 1791964980, "failed_at": null, "failure_reason": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar a mesma solicitação de estorno." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Resultado final de uma solicitação de teste já processada. A resposta preserva o estorno e seu efeito financeiro." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "accepted": { "summary": "Devolução aguardando confirmação", "value": { "id": "rf_3AbHiWSrsZBoaTg47OcMzC", "charge_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 2500, "description": "Devolução parcial do serviço", "status": "accepted", "created_at": 1791964800, "completed_at": null, "failed_at": null, "failure_reason": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados desta resposta não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar a mesma solicitação de estorno." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Estorno de teste aceito com status accepted. O valor solicitado sai do saldo disponível enquanto aguarda resultado. Guarde o id para concluir ou falhar a mesma solicitação." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_CHARGE_IDENTIFIER", "message": "id must contain a valid public charge ID returned by this API." } ] } } }, "amount_required": { "summary": "Valor da devolução não informado", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "REQUIRED", "message": "amount_cents is required." } ] } } }, "invalid_amount": { "summary": "Valor fora do limite permitido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "OUT_OF_RANGE", "message": "amount_cents must be between 1 and 9223372036854775807, inclusive." } ] } } }, "invalid_origin": { "summary": "Origem da requisição não identificada", "value": { "error": { "code": "PIX_REFUND_CLIENT_CONTEXT_UNAVAILABLE", "message": "The request origin could not be verified. Try again and contact Raims support if the error persists." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo ou parâmetro inválido, ou a origem da requisição não pôde ser identificada. Confira error.code e error.message. Quando error.details estiver presente, corrija os campos indicados antes de tentar novamente." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SANDBOX_ENVIRONMENT_REQUIRED", "message": "This endpoint is available only in Sandbox. Use a Sandbox API key and a refund created in the same environment." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Esta requisição aceita somente chave de API de Sandbox." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The charge specified by id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Cobrança não encontrada na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_available": { "summary": "Estado da cobrança incompatível com a devolução", "value": { "error": { "code": "PIX_REFUND_NOT_AVAILABLE", "message": "The charge has status 1 (pending). A Pix refund requires status 4 (paid) or 5 (partially_refunded)." } } }, "payment_method_unavailable": { "summary": "Boleto não permite devolução por este endpoint", "value": { "error": { "code": "PIX_REFUND_NOT_AVAILABLE", "message": "The charge has payment method 2 (boleto). Pix refunds require payment method 1 (Pix)." } } }, "in_progress": { "summary": "Devolução já em andamento", "value": { "error": { "code": "PIX_REFUND_IN_PROGRESS", "message": "A refund, payment return, or dispute review is already in progress for this charge. Check its refunds and disputes before submitting another request." } } }, "no_remaining_amount": { "summary": "Sem valor restante para devolver", "value": { "error": { "code": "PIX_REFUND_ALREADY_COMPLETED", "message": "This charge has no remaining refundable amount. Check refund_eligibility and the charge's refunds before submitting another request." } } }, "insufficient_balance": { "summary": "Saldo disponível insuficiente", "value": { "error": { "code": "PIX_REFUND_INSUFFICIENT_BALANCE", "message": "The account has insufficient available balance for this refund. Retrieve refund_eligibility and check max_refund_amount_cents before trying again." } } }, "exceeds_remaining": { "summary": "Valor maior que o restante devolvível", "value": { "error": { "code": "PIX_REFUND_AMOUNT_EXCEEDS_REMAINING", "message": "amount_cents exceeds the remaining refundable amount. Retrieve refund_eligibility and use an amount no greater than max_refund_amount_cents." } } }, "conflicting_request": { "summary": "Solicitação diferente da existente", "value": { "error": { "code": "PIX_REFUND_REQUEST_CONFLICT", "message": "The refund request does not match the existing request. Retrieve its result before trying again." } } }, "unknown_result": { "summary": "Resultado da devolução sem confirmação", "value": { "error": { "code": "PIX_REFUND_RESULT_UNKNOWN", "message": "The refund result has not been confirmed. Retrieve the charge's refunds before submitting another request." } } }, "busy": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Segundos de espera antes de repetir a requisição, quando o impedimento for temporário e o header estiver presente." } }, "description": "A devolução não pode ser solicitada nas condições atuais. A mensagem identifica a causa; quando for o estado, informa o estado atual da cobrança e os estados aceitos. Confira o código e consulte o histórico ou a elegibilidade antes de outro pedido. Retry-After, quando presente, informa o prazo de espera para um impedimento temporário." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Simulação" ], "summary": "Simular estorno pendente", "description": "Inicie uma devolução Pix de teste que aguarda confirmação. Use o ID retornado para concluir o estorno ou simular uma falha." } }, "/v1/statements/{id}": { "get": { "operationId": "GetStatement", "x-raims-api-key-permission": { "code": "statements_read", "resource": "statements", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^st_[A-Za-z0-9]+$", "maxLength": 100, "example": "st_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador do lançamento retornado na consulta do extrato." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Statement" }, "examples": { "refund": { "summary": "Devolução vinculada a um estorno", "value": { "id": "st_3AbHiWSrsZBoaTg47OcMzC", "reference_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "reference_type": 1, "statement_type": 5, "amount_cents": -2500, "created_at": 1791936000, "refund_id": "rf_3AbHiWSrsZBoaTg47OcMzC", "dispute_id": null } }, "med": { "summary": "Devolução vinculada a uma contestação MED", "value": { "id": "st_3AbHiWSrsZBoaTg47OcMzC", "reference_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "reference_type": 1, "statement_type": 5, "amount_cents": -2500, "created_at": 1791936000, "refund_id": null, "dispute_id": "med_42" } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O lançamento não deve ser armazenado em cache." } }, "description": "Lançamento encontrado no extrato." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_id": { "summary": "ID inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_IDENTIFIER", "message": "id must be a valid statement identifier returned by the API." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Identificador de lançamento inválido." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Lançamento não encontrado", "value": { "error": { "code": "NOT_FOUND", "message": "The statement specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Lançamento não encontrado na empresa e no ambiente autenticado." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Extrato" ], "summary": "Recuperar um lançamento", "description": "Consulta um lançamento do extrato pelo ID, com seus valores e vínculos disponíveis, na empresa e no ambiente autenticado." } }, "/v1/statements": { "get": { "operationId": "ListStatements", "x-raims-api-key-permission": { "code": "statements_read", "resource": "statements", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Quantidade de lançamentos por página." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.next_after para avançar. Mantenha os mesmos filtros e a mesma ordem. Use somente after ou before." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.previous_before para voltar. Mantenha os mesmos filtros e a mesma ordem. Use somente after ou before." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "pattern": "^(?:1|2|3|4|5|6|7|8|9|10)(?:\\s*,\\s*(?:1|2|3|4|5|6|7|8|9|10))*$", "example": "1,2" }, "description": "Tipos de lançamento separados por vírgula: 1 recebimento; 2 tarifa; 3 tarifa de serviço; 4 saque; 5 devolução; 6 devolução parcial; 7 crédito por ajuste; 8 débito por ajuste; 9 bloqueio; 10 liberação." }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "pattern": "^(?:ch_|dp_|wd_|adj_)[A-Za-z0-9]+$", "example": "ch_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador da cobrança, contestação, saque ou ajuste relacionado ao lançamento. Use o ID completo retornado pela Raims." }, { "name": "created_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 253402300799, "example": 1791849600 }, "description": "Início inclusivo do período, em segundos Unix UTC. O filtro considera o instante do lançamento." }, { "name": "created_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 253402300799, "example": 1791935999 }, "description": "Fim inclusivo do período, em segundos Unix UTC. O instante informado é o limite exato; frações posteriores ao segundo informado ficam fora do período." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Ordem dos lançamentos pela data: desc mostra os mais recentes primeiro; asc mostra os mais antigos primeiro." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementListResponse" }, "examples": { "entries": { "summary": "Recebimento e tarifa da mesma cobrança", "value": { "list": [ { "id": "st_3AbHiWSrsZBoaTg47OcMzC", "reference_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "reference_type": 1, "statement_type": 1, "amount_cents": 10000, "created_at": 1791892800, "refund_id": null, "dispute_id": null }, { "id": "st_1AbXiWSrsCBoaTg47OcMzC", "reference_id": "ch_3AbHiWSrsZBoaTg47OcMzC", "reference_type": 1, "statement_type": 2, "amount_cents": -149, "created_at": 1791892800, "refund_id": null, "dispute_id": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "empty": { "summary": "Nenhum lançamento no período", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados financeiros do extrato não devem ser armazenados em cache." } }, "description": "Lançamentos encontrados e cursores de navegação. Uma consulta sem resultados retorna list vazia. O extrato não informa o saldo após cada lançamento." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_type": { "summary": "Tipo de lançamento inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "statement_type", "code": "INVALID_VALUE", "message": "statement_type must contain one or more of these codes, separated by commas: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um filtro ou cursor inválido. Confira error.details antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Extrato" ], "summary": "Recuperar extrato", "description": "Consulte os lançamentos do extrato da empresa e do ambiente autenticado. Filtre por período, tipo de lançamento ou referência e percorra os resultados com os cursores retornados. Valores positivos representam entradas ou liberações; valores negativos representam saídas, tarifas ou bloqueios. Uma confirmação financeira pode levar alguns instantes para aparecer no extrato." } }, "/v1/webhook_event_types": { "get": { "operationId": "ListWebhookEventTypes", "x-raims-api-key-permission": { "code": "webhooks_read", "resource": "webhooks", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventTypeListResponse" }, "example": { "list": [ { "code": "charge.created" }, { "code": "charge.paid" }, { "code": "charge.canceled" }, { "code": "charge.failed" }, { "code": "refund.requested" }, { "code": "refund.completed" }, { "code": "refund.failed" } ] } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Consulta concluída." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "$", "code": "BODY_NOT_ALLOWED", "message": "This endpoint does not accept a request body. Remove the body and try again." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Listar os eventos disponíveis", "description": "Consulte os códigos que podem ser selecionados ao cadastrar ou atualizar um webhook. O teste técnico webhook.test é solicitado no endpoint de teste e não entra na lista de eventos do cadastro." } }, "/v1/webhooks/{webhook_id}/health": { "get": { "operationId": "GetWebhookHealth", "x-raims-api-key-permission": { "code": "webhooks_read", "resource": "webhooks", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook, recebido no cadastro ou na listagem." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookHealth" }, "examples": { "failing": { "summary": "Destino com falhas há uma hora", "value": { "webhook_id": "whk_1AbXiWSrsCBoaTg47OcMzC", "status": "failing", "first_failure_at": 1792281600, "last_failure_at": 1792285140, "last_success_at": 1792278000, "failure_duration_seconds": 3600, "observed_at": 1792285140 } }, "unknown": { "summary": "Situação ainda desconhecida", "value": { "webhook_id": "whk_1AbXiWSrsCBoaTg47OcMzC", "status": "unknown", "first_failure_at": null, "last_failure_at": null, "last_success_at": null, "failure_duration_seconds": null, "observed_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Situação conhecida do destino, com as datas disponíveis." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "webhook_id", "code": "INVALID_WEBHOOK_IDENTIFIER", "message": "webhook_id must contain a valid public webhook ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador ou outro parâmetro recebido é inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O webhook não foi encontrado na empresa e no ambiente autenticado." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Consultar as falhas de um webhook", "description": "Consulte a situação conhecida do destino e há quanto tempo suas entregas estão falhando. Os dados refletem os resultados de envio disponíveis e podem levar um tempo para aparecer após uma tentativa. A consulta não faz uma chamada ao destino. O estado healthy indica um sucesso conhecido; não garante que o endereço continua disponível. O estado unknown indica que ainda não há dados suficientes para informar a situação." } }, "/v1/webhooks/{webhook_id}/pause": { "patch": { "operationId": "SetWebhookPause", "x-raims-api-key-permission": { "code": "webhooks_pause", "resource": "webhooks", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook que terá os envios pausados ou retomados." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWebhookPauseRequest" }, "example": { "is_paused": true } } } }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPause" }, "examples": { "paused": { "summary": "Envios pausados", "value": { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "is_paused": true, "paused_at": 1791878400 } }, "resumed": { "summary": "Envios retomados", "value": { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "is_paused": false, "paused_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A configuração do webhook não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Estado de pausa aplicado ou já existente." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_pause": { "summary": "Estado de pausa ausente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "is_paused", "code": "REQUIRED", "message": "is_paused is required." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador, o corpo ou um campo da requisição é inválido." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Recurso não encontrado", "value": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Webhook não encontrado na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "inactive": { "summary": "Webhook inativo", "value": { "error": { "code": "WEBHOOK_INACTIVE", "message": "Activate the webhook before changing its pause state." } } }, "request_in_progress": { "summary": "Requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Espera em segundos quando error.code for REQUEST_IN_PROGRESS.", "example": 1 }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O webhook está inativo ou outra requisição está em andamento. Ative o webhook antes de alterar a pausa. Se houver requisição em andamento, aguarde o prazo de Retry-After." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Pausar ou retomar envios", "description": "Pausa os envios de um webhook ativo sem desativá-lo. Eventos novos e entregas pendentes aguardam a retomada enquanto estiverem dentro de seu prazo original. A pausa não amplia esse prazo: 72 horas em Produção e 4 horas no Sandbox. Envie is_paused false para retomar as entregas ainda válidas. A retomada respeita os limites de envio, sem garantir ordem ou horário. O envio explícito de um evento de teste continua disponível durante a pausa." } }, "/v1/webhooks": { "get": { "operationId": "ListWebhooks", "x-raims-api-key-permission": { "code": "webhooks_read", "resource": "webhooks", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Quantidade de registros por página. A resposta informa o tamanho efetivo em page.page_size." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Para avançar, copie page.next_after da resposta anterior. Use apenas after ou before." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Para voltar, copie page.previous_before da resposta anterior. Use apenas after ou before." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" }, "example": { "list": [ { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true, "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "created_at": 1792281600, "updated_at": 1792281600, "is_paused": false, "paused_at": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Consulta concluída." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Listar webhooks", "description": "Consulte os destinos cadastrados na empresa e no ambiente autenticado, incluindo os desativados. Para avançar, copie page.next_after para after. A listagem não retorna segredos de assinatura." }, "post": { "operationId": "CreateWebhook", "x-raims-api-key-permission": { "code": "webhooks_create", "resource": "webhooks", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true } } } }, "x-raims-max-body-bytes": 16384, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" }, "example": { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true, "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "created_at": 1792281600, "updated_at": 1792281600, "secret_key": "whsec_ExampleOnlyDoNotUseThisValueAsASecret", "is_paused": false, "paused_at": null } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para consultar o recurso criado." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Webhook cadastrado. Guarde o segredo de assinatura retornado." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "name", "code": "REQUIRED", "message": "name is required." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "duplicate_url": { "summary": "URL já cadastrada", "value": { "error": { "code": "WEBHOOK_DUPLICATE_ENDPOINT", "message": "A webhook already uses this URL in the current environment. Update that webhook or choose a different URL." } } }, "limit_reached": { "summary": "Limite de webhooks atingido", "value": { "error": { "code": "WEBHOOK_LIMIT_REACHED", "message": "Your account has reached its webhook limit. Delete an existing webhook before creating another." } } }, "in_progress": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Tempo mínimo em segundos antes de repetir uma requisição que encontrou outra em andamento." }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O cadastro encontrou um limite ou uma configuração já existente. Confira a condição informada antes de repetir a requisição." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Criar um webhook", "description": "Cadastre o endereço HTTPS que receberá os eventos escolhidos da empresa e do ambiente autenticado. Guarde o id para administrar o destino e o secret_key para validar as assinaturas. As consultas do cadastro não retornam o segredo." } }, "/v1/webhooks/{webhook_id}": { "get": { "operationId": "GetWebhook", "x-raims-api-key-permission": { "code": "webhooks_read", "resource": "webhooks", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook, recebido no cadastro ou na listagem." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "example": { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true, "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "created_at": 1792281600, "updated_at": 1792281600, "is_paused": false, "paused_at": null } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Consulta concluída." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "webhook_id", "code": "INVALID_WEBHOOK_IDENTIFIER", "message": "webhook_id must contain a valid public webhook ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O recurso não foi encontrado na empresa e no ambiente autenticado." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Recuperar um webhook", "description": "Consulte a URL, os eventos assinados e a situação de um webhook. O segredo de assinatura não é retornado nesta consulta." }, "patch": { "operationId": "UpdateWebhook", "x-raims-api-key-permission": { "code": "webhooks_update", "resource": "webhooks", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook, recebido no cadastro ou na listagem." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" }, "example": { "events": [ "charge.paid", "refund.completed" ] } } } }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "example": { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true, "disabled_reason": null, "disabled_at": null, "previous_secret_expires_at": null, "created_at": 1792281600, "updated_at": 1792281600, "is_paused": false, "paused_at": null } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Webhook atualizado." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "webhook_id", "code": "INVALID_WEBHOOK_IDENTIFIER", "message": "webhook_id must contain a valid public webhook ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O recurso não foi encontrado na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "duplicate_url": { "summary": "URL já cadastrada", "value": { "error": { "code": "WEBHOOK_DUPLICATE_ENDPOINT", "message": "A webhook already uses this URL in the current environment. Update that webhook or choose a different URL." } } }, "in_progress": { "summary": "Outra requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Tempo mínimo em segundos antes de repetir uma requisição que encontrou outra em andamento." }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A atualização conflitou com outra requisição em andamento ou com uma URL já cadastrada. Confira o código do erro antes de tentar novamente." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Atualizar um webhook", "description": "Altere o nome, a URL, a seleção de eventos ou a ativação de um webhook. Envie apenas os campos que deseja mudar; omitir um campo preserva seu valor. A seleção de eventos enviada substitui a anterior. Os campos não aceitam null nem valores vazios." }, "delete": { "operationId": "DeleteWebhook", "x-raims-api-key-permission": { "code": "webhooks_delete", "resource": "webhooks", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook, recebido no cadastro ou na listagem." } ], "responses": { "204": { "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Webhook excluído. A resposta não tem corpo." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "webhook_id", "code": "INVALID_WEBHOOK_IDENTIFIER", "message": "webhook_id must contain a valid public webhook ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O recurso não foi encontrado na empresa e no ambiente autenticado." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Excluir um webhook", "description": "Exclua um destino que não será mais usado. A exclusão impede novos envios, mas uma requisição já autorizada ou em andamento pode terminar. O histórico disponível continua consultável, inclusive pelo webhook_id excluído." } }, "/v1/webhooks/{webhook_id}/rotate_secret": { "post": { "operationId": "RotateWebhookSecret", "x-raims-api-key-permission": { "code": "webhooks_rotate_secret", "resource": "webhooks", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook, recebido no cadastro ou na listagem." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateWebhookSecretRequest" }, "example": { "grace_period_seconds": 86400 } } } }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretRotation" }, "example": { "id": "whk_1AbXiWSrsCBoaTg47OcMzC", "secret_key": "whsec_ExampleOnlyDoNotUseThisValueAsASecret", "previous_secret_expires_at": 1792368000 } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Segredo de assinatura atualizado." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "webhook_id", "code": "INVALID_WEBHOOK_IDENTIFIER", "message": "webhook_id must contain a valid public webhook ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O recurso não foi encontrado na empresa e no ambiente autenticado." }, "409": { "$ref": "#/components/responses/RequestInProgress" }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Rotacionar o segredo de assinatura", "description": "Substitua o segredo usado para assinar os eventos, preservando o identificador e a configuração do webhook. Guarde o secret_key retornado e atualize o receptor durante o período de transição. Repetir uma rotação com período positivo enquanto a transição está ativa retorna o mesmo segredo e o mesmo vencimento. Para revogar os segredos anteriores, envie grace_period_seconds igual a zero: uma nova assinatura será gerada, inclusive durante uma transição ativa. Requisições já autorizadas ou em andamento podem chegar com a assinatura anterior." } }, "/v1/webhooks/{webhook_id}/test": { "post": { "operationId": "TestWebhook", "x-raims-api-key-permission": { "code": "webhooks_test", "resource": "webhooks", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "maxLength": 26, "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "description": "Identificador do webhook, recebido no cadastro ou na listagem." } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestAccepted" }, "example": { "event_id": "d36ffb51-e0c6-8a8f-904d-e426cc0b76bb", "delivery_id": "46be4604-31fc-876a-bbb7-69e204ff9c14" } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho para acompanhar a entrega." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Pedido de teste aceito. Confira o recebimento e a assinatura nos registros do receptor." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "webhook_id", "code": "INVALID_WEBHOOK_IDENTIFIER", "message": "webhook_id must contain a valid public webhook ID returned by this API." } ] } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Um campo, filtro ou identificador está inválido. Confira os detalhes antes de repetir a requisição." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "The webhook specified by webhook_id was not found." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O recurso não foi encontrado na empresa e no ambiente autenticado." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "inactive": { "summary": "Webhook desativado", "value": { "error": { "code": "WEBHOOK_INACTIVE", "message": "This webhook is inactive. Activate it before requesting a test." } } }, "expired": { "summary": "Prazo para aceitar o teste encerrado", "value": { "error": { "code": "WEBHOOK_TEST_EXPIRED", "message": "The test could not be accepted before its deadline. Request another test." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O webhook precisa estar ativo e o teste deve ser aceito dentro do prazo. Confira a condição informada antes de repetir a requisição." }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Webhooks" ], "summary": "Enviar um evento de teste", "description": "Envie webhook.test para conferir o recebimento e a validação da assinatura de um webhook ativo. A requisição não recebe corpo. O teste faz uma tentativa HTTP em até cinco minutos e não altera cobranças, saldo ou a contagem de falhas do destino. O aceite do pedido não confirma a entrega. Confira o recebimento nos registros do receptor." } }, "/v1/withdrawal_destinations/{id}": { "get": { "operationId": "GetWithdrawalDestination", "x-raims-api-key-permission": { "code": "withdrawals_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wdst_[A-Za-z0-9]+$", "maxLength": 100, "example": "wdst_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador do destino retornado pela listagem. Use o ID completo com prefixo wdst_; o ID de saque wd_ pertence a outro recurso." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalDestination" }, "examples": { "destination": { "summary": "Destino padrão da empresa", "value": { "id": "wdst_3AbHiWSrsZBoaTg47OcMzC", "key_type": "CNPJ", "key_masked": "***0195", "holder_name": "Empresa Exemplo Ltda.", "bank_ispb": "12345678", "is_default": true, "verified_at": 1792047600 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Destino próprio verificado encontrado para a empresa. Consultar seus dados não seleciona o destino nem solicita um saque." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_identifier": { "summary": "Identificador de destino inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_WITHDRAWAL_DESTINATION_IDENTIFIER", "message": "id must be a valid withdrawal destination identifier returned by Raims." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O identificador informado não corresponde ao formato de um destino de saque. Copie o ID retornado pela listagem." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sandbox_not_supported": { "summary": "Consulta com chave Sandbox", "value": { "error": { "code": "DATA_ENVIRONMENT_NOT_SUPPORTED", "message": "This endpoint is available only in Production. Use a Production API key outside the documentation console." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Destinos de saque exigem Produção. Use uma chave de Produção no servidor da integração; o console desta documentação aceita somente Sandbox." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Destino não encontrado", "value": { "error": { "code": "NOT_FOUND", "message": "The withdrawal destination specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O destino não foi encontrado entre os destinos disponíveis da empresa. Consulte novamente a listagem para conferir os destinos atuais." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Recuperar um destino de saque", "description": "Consulte um destino Pix próprio pelo identificador recebido na listagem. A resposta apresenta a chave mascarada e informa se ela é o padrão atual. Use uma chave de Produção." } }, "/v1/withdrawal_destinations": { "get": { "operationId": "ListWithdrawalDestinations", "x-raims-api-key-permission": { "code": "withdrawals_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Quantidade de registros considerados para a página. A lista pode ter menos destinos e ainda indicar uma próxima página; continue enquanto page.has_next for true." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.next_after para avançar. Copie o valor inteiro e mantenha a mesma chave de API. Não envie junto de before." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor recebido em page.previous_before para voltar. Copie o valor inteiro e mantenha a mesma chave de API. Não envie junto de after." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalDestinationListResponse" }, "examples": { "destinations": { "summary": "Destino padrão da empresa", "value": { "list": [ { "id": "wdst_3AbHiWSrsZBoaTg47OcMzC", "key_type": "CNPJ", "key_masked": "***0195", "holder_name": "Empresa Exemplo Ltda.", "bank_ispb": "12345678", "is_default": true, "verified_at": 1792047600 } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "no_destinations": { "summary": "Nenhum destino disponível", "value": { "list": [], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "A resposta não deve ser armazenada em cache." } }, "description": "Destinos próprios verificados e cursores para continuar a consulta. Uma página vazia não encerra a navegação quando page.has_next for true." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_cursor": { "summary": "Cursor incompatível ou inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "INVALID_CURSOR", "message": "after is invalid or cannot be used with these filters. Use a cursor returned by a matching list request." } ] } } }, "exclusive_cursors": { "summary": "Cursores enviados juntos", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "after", "code": "MUTUALLY_EXCLUSIVE", "message": "after cannot be used together with before." }, { "field": "before", "code": "MUTUALLY_EXCLUSIVE", "message": "before cannot be used together with after." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A consulta contém parâmetros inválidos. Confira os detalhes do campo e use os cursores retornados por esta listagem." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "sandbox_not_supported": { "summary": "Consulta com chave Sandbox", "value": { "error": { "code": "DATA_ENVIRONMENT_NOT_SUPPORTED", "message": "This endpoint is available only in Production. Use a Production API key outside the documentation console." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Destinos de saque exigem Produção. Use uma chave de Produção no servidor da integração; o console desta documentação aceita somente Sandbox." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Listar destinos de saque", "description": "Consulte os destinos Pix próprios verificados e identifique o padrão antes de solicitar um saque. A consulta exige uma chave de Produção." } }, "/v1/withdrawals/limits": { "get": { "operationId": "GetWithdrawalLimits", "x-raims-api-key-permission": { "code": "withdrawals_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalLimits" }, "examples": { "production": { "summary": "Condições de saque em Produção", "value": { "minimum_amount_cents": 200, "fee_threshold_amount_cents": 50000, "fee_below_threshold_cents": 100, "available_amount_cents": 150000, "destination_configured": true, "limits": { "day_limit_cents": 5000000, "night_limit_cents": 1000000, "period_limit_cents": 5000000, "period_used_cents": 125000, "period_remaining_cents": 4875000, "request_maximum_amount_cents": 4875000, "period": "day", "period_ends_at": 1792054800 } } }, "sandbox": { "summary": "Condições no Sandbox", "value": { "minimum_amount_cents": 200, "fee_threshold_amount_cents": 50000, "fee_below_threshold_cents": 100, "available_amount_cents": 150000, "destination_configured": false, "limits": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "As condições financeiras da conta não devem ser armazenadas em cache." } }, "description": "Condições atuais de saque. Em Produção, informa se há destino cadastrado e os limites disponíveis para consulta. No Sandbox, retorna o saldo simulado, destination_configured false e limits null." }, "400": { "$ref": "#/components/responses/InvalidAuthenticationEnvironment" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Consultar condições de saque", "description": "Consulte saldo disponível, mínimo, tarifa e limites de saque para planejar uma retirada. A consulta não reserva dinheiro nem limite e não garante que uma solicitação será aceita." } }, "/v1/withdrawals": { "post": { "operationId": "CreateWithdrawal", "x-raims-api-key-permission": { "code": "withdrawals_create", "resource": "withdrawals", "access": "write" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalRequest" }, "example": { "amount_cents": 25000 } } }, "description": "Valor que deseja retirar da conta Raims e, opcionalmente, o ID do destino padrão esperado. A requisição não cadastra nem altera o destino." }, "x-raims-max-body-bytes": 16384, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" }, "examples": { "completed": { "summary": "Solicitação repetida com saque concluído", "value": { "id": "wd_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 25000, "fee_amount_cents": 100, "net_amount_cents": 24900, "status": "COMPLETED", "failure_reason": null, "bank_account": null, "pix_destination": { "key_type": "CNPJ", "key_masked": "**.***.***/0001-**", "holder_name": "Empresa Exemplo", "bank_ispb": "12345678" }, "requested_at": 1791979200, "completed_at": 1791979260, "failed_at": null, "canceled_at": null } }, "failed": { "summary": "Solicitação repetida com falha confirmada", "value": { "id": "wd_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 25000, "fee_amount_cents": 100, "net_amount_cents": 24900, "status": "FAILED", "failure_reason": { "code": "BANK_TIMEOUT", "message": "The transfer did not complete within the expected time. Check your withdrawal history and contact Raims support before making another request." }, "bank_account": null, "pix_destination": { "key_type": "CNPJ", "key_masked": "**.***.***/0001-**", "holder_name": "Empresa Exemplo", "bank_ispb": "12345678" }, "requested_at": 1791979200, "completed_at": null, "failed_at": 1791979260, "canceled_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados do saque não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho da consulta individual do saque. Use-o para acompanhar o mesmo identificador." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Resultado final de uma solicitação já registrada. Confira status para distinguir conclusão de falha; receber esta resposta não inicia outra transferência." }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" }, "examples": { "pending": { "summary": "Saque aguardando processamento", "value": { "id": "wd_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 25000, "fee_amount_cents": 100, "net_amount_cents": 24900, "status": "PENDING", "failure_reason": null, "bank_account": null, "pix_destination": { "key_type": "CNPJ", "key_masked": "**.***.***/0001-**", "holder_name": "Empresa Exemplo", "bank_ispb": "12345678" }, "requested_at": 1791979200, "completed_at": null, "failed_at": null, "canceled_at": null } }, "processing": { "summary": "Saque em processamento", "value": { "id": "wd_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 25000, "fee_amount_cents": 100, "net_amount_cents": 24900, "status": "PROCESSING", "failure_reason": null, "bank_account": null, "pix_destination": { "key_type": "CNPJ", "key_masked": "**.***.***/0001-**", "holder_name": "Empresa Exemplo", "bank_ispb": "12345678" }, "requested_at": 1791979200, "completed_at": null, "failed_at": null, "canceled_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados do saque não devem ser armazenados em cache." }, "Location": { "schema": { "type": "string" }, "description": "Caminho da consulta individual do saque. Use-o para acompanhar o mesmo identificador." }, "Idempotency-Key": { "$ref": "#/components/headers/IdempotencyKey" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "description": "Saque aceito e ainda sem conclusão confirmada. Guarde o id retornado e acompanhe a consulta individual indicada em Location. Uma resposta aceita não confirma o crédito no destino." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "required_amount": { "summary": "Valor do saque ausente", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "amount_cents", "code": "REQUIRED", "message": "amount_cents is required." } ] } } }, "invalid_amount": { "summary": "Valor incompatível com as condições de saque", "value": { "error": { "code": "PIX_WITHDRAWAL_AMOUNT_INVALID", "message": "The withdrawal amount must comply with the minimum, maximum and fee requirements. Consult the withdrawal limits." } } }, "client_context_unavailable": { "summary": "Origem da requisição indisponível", "value": { "error": { "code": "PIX_WITHDRAWAL_CLIENT_CONTEXT_UNAVAILABLE", "message": "The request source could not be identified. Contact Raims support if the problem persists." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um campo inválido ou não foi possível identificar a origem da requisição. Confira error.code e, nas validações, error.details antes de corrigir o envio." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "production_only": { "summary": "Chave Sandbox usada para solicitar saque", "value": { "error": { "code": "PIX_WITHDRAWAL_PRODUCTION_ONLY", "message": "Withdrawal requests are available only in Production. Use a Production API key." } } }, "account_not_approved": { "summary": "Conta sem aprovação para saques", "value": { "error": { "code": "FINANCIAL_ACCOUNT_NOT_APPROVED", "message": "The financial account is not approved for withdrawals. Check the account notices in the Dashboard." } } }, "withdrawals_unavailable": { "summary": "Saques indisponíveis para a conta", "value": { "error": { "code": "WITHDRAWAL_TEMPORARILY_UNAVAILABLE", "message": "Withdrawals are not currently authorized for this account. Check the account notices in the Dashboard." } } }, "company_restricted": { "summary": "Conta com restrição para saque", "value": { "error": { "code": "PIX_WITHDRAWAL_COMPANY_RESTRICTED", "message": "Withdrawals are not currently authorized for this account. Check the account notices in the Dashboard." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A chave ou a conta não permite esta solicitação. Saques exigem uma chave de Produção e uma conta autorizada a retirar valores. Confira os avisos da conta no Dashboard." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "destination_required": { "summary": "Destino próprio não configurado", "value": { "error": { "code": "PIX_WITHDRAWAL_DESTINATION_REQUIRED", "message": "A verified withdrawal destination is required. Configure and select your company's own Pix destination in the Dashboard." } } }, "destination_changed": { "summary": "Destino alterado ou inválido", "value": { "error": { "code": "PIX_WITHDRAWAL_DESTINATION_CHANGED", "message": "The selected withdrawal destination changed or is no longer valid. Check your destination and withdrawal history in the Dashboard." } } }, "source_unavailable": { "summary": "Conta de origem indisponível", "value": { "error": { "code": "PIX_WITHDRAWAL_SOURCE_UNAVAILABLE", "message": "The source account is not available for this withdrawal. Check the account notices in the Dashboard." } } }, "insufficient_balance": { "summary": "Saldo disponível insuficiente", "value": { "error": { "code": "PIX_WITHDRAWAL_INSUFFICIENT_BALANCE", "message": "There is not enough available balance for the requested amount, including its fee. Consult the current balance and withdrawal limits." } } }, "period_limit_reached": { "summary": "Limite de saque excedido", "value": { "error": { "code": "PIX_WITHDRAWAL_PERIOD_LIMIT_REACHED", "message": "The withdrawal exceeds the remaining Pix limit. Consult the current withdrawal limits before trying again." } } }, "period_changed": { "summary": "Período do limite alterado", "value": { "error": { "code": "PIX_WITHDRAWAL_PERIOD_CHANGED", "message": "The Pix limit period changed during the request. Consult the current limits and withdrawal history before trying again." } } }, "request_conflict": { "summary": "Solicitação anterior com dados diferentes", "value": { "error": { "code": "PIX_WITHDRAWAL_REQUEST_CONFLICT", "message": "This request identifies a withdrawal with different data. Consult the existing withdrawal before making another request." } } }, "result_unknown": { "summary": "Resultado da solicitação não confirmado", "value": { "error": { "code": "PIX_WITHDRAWAL_RESULT_UNKNOWN", "message": "The withdrawal request result could not be confirmed. Retrieve the withdrawal identified by the Location header before making another request." } } }, "expected_destination_changed": { "summary": "Destino padrão diferente do esperado", "value": { "error": { "code": "WITHDRAWAL_DESTINATION_CHANGED", "message": "The expected withdrawal destination is no longer the verified default. Retrieve the current withdrawal destinations and review the request before trying again." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Location": { "schema": { "type": "string" }, "description": "Caminho da consulta do saque quando a resposta exige conferir um resultado não confirmado. Pode estar ausente nas demais recusas." } }, "description": "O saque não pôde ser solicitado nas condições atuais ou seu resultado precisa ser conferido. Consulte saldo, limites e histórico conforme error.code. Em PIX_WITHDRAWAL_RESULT_UNKNOWN, acompanhe o saque indicado em Location antes de outra solicitação." }, "413": { "$ref": "#/components/responses/RequestTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Solicitar saque", "description": "Solicite um saque Pix para a chave padrão da própria empresa cadastrada no Dashboard. O valor solicitado inclui a tarifa. Para exigir o destino padrão que você conferiu, informe expected_destination_id. Guarde o identificador e acompanhe o mesmo saque enquanto o resultado estiver pendente." }, "get": { "operationId": "ListWithdrawals", "x-raims-api-key-permission": { "code": "withdrawals_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "example": 10 }, "description": "Quantidade de saques por página." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor next_after retornado na página anterior. Mantenha os mesmos filtros e a mesma ordem da consulta." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Cursor previous_before retornado na página seguinte. Mantenha os mesmos filtros e a mesma ordem da consulta." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100, "pattern": "^(?:PENDING|PROCESSING|COMPLETED|FAILED|CANCELED)(?:\\s*,\\s*(?:PENDING|PROCESSING|COMPLETED|FAILED|CANCELED))*$", "example": "COMPLETED" }, "description": "Filtre por um ou mais estados separados por vírgula: PENDING, PROCESSING, COMPLETED, FAILED ou CANCELED." }, { "name": "requested_gte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 253402300799, "example": 1791878400 }, "description": "Retorne saques solicitados a partir deste instante, inclusive. Informe segundos Unix UTC." }, { "name": "requested_lte", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 253402300799, "example": 1791964800 }, "description": "Retorne saques solicitados até este instante, inclusive. Informe segundos Unix UTC." }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "desc" }, "description": "Ordenação pela data de solicitação: desc mostra os mais recentes primeiro; asc mostra os mais antigos primeiro." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalListResponse" }, "examples": { "completed": { "summary": "Saque concluído", "value": { "list": [ { "id": "wd_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 10000, "fee_amount_cents": 100, "net_amount_cents": 9900, "status": "COMPLETED", "failure_reason": null, "bank_account": null, "pix_destination": { "key_type": "CNPJ", "key_masked": "**.***.***/0001-**", "holder_name": "Empresa Exemplo", "bank_ispb": "12345678" }, "requested_at": 1791878400, "completed_at": 1791878460, "failed_at": null, "canceled_at": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "failed": { "summary": "Saque com falha confirmada", "value": { "list": [ { "id": "wd_0", "amount_cents": 10000, "fee_amount_cents": 149, "net_amount_cents": 9851, "status": "FAILED", "failure_reason": { "code": "BANK_TIMEOUT", "message": "The transfer did not complete within the expected time. Check your withdrawal history and contact Raims support before making another request." }, "bank_account": null, "pix_destination": null, "requested_at": 1791979200, "completed_at": null, "failed_at": 1791979320, "canceled_at": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } }, "unknown_failure": { "summary": "Saque sem motivo detalhado de falha", "value": { "list": [ { "id": "wd_0", "amount_cents": 10000, "fee_amount_cents": 149, "net_amount_cents": 9851, "status": "FAILED", "failure_reason": { "code": "WITHDRAWAL_FAILURE_REASON_UNAVAILABLE", "message": "No confirmed failure reason is available for this withdrawal. Check your withdrawal history and contact Raims support if needed." }, "bank_account": null, "pix_destination": null, "requested_at": 1791979200, "completed_at": null, "failed_at": 1791979320, "canceled_at": null } ], "page": { "page_size": 10, "has_next": false, "has_previous": false, "next_after": null, "previous_before": null } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados financeiros não devem ser armazenados em cache." } }, "description": "Saques encontrados e cursores de navegação. Uma consulta sem resultados retorna list vazia." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_field": { "summary": "Estado inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "status", "code": "INVALID_VALUE", "message": "status must contain one or more of these names, separated by commas: PENDING, PROCESSING, COMPLETED, FAILED, CANCELED." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um parâmetro inválido. Confira error.details para identificar o campo e o formato aceito." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Listar saques", "description": "Consulte o histórico de saques da sua empresa. Use os filtros de status e período para acompanhar as transferências e conferir as saídas do extrato. A consulta considera o ambiente autenticado." } }, "/v1/withdrawals/{id}": { "get": { "operationId": "GetWithdrawal", "x-raims-api-key-permission": { "code": "withdrawals_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wd_[A-Za-z0-9]+$", "maxLength": 100, "example": "wd_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador do saque, com prefixo wd_." } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" }, "examples": { "completed": { "summary": "Saque concluído", "value": { "id": "wd_3AbHiWSrsZBoaTg47OcMzC", "amount_cents": 10000, "fee_amount_cents": 100, "net_amount_cents": 9900, "status": "COMPLETED", "failure_reason": null, "bank_account": null, "pix_destination": { "key_type": "CNPJ", "key_masked": "**.***.***/0001-**", "holder_name": "Empresa Exemplo", "bank_ispb": "12345678" }, "requested_at": 1791878400, "completed_at": 1791878460, "failed_at": null, "canceled_at": null } }, "failed": { "summary": "Saque com falha confirmada", "value": { "id": "wd_0", "amount_cents": 10000, "fee_amount_cents": 149, "net_amount_cents": 9851, "status": "FAILED", "failure_reason": { "code": "BANK_TIMEOUT", "message": "The transfer did not complete within the expected time. Check your withdrawal history and contact Raims support before making another request." }, "bank_account": null, "pix_destination": null, "requested_at": 1791979200, "completed_at": null, "failed_at": 1791979320, "canceled_at": null } }, "unknown_failure": { "summary": "Saque sem motivo detalhado de falha", "value": { "id": "wd_0", "amount_cents": 10000, "fee_amount_cents": 149, "net_amount_cents": 9851, "status": "FAILED", "failure_reason": { "code": "WITHDRAWAL_FAILURE_REASON_UNAVAILABLE", "message": "No confirmed failure reason is available for this withdrawal. Check your withdrawal history and contact Raims support if needed." }, "bank_account": null, "pix_destination": null, "requested_at": 1791979200, "completed_at": null, "failed_at": 1791979320, "canceled_at": null } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Os dados financeiros não devem ser armazenados em cache." } }, "description": "Dados do saque no momento da consulta. A requisição não solicita, cancela nem repete uma transferência." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_field": { "summary": "Identificador inválido", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "id", "code": "INVALID_IDENTIFIER", "message": "id must be a valid withdrawal identifier returned by Raims." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Há um parâmetro inválido. Confira error.details para identificar o campo e o formato aceito." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "not_found": { "summary": "Saque não encontrado", "value": { "error": { "code": "NOT_FOUND", "message": "The withdrawal specified by id was not found." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "O saque não foi encontrado na empresa e no ambiente autenticado." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Saques" ], "summary": "Recuperar um saque", "description": "Consulte o status, os valores e o destino de um saque pelo identificador. Use o mesmo ID que aparece no histórico de saques ou na referência do extrato." } }, "/v1/withdrawals/summary": { "get": { "operationId": "GetWithdrawalSummary", "x-raims-api-key-permission": { "code": "withdrawals_read", "resource": "withdrawals", "access": "read" }, "security": [ { "BearerAuth": [] }, { "ApplicationOAuth": [ "raims:api" ] } ], "parameters": [ { "$ref": "#/components/parameters/OAuthProductionEnvironment" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalSummary" }, "examples": { "processing": { "summary": "Saques que aguardam conclusão", "value": { "processing_count": 3, "processing_amount_cents": 175000 } }, "empty": { "summary": "Nenhum saque pendente ou em processamento", "value": { "processing_count": 0, "processing_amount_cents": 0 } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "O resumo financeiro não deve ser armazenado em cache." } }, "description": "Quantidade e valor total dos saques pendentes ou em processamento. O valor inclui a tarifa e não representa crédito confirmado no destino. Os dois campos retornam zero quando não houver saques nessas situações." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknown_query": { "summary": "Parâmetro de consulta não aceito", "value": { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "period", "code": "UNKNOWN_QUERY_PARAMETER", "message": "period is not a supported query parameter. Remove it from the request URL." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Esta consulta não aceita corpo nem parâmetros de consulta. Remova os dados indicados nos detalhes do erro." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "production_only": { "summary": "Consulta indisponível no Sandbox", "value": { "error": { "code": "DATA_ENVIRONMENT_NOT_SUPPORTED", "message": "This endpoint is available only in Production. Use a Production API key outside the documentation console." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "A consulta exige uma chave de API de Produção. O Sandbox não oferece este resumo de saques." }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/StoreUnavailable" } }, "tags": [ "Informações financeiras" ], "summary": "Consultar saques em processamento", "description": "Consulte a quantidade e o valor total dos saques pendentes ou em processamento da empresa. A consulta exige uma chave de API de Produção e não altera o andamento dos pedidos." } } }, "components": { "parameters": { "OAuthEnvironment": { "name": "X-Raims-Environment", "in": "header", "required": false, "x-raims-security-schemes": [ "ApplicationOAuth" ], "schema": { "type": "string", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" }, "description": "Ambiente da requisição OAuth. Informe Sandbox para testes ou Production para dados reais, conforme o acesso autorizado. Com chave de API, o ambiente é definido pela própria chave; não envie este header." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]{1,255}$", "example": "b2816b4f-7c18-4bc4-a1d4-fc01cde750d0" }, "description": "Chave única escolhida pelo seu sistema para identificar esta requisição. Ao repetir a tentativa, envie a mesma chave e os mesmos parâmetros. Sem este header, a requisição é processada normalmente. Consulte o guia de idempotência para os prazos e o tratamento de respostas pendentes ou incertas." }, "OAuthSandboxEnvironment": { "name": "X-Raims-Environment", "in": "header", "required": false, "x-raims-security-schemes": [ "ApplicationOAuth" ], "schema": { "type": "string", "enum": [ "Sandbox" ], "example": "Sandbox" }, "description": "Ambiente da requisição OAuth. Esta operação aceita somente Sandbox. Com chave de API, use uma chave Sandbox e não envie este header." }, "OAuthProductionEnvironment": { "name": "X-Raims-Environment", "in": "header", "required": false, "x-raims-security-schemes": [ "ApplicationOAuth" ], "schema": { "type": "string", "enum": [ "Production" ], "example": "Production" }, "description": "Ambiente da requisição OAuth. Esta operação aceita somente Production. Com chave de API, use uma chave de Produção e não envie este header." } }, "headers": { "RequestId": { "required": true, "schema": { "type": "string", "minLength": 5, "pattern": "^req_[A-Za-z0-9]+$", "example": "req_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Identificador desta tentativa HTTP, gerado pela Raims em cada resposta processada pela API. Informe este valor ao suporte ao investigar a requisição. Uma nova tentativa recebe outro identificador, inclusive em replay de idempotência." }, "LegacyRequestId": { "required": true, "schema": { "type": "string", "minLength": 5, "pattern": "^req_[A-Za-z0-9]+$", "example": "req_3AbHiWSrsZBoaTg47OcMzC" }, "description": "Alias de compatibilidade de Request-Id, com o mesmo valor. Prefira Request-Id em novas integrações." }, "IdempotencyKey": { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!-~]{1,255}$" }, "description": "Chave de idempotência informada na requisição, quando aceita." }, "IdempotencyReplayed": { "schema": { "type": "boolean", "const": true }, "description": "Presente com true quando o status e o corpo repetem a resposta preservada da primeira tentativa." } }, "schemas": { "Charge": { "type": "object", "required": [ "id", "customer_id", "amount_cents", "payment_method", "checkout_payment_method", "due_date", "title", "description", "status", "created_at", "checkout_url", "is_payable", "payment_information", "payment_method_types", "external_reference", "metadata" ], "properties": { "id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança." }, "customer_id": { "type": "string", "description": "Identificador público do cliente vinculado." }, "amount_cents": { "type": "integer", "format": "int64", "description": "Valor da cobrança em centavos de real." }, "payment_method": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Meio de pagamento da cobrança: 0 indefinido, 1 Pix, 2 boleto, 3 cartão de crédito e 4 cartão de débito. O valor 0 pode mudar para 1 ou 2 quando o Pix ou boleto é gerado no checkout. A escolha do checkout aparece separadamente em checkout_payment_method." }, "checkout_payment_method": { "type": [ "integer", "null" ], "enum": [ 0, 1, 2, 3, 4, null ], "description": "Meio de pagamento informado pelo checkout: 0 indefinido, 1 Pix, 2 boleto, 3 cartão de crédito e 4 cartão de débito. null quando essa informação ainda não estiver disponível. A seleção de uma opção na tela não confirma a geração do pagamento nem que a cobrança foi paga." }, "due_date": { "type": "integer", "format": "int64", "description": "Vencimento da cobrança em segundos Unix UTC." }, "title": { "type": [ "string", "null" ], "description": "Título da cobrança, ou null quando não informado." }, "description": { "type": [ "string", "null" ], "description": "Descrição da cobrança, ou null quando não informada." }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "Status da cobrança, considerando o vencimento. 0 criado, 1 aguardando pagamento, 2 autorizado, 3 em processamento, 4 pago, 5 parcialmente devolvido, 6 devolvido, 7 cancelado, 8 expirado, 9 falha, 10 chargeback, 11 chargeback em análise, 12 chargeback perdido e 13 chargeback ganho." }, "created_at": { "type": "integer", "format": "int64", "description": "Instante de criação em segundos Unix UTC." }, "checkout_url": { "type": [ "string", "null" ], "description": "Link para o pagador abrir o checkout, ou null quando não houver link disponível." }, "is_payable": { "type": "boolean", "description": "Indica se a cobrança pode ser paga. Os dados de Pix ou boleto ainda podem estar ausentes em payment_information; consulte status para acompanhar o pagamento." }, "payment_information": { "$ref": "#/components/schemas/ChargePaymentInformation", "description": "Instruções de pagamento e resultado da emissão de Pix ou boleto. pix e boleto são null quando os dados não estão disponíveis." }, "payment_method_types": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "example": [ 1, 2 ], "description": "Lista de meios configurada para a cobrança, ou null quando ela usa a configuração de checkout herdada. 1 significa Pix e 2 significa boleto. A lista não muda com o meio usado no pagamento nem representa a disponibilidade momentânea do checkout." }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Referência do pedido ou da cobrança no seu sistema, ou null quando não informada. É independente da referência do cliente e pode ser repetida em outras cobranças." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dados de integração associados ao recurso. Retorna {} quando não há valores. Esse mapa não é usado como filtro de busca nem incluído automaticamente nos eventos de webhook.", "example": { "pedido": "12345", "filial": "matriz" } } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/Error", "description": "Código e explicação do erro retornado pela API." } } }, "UpdateChargeRequest": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": [ "string", "null" ], "maxLength": 512, "description": "Título da cobrança. Omita para manter o título atual; envie null ou texto vazio para removê-lo.", "example": "Serviço atualizado" }, "description": { "type": [ "string", "null" ], "maxLength": 512, "description": "Descrição da cobrança. Omita para manter a descrição atual; envie null ou texto vazio para removê-la.", "example": "Descrição atualizada da cobrança" }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "example": "pedido_12345_atualizado", "description": "Referência do pedido ou da cobrança no seu sistema. Omita para manter o valor atual; envie null ou texto vazio para removê-lo. Pode ser repetida em outras cobranças e é independente da referência do cliente." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "null" ], "maxLength": 500 }, "maxProperties": 32, "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[A-Za-z0-9_.-]+$" }, "x-raims-max-utf8-bytes": 8192, "description": "Dados de integração associados ao recurso. Informe pares de chave e texto. Chaves diferenciam maiúsculas de minúsculas. Omitir ou enviar {} preserva os dados; null remove todos os pares, e null em uma chave remove somente essa chave. Texto vazio é um valor válido.", "example": { "pedido": "12345", "filial": "matriz" } } } }, "ChargeRevoked": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "revoked", "revocation_pending" ], "properties": { "id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança." }, "status": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 13, "description": "Estado atual da cobrança, considerando o vencimento.", "const": 7 }, "revoked": { "type": "boolean", "const": true, "description": "Indica que a revogação foi confirmada." }, "revocation_pending": { "type": "boolean", "const": false, "description": "Indica que o cancelamento ainda aguarda confirmação." } } }, "ChargeRevocationPending": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "revoked", "revocation_pending" ], "properties": { "id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança." }, "status": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 13, "description": "Status atual da cobrança, considerando o vencimento." }, "revoked": { "type": "boolean", "const": false, "description": "Indica que a revogação foi confirmada." }, "revocation_pending": { "type": "boolean", "const": true, "description": "Indica que o cancelamento ainda aguarda confirmação." } } }, "ChargeListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "description": "Cobranças encontradas na empresa e no ambiente autenticado.", "items": { "$ref": "#/components/schemas/ChargeListItem" } }, "page": { "$ref": "#/components/schemas/ChargeListPage", "description": "Informações para continuar ou voltar na listagem." } } }, "CreateChargeRequest": { "type": "object", "additionalProperties": false, "required": [ "customer_id", "amount_cents", "due_date" ], "properties": { "customer_id": { "type": "string", "maxLength": 100, "pattern": "^cus_[A-Za-z0-9]+$", "example": "cus_1Q2W3E4R5T6Y7U8I9O0P", "description": "ID de um cliente da empresa e do ambiente autenticado. Copie o id retornado no cadastro ou na consulta. Pix direto exige CPF/CNPJ válido. Boleto direto exige nome, e-mail válido, CPF/CNPJ e endereço, incluindo CEP e número; complete esses dados no cadastro do cliente." }, "amount_cents": { "type": "integer", "format": "int64", "minimum": 100, "maximum": 999999999999, "example": 10000, "description": "Valor da cobrança em centavos de real. Por exemplo, 10000 representa R$ 100,00." }, "payment_method": { "type": "integer", "enum": [ 0, 1, 2 ], "default": 0, "x-raims-enum-labels": [ "Indefinido", "Pix", "Boleto" ], "example": 0, "description": "Meio da cobrança. Omitir ou enviar 0 permite escolher no checkout. Sem payment_method_types, 1 solicita Pix e 2 solicita boleto na criação, conforme os meios habilitados. Boleto usa o endereço do cliente e completa campos ausentes pelo CEP quando disponíveis. Com lista própria, envie 0 ou omita este campo; a emissão acontece após a escolha no checkout." }, "due_date": { "type": "integer", "format": "int64", "example": 1893456000, "description": "Vencimento em segundos Unix UTC, pelo menos cinco minutos no futuro. A data máxima é hoje mais dez anos, no calendário de São Paulo." }, "title": { "type": [ "string", "null" ], "maxLength": 512, "example": "Serviço contratado", "description": "Título da cobrança. Você pode deixar este campo vazio." }, "description": { "type": [ "string", "null" ], "maxLength": 512, "example": "Cobrança do serviço", "description": "Descrição da cobrança. Você pode deixar este campo vazio." }, "send_email": { "type": "boolean", "default": false, "example": false, "description": "Com true, solicita o envio da cobrança ao e-mail do cliente e gera checkout_url. Em contas pendentes, o cliente precisa ter o mesmo e-mail principal da conta. Fora dessa condição, um e-mail ausente ou inválido impede o envio, mas permite criar a cobrança quando não houver emissão direta de boleto. Boleto direto exige e-mail válido mesmo com false. A resposta não confirma a entrega da mensagem." }, "create_checkout": { "type": "boolean", "default": false, "example": true, "description": "Com true, gera o link retornado em checkout_url, sem exigir uma URL de retorno nem solicitar envio de e-mail. Com false, o link ainda é gerado quando send_email é true ou uma URL de retorno é informada." }, "success_redirect_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "example": "https://loja.example.com/pagamento/concluido", "description": "URL HTTPS do seu site para retorno após a confirmação do pagamento. O redirecionamento não comprova o pagamento; consulte a cobrança para confirmá-lo. Não aceita credenciais no endereço, IP literal, localhost ou domínio Raims. Quando preenchida, gera checkout_url mesmo com send_email false. Se omitida, vazia ou null, o retorno não é definido." }, "cancel_redirect_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "example": "https://loja.example.com/carrinho", "description": "URL HTTPS do seu site para o pagador voltar pelo checkout. Voltar não cancela a cobrança, o Pix ou o boleto. Não aceita credenciais no endereço, IP literal, localhost ou domínio Raims. Quando preenchida, gera checkout_url mesmo com send_email false. Se omitida, vazia ou null, o retorno não é definido." }, "payment_method_types": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "example": [ 1, 2 ], "description": "Meios permitidos para a cobrança: 1 para Pix e 2 para boleto. Omitir ou enviar null usa a configuração de checkout herdada. Informe uma lista sem repetições. A configuração própria substitui o padrão da conta; uma configuração do link pode apenas restringir essa lista. Combine com payment_method omitido ou 0." }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "example": "pedido_12345", "description": "Referência do pedido ou da cobrança no seu sistema. Null, vazio ou somente espaços deixam sem referência. Pode ser repetida e não evita cobranças duplicadas. É diferente da referência do cadastro do cliente." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "null" ], "maxLength": 500 }, "maxProperties": 32, "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[A-Za-z0-9_.-]+$" }, "x-raims-max-utf8-bytes": 8192, "description": "Dados de integração associados à cobrança, em pares de chave e texto. Chaves diferenciam maiúsculas de minúsculas. Omitir, enviar null ou {} cria a cobrança sem esses dados; pares com valor null não são incluídos. Texto vazio é um valor válido.", "example": { "pedido": "12345", "filial": "matriz" } } } }, "ChargeCreated": { "type": "object", "required": [ "id", "customer_id", "amount_cents", "payment_method", "due_date", "title", "description", "status", "created_at", "checkout_url", "payment_information", "payment_method_types", "external_reference", "metadata" ], "properties": { "id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança criada." }, "customer_id": { "type": "string", "description": "Identificador público do cliente vinculado." }, "amount_cents": { "type": "integer", "format": "int64", "description": "Valor da cobrança em centavos de real." }, "payment_method": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "Meio da cobrança. Com lista própria, retorna 0 até a emissão do pagamento. Sem lista, 1 solicita Pix direto e 2 solicita boleto direto. A lista de meios permanece separada da escolha registrada." }, "due_date": { "type": "integer", "format": "int64", "description": "Vencimento da cobrança em segundos Unix UTC." }, "title": { "type": [ "string", "null" ], "description": "Título da cobrança, ou null quando não informado." }, "description": { "type": [ "string", "null" ], "description": "Descrição da cobrança, ou null quando não informada." }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "Status da cobrança, considerando o vencimento. 0 criado, 1 aguardando pagamento, 2 autorizado, 3 em processamento, 4 pago, 5 parcialmente devolvido, 6 devolvido, 7 cancelado, 8 expirado, 9 falha, 10 chargeback, 11 chargeback em análise, 12 chargeback perdido e 13 chargeback ganho." }, "created_at": { "type": "integer", "format": "int64", "description": "Instante de criação em segundos Unix UTC." }, "checkout_url": { "type": [ "string", "null" ], "description": "Link para o pagador abrir o checkout. É retornado quando create_checkout ou send_email é true, ou uma URL de retorno é informada; nos demais casos, é null. O link não comprova pagamento nem entrega de e-mail." }, "payment_method_types": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "example": [ 1, 2 ], "description": "Lista de meios configurada para a cobrança, ou null quando ela usa a configuração de checkout herdada. 1 significa Pix e 2 significa boleto. A lista não muda com o meio usado no pagamento nem representa a disponibilidade momentânea do checkout." }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Referência do pedido ou da cobrança no seu sistema, ou null quando não informada. É independente da referência do cliente e pode ser repetida em outras cobranças." }, "payment_information": { "$ref": "#/components/schemas/ChargePaymentInformation", "description": "Instruções de pagamento e resultado da emissão de Pix ou boleto. Sem lista própria, payment_method 1 solicita Pix e 2 solicita boleto. Confira pix_status ou boleto_status e os dados do meio solicitado." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dados de integração associados ao recurso. Retorna {} quando não há valores. Esse mapa não é usado como filtro de busca nem incluído automaticamente nos eventos de webhook.", "example": { "pedido": "12345", "filial": "matriz" } } }, "additionalProperties": false }, "CreateCustomerRequest": { "type": "object", "additionalProperties": false, "required": [ "tax_id" ], "properties": { "full_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Nome completo do pagador." }, "tax_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "CPF ou CNPJ válido, com ou sem pontos, barra, hífen e espaços." }, "email": { "type": [ "string", "null" ], "maxLength": 254, "description": "E-mail do pagador. Cadastrar o e-mail não envia uma mensagem." }, "dial_code": { "type": [ "string", "null" ], "maxLength": 5, "description": "Código de discagem internacional. Pode ser informado sem phone_local." }, "phone_local": { "type": [ "string", "null" ], "maxLength": 20, "description": "Número de telefone sem o código de discagem, com ou sem pontuação. Pode ser informado sem dial_code." }, "zip_code": { "type": [ "string", "null" ], "maxLength": 15, "description": "CEP do endereço, com ou sem hífen. Se street, neigh, city, uf, street_number e complement estiverem vazios, o CEP pode preencher rua, bairro, cidade e estado. O preenchimento não inclui número nem complemento." }, "street": { "type": [ "string", "null" ], "maxLength": 120, "description": "Logradouro do endereço." }, "street_number": { "type": [ "string", "null" ], "maxLength": 10, "description": "Número do endereço." }, "complement": { "type": [ "string", "null" ], "maxLength": 40, "description": "Complemento do endereço." }, "neigh": { "type": [ "string", "null" ], "maxLength": 80, "description": "Bairro do endereço." }, "city": { "type": [ "string", "null" ], "maxLength": 80, "description": "Cidade do endereço." }, "uf": { "type": [ "string", "null" ], "maxLength": 5, "description": "Sigla do estado, como SP." }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Identificador do cliente no seu sistema. Para um cliente já cadastrado, omita para manter a referência ou envie null ou texto vazio para removê-la. Use external_reference na listagem de clientes para buscar esse valor.", "example": "cliente_12345" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "null" ], "maxLength": 500 }, "maxProperties": 32, "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[A-Za-z0-9_.-]+$" }, "x-raims-max-utf8-bytes": 8192, "description": "Dados de integração associados ao recurso. Informe pares de chave e texto. Chaves diferenciam maiúsculas de minúsculas. Omitir ou enviar {} preserva os dados; null remove todos os pares, e null em uma chave remove somente essa chave. Texto vazio é um valor válido.", "example": { "pedido": "12345", "filial": "matriz" } } } }, "CustomerCreated": { "type": "object", "additionalProperties": false, "required": [ "id", "metadata", "external_reference", "object", "tax_id", "tax_id_type", "created_at" ], "properties": { "id": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "description": "Identificador público do cliente para reutilizar nas próximas requisições." }, "object": { "type": "string", "const": "customer", "description": "Tipo do recurso retornado." }, "tax_id": { "type": "string", "maxLength": 20, "description": "CPF ou CNPJ do cliente." }, "tax_id_type": { "type": "string", "enum": [ "cpf", "cnpj" ], "description": "Tipo do documento do cliente: cpf ou cnpj." }, "created_at": { "type": "integer", "format": "int64", "description": "Instante da criação em segundos Unix UTC." }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Identificador do cliente no seu sistema, quando informado." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dados de integração associados ao recurso. Retorna {} quando não há valores. Esse mapa não é usado como filtro de busca nem incluído automaticamente nos eventos de webhook.", "example": { "pedido": "12345", "filial": "matriz" } } } }, "CustomerListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "description": "Clientes encontrados na empresa e no ambiente autenticado.", "items": { "$ref": "#/components/schemas/CustomerListItem" } }, "page": { "$ref": "#/components/schemas/CustomerListPage", "description": "Informações para continuar ou voltar na listagem." } } }, "CustomerBatchDeleted": { "type": "object", "required": [ "removed", "blocked", "invalid", "errors" ], "properties": { "removed": { "type": "array", "items": { "type": "string" }, "description": "IDs dos clientes removidos, incluindo os que já haviam sido removidos." }, "blocked": { "type": "array", "items": { "type": "string" }, "description": "IDs dos clientes com cobranças vinculadas ainda não removidas, inclusive pagas." }, "invalid": { "type": "array", "items": { "type": [ "string", "null" ] }, "description": "Valores inválidos, de clientes inexistentes ou de clientes que sua autenticação não permite acessar." }, "errors": { "type": "array", "description": "Motivo de cada item não removido, com campo identifiers[índice], código e explicação em inglês. Um lote sem falhas retorna uma lista vazia.", "items": { "$ref": "#/components/schemas/FieldError" } } }, "additionalProperties": false }, "RemoveCustomersRequest": { "type": "object", "additionalProperties": false, "required": [ "identifiers" ], "properties": { "identifiers": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": [ "string", "null" ] }, "description": "IDs dos clientes que deseja remover. IDs repetidos não geram mais de uma remoção. IDs inválidos ou de clientes que a chave não pode acessar aparecem em invalid." } } }, "CustomerListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "metadata", "external_reference", "name", "first_name", "last_name", "email", "tax_id", "tax_id_type", "dial_code", "phone_local", "zip_code", "street", "street_number", "complement", "neigh", "city", "state", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Identificador público do cliente.", "pattern": "^cus_[A-Za-z0-9]+$" }, "name": { "type": "string", "description": "Nome completo do cliente." }, "first_name": { "type": "string", "description": "Primeiro nome do cliente." }, "last_name": { "type": "string", "description": "Restante do nome do cliente." }, "email": { "type": "string", "description": "E-mail do cliente." }, "tax_id": { "type": "string", "description": "CPF ou CNPJ do cliente." }, "tax_id_type": { "type": "string", "description": "Tipo do documento: cpf ou cnpj.", "enum": [ "cpf", "cnpj" ] }, "dial_code": { "type": "string", "description": "Código de discagem internacional do telefone." }, "phone_local": { "type": "string", "description": "Número de telefone sem o código de discagem, somente com dígitos." }, "zip_code": { "type": "string", "description": "CEP do endereço." }, "street": { "type": "string", "description": "Logradouro." }, "street_number": { "type": "string", "description": "Número do endereço." }, "complement": { "type": [ "string", "null" ], "description": "Complemento do endereço, quando informado." }, "neigh": { "type": "string", "description": "Bairro." }, "city": { "type": "string", "description": "Cidade." }, "state": { "type": "string", "description": "Sigla do estado." }, "created_at": { "type": "integer", "description": "Instante da criação em segundos Unix UTC.", "format": "int64" }, "updated_at": { "type": "integer", "description": "Instante da atualização cadastral em segundos Unix UTC.", "format": "int64" }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Identificador do cliente no seu sistema, quando informado." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dados de integração associados ao recurso. Retorna {} quando não há valores. Esse mapa não é usado como filtro de busca nem incluído automaticamente nos eventos de webhook.", "example": { "pedido": "12345", "filial": "matriz" } } } }, "CustomerDeleted": { "type": "object", "additionalProperties": false, "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "description": "Identificador público do cliente removido na Raims." }, "deleted": { "type": "boolean", "const": true, "description": "Confirma que o cliente foi removido." } } }, "UpdateCustomerRequest": { "type": "object", "additionalProperties": false, "properties": { "full_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Nome completo do pagador. Omita para manter o valor atual; envie null ou texto vazio para removê-lo." }, "email": { "type": [ "string", "null" ], "maxLength": 254, "description": "E-mail do pagador. Atualizar o e-mail não envia uma mensagem. Omita para manter o valor atual; envie null ou texto vazio para removê-lo." }, "dial_code": { "type": [ "string", "null" ], "maxLength": 5, "description": "Código de discagem internacional. Pode ser informado sem phone_local. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "+55" }, "phone_local": { "type": [ "string", "null" ], "maxLength": 20, "description": "Número de telefone sem o código de discagem, com ou sem pontuação. Pode ser informado sem dial_code. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "11999999999" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 15, "description": "CEP do endereço, com ou sem hífen. Atualizar o CEP não preenche os outros campos de endereço. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "01310930" }, "street": { "type": [ "string", "null" ], "maxLength": 120, "description": "Logradouro do endereço. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "Avenida Paulista" }, "street_number": { "type": [ "string", "null" ], "maxLength": 10, "description": "Número do endereço. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "1000" }, "complement": { "type": [ "string", "null" ], "maxLength": 40, "description": "Complemento do endereço. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "Conjunto 101" }, "neigh": { "type": [ "string", "null" ], "maxLength": 80, "description": "Bairro do endereço. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "Bela Vista" }, "city": { "type": [ "string", "null" ], "maxLength": 80, "description": "Cidade do endereço. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "São Paulo" }, "uf": { "type": [ "string", "null" ], "maxLength": 5, "description": "Sigla do estado, como SP. Omita para manter o valor atual; envie null ou texto vazio para removê-lo.", "example": "SP" }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Identificador do cliente no seu sistema. Omita para manter a referência atual; envie null ou texto vazio para removê-la. Use external_reference na listagem de clientes para buscar esse valor.", "example": "cliente_12345" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "null" ], "maxLength": 500 }, "maxProperties": 32, "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[A-Za-z0-9_.-]+$" }, "x-raims-max-utf8-bytes": 8192, "description": "Dados de integração associados ao recurso. Informe pares de chave e texto. Chaves diferenciam maiúsculas de minúsculas. Omitir ou enviar {} preserva os dados; null remove todos os pares, e null em uma chave remove somente essa chave. Texto vazio é um valor válido.", "example": { "pedido": "12345", "filial": "matriz" } } }, "description": "Campos do perfil e dados de integração do cliente. Omita um campo para manter seu valor. Nos campos de texto, null ou texto vazio apagam o conteúdo. Em metadata, null remove todos os pares, {} preserva o mapa e null em uma chave remove somente essa chave. CPF/CNPJ e ID não podem ser alterados." }, "AccountFees": { "type": "object", "additionalProperties": false, "required": [ "pix", "boleto" ], "properties": { "pix": { "anyOf": [ { "$ref": "#/components/schemas/AccountFee" }, { "type": "null" } ], "description": "Condições vigentes para Pix, ou null quando não houver regra vigente para o plano selecionado." }, "boleto": { "anyOf": [ { "$ref": "#/components/schemas/AccountFee" }, { "type": "null" } ], "description": "Condições vigentes para boleto, ou null quando não houver regra vigente para o plano selecionado." } }, "description": "Condições comerciais atuais da empresa. A consulta não altera o plano e não informa tarifas aplicadas a pagamentos anteriores." }, "ChargeSimulation": { "type": "object", "additionalProperties": false, "required": [ "charge_id", "status", "amount_cents", "duplicate" ], "properties": { "charge_id": { "type": "string", "description": "ID público da cobrança simulada. Use o mesmo identificador ao consultar os resultados." }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "Estado registrado após a simulação: 4 corresponde a paga e 9 a falha." }, "amount_cents": { "type": "integer", "format": "int64", "description": "Valor da cobrança, em centavos de real. Confirmar o pagamento credita esse valor no saldo de teste uma única vez." }, "duplicate": { "type": "boolean", "description": "Indica que a cobrança já tinha o mesmo resultado. Nesse caso, a simulação não repete o efeito financeiro." } }, "description": "Resultado da simulação registrada na cobrança do Sandbox. Consulte saldo e extrato nos respectivos recursos." }, "AccountContext": { "type": "object", "additionalProperties": false, "required": [ "company_id", "company_name", "company_status", "data_environment", "checked_at", "access_revision", "currency", "amount_unit", "timestamp_unit", "business_timezone" ], "properties": { "company_id": { "type": "string", "pattern": "^co_[A-Za-z0-9]+$", "description": "Identificador público da empresa na Raims." }, "company_name": { "type": [ "string", "null" ], "description": "Nome empresarial da conta, ou null quando não disponível." }, "company_status": { "type": "string", "enum": [ "pending", "active", "limited" ], "description": "Situação cadastral da empresa na Raims. As condições de cada operação continuam sendo verificadas na requisição." }, "data_environment": { "type": "string", "enum": [ "sandbox", "production" ], "description": "Ambiente dos recursos acessados pela chave usada nesta consulta." }, "checked_at": { "type": "integer", "format": "int64", "minimum": 0, "description": "Instante da consulta, em segundos Unix UTC." }, "access_revision": { "type": "string", "minLength": 64, "maxLength": 64, "pattern": "^[0-9a-f]{64}$", "description": "Revisão do contexto consultado. Compare-a com outra resposta para reconhecer alterações de identidade, situação ou acesso. Não é uma autorização para executar operações." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda dos valores financeiros em reais." }, "amount_unit": { "type": "string", "enum": [ "cents" ], "description": "Unidade dos valores monetários inteiros: cents representa centavos de real." }, "timestamp_unit": { "type": "string", "enum": [ "unix_seconds" ], "description": "Formato dos instantes: unix_seconds representa segundos Unix UTC." }, "business_timezone": { "type": "string", "enum": [ "America/Sao_Paulo" ], "description": "Fuso usado nas datas e janelas de negócio da conta." } }, "description": "Identidade e referências de interpretação da conta autenticada. Não inclui credenciais, dados bancários ou identidade de usuário." }, "AccountNumber": { "type": "object", "additionalProperties": false, "required": [ "agency", "account" ], "properties": { "agency": { "type": "string", "description": "Agência da conta financeira, preservando os zeros à esquerda." }, "account": { "type": "string", "description": "Número da conta financeira conforme o cadastro, preservando os zeros à esquerda e a formatação retornada." } }, "description": "Dados da conta financeira da própria empresa na Raims. A consulta não cadastra uma conta nem altera o destino dos saques." }, "AutomaticWithdrawalSettings": { "type": "object", "additionalProperties": false, "required": [ "enabled", "minimum_amount_cents", "time", "next_execution_at" ], "properties": { "enabled": { "type": "boolean", "description": "Indica se a tentativa diária de saque está ativa.", "example": true }, "minimum_amount_cents": { "type": "integer", "format": "int64", "minimum": 200, "maximum": 100000000, "description": "Saldo mínimo para tentar o saque, em centavos de real. O valor retirado depende do saldo disponível e do limite Pix restante.", "example": 50000 }, "time": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "minLength": 5, "maxLength": 5, "description": "Horário diário no formato HH:mm, pelo fuso de São Paulo.", "example": "18:30" }, "next_execution_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Próxima tentativa prevista, em segundos Unix UTC, ou null quando não houver uma programada. Esse instante não confirma uma transferência.", "example": 1792186200 } }, "description": "Configuração da tentativa diária de saque para o destino próprio da empresa." }, "UpdateAutomaticWithdrawalSettingsRequest": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Ativa ou desativa novas tentativas de saque. Desativar não cancela saques já solicitados.", "example": true }, "minimum_amount_cents": { "type": "integer", "format": "int64", "minimum": 200, "maximum": 100000000, "description": "Saldo mínimo para tentar o saque, em centavos de real. O valor retirado depende do saldo disponível e do limite Pix restante.", "example": 50000 }, "time": { "type": "string", "maxLength": 5, "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "minLength": 5, "description": "Horário diário no formato HH:mm, pelo fuso de São Paulo.", "example": "18:30" } }, "description": "Alterações da configuração de saque automático. Campos omitidos são preservados; null não é aceito." }, "BalanceForecast": { "type": "object", "additionalProperties": false, "required": [ "period", "start_at", "end_at", "forecast_date", "receivable_amount_cents", "projected_balance_cents", "updated_at" ], "properties": { "period": { "type": "string", "enum": [ "today", "last_7_days", "last_15_days", "last_30_days" ], "description": "Período consultado, incluindo hoje e os dias anteriores conforme a opção." }, "start_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Início incluído do período, em segundos Unix UTC." }, "end_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Fim excluído do período, em segundos Unix UTC." }, "forecast_date": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Dia de referência da estimativa: meia-noite de hoje em São Paulo, em segundos Unix UTC." }, "receivable_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor dos pagamentos ainda considerados previstos para recebimento no período, em centavos de real. Não inclui cobranças abertas por vencer." }, "projected_balance_cents": { "type": "integer", "format": "int64", "description": "Soma do saldo total atual com os recebimentos previstos, em centavos de real. Pode incluir valores bloqueados; não representa saldo disponível para saque." }, "updated_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Última atualização dos dados da previsão, em segundos Unix UTC, ou null quando não estiver disponível." } }, "description": "Estimativa financeira do período. Os valores não comprovam liquidação bancária nem disponibilidade para saque." }, "Balance": { "type": "object", "additionalProperties": false, "required": [ "total_amount_cents", "blocked_amount_cents", "available_amount_cents" ], "properties": { "total_amount_cents": { "type": "integer", "format": "int64", "description": "Saldo total atual, em centavos de real, incluindo a parcela bloqueada. Pode ser negativo quando houver débitos superiores ao saldo." }, "blocked_amount_cents": { "type": "integer", "format": "int64", "description": "Parcela do saldo bloqueada, em centavos de real." }, "available_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Saldo total menos o bloqueado, em centavos de real, com mínimo de zero. A realização de saques e estornos também depende das regras de cada recurso." } }, "description": "Valores atuais da conta, separados entre total, bloqueado e disponível." }, "PaymentReceipt": { "type": "object", "additionalProperties": false, "required": [ "charge_id", "customer_id", "amount_cents", "payment_method", "paid_at", "customer", "merchant", "is_sandbox", "is_fiscal_document", "end_to_end_id" ], "properties": { "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança paga." }, "customer_id": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "description": "Identificador público do cliente vinculado à cobrança." }, "amount_cents": { "type": "integer", "format": "int64", "minimum": 1, "description": "Valor original da cobrança paga, em centavos de real, sem descontar tarifas ou devoluções." }, "payment_method": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Meio registrado no pagamento: 1 Pix, 2 boleto, 3 cartão de crédito ou 4 cartão de débito. O código 0 indica meio não informado." }, "paid_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Data e hora do pagamento confirmado, em segundos Unix UTC." }, "customer": { "$ref": "#/components/schemas/ReceiptParty", "description": "Dados cadastrais do cliente associados à cobrança. Não comprovam a identidade bancária de quem efetuou o pagamento." }, "merchant": { "$ref": "#/components/schemas/ReceiptParty", "description": "Dados cadastrais da empresa recebedora." }, "is_sandbox": { "type": "boolean", "description": "Indica que o pagamento pertence ao Sandbox e não movimentou dinheiro real." }, "is_fiscal_document": { "type": "boolean", "const": false, "description": "Sempre false. O recibo da Raims não substitui nota fiscal." }, "end_to_end_id": { "type": [ "string", "null" ], "description": "Identificador bancário do recebimento Pix, quando disponível. Retorna null no Sandbox, nos pagamentos por boleto e quando o identificador do recebimento não está confirmado. É diferente do ID da cobrança e dos dados de emissão do Pix." } }, "description": "Pagamento confirmado e identificação cadastral das partes da cobrança. O valor corresponde ao recebimento original, sem descontar estornos ou tarifas." }, "FinancialDocument": { "type": "object", "additionalProperties": false, "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL HTTPS temporária em files.raims.com. Use o endereço completo em um GET para baixar o PDF, sem enviar Authorization ou a chave de API. Não altere seus parâmetros." }, "expires_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Expiração do link em segundos Unix UTC. Depois desse instante, consulte novamente o endpoint do documento com a chave de API." } }, "description": "URL temporária para baixar um documento financeiro em PDF. A URL permite acesso a quem a possuir até expires_at e pode ser reutilizada nesse prazo. Compartilhe-a somente com pessoas autorizadas e não a registre em logs. Após a expiração, consulte novamente o endpoint autenticado para obter outro link. O download pode retornar HTTP 403 para um link inválido ou expirado, sem o envelope JSON de erros da API." }, "CreateRefundRequest": { "type": "object", "additionalProperties": false, "required": [ "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "minimum": 1, "description": "Valor solicitado para devolução, em centavos de real. Para devolver tudo, informe o valor restante mostrado na consulta de elegibilidade.", "example": 2500 }, "description": { "type": [ "string", "null" ], "maxLength": 200, "description": "Descrição da solicitação de devolução. Você pode deixar este campo vazio.", "example": "Devolução parcial do serviço" } }, "description": "Valor explícito da devolução Pix e descrição opcional." }, "Refund": { "type": "object", "additionalProperties": false, "required": [ "id", "charge_id", "amount_cents", "description", "status", "created_at", "completed_at", "failed_at", "failure_reason" ], "properties": { "id": { "type": "string", "pattern": "^rf_[A-Za-z0-9]+$", "description": "Identificador público da solicitação de estorno." }, "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador da cobrança que recebeu o pagamento original." }, "amount_cents": { "type": "integer", "format": "int64", "description": "Valor solicitado para devolução, em centavos de real." }, "description": { "type": [ "string", "null" ], "description": "Descrição da solicitação, ou null quando não informada." }, "status": { "type": "string", "enum": [ "reserved", "accepted", "completed", "failed", "unknown" ], "description": "Estado atual: reserved para solicitação em preparação, accepted para pedido aceito e aguardando confirmação, completed para devolução concluída, failed para falha confirmada e unknown para resultado ainda não confirmado. Consulte a mesma solicitação enquanto não houver resultado confirmado." }, "created_at": { "type": "integer", "format": "int64", "description": "Data da solicitação, em segundos Unix UTC." }, "completed_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Data da confirmação da devolução, em segundos Unix UTC, ou null." }, "failed_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Data da falha confirmada, em segundos Unix UTC, ou null." }, "failure_reason": { "anyOf": [ { "$ref": "#/components/schemas/RefundFailureReason" }, { "type": "null" } ], "description": "Motivo disponível quando o estado é failed, ou null nos demais estados. Uma falha sem causa registrada usa REFUND_FAILURE_REASON_UNAVAILABLE; não presuma que o pedido foi rejeitado." } }, "description": "Solicitação de devolução Pix vinculada a uma cobrança." }, "RefundListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" }, "description": "Estornos presentes nesta página, dos mais recentes para os mais antigos." }, "page": { "$ref": "#/components/schemas/RefundListPage", "description": "Cursores para continuar a mesma listagem, com a mesma empresa, ambiente e cobrança quando informada." } }, "description": "Página de solicitações de estorno no escopo consultado." }, "RefundEligibility": { "type": "object", "additionalProperties": false, "required": [ "charge_id", "eligible", "reason", "refundable_amount_cents", "pending_amount_cents", "max_refund_amount_cents" ], "properties": { "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança consultada." }, "eligible": { "type": "boolean", "description": "Indica se a cobrança pode receber um pedido de devolução nas condições atuais." }, "reason": { "anyOf": [ { "$ref": "#/components/schemas/RefundUnavailableReason" }, { "type": "null" } ], "description": "Motivo que impede a devolução, ou null quando eligible for true. Quando o impedimento for o estado, a mensagem informa o estado atual da cobrança e os estados aceitos." }, "refundable_amount_cents": { "type": "integer", "format": "int64", "description": "Valor restante da cobrança que pode ser devolvido, em centavos de real. O máximo disponível para um pedido agora está em max_refund_amount_cents." }, "pending_amount_cents": { "type": "integer", "format": "int64", "description": "Valor de solicitações que ainda aguardam resultado, em centavos de real." }, "max_refund_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Máximo que pode ser solicitado agora, em centavos de real, considerando o restante da cobrança e o saldo disponível. Zero quando houver impedimento. A consulta não reserva esse valor." } }, "description": "Disponibilidade atual para solicitar um estorno Pix." }, "ChargeStatistics": { "type": "object", "additionalProperties": false, "required": [ "period", "start_at", "end_at", "issued", "issued_paid", "received", "payment_rate", "updated_at" ], "properties": { "period": { "type": "string", "enum": [ "today", "last_7_days", "last_15_days", "last_30_days" ], "description": "Período considerado na consulta." }, "start_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Início do período, incluído na consulta, em segundos Unix UTC. Corresponde à meia-noite de São Paulo no primeiro dia." }, "end_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Fim do período, excluído da consulta, em segundos Unix UTC. Corresponde à meia-noite de São Paulo após o último dia." }, "issued": { "$ref": "#/components/schemas/ChargeStatisticsAggregate", "description": "Cobranças criadas no período, independentemente do estado atual." }, "issued_paid": { "$ref": "#/components/schemas/ChargeStatisticsAggregate", "description": "Cobranças criadas no período que estão pagas ou devolvidas, parcial ou integralmente. O pagamento pode ter ocorrido depois da criação. Cobranças em contestação não entram neste total." }, "received": { "$ref": "#/components/schemas/ChargeStatisticsAggregate", "description": "Cobranças pagas ou devolvidas cujo pagamento ocorreu no período, mesmo que tenham sido criadas antes dele. Cobranças em contestação não entram neste total. Devoluções não são subtraídas. Não some este valor a issued_paid, pois um pagamento pode aparecer nos dois conjuntos." }, "payment_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Percentual de cobranças emitidas que foram pagas: issued_paid.count dividido por issued.count, multiplicado por 100. Usa até duas casas decimais e retorna zero quando não há cobranças emitidas." }, "updated_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Última atualização conhecida dos totais consultados, em segundos Unix UTC, ou null quando essa informação não estiver disponível." } }, "description": "Estatísticas de emissão e recebimento de cobranças no período. Cobranças canceladas permanecem no total emitido; cadastros excluídos não entram nos totais." }, "CreateCheckoutLogoUploadRequest": { "type": "object", "additionalProperties": false, "required": [ "content_type", "file_size", "width", "height" ], "properties": { "content_type": { "type": "string", "maxLength": 32, "enum": [ "image/png", "image/jpeg" ], "minLength": 1, "description": "Tipo de conteúdo do arquivo: image/png ou image/jpeg.", "example": "image/png" }, "file_size": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 524288, "description": "Tamanho do arquivo em bytes.", "example": 12345 }, "width": { "type": "integer", "minimum": 128, "maximum": 2048, "description": "Largura da imagem em pixels.", "example": 512 }, "height": { "type": "integer", "minimum": 128, "maximum": 2048, "description": "Altura da imagem em pixels.", "example": 128 } }, "description": "Metadados da imagem que será enviada como logo do checkout." }, "CheckoutAssetUpload": { "type": "object", "additionalProperties": false, "required": [ "id", "upload_url", "method", "content_type", "file_size", "expires_at" ], "properties": { "id": { "type": "string", "pattern": "^cau_[A-Za-z0-9]+$", "maxLength": 26, "description": "Identificador do envio. Use-o no campo correspondente do PATCH depois de enviar o arquivo." }, "upload_url": { "type": "string", "format": "uri", "description": "URL temporária para envio dos bytes do arquivo. Não envie a chave de API Raims para este endereço." }, "method": { "type": "string", "const": "PUT", "description": "Método HTTP para enviar o arquivo à URL retornada." }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg" ], "description": "Tipo de conteúdo que deve ser enviado no header Content-Type do PUT." }, "file_size": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 524288, "description": "Quantidade de bytes que deve ser enviada, também informada no header Content-Length do PUT." }, "expires_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Prazo de validade da autorização de envio, em segundos Unix UTC." } }, "description": "Autorização temporária para enviar um arquivo de imagem da empresa, no ambiente autenticado." }, "CreateCheckoutFaviconUploadRequest": { "type": "object", "additionalProperties": false, "required": [ "content_type", "file_size", "width", "height" ], "properties": { "content_type": { "type": "string", "maxLength": 32, "enum": [ "image/png", "image/jpeg" ], "minLength": 1, "description": "Tipo de conteúdo do arquivo: image/png ou image/jpeg.", "example": "image/png" }, "file_size": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 524288, "description": "Tamanho do arquivo em bytes.", "example": 4567 }, "width": { "type": "integer", "minimum": 128, "maximum": 512, "description": "Largura do ícone em pixels. Deve ser igual à altura.", "example": 128 }, "height": { "type": "integer", "minimum": 128, "maximum": 512, "description": "Altura do ícone em pixels. Deve ser igual à largura.", "example": 128 } }, "description": "Metadados da imagem que será enviada como ícone do checkout." }, "CheckoutAssetUploadDeleted": { "type": "object", "additionalProperties": false, "required": [ "id", "deleted" ], "properties": { "id": { "type": "string", "pattern": "^cau_[A-Za-z0-9]+$", "maxLength": 26, "description": "Identificador do envio descartado.", "example": "cau_3AbHiWSrsZBoaTg47OcMzC" }, "deleted": { "type": "boolean", "const": true, "description": "Confirma que o envio foi descartado e não pode mais ser associado ao checkout.", "example": true } }, "description": "Confirmação do descarte de um envio de imagem que não será aplicado." }, "CheckoutSettings": { "type": "object", "additionalProperties": false, "required": [ "support_email", "hex_primary_color", "hex_secondary_color", "payment_method_types", "logo", "favicon" ], "properties": { "support_email": { "type": [ "string", "null" ], "description": "E-mail de suporte apresentado no checkout, ou null quando não informado." }, "hex_primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "minLength": 7, "maxLength": 7, "description": "Cor principal do checkout no formato #RRGGBB." }, "hex_secondary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "minLength": 7, "maxLength": 7, "description": "Cor de fundo do checkout no formato #RRGGBB." }, "payment_method_types": { "type": "array", "items": { "type": "integer", "enum": [ 1, 2 ] }, "uniqueItems": true, "maxItems": 2, "minItems": 1, "description": "Meios padrão habilitados e disponíveis: 1 para Pix e 2 para boleto. Cobranças e links podem ter configurações próprias. Para alterar o padrão, use o Dashboard." }, "logo": { "$ref": "#/components/schemas/CheckoutAsset", "description": "Imagem atual e andamento da última alteração." }, "favicon": { "$ref": "#/components/schemas/CheckoutAsset", "description": "Imagem atual e andamento da última alteração." } }, "description": "Imagens, cores, contato de suporte e meios padrão do checkout no ambiente autenticado." }, "UpdateCheckoutSettingsRequest": { "type": "object", "additionalProperties": false, "properties": { "support_email": { "type": [ "string", "null" ], "maxLength": 254, "description": "E-mail de suporte apresentado no checkout. Omitir preserva o valor; null ou texto vazio remove o contato.", "example": "suporte@example.com" }, "hex_primary_color": { "type": "string", "maxLength": 7, "minLength": 7, "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Cor principal do checkout no formato #RRGGBB. Omitir preserva o valor; null ou texto vazio não são aceitos.", "example": "#FF6D00" }, "hex_secondary_color": { "type": "string", "maxLength": 7, "minLength": 7, "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Cor de fundo do checkout no formato #RRGGBB. Omitir preserva o valor; null ou texto vazio não são aceitos.", "example": "#FFFFFF" }, "logo_upload_id": { "type": [ "string", "null" ], "maxLength": 26, "pattern": "^cau_[A-Za-z0-9]+$", "description": "ID retornado ao preparar o envio da logo. Envie o arquivo antes de associá-lo. Omitir preserva a imagem atual; null a remove.", "example": "cau_3AbHiWSrsZBoaTg47OcMzC" }, "favicon_upload_id": { "type": [ "string", "null" ], "maxLength": 26, "pattern": "^cau_[A-Za-z0-9]+$", "description": "ID retornado ao preparar o envio do ícone. Envie o arquivo antes de associá-lo. Omitir preserva a imagem atual; null a remove.", "example": "cau_1AbXiWSrsCBoaTg47OcMzC" } }, "description": "Alterações da aparência do checkout. Campos omitidos são preservados. Os identificadores de envio de imagem aceitam null para remover a imagem." }, "Dispute": { "type": "object", "additionalProperties": false, "required": [ "opened_at", "due_at", "complaint_details", "company_response", "responded_at", "resolved_at", "won_amount_cents", "lost_amount_cents", "refunded_amount_cents", "infraction_result", "refund_result", "loss_reason_code", "loss_reason_note", "id", "charge_id", "kind", "stage", "reason_code", "disputed_amount_cents", "created_at", "updated_at" ], "properties": { "opened_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Data de abertura da contestação, em segundos Unix UTC, ou null quando não informada." }, "due_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Prazo registrado para resposta, em segundos Unix UTC, ou null quando não informado. Esta consulta não permite enviar uma resposta." }, "complaint_details": { "type": [ "string", "null" ], "description": "Relato disponível da contestação, ou null quando não informado." }, "company_response": { "type": [ "string", "null" ], "description": "Resposta registrada da empresa, ou null quando não informada." }, "responded_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Data da resposta registrada da empresa, em segundos Unix UTC, ou null." }, "resolved_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Data registrada de encerramento ou resolução do caso, em segundos Unix UTC, ou null. Não confirma movimentação financeira." }, "won_amount_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Valor com decisão favorável à empresa em um registro chargeback, em centavos de real. Null para casos MED ou quando não disponível." }, "lost_amount_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Valor com decisão desfavorável à empresa em um registro chargeback, em centavos de real. Null para casos MED ou quando não disponível." }, "refunded_amount_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Total de devoluções confirmadas para o caso MED, em centavos de real. Null para registros chargeback ou quando não houver resultado disponível. O aceite da análise não confirma este valor." }, "infraction_result": { "type": [ "string", "null" ], "enum": [ "agreed", "disagreed", null ], "description": "Resultado da análise de infração MED: agreed para infração reconhecida ou disagreed para infração não reconhecida. Null quando não disponível ou não aplicável." }, "refund_result": { "type": [ "string", "null" ], "enum": [ "partially_accepted", "totally_accepted", "rejected", null ], "description": "Resultado da análise de devolução MED: partially_accepted, totally_accepted ou rejected. Null quando não disponível ou não aplicável. Aceite não comprova devolução financeira." }, "loss_reason_code": { "type": [ "integer", "null" ], "description": "Motivo informado para o resultado desfavorável: 1 prazo de resposta expirado, 2 evidências insuficientes, 3 documentação inválida, 4 decisão final ou 5 outro. Null quando não disponível ou não aplicável." }, "loss_reason_note": { "type": [ "string", "null" ], "description": "Observação disponível sobre o motivo do resultado desfavorável, ou null." }, "id": { "type": "string", "pattern": "^(?:dp_[A-Za-z0-9]+|med_[1-9][0-9]*)$", "description": "Identificador público completo do caso, com prefixo dp_ ou med_. Use este valor na consulta individual." }, "charge_id": { "type": [ "string", "null" ], "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador da cobrança vinculada, ou null quando não houver vínculo disponível." }, "kind": { "type": "string", "enum": [ "chargeback", "med" ], "description": "Tipo do caso: med para o procedimento MED do Pix e chargeback para os demais registros de contestação apresentados pela Raims." }, "stage": { "type": "string", "enum": [ "open", "in_analysis", "refund_in_analysis", "closed", "cancelled", "rejected", "failed" ], "description": "Etapa atual: open, in_analysis, refund_in_analysis, closed, cancelled, rejected ou failed. Closed informa análise encerrada, sem confirmar decisão favorável ou devolução." }, "reason_code": { "type": [ "integer", "null" ], "description": "Motivo relatado, que não confirma fraude, conforme kind. Para med: 1 golpe, 2 conta invadida, 3 coação, 4 acesso fraudulento, 5 outro e 6 desconhecido. Para chargeback: 1 alegação de fraude, 2 compra não reconhecida, 3 serviço não reconhecido, 4 produto ou serviço divergente, 5 cobrança indevida e 6 outro. Null quando não informado." }, "disputed_amount_cents": { "type": "integer", "format": "int64", "description": "Valor contestado, em centavos de real. Não representa o valor atualmente bloqueado nem confirma devolução." }, "created_at": { "type": "integer", "format": "int64", "description": "Data de criação do registro na Raims, em segundos Unix UTC." }, "updated_at": { "type": "integer", "format": "int64", "description": "Data da última atualização disponível, em segundos Unix UTC." } }, "description": "Detalhes e resultados disponíveis de uma contestação." }, "DisputeListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/DisputeListItem" }, "description": "Contestações presentes nesta página, na ordenação solicitada." }, "page": { "$ref": "#/components/schemas/DisputeListPage", "description": "Informações de navegação para a mesma consulta." } }, "description": "Página de contestações acessíveis à chave utilizada." }, "PaymentLinkEmailRequestAccepted": { "type": "object", "additionalProperties": false, "required": [ "id", "charge_id", "recipient_email", "retry_after_seconds", "retry_after_until" ], "properties": { "id": { "type": "string", "pattern": "^pl_[A-Za-z0-9]+$", "description": "Identificador público do link de pagamento." }, "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador da cobrança vinculada ao link." }, "recipient_email": { "type": "string", "description": "E-mail escolhido para receber o link: o do pagador do boleto, quando registrado; na ausência dele, o da cobrança e, por último, o do cadastro atual do cliente. Um endereço inválido impede o envio." }, "retry_after_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Tempo, em segundos, até permitir outra solicitação de envio para a cobrança." }, "retry_after_until": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante, em segundos Unix UTC, a partir do qual outra solicitação de envio pode ser feita." } } }, "CreatePaymentLinkRequest": { "type": "object", "additionalProperties": false, "required": [ "charge_id" ], "properties": { "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "maxLength": 100, "description": "Identificador da cobrança existente. O link utiliza o cliente, o valor e o vencimento dessa cobrança." }, "success_redirect_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "URL HTTPS de retorno após o pagamento confirmado. Omitir, enviar null ou texto vazio preserva a URL existente.", "example": "https://loja.example.com/pagamento/concluido" }, "cancel_redirect_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "URL HTTPS para voltar ao seu site. Esse retorno não cancela a cobrança. Omitir, enviar null ou texto vazio preserva a URL existente.", "example": "https://loja.example.com/carrinho" }, "payment_method_types": { "type": [ "array", "null" ], "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "Meios permitidos no link. Omitir preserva a configuração; null remove a configuração própria. Uma lista limita os meios do checkout e não amplia os permitidos pela cobrança.", "example": [ 1, 2 ] } } }, "PaymentLink": { "type": "object", "additionalProperties": false, "required": [ "id", "charge_id", "url", "success_redirect_url", "cancel_redirect_url", "payment_method_types", "created_at", "updated_at", "is_active" ], "properties": { "id": { "type": "string", "pattern": "^pl_[A-Za-z0-9]+$", "description": "Identificador público do link de pagamento." }, "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador da cobrança vinculada. Consulte a cobrança para obter seus dados financeiros." }, "url": { "type": "string", "format": "uri", "description": "URL do checkout dessa cobrança. Repetir a criação reutiliza o mesmo link." }, "success_redirect_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL de retorno após a confirmação do pagamento, ou null quando não configurada." }, "cancel_redirect_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL de retorno ao seu site, ou null quando não configurada. Voltar ao site não cancela a cobrança." }, "payment_method_types": { "type": [ "array", "null" ], "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "Configuração própria dos meios do link, ou null para herança. A cobrança e a disponibilidade da plataforma continuam limitando os meios aceitos." }, "created_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Data de criação do link em segundos Unix UTC." }, "updated_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Data da última alteração do link ou de suas configurações em segundos Unix UTC." }, "is_active": { "type": "boolean", "description": "Indica se o link está ativo. False significa que o checkout foi pausado. Um link ativo continua sujeito às condições da cobrança." } } }, "PaymentLinkListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" }, "description": "Links presentes nesta página." }, "page": { "$ref": "#/components/schemas/PaymentLinkListPage", "description": "Cursores para navegar entre páginas." } } }, "PaymentLinkDetails": { "type": "object", "additionalProperties": false, "required": [ "id", "charge_id", "url", "success_redirect_url", "cancel_redirect_url", "payment_method_types", "created_at", "updated_at", "is_payable", "effective_payment_method_types", "unavailable_reason", "is_active" ], "properties": { "id": { "type": "string", "pattern": "^pl_[A-Za-z0-9]+$", "description": "Identificador público do link de pagamento." }, "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador da cobrança vinculada. Consulte a cobrança para obter seus dados financeiros." }, "url": { "type": "string", "format": "uri", "description": "URL do checkout dessa cobrança. Repetir a criação reutiliza o mesmo link." }, "success_redirect_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL de retorno após a confirmação do pagamento, ou null quando não configurada." }, "cancel_redirect_url": { "type": [ "string", "null" ], "format": "uri", "description": "URL de retorno ao seu site, ou null quando não configurada. Voltar ao site não cancela a cobrança." }, "payment_method_types": { "type": [ "array", "null" ], "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "minItems": 0, "maxItems": 2, "uniqueItems": true, "description": "Configuração própria de Pix e boleto no link. Null indica herança; uma lista vazia indica que a configuração não contém nenhum desses meios. A disponibilidade efetiva aparece em effective_payment_method_types." }, "created_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Data de criação do link em segundos Unix UTC." }, "updated_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Data da última alteração do link ou de suas configurações em segundos Unix UTC." }, "is_payable": { "type": "boolean", "description": "Indica se a cobrança ainda pode ser paga por este link. Links pausados e cobranças pagas, revogadas ou vencidas, por exemplo, retornam false. A informação vale para o instante da consulta e não confirma pagamento." }, "effective_payment_method_types": { "type": "array", "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "minItems": 0, "maxItems": 2, "uniqueItems": true, "description": "Meios de pagamento definidos pelas configurações da cobrança, do link e da conta, entre os disponíveis na plataforma. Uma cobrança já paga ou um link pausado pode continuar mostrando Pix e boleto nessa lista. Use is_payable para saber se ainda é possível pagar pelo checkout." }, "unavailable_reason": { "anyOf": [ { "$ref": "#/components/schemas/PaymentLinkUnavailableReason" }, { "type": "null" } ], "description": "Motivo que impede pagar a cobrança por este link, ou null quando is_payable for true." }, "is_active": { "type": "boolean", "description": "Indica se o link está ativo. False significa que o checkout foi pausado. Um link ativo continua sujeito às condições da cobrança." } }, "description": "Dados do link de pagamento de uma cobrança." }, "UpdatePaymentLinkRequest": { "type": "object", "additionalProperties": false, "properties": { "is_active": { "type": "boolean", "description": "Envie false para pausar o checkout e true para reativar a mesma URL. Omitir preserva o estado atual. A pausa não cancela Pix ou boleto emitidos nem prorroga o vencimento.", "example": false }, "success_redirect_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "URL HTTPS de retorno após o pagamento confirmado. Omitir, enviar null ou texto vazio preserva a URL existente. Para removê-la, use clear_success_redirect_url com true, sem informar uma URL preenchida." }, "cancel_redirect_url": { "type": [ "string", "null" ], "maxLength": 2048, "format": "uri", "description": "URL HTTPS para voltar ao seu site. Esse retorno não cancela a cobrança. Omitir, enviar null ou texto vazio preserva a URL existente. Para removê-la, use clear_cancel_redirect_url com true, sem informar uma URL preenchida.", "example": "https://loja.example.com/carrinho" }, "clear_success_redirect_url": { "type": "boolean", "default": false, "description": "Envie true para remover o destino de retorno após o pagamento. False ou omissão não solicita remoção. Não envie true junto de success_redirect_url preenchida.", "example": true }, "clear_cancel_redirect_url": { "type": "boolean", "default": false, "description": "Envie true para remover o destino de voltar ao site. False ou omissão não solicita remoção. Não envie true junto de cancel_redirect_url preenchida.", "example": true }, "payment_method_types": { "type": [ "array", "null" ], "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "description": "Meios permitidos no link. Omitir preserva a configuração; null remove a configuração própria. Uma lista limita os meios do checkout e não amplia os permitidos pela cobrança." } } }, "ChargeScenarioRequest": { "type": "object", "additionalProperties": false, "required": [ "action", "outcome" ], "properties": { "action": { "type": "string", "maxLength": 32, "enum": [ "pix_issuance", "boleto_issuance", "cancellation" ], "minLength": 1, "description": "Ação a testar: pix_issuance para emissão Pix, boleto_issuance para emissão de boleto ou cancellation para cancelamento. Para cancellation, mantenha a cobrança aberta com Pix ou boleto já emitido, sem confirmar o pagamento.", "example": "pix_issuance" }, "outcome": { "type": "string", "maxLength": 16, "enum": [ "pending", "failed" ], "minLength": 1, "description": "Resultado da ação: pending mantém a confirmação em aberto; failed apresenta uma falha.", "example": "pending" } }, "description": "Cenário para a próxima emissão ou cancelamento da cobrança." }, "ChargeScenario": { "type": "object", "additionalProperties": false, "required": [ "charge_id", "action", "outcome", "state", "charge_status", "duplicate" ], "properties": { "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança do Sandbox." }, "action": { "type": "string", "enum": [ "pix_issuance", "boleto_issuance", "cancellation" ], "description": "Ação do cenário: emissão de Pix, emissão de boleto ou cancelamento." }, "outcome": { "type": "string", "enum": [ "pending", "failed", "completed" ], "description": "Resultado escolhido para a ação: pending, failed ou completed." }, "state": { "type": "string", "enum": [ "configured", "pending", "failed", "completed" ], "description": "Andamento do cenário: configured aguarda a ação; pending aguarda resolução; failed e completed são resultados finais." }, "charge_status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "Estado atual da cobrança, conforme os códigos do recurso Cobranças." }, "duplicate": { "type": "boolean", "description": "Indica que o mesmo resultado já estava registrado, sem repetir a ação." } }, "description": "Resultado da configuração ou resolução de um cenário do Sandbox." }, "ResolveChargeScenarioRequest": { "type": "object", "additionalProperties": false, "required": [ "action", "outcome" ], "properties": { "action": { "type": "string", "maxLength": 32, "enum": [ "pix_issuance", "boleto_issuance", "cancellation" ], "minLength": 1, "description": "Ação a testar: pix_issuance para emissão Pix, boleto_issuance para emissão de boleto ou cancellation para cancelamento.", "example": "pix_issuance" }, "outcome": { "type": "string", "maxLength": 16, "enum": [ "completed", "failed" ], "minLength": 1, "description": "Resultado para a pendência: completed conclui a ação; failed confirma a falha.", "example": "completed" } }, "description": "Ação pendente e resultado da simulação." }, "IssueSimulationPaymentRequest": { "type": "object", "additionalProperties": false, "required": [ "payment_method" ], "properties": { "payment_method": { "type": "integer", "minimum": 1, "maximum": 2, "description": "Meio a emitir: 1 para Pix ou 2 para boleto. Deve estar habilitado na cobrança.", "example": 1 } }, "description": "Meio de pagamento da emissão de teste." }, "ChargeBoletoCompensation": { "type": "object", "additionalProperties": false, "required": [ "charge_id", "status", "amount_cents", "duplicate" ], "properties": { "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "ID público da cobrança simulada. Use o mesmo identificador ao consultar os resultados." }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "Estado da cobrança enquanto o boleto aguarda liquidação. A compensação não equivale a status pago." }, "amount_cents": { "type": "integer", "format": "int64", "minimum": 100, "description": "Valor do boleto em centavos de real. Informar esse valor não confirma crédito no saldo." }, "duplicate": { "type": "boolean", "description": "Indica que a cobrança já tinha o mesmo resultado. Nesse caso, a simulação não repete o efeito financeiro." } }, "description": "Resultado da compensação simulada do boleto, sem confirmação de crédito." }, "Statement": { "type": "object", "additionalProperties": false, "required": [ "id", "reference_id", "reference_type", "statement_type", "amount_cents", "created_at", "refund_id", "dispute_id" ], "properties": { "id": { "type": "string", "pattern": "^st_[A-Za-z0-9]+$", "description": "Identificador público do lançamento, com prefixo st_." }, "reference_id": { "type": [ "string", "null" ], "description": "Identificador do recurso relacionado, ou null quando não houver referência. Cobranças usam ch_, contestações usam dp_, saques usam wd_ e ajustes usam adj_. Referências manuais podem não ter prefixo." }, "reference_type": { "type": [ "integer", "null" ], "enum": [ 1, 2, 3, 4, 5, null ], "description": "Categoria da referência: 1 cobrança; 2 contestação; 3 saque; 4 ajuste; 5 lançamento manual. Retorna null quando não houver referência.", "x-raims-enum-labels": [ "Cobrança", "Contestação", "Saque", "Ajuste", "Manual", "Sem referência" ] }, "statement_type": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ], "description": "Natureza do lançamento. Recebimentos, créditos por ajuste e liberações têm valor positivo; tarifas, saques, devoluções, débitos por ajuste e bloqueios têm valor negativo.", "x-raims-enum-labels": [ "Recebimento", "Tarifa", "Tarifa de serviço", "Saque", "Devolução", "Devolução parcial", "Crédito por ajuste", "Débito por ajuste", "Bloqueio", "Liberação" ] }, "amount_cents": { "type": "integer", "format": "int64", "description": "Valor assinado do lançamento em centavos de real. Por exemplo, 10000 representa R$ 100,00 e -149 representa uma saída de R$ 1,49." }, "created_at": { "type": "integer", "format": "int64", "description": "Instante do lançamento em segundos Unix UTC." }, "refund_id": { "type": [ "string", "null" ], "pattern": "^rf_[A-Za-z0-9]+$", "description": "ID do estorno que originou o lançamento, ou null quando não houver vínculo confirmado." }, "dispute_id": { "type": [ "string", "null" ], "pattern": "^(?:dp_[A-Za-z0-9]+|med_[1-9][0-9]*)$", "description": "ID da contestação vinculada ao lançamento, ou null quando não houver vínculo confirmado. Um bloqueio sem contestação identificada mantém este campo nulo." } } }, "StatementListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Statement" }, "description": "Lançamentos da página, na ordem solicitada." }, "page": { "$ref": "#/components/schemas/StatementListPage", "description": "Tamanho da página e cursores para avançar ou voltar." } } }, "WebhookEventTypeListResponse": { "type": "object", "additionalProperties": false, "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Catálogo de eventos disponíveis." } }, "description": "Eventos disponíveis para novas assinaturas." }, "WebhookHealth": { "type": "object", "additionalProperties": false, "required": [ "webhook_id", "status", "first_failure_at", "last_failure_at", "last_success_at", "failure_duration_seconds", "observed_at" ], "properties": { "webhook_id": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "description": "Identificador do webhook consultado.", "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "status": { "type": "string", "enum": [ "unknown", "healthy", "failing", "disabled" ], "description": "Situação conhecida do destino: unknown quando faltam dados, healthy após sucesso, failing durante uma sequência de falhas ou disabled quando está desativado.", "example": "failing" }, "first_failure_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Início da sequência atual de falhas, em segundos Unix UTC, ou null quando não há sequência de falhas informada.", "example": 1792281600 }, "last_failure_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Última falha da sequência atual, em segundos Unix UTC, ou null quando não há sequência de falhas informada.", "example": 1792285140 }, "last_success_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Último sucesso conhecido para a configuração atual, em segundos Unix UTC, ou null quando esse dado não está disponível.", "example": 1792278000 }, "failure_duration_seconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "description": "Tempo desde a primeira falha da sequência atual até esta consulta, em segundos. Retorna null quando o estado não é failing ou não há dados suficientes.", "example": 3600 }, "observed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante de atualização dos dados apresentados, em segundos Unix UTC, ou null quando não há informação disponível.", "example": 1792285140 } }, "description": "Situação conhecida das entregas de um webhook." }, "SetWebhookPauseRequest": { "type": "object", "additionalProperties": false, "required": [ "is_paused" ], "properties": { "is_paused": { "type": "boolean", "description": "Envie true para pausar os envios ou false para retomá-los. Repetir o mesmo valor preserva o estado e a data de pausa.", "example": true } } }, "WebhookPause": { "type": "object", "additionalProperties": false, "required": [ "id", "is_paused", "paused_at" ], "properties": { "id": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "description": "Identificador do webhook.", "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "is_paused": { "type": "boolean", "description": "Indica se os envios aguardam a retomada. O prazo original das entregas continua correndo durante a pausa.", "example": false }, "paused_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Início da pausa atual, em segundos Unix UTC, ou null quando os envios não estão pausados.", "example": null } } }, "WebhookListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Webhooks desta página." }, "page": { "$ref": "#/components/schemas/WebhookListPage", "description": "Informações para continuar ou voltar na listagem." } }, "description": "Página de webhooks cadastrados." }, "CreateWebhookRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string", "maxLength": 25, "minLength": 1, "description": "Nome para identificar o destino.", "example": "Pedidos pagos" }, "url": { "type": "string", "maxLength": 512, "minLength": 1, "format": "uri", "description": "URL HTTPS que recebe os eventos. Use a porta padrão 443 e um endereço público externo à Raims.", "example": "https://webhooks.example.com/raims" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "charge.created", "charge.paid", "charge.canceled", "charge.failed", "refund.requested", "refund.completed", "refund.failed" ] }, "minItems": 1, "description": "Códigos dos eventos que este destino deve receber. Consulte o catálogo de eventos disponíveis.", "example": [ "charge.paid" ] }, "is_active": { "type": "boolean", "default": true, "description": "Define se o destino pode receber eventos após o cadastro.", "example": true } }, "description": "Dados do webhook a cadastrar." }, "WebhookCreated": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "events", "is_active", "disabled_reason", "disabled_at", "previous_secret_expires_at", "created_at", "updated_at", "secret_key", "is_paused", "paused_at" ], "properties": { "id": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "description": "Identificador público do webhook.", "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "name": { "type": "string", "description": "Nome usado para identificar o destino.", "example": "Pedidos pagos" }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS cadastrada para receber os eventos.", "example": "https://webhooks.example.com/raims" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Códigos dos eventos assinados por este destino.", "example": [ "charge.paid" ] }, "is_active": { "type": "boolean", "description": "Indica se o webhook está ativo para receber eventos.", "example": true }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ null, "manual", "continuous_failure" ], "description": "Motivo da desativação: manual para uma ação do cliente; continuous_failure pode aparecer em cadastros desativados anteriormente por falhas. Retorna null quando o webhook está ativo." }, "disabled_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da desativação, em segundos Unix UTC, ou null quando o webhook está ativo ou essa data não foi registrada." }, "previous_secret_expires_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Fim da validade do segredo anterior, em segundos Unix UTC, ou null quando não há transição vigente." }, "created_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante do cadastro, em segundos Unix UTC.", "example": 1792281600 }, "updated_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da última alteração do cadastro, em segundos Unix UTC.", "example": 1792281600 }, "secret_key": { "type": "string", "pattern": "^whsec_[A-Za-z0-9]+$", "description": "Segredo usado para validar a assinatura dos eventos. Guarde-o em local seguro; as consultas do cadastro não o retornam.", "example": "whsec_ExampleOnlyDoNotUseThisValueAsASecret" }, "is_paused": { "type": "boolean", "description": "Indica se os envios aguardam a retomada. O prazo original das entregas continua correndo durante a pausa.", "example": false }, "paused_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Início da pausa atual, em segundos Unix UTC, ou null quando os envios não estão pausados.", "example": null } }, "description": "Webhook cadastrado e segredo necessário para validar suas assinaturas." }, "Webhook": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "url", "events", "is_active", "disabled_reason", "disabled_at", "previous_secret_expires_at", "created_at", "updated_at", "is_paused", "paused_at" ], "properties": { "id": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "description": "Identificador público do webhook.", "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "name": { "type": "string", "description": "Nome usado para identificar o destino.", "example": "Pedidos pagos" }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS cadastrada para receber os eventos.", "example": "https://webhooks.example.com/raims" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Códigos dos eventos assinados por este destino.", "example": [ "charge.paid" ] }, "is_active": { "type": "boolean", "description": "Indica se o webhook está ativo para receber eventos.", "example": true }, "disabled_reason": { "type": [ "string", "null" ], "enum": [ null, "manual", "continuous_failure" ], "description": "Motivo da desativação: manual para uma ação do cliente; continuous_failure pode aparecer em cadastros desativados anteriormente por falhas. Retorna null quando o webhook está ativo." }, "disabled_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da desativação, em segundos Unix UTC, ou null quando o webhook está ativo ou essa data não foi registrada." }, "previous_secret_expires_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Fim da validade do segredo anterior, em segundos Unix UTC, ou null quando não há transição vigente." }, "created_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante do cadastro, em segundos Unix UTC.", "example": 1792281600 }, "updated_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da última alteração do cadastro, em segundos Unix UTC.", "example": 1792281600 }, "is_paused": { "type": "boolean", "description": "Indica se os envios aguardam a retomada. O prazo original das entregas continua correndo durante a pausa.", "example": false }, "paused_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Início da pausa atual, em segundos Unix UTC, ou null quando os envios não estão pausados.", "example": null } }, "description": "Configuração de um destino para eventos." }, "UpdateWebhookRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 25, "minLength": 1, "description": "Novo nome do webhook.", "example": "Pedidos pagos" }, "url": { "type": "string", "maxLength": 512, "format": "uri", "description": "Nova URL HTTPS que recebe os eventos, na porta padrão 443.", "example": "https://webhooks.example.com/raims" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Lista completa dos eventos que o destino deve receber. Ela substitui a seleção anterior.", "example": [ "charge.paid" ] }, "is_active": { "type": "boolean", "description": "Use true para permitir envios ou false para desativar o destino.", "example": true } }, "description": "Campos do webhook a alterar. Omita os campos que deseja manter." }, "RotateWebhookSecretRequest": { "type": "object", "additionalProperties": false, "properties": { "grace_period_seconds": { "type": "integer", "minimum": 0, "maximum": 86400, "default": 86400, "description": "Período em que o segredo anterior pode continuar assinando envios. Zero gera uma nova assinatura e encerra a validade dos segredos anteriores, inclusive durante uma transição ativa. Requisições já autorizadas ou em andamento podem chegar com a assinatura anterior.", "example": 86400 } }, "description": "Prazo de transição entre os segredos de assinatura." }, "WebhookSecretRotation": { "type": "object", "additionalProperties": false, "required": [ "id", "secret_key", "previous_secret_expires_at" ], "properties": { "id": { "type": "string", "pattern": "^whk_[A-Za-z0-9]+$", "description": "Identificador público do webhook.", "example": "whk_1AbXiWSrsCBoaTg47OcMzC" }, "secret_key": { "type": "string", "pattern": "^whsec_[A-Za-z0-9]+$", "description": "Segredo usado para validar a assinatura dos eventos. Guarde-o em local seguro; as consultas do cadastro não o retornam.", "example": "whsec_ExampleOnlyDoNotUseThisValueAsASecret" }, "previous_secret_expires_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Fim da validade do segredo anterior, em segundos Unix UTC, ou null quando não há transição vigente." } }, "description": "Novo segredo de assinatura e validade do segredo anterior." }, "WebhookTestAccepted": { "type": "object", "additionalProperties": false, "required": [ "event_id", "delivery_id" ], "properties": { "event_id": { "type": "string", "format": "uuid", "pattern": "^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "Identificador do evento técnico solicitado.", "example": "d36ffb51-e0c6-8a8f-904d-e426cc0b76bb" }, "delivery_id": { "type": "string", "format": "uuid", "pattern": "^(?!00000000-0000-0000-0000-000000000000$)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "Identificador da entrega para acompanhar o resultado.", "example": "46be4604-31fc-876a-bbb7-69e204ff9c14" } }, "description": "Pedido de teste aceito para um único destino." }, "WithdrawalDestination": { "type": "object", "additionalProperties": false, "required": [ "id", "key_type", "key_masked", "holder_name", "bank_ispb", "is_default", "verified_at" ], "properties": { "id": { "type": "string", "pattern": "^wdst_[A-Za-z0-9]+$", "description": "Identificador público do destino, com prefixo wdst_. Use-o para consultar este destino; ele não identifica uma solicitação de saque." }, "key_type": { "type": "string", "enum": [ "CNPJ", "EVP", "PHONE", "EMAIL" ], "description": "Tipo da chave Pix: CNPJ, chave aleatória (EVP), telefone (PHONE) ou e-mail (EMAIL)." }, "key_masked": { "type": "string", "description": "Chave Pix parcialmente ocultada. A consulta não retorna o valor completo." }, "holder_name": { "type": "string", "description": "Nome do titular associado ao destino verificado da empresa." }, "bank_ispb": { "type": "string", "description": "ISPB da instituição do destino. Preserve os zeros à esquerda." }, "is_default": { "type": "boolean", "description": "Informa se este é o destino padrão atual para solicitar saques." }, "verified_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Data da verificação do destino, em segundos Unix UTC." } }, "description": "Destino Pix verificado da própria empresa, disponível para consulta em Produção." }, "WithdrawalDestinationListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalDestination" }, "description": "Destinos próprios disponíveis nesta página. Pode estar vazia mesmo quando page.has_next for true." }, "page": { "$ref": "#/components/schemas/WithdrawalDestinationListPage", "description": "Dados de navegação da listagem. Continue enquanto has_next for true." } }, "description": "Página de destinos próprios e dados para continuar a consulta." }, "WithdrawalLimits": { "type": "object", "additionalProperties": false, "required": [ "minimum_amount_cents", "fee_threshold_amount_cents", "fee_below_threshold_cents", "available_amount_cents", "destination_configured", "limits" ], "properties": { "minimum_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor mínimo permitido por solicitação, em centavos de real." }, "fee_threshold_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor solicitado a partir do qual a tarifa de saque é zero, em centavos de real." }, "fee_below_threshold_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Tarifa descontada do valor solicitado quando ele fica abaixo de fee_threshold_amount_cents, em centavos de real." }, "available_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Saldo disponível para retirada, em centavos de real. A solicitação também precisa respeitar os limites e a tarifa aplicáveis." }, "destination_configured": { "type": "boolean", "description": "Indica se há destino Pix próprio cadastrado para o saque. No Sandbox, retorna false." }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalPeriodLimits" }, { "type": "null" } ], "description": "Limites Pix e consumo do período atual, ou null quando não houver limites disponíveis para consulta. No Sandbox, retorna null. Esse valor não significa que o saque esteja livre de limites." } }, "description": "Condições atuais para planejar a retirada. Valores monetários usam centavos de real. O aceite do saque depende da conferência das condições no momento da solicitação." }, "CreateWithdrawalRequest": { "type": "object", "additionalProperties": false, "required": [ "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "format": "int64", "minimum": 200, "maximum": 1000000000000, "description": "Valor total a retirar, em centavos de real, incluindo a tarifa. Consulte as condições de saque para conferir saldo, tarifa e limites antes de solicitar.", "example": 25000 }, "expected_destination_id": { "type": [ "string", "null" ], "maxLength": 100, "pattern": "^wdst_[A-Za-z0-9]+$", "description": "ID do destino próprio que deve continuar selecionado como padrão. Copie o id retornado na consulta dos destinos. Se o destino mudar ou deixar de ser válido, o saque é recusado. Omitir ou enviar null usa o destino padrão vigente.", "example": "wdst_3AbHiWSrsZBoaTg47OcMzC" } }, "description": "Valor total solicitado para o saque Pix. A tarifa, quando aplicável, é descontada desse valor." }, "Withdrawal": { "type": "object", "additionalProperties": false, "required": [ "id", "amount_cents", "fee_amount_cents", "net_amount_cents", "status", "failure_reason", "bank_account", "pix_destination", "requested_at", "completed_at", "failed_at", "canceled_at" ], "properties": { "id": { "type": "string", "pattern": "^wd_[A-Za-z0-9]+$", "description": "Identificador público do saque, com prefixo wd_. Também pode aparecer como reference_id no extrato." }, "amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor solicitado para saque, em centavos de real, incluindo a tarifa. Um saque pendente, com falha ou cancelado não confirma a transferência desse valor." }, "fee_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Tarifa do saque, em centavos de real. A tarifa é cobrada quando o saque é concluído; falha ou cancelamento não confirma cobrança." }, "net_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor destinado à conta de destino, em centavos de real: amount_cents menos fee_amount_cents. Consulte status para saber se a transferência foi concluída." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELED", "UNKNOWN" ], "description": "Estado atual do saque. PENDING: aguardando processamento; PROCESSING: em processamento; COMPLETED: concluído; FAILED: falhou; CANCELED: cancelado; UNKNOWN: estado sem classificação disponível. Apenas COMPLETED confirma a conclusão." }, "failure_reason": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalFailureReason" }, { "type": "null" } ], "description": "Motivo conhecido da falha, ou null quando o saque não está em FAILED. Um motivo indisponível não deve ser interpretado como autorização para repetir o saque." }, "bank_account": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalBankAccount" }, { "type": "null" } ], "description": "Conta de destino registrada em um saque bancário, ou null quando não se aplica. O número da conta é apresentado parcialmente." }, "pix_destination": { "anyOf": [ { "$ref": "#/components/schemas/WithdrawalPixDestination" }, { "type": "null" } ], "description": "Destino Pix registrado para o saque, ou null quando não há dados disponíveis. A chave é apresentada parcialmente." }, "requested_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da solicitação, em segundos Unix UTC." }, "completed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da conclusão, em segundos Unix UTC, ou null quando não houve conclusão." }, "failed_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante da falha, em segundos Unix UTC, ou null quando não houve falha." }, "canceled_at": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Instante do cancelamento, em segundos Unix UTC, ou null quando não houve cancelamento." } } }, "WithdrawalListResponse": { "type": "object", "additionalProperties": false, "required": [ "list", "page" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Withdrawal" }, "description": "Saques da página, na ordem solicitada." }, "page": { "$ref": "#/components/schemas/WithdrawalListPage", "description": "Tamanho da página e cursores para avançar ou voltar." } } }, "WithdrawalSummary": { "type": "object", "additionalProperties": false, "required": [ "processing_count", "processing_amount_cents" ], "properties": { "processing_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Quantidade de saques com situação PENDING ou PROCESSING.", "example": 3 }, "processing_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor total solicitado nesses saques, incluindo a tarifa, em centavos de real. Não some este valor ao saldo disponível.", "example": 175000 } }, "description": "Resumo atual dos saques pendentes ou em processamento da empresa." }, "ChargePaymentInformation": { "type": "object", "additionalProperties": false, "required": [ "pix", "boleto", "pix_status", "pix_error", "boleto_status", "boleto_error", "boleto_payment_status" ], "properties": { "pix": { "anyOf": [ { "$ref": "#/components/schemas/ChargePixPaymentInformation" }, { "type": "null" } ], "description": "Dados do Pix para pagamento, ou null quando não disponíveis." }, "boleto": { "anyOf": [ { "$ref": "#/components/schemas/ChargeBoletoPaymentInformation" }, { "type": "null" } ], "description": "Dados do boleto para pagamento, ou null quando não disponíveis." }, "pix_status": { "type": "string", "enum": [ "not_generated", "available", "pending", "failed" ], "description": "Resultado da emissão do Pix: not_generated quando não há emissão disponível ou solicitada; available quando os dados estão disponíveis; pending enquanto não há resultado confirmado; failed quando não foi possível emitir." }, "pix_error": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ], "description": "Motivo da pendência ou da falha de emissão do Pix, ou null. Guarde o ID da cobrança e use a consulta individual para acompanhar. Se a condição persistir, entre em contato com o suporte; não repita a criação para tentar emitir o Pix." }, "boleto_status": { "type": "string", "enum": [ "not_generated", "available", "pending", "failed" ], "description": "Resultado da emissão do boleto: not_generated quando não há emissão disponível ou solicitada; available quando os dados estão disponíveis; pending enquanto não há resultado confirmado; failed quando não foi possível emitir." }, "boleto_error": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ], "description": "Motivo da pendência ou da falha de emissão do boleto, ou null. Guarde o ID da cobrança e use a consulta individual para acompanhar. Se a condição persistir, entre em contato com o suporte; não repita a criação para tentar emitir o boleto." }, "boleto_payment_status": { "type": [ "string", "null" ], "enum": [ "awaiting_payment", "compensated", "settled", null ], "description": "Andamento do pagamento do boleto: awaiting_payment aguarda pagamento, compensated aguarda liquidação e settled confirma a liquidação. Null quando não há andamento disponível. A compensação ainda não representa crédito disponível." } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "description": "Código estável do erro." }, "message": { "type": "string", "description": "Explicação do erro em inglês. Em validações, resume a categoria; os detalhes identificam as correções. Use os códigos para tratar a resposta." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" }, "description": "Falhas em campos recebidos ou referências enviadas no corpo, com campo, código e explicação. Omitido em erros gerais e quando não há correção de campo a indicar." } } }, "ChargeListItem": { "type": "object", "required": [ "id", "customer_id", "amount_cents", "payment_method", "checkout_payment_method", "due_date", "title", "description", "status", "created_at", "checkout_url", "payment_method_types", "external_reference", "metadata" ], "properties": { "id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador público da cobrança." }, "customer_id": { "type": "string", "description": "Identificador público do cliente vinculado." }, "amount_cents": { "type": "integer", "format": "int64", "description": "Valor da cobrança em centavos de real." }, "payment_method": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Meio de pagamento da cobrança: 0 indefinido, 1 Pix, 2 boleto, 3 cartão de crédito e 4 cartão de débito. O valor 0 pode mudar para 1 ou 2 quando o Pix ou boleto é gerado no checkout. A escolha do checkout aparece separadamente em checkout_payment_method." }, "checkout_payment_method": { "type": [ "integer", "null" ], "enum": [ 0, 1, 2, 3, 4, null ], "description": "Meio de pagamento informado pelo checkout: 0 indefinido, 1 Pix, 2 boleto, 3 cartão de crédito e 4 cartão de débito. null quando essa informação ainda não estiver disponível. A seleção de uma opção na tela não confirma a geração do pagamento nem que a cobrança foi paga." }, "due_date": { "type": "integer", "format": "int64", "description": "Vencimento da cobrança em segundos Unix UTC." }, "title": { "type": [ "string", "null" ], "description": "Título da cobrança, ou null quando não informado." }, "description": { "type": [ "string", "null" ], "description": "Descrição da cobrança, ou null quando não informada." }, "status": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ], "description": "Status da cobrança, considerando o vencimento. 0 criado, 1 aguardando pagamento, 2 autorizado, 3 em processamento, 4 pago, 5 parcialmente devolvido, 6 devolvido, 7 cancelado, 8 expirado, 9 falha, 10 chargeback, 11 chargeback em análise, 12 chargeback perdido e 13 chargeback ganho." }, "created_at": { "type": "integer", "format": "int64", "description": "Instante de criação em segundos Unix UTC." }, "checkout_url": { "type": [ "string", "null" ], "description": "Link para o pagador abrir o checkout, ou null quando não houver link disponível." }, "payment_method_types": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "integer", "enum": [ 1, 2 ], "x-raims-enum-labels": [ "Pix", "Boleto" ] }, "example": [ 1, 2 ], "description": "Lista de meios configurada para a cobrança, ou null quando ela usa a configuração de checkout herdada. 1 significa Pix e 2 significa boleto. A lista não muda com o meio usado no pagamento nem representa a disponibilidade momentânea do checkout." }, "external_reference": { "type": [ "string", "null" ], "maxLength": 120, "description": "Referência do pedido ou da cobrança no seu sistema, ou null quando não informada. É independente da referência do cliente e pode ser repetida em outras cobranças." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dados de integração associados ao recurso. Retorna {} quando não há valores. Esse mapa não é usado como filtro de busca nem incluído automaticamente nos eventos de webhook.", "example": { "pedido": "12345", "filial": "matriz" } } }, "additionalProperties": false }, "ChargeListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Tamanho de página aplicado à consulta." }, "has_next": { "type": "boolean", "description": "Indica se há cobranças na próxima página." }, "has_previous": { "type": "boolean", "description": "Indica se há cobranças na página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para continuar com after; null quando não há próxima página." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para voltar com before; null quando não há página anterior." } } }, "CustomerListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Tamanho de página aplicado à consulta." }, "has_next": { "type": "boolean", "description": "Indica se há clientes na próxima página." }, "has_previous": { "type": "boolean", "description": "Indica se há clientes na página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para continuar com after; null quando não há próxima página." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para voltar com before; null quando não há página anterior." } } }, "FieldError": { "type": "object", "additionalProperties": false, "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string", "description": "Nome público do campo JSON, parâmetro de consulta, parâmetro de rota ou header relacionado ao erro. Campos aninhados e listas preservam o caminho e o índice. $ representa a raiz do corpo JSON." }, "code": { "type": "string", "description": "Motivo do erro no campo, como REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD ou INVALID_TYPE." }, "message": { "type": "string", "description": "Explicação em inglês sobre o problema nesse campo ou parâmetro e a correção disponível. Não use o texto para decidir o fluxo da integração." } } }, "AccountFee": { "type": "object", "additionalProperties": false, "required": [ "percentage_rate", "fixed_fee_cents", "minimum_fee_cents", "maximum_fee_cents" ], "properties": { "percentage_rate": { "type": [ "number", "null" ], "description": "Percentual da tarifa. Por exemplo, 0.8 representa 0,8%. Retorna null quando não houver parcela percentual informada." }, "fixed_fee_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Parcela fixa da tarifa, em centavos de real. Por exemplo, 85 representa R$ 0,85. Retorna null quando não houver parcela fixa informada." }, "minimum_fee_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Valor mínimo da tarifa, em centavos de real, ou null quando não houver mínimo informado." }, "maximum_fee_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Valor máximo da tarifa, em centavos de real, ou null quando não houver máximo informado." } }, "description": "Componentes da tarifa vigente. As parcelas percentual e fixa podem estar presentes na mesma condição comercial." }, "ReceiptParty": { "type": "object", "additionalProperties": false, "required": [ "name", "tax_id" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Nome cadastral, ou null quando não informado." }, "tax_id": { "type": [ "string", "null" ], "description": "CPF ou CNPJ cadastral, ou null quando não informado." } }, "description": "Nome e documento cadastrais associados à cobrança, sem dados de conta bancária." }, "RefundFailureReason": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "REFUND_NOT_SUBMITTED", "REFUND_REJECTED", "REFUND_PROCESSING_UNAVAILABLE", "REFUND_PROCESSING_FAILED", "REFUND_FAILURE_REASON_UNAVAILABLE" ], "description": "Código da causa confirmada. REFUND_FAILURE_REASON_UNAVAILABLE informa que a causa não está disponível." }, "message": { "type": "string", "description": "Explicação em inglês e orientação para acompanhamento. Use code para tratar a causa; não dependa do texto literal." } }, "description": "Causa pública de uma falha confirmada na solicitação de estorno." }, "RefundListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Quantidade de estornos solicitada nesta página." }, "has_next": { "type": "boolean", "description": "Indica se há uma próxima página." }, "has_previous": { "type": "boolean", "description": "Indica se há uma página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor da próxima página, ou null." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor da página anterior, ou null." } }, "description": "Informações para navegar pela mesma listagem de estornos." }, "RefundUnavailableReason": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "PIX_REFUND_NOT_AVAILABLE", "PIX_REFUND_CASHIN_NOT_FOUND", "PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY", "PIX_REFUND_IN_PROGRESS", "PIX_REFUND_ALREADY_COMPLETED", "PIX_REFUND_INSUFFICIENT_BALANCE", "PIX_REFUND_PROVIDER_UNAVAILABLE" ], "description": "Código do impedimento. Use esse valor para definir o tratamento na integração." }, "message": { "type": "string", "description": "Explicação em inglês para diagnóstico. O texto pode melhorar sem mudar o código; não o use para controlar a integração." } }, "description": "Condição que impede um pedido de devolução." }, "ChargeStatisticsAggregate": { "type": "object", "additionalProperties": false, "required": [ "count", "amount_cents" ], "properties": { "count": { "type": "integer", "format": "int64", "minimum": 0, "description": "Quantidade de cobranças no conjunto." }, "amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Soma dos valores das cobranças, em centavos de real, sem descontar tarifas ou devoluções." } }, "description": "Quantidade de cobranças e soma dos seus valores brutos." }, "CheckoutAsset": { "type": "object", "additionalProperties": false, "required": [ "url", "status", "error_code" ], "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "description": "Endereço da imagem atual, ou null quando não houver imagem disponível. Durante uma troca pendente ou com falha, conserva a imagem anterior, quando existir." }, "status": { "type": "string", "enum": [ "absent", "ready", "pending", "failed" ], "description": "Situação da imagem: absent quando não há imagem configurada; ready quando está disponível; pending durante o processamento; failed quando a alteração não pôde ser aplicada." }, "error_code": { "type": [ "string", "null" ], "enum": [ null, "CHECKOUT_ASSET_INVALID_IMAGE", "CHECKOUT_ASSET_UPLOAD_NOT_FOUND", "CHECKOUT_ASSET_PROCESSING_FAILED" ], "description": "Código público da falha na aplicação da imagem, ou null quando não houver falha." } }, "description": "Endereço da imagem atual e andamento da última alteração solicitada." }, "DisputeListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "charge_id", "kind", "stage", "reason_code", "disputed_amount_cents", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^(?:dp_[A-Za-z0-9]+|med_[1-9][0-9]*)$", "description": "Identificador público completo do caso, com prefixo dp_ ou med_. Use este valor na consulta individual." }, "charge_id": { "type": [ "string", "null" ], "pattern": "^ch_[A-Za-z0-9]+$", "description": "Identificador da cobrança vinculada, ou null quando não houver vínculo disponível." }, "kind": { "type": "string", "enum": [ "chargeback", "med" ], "description": "Tipo do caso: med para o procedimento MED do Pix e chargeback para os demais registros de contestação apresentados pela Raims." }, "stage": { "type": "string", "enum": [ "open", "in_analysis", "refund_in_analysis", "closed", "cancelled", "rejected", "failed" ], "description": "Etapa atual: open, in_analysis, refund_in_analysis, closed, cancelled, rejected ou failed. Closed informa análise encerrada, sem confirmar decisão favorável ou devolução." }, "reason_code": { "type": [ "integer", "null" ], "description": "Motivo relatado, que não confirma fraude, conforme kind. Para med: 1 golpe, 2 conta invadida, 3 coação, 4 acesso fraudulento, 5 outro e 6 desconhecido. Para chargeback: 1 alegação de fraude, 2 compra não reconhecida, 3 serviço não reconhecido, 4 produto ou serviço divergente, 5 cobrança indevida e 6 outro. Null quando não informado." }, "disputed_amount_cents": { "type": "integer", "format": "int64", "description": "Valor contestado, em centavos de real. Não representa o valor atualmente bloqueado nem confirma devolução." }, "created_at": { "type": "integer", "format": "int64", "description": "Data de criação do registro na Raims, em segundos Unix UTC." }, "updated_at": { "type": "integer", "format": "int64", "description": "Data da última atualização disponível, em segundos Unix UTC." } }, "description": "Dados de uma contestação presentes na listagem." }, "DisputeListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Quantidade efetiva de contestações solicitada por página." }, "has_next": { "type": "boolean", "description": "Indica se há outra página na direção de avanço." }, "has_previous": { "type": "boolean", "description": "Indica se há uma página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para after na próxima página, ou null quando não houver avanço." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para before na página anterior, ou null quando não houver retorno." } }, "description": "Informações para navegar pelas contestações com os mesmos filtros e ordenação." }, "PaymentLinkListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Quantidade de links solicitada nesta página." }, "has_next": { "type": "boolean", "description": "Indica se há uma próxima página." }, "has_previous": { "type": "boolean", "description": "Indica se há uma página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor da próxima página, ou null." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor da página anterior, ou null." } } }, "PaymentLinkUnavailableReason": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "PAYMENT_LINK_PAUSED", "CHARGE_EXPIRED", "CHARGE_NOT_OPEN", "BOLETO_AWAITING_SETTLEMENT", "PIX_CANCELLATION_PENDING", "PIX_CANCELLED", "PAYMENT_METHODS_UNAVAILABLE" ], "description": "Código do impedimento. Use esse valor para decidir o tratamento da integração." }, "message": { "type": "string", "description": "Explicação em inglês para diagnóstico. O texto pode ser aprimorado sem mudar o código; não o use para controlar a integração." } }, "description": "Motivo que impede pagar a cobrança pelo link. O link continua disponível para consulta." }, "StatementListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Tamanho efetivo da página." }, "has_next": { "type": "boolean", "description": "Indica se há uma próxima página." }, "has_previous": { "type": "boolean", "description": "Indica se há uma página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para after na próxima consulta, ou null no fim da lista." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para before na consulta anterior, ou null no início da lista." } } }, "WebhookEventType": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "charge.created", "charge.paid", "charge.canceled", "charge.failed", "refund.requested", "refund.completed", "refund.failed" ], "description": "Código usado no campo events do cadastro e da atualização.", "example": "charge.paid" } }, "description": "Um evento disponível para assinatura." }, "WebhookListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Quantidade efetiva de registros por página.", "example": 10 }, "has_next": { "type": "boolean", "description": "Indica se há outra página para avançar.", "example": false }, "has_previous": { "type": "boolean", "description": "Indica se há outra página para voltar.", "example": false }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para usar em after, ou null quando não há próxima página." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para usar em before, ou null quando não há página anterior." } }, "description": "Paginação dos webhooks." }, "WithdrawalDestinationListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Tamanho considerado para esta página. Não representa necessariamente a quantidade de destinos em list." }, "has_next": { "type": "boolean", "description": "Informa se existe uma próxima página. Continue mesmo quando list estiver vazia." }, "has_previous": { "type": "boolean", "description": "Informa se existe uma página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para copiar em after na próxima consulta, ou null quando não houver próxima página." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para copiar em before na consulta anterior, ou null quando não houver página anterior." } }, "description": "Cursores da listagem de destinos. A presença de uma próxima página independe da quantidade de destinos retornados em list." }, "WithdrawalPeriodLimits": { "type": "object", "additionalProperties": false, "required": [ "day_limit_cents", "night_limit_cents", "period_limit_cents", "period_used_cents", "period_remaining_cents", "request_maximum_amount_cents", "period", "period_ends_at" ], "properties": { "day_limit_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Limite diário de saques, em centavos de real. O dia de saque vai das 06:00 às 06:00 do dia seguinte, no horário de São Paulo." }, "night_limit_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Limite noturno de saques, em centavos de real, das 20:00 às 06:00 do dia seguinte. Esse valor faz parte do limite diário." }, "period_limit_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Limite aplicável ao período indicado por period, em centavos de real." }, "period_used_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor que já compromete o limite do período, em centavos de real. Inclui saques ainda em processamento." }, "period_remaining_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Valor restante no limite do período, em centavos de real. Não representa o saldo da conta." }, "request_maximum_amount_cents": { "type": "integer", "format": "int64", "minimum": 0, "description": "Teto informado para uma solicitação, em centavos de real, considerando os limites de saque. O saldo disponível e a tarifa também restringem o valor que pode ser solicitado." }, "period": { "type": "string", "description": "Período vigente: day durante o período diurno ou night das 20:00 às 06:00, no horário de São Paulo." }, "period_ends_at": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 253402300799, "description": "Término do período vigente, em segundos Unix UTC. Consulte novamente após esse instante para conferir as condições atualizadas." } }, "description": "Limites e consumo de saque no período atual, pelo horário de São Paulo. O limite noturno faz parte do diário." }, "WithdrawalFailureReason": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_BANK_ACCOUNT", "BANK_ACCOUNT_UNAVAILABLE", "BANK_UNSUPPORTED", "INVALID_ACCOUNT_TYPE", "INSUFFICIENT_BALANCE", "BLOCKED_BALANCE", "BELOW_MINIMUM_WITHDRAWAL", "ABOVE_MAXIMUM_WITHDRAWAL", "WITHDRAWAL_LIMIT_REACHED", "DUPLICATED_REQUEST", "RISK_POLICY_REJECTED", "WITHDRAWAL_TEMPORARILY_UNAVAILABLE", "BANK_PROCESSING_FAILURE", "BANK_TIMEOUT", "INTERNAL_ERROR", "WITHDRAWAL_FAILURE_REASON_UNAVAILABLE" ], "description": "Motivo registrado para a falha. Consulte os códigos e a orientação de tratamento em [Falhas de saque](/tipos-e-identificadores/financeiro#motivos-de-falha-do-saque)." }, "message": { "type": "string", "description": "Explicação da falha em inglês. O texto ajuda no diagnóstico; a integração deve usar code." } } }, "WithdrawalBankAccount": { "type": "object", "additionalProperties": false, "required": [ "bank_code", "branch", "account_number_masked" ], "properties": { "bank_code": { "type": "string", "description": "Código do banco de destino registrado no saque." }, "branch": { "type": [ "string", "null" ], "description": "Agência registrada no saque, com dígito quando informado, ou null." }, "account_number_masked": { "type": [ "string", "null" ], "description": "Número parcialmente oculto da conta de destino, com dígito quando informado, ou null." } } }, "WithdrawalPixDestination": { "type": "object", "additionalProperties": false, "required": [ "key_type", "key_masked", "holder_name", "bank_ispb" ], "properties": { "key_type": { "type": "string", "enum": [ "CNPJ", "EVP", "PHONE", "EMAIL" ], "description": "Tipo da chave usada no saque: CNPJ, EVP (aleatória), PHONE (telefone) ou EMAIL." }, "key_masked": { "type": "string", "description": "Chave Pix parcialmente oculta." }, "holder_name": { "type": "string", "description": "Nome do titular do destino registrado no saque." }, "bank_ispb": { "type": "string", "description": "ISPB da instituição de destino." } } }, "WithdrawalListPage": { "type": "object", "additionalProperties": false, "required": [ "page_size", "has_next", "has_previous", "next_after", "previous_before" ], "properties": { "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Tamanho efetivo da página." }, "has_next": { "type": "boolean", "description": "Indica se há uma próxima página." }, "has_previous": { "type": "boolean", "description": "Indica se há uma página anterior." }, "next_after": { "type": [ "string", "null" ], "description": "Cursor para a próxima página, ou null." }, "previous_before": { "type": [ "string", "null" ], "description": "Cursor para a página anterior, ou null." } } }, "ChargePixPaymentInformation": { "type": "object", "additionalProperties": false, "required": [ "copy_paste", "expires_at", "qr_code_base64" ], "properties": { "copy_paste": { "type": "string", "minLength": 1, "description": "Código Pix copia e cola para pagar a cobrança." }, "expires_at": { "type": "integer", "format": "int64", "description": "Expiração do código Pix em segundos Unix UTC." }, "qr_code_base64": { "type": "string", "minLength": 1, "contentEncoding": "base64", "contentMediaType": "image/png", "description": "Imagem PNG do QR Code em Base64, sem prefixo de data URI. Para exibir no navegador, acrescente data:image/png;base64, antes do valor." } } }, "ChargeBoletoPaymentInformation": { "type": "object", "additionalProperties": false, "required": [ "line_digits", "barcode", "due_date" ], "properties": { "line_digits": { "type": "string", "pattern": "^[0-9]{47}$", "description": "Linha digitável de 47 dígitos do boleto emitido." }, "barcode": { "type": "string", "pattern": "^[0-9]{44}$", "description": "Código de barras de 44 dígitos do boleto emitido." }, "due_date": { "type": "integer", "format": "int64", "description": "Vencimento do boleto em segundos Unix UTC." } } } }, "responses": { "Unauthorized": { "description": "Informe uma chave de API válida ou um access token OAuth válido no header Authorization: Bearer. Para OAuth expirado, renove a sessão ou autorize o aplicativo novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Provide a valid API key or OAuth access token in the Authorization: Bearer header." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "Forbidden": { "description": "O acesso foi recusado pela situação da empresa, pelas permissões ou restrições de IP da chave, ou pelo uso de uma chave de Produção no console. Confira error.code e a orientação de error.message. Para empresa suspensa ou encerrada, contate sac@raims.com. Para cadastro pendente, consulte a situação no Dashboard. Revise as permissões e os IPs permitidos pela chave; o console exige uma chave de Sandbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "api_key_permission_denied": { "summary": "Permissão ausente na chave", "value": { "error": { "code": "API_KEY_PERMISSION_DENIED", "message": "The API key does not allow this request. Review the key's permissions in the Dashboard." } } }, "ip_restricted": { "summary": "IP não autorizado pela chave", "value": { "error": { "code": "API_KEY_IP_RESTRICTED", "message": "The API key does not allow requests from this IP address. Check the integration server's outbound IP and the key's allowed IPs in the Dashboard." } } }, "documentation_environment": { "summary": "Chave de Produção no console da documentação", "value": { "error": { "code": "DOCUMENTATION_PRODUCTION_CREDENTIAL_NOT_ALLOWED", "message": "Production credentials are not allowed in the Raims documentation console. Use a Sandbox credential." } } }, "company_suspended": { "summary": "Empresa suspensa", "value": { "error": { "code": "COMPANY_STATUS_RESTRICTED", "message": "Your company is suspended and cannot access the API. Contact our support team at sac@raims.com for assistance." } } }, "company_closed": { "summary": "Conta da empresa encerrada", "value": { "error": { "code": "COMPANY_STATUS_RESTRICTED", "message": "Your company account is closed and cannot access the API. Contact our support team at sac@raims.com if you need assistance." } } }, "company_pending": { "summary": "Cadastro pendente em Produção", "value": { "error": { "code": "COMPANY_STATUS_RESTRICTED", "message": "Your company registration is pending and cannot access the production API. Check the registration status in the Dashboard." } } }, "company_status": { "summary": "Situação da empresa impede a requisição", "value": { "error": { "code": "COMPANY_STATUS_RESTRICTED", "message": "The company's current status does not allow this request. Check the company's status in the Dashboard." } } }, "oauth_scope": { "summary": "Requisição fora das permissões autorizadas", "value": { "error": { "code": "OAUTH_SCOPE_FORBIDDEN", "message": "The OAuth connection does not allow this request. Review the application's permissions in the Dashboard." } } }, "oauth_environment": { "summary": "Ambiente fora da autorização", "value": { "error": { "code": "OAUTH_ENVIRONMENT_FORBIDDEN", "message": "The OAuth connection does not allow the selected environment. Select an authorized environment." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "RateLimited": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMITED", "message": "The API request limit was exceeded. Wait for Retry-After and reduce the request rate or the number of concurrent requests." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Tempo de espera em segundos antes de repetir a requisição.", "example": 1 }, "Raims-Rate-Limited-Reason": { "schema": { "type": "string", "enum": [ "global-rate", "endpoint-rate", "global-concurrency", "endpoint-concurrency" ] }, "description": "Limite atingido: frequência total, frequência do endpoint, concorrência total ou concorrência do endpoint. Todas as chaves da empresa no ambiente compartilham a cota. A concorrência por endpoint só é limitada quando esse teto específico está habilitado para a empresa.", "example": "endpoint-rate" } }, "description": "O limite de frequência ou de requisições simultâneas da empresa no ambiente foi atingido. Aguarde Retry-After e ajuste as chamadas conforme Raims-Rate-Limited-Reason." }, "InternalError": { "description": "Não foi possível concluir a solicitação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error prevented the request from completing. Contact support if it persists." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "StoreUnavailable": { "description": "O serviço está temporariamente indisponível. Confira o código e tente novamente. Em pedidos de estorno ou saque, consulte o histórico antes de enviar outro pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "store_unavailable": { "summary": "Serviço temporariamente indisponível", "value": { "error": { "code": "STORE_UNAVAILABLE", "message": "The service is temporarily unavailable. Try again." } } }, "refund_unavailable": { "summary": "Processamento da devolução indisponível", "value": { "error": { "code": "PIX_REFUND_PROVIDER_UNAVAILABLE", "message": "Refund processing is temporarily unavailable. Retrieve the charge's refunds before trying again." } } }, "refund_request_unavailable": { "summary": "Solicitação não processada", "value": { "error": { "code": "PIX_REFUND_PROVIDER_REQUEST_INVALID", "message": "Refund processing is temporarily unavailable. Retrieve the charge's refunds before trying again." } } }, "withdrawal_provider_unavailable": { "summary": "Solicitação de saque temporariamente indisponível", "value": { "error": { "code": "PIX_WITHDRAWAL_PROVIDER_UNAVAILABLE", "message": "Withdrawal requests are temporarily unavailable. Check your withdrawal history before trying again." } } }, "withdrawal_unavailable": { "summary": "Processamento do saque temporariamente indisponível", "value": { "error": { "code": "PIX_WITHDRAWAL_UNAVAILABLE", "message": "Withdrawal requests are temporarily unavailable. Check your withdrawal history before trying again." } } }, "webhook_configuration_unavailable": { "summary": "Configuração de webhooks temporariamente indisponível", "value": { "error": { "code": "WEBHOOK_CONFIGURATION_UNAVAILABLE", "message": "Webhook configuration is temporarily unavailable. Try again later." } } }, "webhook_deliveries_unavailable": { "summary": "Histórico de webhooks temporariamente indisponível", "value": { "error": { "code": "WEBHOOK_DELIVERIES_UNAVAILABLE", "message": "Webhook deliveries are temporarily unavailable. Try again later." } } }, "webhook_test_unavailable": { "summary": "Teste de webhook temporariamente indisponível", "value": { "error": { "code": "WEBHOOK_TEST_UNAVAILABLE", "message": "Webhook testing is temporarily unavailable. Try again later." } } }, "rate_limit_store_unavailable": { "summary": "API temporariamente indisponível para aceitar a requisição", "value": { "error": { "code": "RATE_LIMIT_STORE_UNAVAILABLE", "message": "Request admission is temporarily unavailable. Wait for Retry-After before trying again." } } }, "oauth_unavailable": { "summary": "Autorização temporariamente indisponível", "value": { "error": { "code": "OAUTH_AUTHORIZATION_UNAVAILABLE", "message": "The current OAuth authorization could not be confirmed. Try again later." } } }, "oauth_authorization_changed": { "summary": "Resultado da requisição exige consulta", "value": { "error": { "code": "OAUTH_AUTHORIZATION_CHANGED", "message": "The request may have completed, but its result could not be delivered because authorization changed or could not be confirmed. Restore access and check the resource before retrying. Preserve the same Idempotency-Key when one was supplied." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "RequestTooLarge": { "description": "O corpo da requisição excede o limite aceito pelo endpoint. Reduza o JSON enviado antes de tentar novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "REQUEST_TOO_LARGE", "message": "The request body exceeds the allowed size." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "UnsupportedMediaType": { "description": "Envie o corpo com Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Send the request body with Content-Type application/json." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "UnprocessableEntity": { "description": "A solicitação não pôde ser processada. IDEMPOTENCY_KEY_REUSED indica que a chave já foi usada com outros parâmetros. Para repetir a mesma intenção, preserve a chave e a requisição original.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "idempotency_key_reused": { "summary": "Chave usada com outra requisição", "value": { "error": { "code": "IDEMPOTENCY_KEY_REUSED", "message": "This idempotency key was already used with a different request. To retry, send the original request unchanged with this key. Use a new key only for a new request." } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "RequestInProgress": { "description": "Outra requisição está em andamento ou o resultado precisa ser conferido antes de repetir a tentativa. Confira error.code. Respeite Retry-After quando informado. Para IDEMPOTENCY_RESULT_UNKNOWN, consulte o recurso antes de tentar novamente com a mesma chave; não crie outra intenção.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "request_in_progress": { "summary": "Requisição em andamento", "value": { "error": { "code": "REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } }, "idempotency_request_in_progress": { "summary": "Primeira tentativa ainda em andamento", "value": { "error": { "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS", "message": "Another request is in progress. Wait and retry the same request." } } }, "idempotency_result_unknown": { "summary": "Resultado a conferir antes de repetir", "value": { "error": { "code": "IDEMPOTENCY_RESULT_UNKNOWN", "message": "The request may have completed, but its response could not be saved for idempotent replay. Retrieve the affected resource, using Location when available, before retrying with the same Idempotency-Key. Do not use a new key." } } } } } }, "headers": { "Retry-After": { "description": "Tempo mínimo de espera em segundos quando uma requisição está em andamento. Pode estar ausente quando o resultado exige consulta.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } }, "InvalidAuthenticationEnvironment": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "environment_required": { "summary": "Ambiente não informado para OAuth", "value": { "error": { "code": "OAUTH_ENVIRONMENT_REQUIRED", "message": "Set X-Raims-Environment to an environment accepted by this operation when using OAuth.", "details": [ { "field": "X-Raims-Environment", "code": "REQUIRED", "message": "X-Raims-Environment is required." } ] } } }, "environment_invalid": { "summary": "Header de ambiente inválido", "value": { "error": { "code": "OAUTH_ENVIRONMENT_INVALID", "message": "The X-Raims-Environment header must contain exactly one supported value. Check the environments accepted by this operation.", "details": [ { "field": "X-Raims-Environment", "code": "INVALID_VALUE", "message": "X-Raims-Environment must contain one of the supported values documented for this field." } ] } } } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } }, "description": "Ao usar OAuth, informe X-Raims-Environment com um dos valores aceitos pela operação. Com chave de API, o ambiente vem da própria chave." }, "BadGateway": { "description": "O pedido foi recusado durante o processamento e não há devolução confirmada. Consulte o histórico da cobrança antes de tentar novamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "PIX_REFUND_PROVIDER_REJECTED", "message": "The refund request was rejected and no refund was confirmed. Check the charge's refunds before trying again." } } } }, "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Request-Id": { "$ref": "#/components/headers/LegacyRequestId" } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Chave API Raims", "description": "Envie a chave de API emitida pela Raims em Authorization: Bearer. A chave determina a empresa e o ambiente da requisição." }, "ApplicationOAuth": { "type": "oauth2", "x-raims-resource": "https://api.raims.com", "flows": { "authorizationCode": { "authorizationUrl": "https://internal-api.raims.com/oauth/authorize", "tokenUrl": "https://internal-api.raims.com/oauth/token", "scopes": { "raims:api": "Acesso às operações autorizadas da conta." } } }, "description": "Autorize o aplicativo na Raims pelo fluxo authorization code com PKCE S256. Informe resource=https://api.raims.com na autorização e na troca ou renovação do token. Envie o access token em Authorization: Bearer e selecione o ambiente com X-Raims-Environment. O acesso permanece limitado à conta, aos ambientes e às permissões autorizadas." } } } }