Crear Cobro
Descripción general
El endpoint PUT /cob/:txid crea un cobro inmediato (cob) asociado al identificador de transacción (txid) proporcionado. Este endpoint sigue la especificacion oficial del Banco Central de Brasil para cobros PIX.
El txid es un identificador único generado por su sistema. Debe tener entre 26 y 35 caracteres alfanumericos.
Endpoint
PUT /cob/{txid}Autenticación
Token Bearer obtenido via /oauth/token.
Ejemplo: Bearer eyJhbGciOiJSUzI1NiIs...
Parámetros de URL
txidstringobrigatorioIdentificador de la transacción. Debe ser único y contener entre 26 y 35 caracteres alfanumericos [a-zA-Z0-9].
Ejemplo: 7978c0c97ea847e78e8849634473c1f1
Cuerpo de la Solicitud
Información de control temporal del cobro.
Datos del deudor (pagador). Puede ser una persona fisica (CPF) o juridica (CNPJ).
Valores monetarios del cobro.
Clave PIX del receptor. Puede ser número de telefono, correo electrónico, CPF/CNPJ o EVP (clave aleatoria). Máximo 77 caracteres.
Texto libre para el pagador. Máximo 140 caracteres.
Lista de información adicional para el pagador.
Solicitud
curl -X PUT https://api.avista.global/cob/7978c0c97ea847e78e8849634473c1f1 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"calendario": {
"expiracao": 3600
},
"devedor": {
"cpf": "12345678909",
"nome": "Carlos Oliveira"
},
"valor": {
"original": "123.45",
"modalidadeAlteracao": 0
},
"chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
"solicitacaoPagador": "Servico realizado.",
"infoAdicionais": [
{
"nome": "Pedido",
"valor": "#12345"
}
]
}'const response = await fetch(
'https://api.avista.global/cob/7978c0c97ea847e78e8849634473c1f1',
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
calendario: {
expiracao: 3600,
},
devedor: {
cpf: '12345678909',
nome: 'Carlos Oliveira',
},
valor: {
original: '123.45',
modalidadeAlteracao: 0,
},
chave: '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
solicitacaoPagador: 'Servico realizado.',
infoAdicionais: [
{ nome: 'Pedido', valor: '#12345' },
],
}),
}
);
const cobranca = await response.json();import requests
response = requests.put(
'https://api.avista.global/cob/7978c0c97ea847e78e8849634473c1f1',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
},
json={
'calendario': {
'expiracao': 3600,
},
'devedor': {
'cpf': '12345678909',
'nome': 'Carlos Oliveira',
},
'valor': {
'original': '123.45',
'modalidadeAlteracao': 0,
},
'chave': '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
'solicitacaoPagador': 'Servico realizado.',
'infoAdicionais': [
{'nome': 'Pedido', 'valor': '#12345'},
],
}
)
cobranca = response.json()Respuesta
{
"calendario": {
"criacao": "2024-01-15T10:30:00.358Z",
"expiracao": 3600
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 12345,
"location": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD",
"tipoCob": "cob"
},
"location": "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD",
"status": "ATIVA",
"devedor": {
"cpf": "12345678909",
"nome": "Carlos Oliveira"
},
"valor": {
"original": "123.45",
"modalidadeAlteracao": 0
},
"chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
"solicitacaoPagador": "Servico realizado.",
"infoAdicionais": [
{
"nome": "Pedido",
"valor": "#12345"
}
]
}{
"statusCode": 400,
"message": "CPF deve conter exatamente 11 digitos numericos",
"error": "Bad Request"
}{
"statusCode": 409,
"message": "Cobranca com este txid ja existe",
"error": "Conflict"
}Campos de Respuesta
calendarioobjecttxidstringIdentificador de transacción proporcionado en la solicitud.
revisaonumberNúmero de revisión del cobro. Siempre 0 en la creación.
locobjectInformación del payload PIX.
locationstringCódigo PIX copia y pega (mismo valor que loc.location). Cadena en formato EMV que puede usarse para el pago.
statusstringEstado del cobro:
ATIVA: Cobro activo, esperando pagoCONCLUIDA: Pago recibidoREMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelado por el receptorREMOVIDA_PELO_PSP: Removido por el PSP
Estado del Cobro
stateDiagram-v2
[*] --> ATIVA: Cobro creado
ATIVA --> CONCLUIDA: Pago recibido
ATIVA --> REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelado
ATIVA --> REMOVIDA_PELO_PSP: Expirado/Removido
CONCLUIDA --> [*]
REMOVIDA_PELO_USUARIO_RECEBEDOR --> [*]
REMOVIDA_PELO_PSP --> [*]Webhook de Pago
Cuando el pago es confirmado, recibira un webhook V2 de tipo RECEIVE:
{
"type": "RECEIVE",
"data": {
"id": 123,
"txId": "7978c0c97ea847e78e8849634473c1f1",
"status": "LIQUIDATED",
"payment": {
"amount": "123.45",
"currency": "BRL"
},
"endToEndId": "E12345678901234567890123456789012",
"debtorAccount": {
"name": "Carlos Oliveira",
"document": "123.xxx.xxx-xx"
}
}
}Webhooks V2
Vea la documentación completa del webhook RECEIVE
Errores Comunes
| Código | Error | Solución |
|---|---|---|
| 400 | txid no coincide con el patron | Use entre 26-35 caracteres alfanumericos |
| 400 | CPF/CNPJ invalido | Verifique el formato (solo números) |
| 400 | Valor invalido | Use el formato "123.45" (string con 2 decimales) |
| 401 | Token invalido | Renueve el token de acceso |
| 409 | txid ya existe | Use un txid diferente |