Cobranças imediatas

O conjunto de endpoints a seguir é responsável pela gestão de cobranças imediatas.

Criar cobrança imediata

Endpoint para criar uma cobrança imediata, neste caso, o txid deve ser definido pelo PSP.

POST /v1/cob

Requer autorização para o escopo: cob.write

Requisição

Exemplo

{
  "calendario": {
    "expiracao": 3600
  },
  "devedor": {
    "cnpj": "12345678000195",
    "nome": "Empresa de Serviços SA"
  },
  "valor": {
    "original": "37.00"
  },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitacaoPagador": "Serviço realizado.",
  "infoAdicionais": [
    {
      "nome": "Campo 1",
      "valor": "Informação Adicional1 do PSP-Recebedor"
    },
    {
      "nome": "Campo 2",
      "valor": "Informação Adicional2 do PSP-Recebedor"
    }
  ]
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

🟢 201

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "calendario": {
    "criacao": "2020-09-09T20:15:00.358Z",
    "expiracao": 3600
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "qrcodes-pix.sejaefi.com.br/v2/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cob"
  },
  "location": "qrcodes-pix.sejaefi.com.br/v2/9d36b84fc70b478fb95c12729b90ca25",
  "status": "ATIVA",
  "devedor": {
    "cnpj": "12345678000195",
    "nome": "Empresa de Serviços SA"
  },
  "valor": {
    "original": "567.89"
  },
  "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
  "solicitacaoPagador": "Informar cartão fidelidade"
}

🔴 400

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "detail": "O documento desta conta tem bloqueios que impedem a emissão",
    "title": "documento_bloqueado",
    "status": 400
  }
}

🔴 409

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "txid_duplicado",
    "detail": "Campo txid informado já foi utilizado em outra cobrança",
    "status": 409
  }
}

🔴 500

{
  "responseTime": 123,
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "erro_aplicacao",
    "detail": "Ocorreu um erro ao validar a chave",
    "status": 500
  }
}

Criar cobrança imediata com txid

Endpoint para criar uma cobrança imediata (cob) com TxId específico fornecido pelo PSP.

Características da Cobrança Imediata (Cob):

• Pagamento imediato: Deve ser paga no ato da consulta
• Sem data de vencimento: Não possui vencimento específico
• Expira automaticamente: Baseado no tempo configurado em expiracao (padrão 24h)
• QR Code dinâmico: Gera QR Code único para pagamento

Diferenças entre Cob e Cobv:

Característica	Cob (Imediata)	Cobv (Com Vencimento)
Vencimento	❌ Não tem	✅ Obrigatório
Pagamento	Imediato	Pode ser futuro
Juros/Multa	❌ Não permite	✅ Configurável
Abatimento	❌ Não permite	✅ Configurável
Desconto	❌ Não permite	✅ Configurável
Endereço devedor	❌ Opcional básico	✅ Obrigatório completo

Idempotência:

A operação é idempotente quando utilizado o mesmo txid. Requisições repetidas com o mesmo txid retornarão os mesmos dados da primeira requisição processada.

Validações:

• Pix Key: Deve ser uma chave válida e ativa
• Amount: Deve ser positivo e no formato correto (ex: "100.50")
• Debtor CPF/CNPJ: Se informado, deve ser válido e não bloqueado
• Expiration: Entre 1 segundo e 365 dias (padrão: 86400s = 24h)

PUT /v1/cob/:txid

Requer autorização para o escopo: cob.write

Requisição

Cobrança simples

{
  "calendario": {
    "expiracao": 3600
  },
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777"
}

Cobranças completa com devedor

{
  "calendario": {
    "expiracao": 7200
  },
  "devedor": {
    "nome": "João Silva",
    "cpf": "12345678901"
  },
  "valor": {
    "original": "150.75"
  },
  "chave": "[email protected]",
  "solicitacaoPagador": "Pagamento referente ao serviço prestado",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#456"
    },
    {
      "nome": "Categoria",
      "valor": "Serviços"
    }
  ]
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

🟢 200

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cob"
  },
  "status": "ATIVA",
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Chave Pix informada é inválida"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Consultar cobrança imediata

Endpoint para recuperar informações detalhadas de uma cobrança imediata específica através do seu txid.

Casos de Uso:

• Verificar status: Antes de tentar atualizar ou cancelar
• Obter QR Code: Para disponibilizar ao pagador
• Auditoria: Acompanhar histórico de modificações

GET /v1/cob/:txid

Requer autorização para o escopo: cob.read

Requisição

A requisição enviada para esse endpoint não precisa de um body, apenas os cabeçalhos de autorização OAuth, parâmetros e o certificado da conta.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

// Cobrança ativa
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cob",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva",
    "cpf": "12345678901"
  },
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777",
  "solicitacaoPagador": "Pagamento referente ao serviço prestado",
  "infoAdicionais": [
    {
      "nome": "Pedido",
      "valor": "#123"
    }
  ],
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🟢 200

// Cobrança concluída
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cob",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "CONCLUIDA",
  "valor": {
    "original": "50.00"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "TxId deve ter entre 26 e 35 caracteres alfanuméricos"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 404

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Cobrança com o txid informado não foi encontrada"
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Atualizar cobrança imediata

Endpoint para atualizar informações de uma cobrança imediata (cob) existente.

Restrições:

• Status: Apenas cobranças com status ATIVA podem ser atualizadas
• Chave: Não pode ser alterada após criação
• Calendário: Não pode ser alterado após criação
• Location: Não pode ser alterado após criação

Comportamentos:

• Revisão: Incrementa automaticamente a cada atualização
• QR Code: É regenerado com as novas informações
• Idempotência: Atualizações idênticas não alteram a revisão

Validações:

• Valor: Deve ser positivo e no formato correto
• CPF/CNPJ: Se alterado, deve ser válido e não bloqueado
• Status ATIVA: Cobrança deve estar ativa para permitir alterações

Importante!

Após a atualização, um novo QR Code será gerado. QR Codes anteriores podem não funcionar.

PATCH /v1/cob/:txid

Requer autorização para o escopo: cob.write

Requisição

Atualizar apenas o valor

{
  "valor": {
    "original": "75.00"
  }
}

Atualizar dados do devedor

{
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "98765432100"
  },
  "solicitacaoPagador": "Dados do devedor atualizados"
}

Atualização completa

{
  "devedor": {
    "nome": "Maria Silva",
    "cnpj": "12345678000195"
  },
  "valor": {
    "original": "150.00"
  },
  "solicitacaoPagador": "Pagamento atualizado com novos dados",
  "infoAdicionais": [
    {
      "nome": "Desconto",
      "valor": "5%"
    },
    {
      "nome": "Categoria",
      "valor": "Premium"
    }
  ]
}

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "expiracao": 3600
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 1,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cob"
  },
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "98765432100"
  },
  "valor": {
    "original": "75.00"
  },
  "chave": "+5561988887777",
  "solicitacaoPagador": "Pagamento atualizado - referente ao pedido #123",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Cobrança não está no status ATIVA, não pode ser atualizada"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 404

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Cobrança com o txid informado não foi encontrada"
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Listar cobranças imediatas

Endpoint para recuperar uma lista paginada de cobranças imediatas (cob) criadas pelo PSP.

Este endpoint possui filtros para afunilar os resultados da busca, tais como CPF/CNPJ e status. Dentre todos os filtros disponíveis, os filtros inicio e fim são obrigatórios e representam o intervalo de datas em que as cobranças consultadas devem estar compreendidas.

GET /v1/cob

Requer autorização para o escopo: cob.read

Requisição

O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datas inicio e fim) e o formato em que esses parâmetros devem ser repassados.

/v1/cob?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

🟢 200

{
  "parametros": {
    "inicio": "2023-10-01T00:00:00Z",
    "fim": "2023-10-31T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "cobs": [
    {
      "calendario": {
        "criacao": "2023-10-15T14:30:00Z",
        "expiracao": 3600
      },
      "txid": "fb2761260e054c7a94fb7b7b",
      "revisao": 0,
      "loc": {
        "id": 789,
        "location": "pix.example.com/qr/v2/cob/fb2761260e054c7a94fb7b7b",
        "tipoCob": "cob"
      },
      "status": "ATIVA",
      "devedor": {
        "nome": "João Silva",
        "cpf": "12345678901"
      },
      "valor": {
        "original": "50.00"
      },
      "chave": "+5561988887777",
      "solicitacaoPagador": "Pagamento referente ao serviço prestado",
      "infoAdicionais": [
        {
          "nome": "Pedido",
          "valor": "#123"
        }
      ]
    },
    {
      "calendario": {
        "criacao": "2023-10-16T09:15:00Z",
        "expiracao": 7200
      },
      "txid": "ac3849f6b2d54e8a95fb1b2c",
      "revisao": 0,
      "loc": {
        "id": 790,
        "location": "pix.example.com/qr/v2/cob/ac3849f6b2d54e8a95fb1b2c",
        "tipoCob": "cob"
      },
      "status": "CONCLUIDA",
      "valor": {
        "original": "100.00"
      },
      "chave": "[email protected]"
    }
  ]
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de início deve ser anterior à data de fim"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}