> ## Documentation Index > Fetch the complete documentation index at: https://docs.base39.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar recarga de saldo por Pix > Valores em centavos de BRL. Repetir idempotency_key com os mesmos dados retorna a mesma recarga; dados diferentes retornam 409. A criação pode ficar em verificação; consulte a recarga antes de tentar outra. O saldo muda somente após confirmar o pagamento. ## OpenAPI ````yaml /api-reference/openapi.json post /v3/topups openapi: 3.1.2 info: title: API Base39 version: 3.0.0 description: >- Contratos canônicos Base39 compartilhados entre API e MCP. Campos de negócio em snake_case. Valores financeiros em centavos de BRL; montantes de dados consultados são textos decimais que preservam a precisão informada. Datas cadastrais usam YYYY-MM-DD. As consultas podem debitar o saldo; a repetição equivalente na organização é gratuita até meia-noite de São Paulo. O extrato informa o consumo. Campos ausentes não significam zero nem aprovação de crédito. servers: - url: https://mcp.base39.com.br description: API pública Base39, independente do caminho do protocolo MCP. security: - bearer_auth: [] tags: - name: Consultas description: Consultas canônicas de dados. - name: Modelos de relatórios description: Modelos de relatório e seus recursos na organização autenticada. - name: Saldo e pagamentos description: Saldo e extrato da organização autenticada. paths: /v3/topups: post: tags: - Saldo e pagamentos summary: Criar recarga de saldo por Pix description: >- Valores em centavos de BRL. Repetir idempotency_key com os mesmos dados retorna a mesma recarga; dados diferentes retornam 409. A criação pode ficar em verificação; consulte a recarga antes de tentar outra. O saldo muda somente após confirmar o pagamento. operationId: create_balance_topup requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: amount: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Valor da recarga em centavos de real. payer: type: object properties: name: type: string minLength: 1 maxLength: 50 description: Nome do pagador. document: type: string pattern: ^(?:\d{11}|[A-Z0-9]{12}\d{2})$ description: >- CPF ou CNPJ do pagador sem pontuação; letras do CNPJ em maiúsculas. email: type: string format: email pattern: >- ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: E-mail do pagador. address: type: object properties: street: type: string minLength: 1 maxLength: 100 description: Logradouro do endereço do pagador. number: type: string minLength: 1 maxLength: 10 description: Número do endereço. complement: description: Complemento do endereço. type: string maxLength: 50 neighborhood: type: string minLength: 1 maxLength: 100 description: Bairro do endereço. postal_code: type: string pattern: ^\d{5}-\d{3}$ description: CEP no formato 00000-000. city: type: string minLength: 1 maxLength: 50 description: Município do endereço. state: type: string enum: - AC - AL - AP - AM - BA - CE - DF - ES - GO - MA - MT - MS - MG - PA - PB - PR - PE - PI - RJ - RN - RS - RO - RR - SC - SP - SE - TO description: Sigla da unidade federativa do endereço. required: - street - number - neighborhood - postal_code - city - state additionalProperties: false description: Endereço completo do pagador. required: - name - document - email - address additionalProperties: false description: Dados obrigatórios do pagador da recarga. idempotency_key: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Chave gerada uma vez por recarga; reutilize ao repetir a requisição. required: - amount - payer - idempotency_key additionalProperties: false examples: requisicao: value: amount: 10000 payer: name: Pessoa Exemplo document: '52998224725' email: pessoa@example.com address: street: Rua Exemplo number: '1' neighborhood: Centro postal_code: 01001-000 city: São Paulo state: SP idempotency_key: 70bfcacb-f883-49a6-a80b-afd98ba3df2e responses: '201': description: Cobrança criada ou recarga existente com a mesma chave. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: object: type: string const: balance_topup description: Tipo da recarga de saldo. id: type: string pattern: ^topup_[a-f0-9]{32}$ description: Identificador Base39 da recarga. amount: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Valor da recarga em centavos de real. currency: type: string const: BRL description: 'Moeda da recarga: real brasileiro.' status: type: string enum: - creating - active - paid - canceled - expired - failed - review description: >- Situação da recarga; o saldo é creditado após a confirmação do pagamento. created_at: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Instante da criação em milissegundos UTC. expires_at: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Limite exclusivo da validade em milissegundos UTC. paid_at: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: >- Instante confirmado do pagamento; nulo enquanto não confirmado. transaction_id: description: >- Identificador do crédito no extrato; nulo antes da confirmação. type: - string - 'null' pix_copy_paste: description: >- Código Pix copia e cola; disponível enquanto a cobrança está ativa. type: - string - 'null' required: - object - id - amount - currency - status - created_at - expires_at - paid_at - transaction_id - pix_copy_paste additionalProperties: false examples: resposta: summary: Exemplo de resposta Base39. value: object: balance_topup id: topup_00000000000000000000000000000001 amount: 10000 currency: BRL status: active created_at: 1794240000000 expires_at: 1794441600000 paid_at: null transaction_id: null pix_copy_paste: 000201...6304ABCD '400': $ref: '#/components/responses/error_400' '401': $ref: '#/components/responses/error_401' '403': $ref: '#/components/responses/error_403' '405': $ref: '#/components/responses/error_405' '409': $ref: '#/components/responses/error_409' '413': $ref: '#/components/responses/error_413' '415': $ref: '#/components/responses/error_415' '503': $ref: '#/components/responses/error_503' components: responses: error_400: description: Parâmetros inválidos. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Parâmetros inválidos. value: error: type: invalid_request_error code: invalid_request message: Revise os parâmetros da requisição. error_401: description: Autenticação ausente ou inválida. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Autenticação ausente ou inválida. value: error: type: authentication_error code: unauthorized message: Autenticação necessária. error_403: description: Acesso não permitido. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Acesso não permitido. value: error: type: permission_error code: forbidden message: Acesso não permitido. error_405: description: Método HTTP não permitido. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Método HTTP não permitido. value: error: type: invalid_request_error code: method_not_allowed message: Método HTTP não permitido para esta operação. error_409: description: Consulta equivalente em andamento. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store Retry-After: description: Tempo em segundos antes de uma nova tentativa. schema: type: integer minimum: 1 example: 2 content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Consulta equivalente em andamento. value: error: type: invalid_request_error code: query_in_progress message: Uma consulta equivalente está em andamento. error_413: description: Corpo da requisição acima do limite permitido para a operação. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Corpo da requisição acima do limite permitido para a operação. value: error: type: invalid_request_error code: request_too_large message: A requisição excedeu o limite permitido. error_415: description: O corpo deve usar application/json. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: O corpo deve usar application/json. value: error: type: invalid_request_error code: unsupported_media_type message: Envie o corpo como application/json. error_503: description: Serviço temporariamente indisponível. headers: Request-Id: description: Identificador da requisição para suporte e rastreamento. schema: type: string example: req_example Cache-Control: description: >- As respostas autenticadas não devem ser armazenadas por serviços HTTP compartilhados. schema: type: string const: no-store example: no-store Retry-After: description: Tempo em segundos antes de uma nova tentativa. schema: type: integer minimum: 1 example: 2 content: application/json: schema: $ref: '#/components/schemas/error' examples: erro: summary: Serviço temporariamente indisponível. value: error: type: api_error code: query_unavailable message: Não foi possível concluir a consulta. schemas: error: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - balance_error - api_error description: Categoria estável da falha. code: type: string pattern: ^[a-z][a-z0-9_]*$ description: Código estável da falha para tratamento pela aplicação. message: type: string description: Descrição da falha em português brasileiro. param: description: Parâmetro relacionado à falha, quando aplicável. type: string required: - type - code - message additionalProperties: false description: Falha que impediu a operação. required: - error additionalProperties: false securitySchemes: bearer_auth: type: http scheme: bearer description: >- Credencial OAuth da Base39 com os escopos profile e user:org:read, ou chave de API pertencente à organização. A organização e o autor são obtidos da autenticação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.