Acessar minha contaAbrir uma conta
PUT/api/v2/cobranca/cob/{txid}

Criar com txid

Cria cobrança dinâmica Pix com o txid informado na URL. Não é atualização (atualizar usa PATCH). Validação HTTP 422 exige apenas chave; para 200 envie também valor.original (>0). Scope: cob.write.

Parâmetros

Content-TypeObrigatório
header

Tipo de conteúdo da requisição

Tipo:string
AcceptObrigatório
header

Tipo de conteúdo aceito na resposta

Tipo:string
AuthorizationObrigatório
header

Token de autenticação Bearer

Tipo:string
txidObrigatório
path

Identificador único da transação Pix

Tipo:string

Autenticação e scopes

Requer Bearer token com scope cob.write.

PUT /api/v2/cobranca/cob/{txid} cria a cobrança dinâmica com o txid informado na URL. Não é atualização — revisão/alteração usa PATCH (quando documentado).

Body — validação HTTP vs uso real

Campo422 (validação HTTP)Para obter 200Observação
chaveObrigatórioSimDeve pertencer à conta autenticada
valor.originalNão (omitir pode virar 500)SimValor > 0
{txid} (path)—Sim26–35 caracteres (padding se curto)
nomeRecebedorNãoNãoPreenchido com o titular da chave se omitido
devedor.*NãoNãoOpcional na criação; sem regra XOR CPF/CNPJ
calendario.expiracaoNãoRecomendadoOmitir não aplica default 3600 na borda
valor.modalidadeAlteracaoNãoNãoDefault 0
solicitacaoPagadorNãoNãoOpcional

Request mínimo (sandbox)

{
  "chave": "[email protected]",
  "valor": { "original": 150.00 },
  "calendario": { "expiracao": 3600 }
}

Resposta 200: objeto da cobrança + correlationId.

Códigos de resposta

CódigoSignificadoDescrição
200OKCobrança criada
401UnauthorizedToken inválido
403ForbiddenScope cob.write ausente
422Unprocessable EntitySó chave ausente/inválida gera esse formato de validação
500Internal Server ErrorEx.: valor.original omitido

Notas

  • Técnica: Criar QR Code.
  • Evite enviar Account-Id; a conta vem do token.
curl --location --request PUT 'https://api-h.nuvende.com.br/api/v2/cobranca/cob/{{ txid }}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{ access_token }}' \
--data '{
  "chave": "[email protected]",
  "valor": { "original": 150.00 },
  "calendario": { "expiracao": 3600 }
}'

const axios = require("axios");

const data = {
  chave: "[email protected]",
  valor: { original: 150.0 },
  calendario: { expiracao: 3600 },
};

axios({
  method: "put",
  url: "https://api-h.nuvende.com.br/api/v2/cobranca/cob/{{ txid }}",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: "Bearer {{ access_token }}",
  },
  data,
})
  .then((response) => console.log(JSON.stringify(response.data)))
  .catch((error) => console.log(error.response?.data || error.message));

import requests
import json

url = "https://api-h.nuvende.com.br/api/v2/cobranca/cob/{{ txid }}"
payload = {
    "chave": "[email protected]",
    "valor": {"original": 150.00},
    "calendario": {"expiracao": 3600},
}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {{ access_token }}",
}
response = requests.put(url, headers=headers, data=json.dumps(payload))
print(response.text)

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api-h.nuvende.com.br/api/v2/cobranca/cob/{{ txid }}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS => json_encode([
    'chave' => '[email protected]',
    'valor' => ['original' => 150.00],
    'calendario' => ['expiracao' => 3600],
  ]),
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {{ access_token }}',
  ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

{
  "txid": "OjV78rsszBmtOhD3SjEndAKb7c",
  "revisao": 0,
  "status": "ATIVA",
  "calendario": {
    "criacao": "2024-12-26T12:34:56Z",
    "expiracao": 3600
  },
  "valor": {
    "original": "150.00",
    "modalidadeAlteracao": 0
  },
  "chave": "[email protected]",
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}